Openship服务器SSH连接排障：端口、密钥与host通道诊断-育师

Openship服务器SSH连接排障：端口、密钥与host通道诊断

【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship

Openship是一个自托管部署平台（Self-hosted deployment platform）。在容器内运行，通过 SSH 连接到你的服务器完成部署、终端、端口扫描等操作。SSH 连接失败是新手最常卡住的环节：安装显示成功、仪表盘一切正常，偏偏某项操作报"没有 host channel"。本文按"先辨类型、再看错误、后给修复"的顺序，带你快速定位Openship SSH 连接排障的根因。

一、先分清：Openship 里有两种 SSH 连接

很多人一上来就改错地方，是因为没区分这两种连接：

连接	用途	凭据来自哪里
服务器 SSH 连接	首次接入服务器（添加自定义服务器时）	你在表单里填的主机、端口、用户名、密码/密钥
host 通道（host channel）	Openship 容器反向 SSH 回宿主机，执行宿主机级操作	`openship up`自动生成的专属 ed25519 密钥

⚠️ 关键认知：仪表盘上保存的服务器 SSH 凭据，并不用于 host 通道。host 通道有自己独立、受限的密钥。认证失败时改仪表盘里的凭据是徒劳的。

接入表单的参数定义：ssh.ts（端口默认22，用户默认root，支持密码或密钥两种方式）
地址合法性与内网 IP 检测：validation.ts

二、服务器 SSH 连接排障：端口、用户与认证方式

接入服务器失败时，按顺序检查这三项：

端口：默认 22。如果你的 sshd 改过端口（常见于上云后改端口防扫描），务必填实际端口，且云控制台安全组要放行该端口。
用户名：默认root。部分发行版（如 Debian/Ubuntu）默认禁止 root 登录，可改用sudo权限用户，或确认sshd -T | grep -i permitrootlogin的输出。
认证方式：密码或密钥二选一。选密钥时必须填写密钥文件路径（可带 passphrase）；内网服务器（10./192.168./172.16-31.开头）无法从公网直连时，可配置跳板机（jump host）中转。

三、host 通道排障：五种错误，五种病因

openship doctor与仪表盘横幅会给出标准化诊断，全部逻辑集中在 host-channel.ts 中。对照你的报错找病因：

1. "no response, not even a refusal"（超时/无响应）

这是防火墙丢包的典型特征。host 通道的地址是宿主机本地地址，要穿过宿主机的filter/INPUT链；而:80、:443、:4000等容器发布端口走 DNAT 转发、根本不到这条链——这就是"别的检查都正常、只有它卡住"的原因。

✅ 修复：为 Docker 网桥网段放行 SSH 端口。规则模板（含 ufw/firewalld/nftables/iptables 各语法及重启后持久化提示）由 hostFirewallRule 生成，桥接网段读不到时回退到覆盖全部默认网桥的172.16.0.0/12。

2. "connection refused"（连接被拒绝）

包到达了但没有进程接收：sshd 没在容器可达的地址上监听。

✅ 修复：

检查/etc/ssh/sshd_config的ListenAddress是否被钉死在127.0.0.1
确认 sshd 已启用：Debian/Ubuntu 是sudo systemctl enable --now ssh，RHEL 系单元名叫sshd，Alpine 用rc-service（SSHD_ENABLE_HINT_UNKNOWN）

3. "didn't resolve inside the container"（主机名无法解析）

通道走host.docker.internal桥接，需要extra_hosts: host.docker.internal:host-gateway和 Docker 20.10+；rootless Docker 不提供 host gateway。

✅ 修复：升级 Docker / 改用 root 模式，然后重跑openship up重新配置通道。

4. "no route from the Openship container"（无路由）

通道配置的地址在宿主机网络上不可达（常见于更新后 API 容器落入新网段子网）。

✅ 修复：重跑openship up重新配置，或将OPENSHIP_HOST_SSH_HOST指向容器可达的地址。

5. "accepted the connection and then refused Openship's key"（密钥被拒）

端口是通的（健康检查因此显示正常），但 sshd 拒绝了密钥。两种可能，修复方式完全不同：

密钥不在目标账户的authorized_keys里 → 重新授权
sshd 不允许该账户登录 → 对 root 通道执行sshd -T | grep -i permitrootlogin检查

见 HOST_CHANNEL_AUTH_REJECTED。

四、修复 host 通道：两条命令搞定

openship up # 重新生成并授权密钥、写环境变量、重建容器后从容器内拨测 openship doctor # 复查通道是否真的恢复

openship up是幂等的：密钥、数据库卷、证书都会保留；探测到丢包时还会主动提议帮你加防火墙规则（脚本化运行可加--open-host-firewall）。

💡 如果你是从裸docker/docker-compose.yml装起的（~/.openship/compose/不存在），不要直接跑openship up，而是按官方文档手动五步配置：宿主机生成密钥 → 以from=172.16.0.0/12,192.168.0.0/16,10.0.0.0/8,127.0.0.1限制授权给 root → 打通 sshd 与防火墙 → 设置OPENSHIP_HOST_SSH_*环境变量 → 重建容器。完整步骤见 host-channel.mdx。

五、通道挂掉时，哪些功能受影响？

记住官方口径：这是降级（degraded），不是坏了（broken）：

✅照常可用：普通部署——走的是 Docker socket，不经过此通道
❌被阻塞：宿主终端、宿主系统信息、宿主端口扫描；从 Openship 未启动的代理接管:80/:443；安装/升级邮件引擎；需要宿主机生成配置文件的目录应用（如 Supabase 的kong.yml）
📍附带症状：仪表盘服务器列表中该机器显示Offline——机器本身是好的，只是探测用的这条通道断了

完整功能清单见 HOST_CHANNEL_BLOCKED。若你出于加固目的就是不想让容器碰宿主机，可用openship up --no-host-control显式关闭通道——这是一个安全决策，不是修复手段。

六、快速自检清单

现象	第一反应
超时无响应	宿主机防火墙放行 Docker 网桥网段 → SSH 端口
connection refused	sshd 监听地址 + 单元是否启用
主机名解析失败	Docker 版本 ≥ 20.10、非 rootless、`extra_hosts`配置
密钥被拒	`authorized_keys`授权 /`PermitRootLogin`
更新后突然断	`openship up`重配 +`openship doctor`复查