LinkPort/docs/connection-diagnostics.md

连接路径与失败阶段

通用网络与协议错误细化（2026-09-28）

此前除少数已结构化协议外，连接测试可能只返回 target_connection_or_protocol，无法区分端口拒绝、协议握手失败、权限拒绝和查询失败。现在所有协议复用已执行阶段进行分类：TCP 连接、TLS、协议握手、认证、权限、协议会话、查询/健康检查和 HTTP 响应。

TCP 连接还会在底层错误可安全识别时细分为 target_connect_refused（例如 Windows 10061）、target_connect_timeout、target_connect_dns、target_connect_unreachable 和 target_connect_reset。例如 RabbitMQ 的 192.168.9.9:5672 被拒绝时，重新测试会显示目标 TCP 连接被拒绝，而不是泛化的 target_connection_or_protocol；这表示尚未进入 RabbitMQ 用户密码或 vhost 认证。

管理 API 和前端只使用稳定诊断码、阶段和排查提示，不透传服务端原始错误，以避免泄露地址、账号、密码或业务数据。旧诊断码保持兼容；历史记录不会自动重分类，需使用新版后端重新测试。

验证覆盖拒绝、重置、不可达、超时、协议、认证、权限和 HTTP 阶段，使用 Go 错误/诊断 fixture，不代表真实目标服务联调。

SSH 本地主机密钥校验（2026-09-23）

补充：SSH 服务端发送的是主机公钥，指纹比较由本地 SSH 库完成；不匹配时现在明确返回 ssh_host_identity，显示库的原始安全判定 ssh: host key mismatch，并在阶段记录中标记身份校验失败，账号认证尚未执行。缺失/无效的已确认密钥另用 ssh_host_key_unconfirmed，且目标 TCP 尚未尝试。只允许该精确的无凭据库错误进入 rawError；任意服务端原始文本可能含密码、令牌、地址或业务数据，不透传到管理 API、审计或复制的脱敏诊断。

原因：SSH 目标测试在拨号前验证已确认的主机密钥；缺失或无效时立即返回，原先未附结构化阶段，界面只能显示 target_connection_or_protocol，所有网络阶段仍为未执行。用户提供的 2026-09-23 13:51:46 失败记录只证明测试在拨号前或未记录到拨号的路径失败，不能仅凭记录判定具体原因。

结果：确认是未配置或无效 SSH 目标主机密钥时，返回安全的 ssh_host_identity 诊断和核对提示；target_connect 仍显示未执行，不虚构 TCP 成功，也不推断密码错误。其他发生在拨号前的未知失败仍保持未知分类。范围仅涉及 SSH/SFTP 目标测试和相同校验路径；没有配置迁移或目标数据修改。需部署新后端并重测，历史诊断不会改变。

验证：SSH 协议 fixture 测试断言无拨号及类型化错误，网关分类测试检查安全代码；未连接用户提供的真实目标。

网关认证库兼容（2026-09-21）

客户端连接 MongoDB 网关时不再要求 authSource=admin，可使用 ttx-xwms-test 等非空认证库。网关账号为全局身份，仍按网关用户名和密码校验，然后使用该账号映射的目标凭据及目标 authSource 连接上游；客户端认证库不会覆盖目标配置，也不会赋予额外的业务库权限。同一 SCRAM 会话的认证库必须保持一致，空认证库仍拒绝。

原有 admin 客户端保持兼容，无数据迁移。此修复需要运行新构建的程序才生效；仅保存配置或重启旧二进制不能获得修复。回归使用官方 Go 驱动与本地 MongoDB 协议 fixture，未宣称完成 Java 驱动或真实目标验证。

MongoDB 握手兼容修复（2026-09-21）

初次连接使用 isMaster 并声明 helloOk；仅在目标确认支持时，后续刷新才使用 hello。集群发现对明确的 CommandNotFound 回退 isMaster，其他错误不隐藏。认证机制通过 authSource.username 协商，优先 SCRAM-SHA-256，未声明支持时使用 SCRAM-SHA-1；网关侧客户端认证仍保持 SHA-256。旧服务端要求的额外空结束交换也被正确处理，仍要求服务端证明有效且最终完成，认证失败不会触发降级重试。

MongoDB 的认证库使用 authSource，不是 MySQL/Redis 专用的 database 字段。网络与握手成功不代表认证成功，正确密码配上错误认证库也可能被拒绝。真实测试已验证一个返回版本 4.1.13 的 K8s StatefulSet 目标完成认证和 buildInfo 查询，保存后重读配置复测也成功；这不等同于所有旧版 MongoDB 的完整业务兼容验证。

连接测试子页面显示：配置连接路径、中文失败阶段、问题类型、稳定诊断代码及安全排查提示。监控运维的检查结果和阶段列使用相同说明；复制脱敏诊断只带阶段代码，不带地址、账号、密码、Kubeconfig 正文或服务器原始报错。

路径是什么

网关测试按“网关账号 → 目标账号”选择实际目标。拖拽到单个网关账号后，即使网关默认 targetId 为空，也使用该账号映射中的目标配置计算路径；多账号先选择测试账号。不能因为网关默认地址为空就显示为“直连 → 未配置地址/端口”。目标/账号缺失时阻止发送测试，连接资产缺失则明确显示不可用，不能悄悄回退直连。

• 直连：LinkPort → 直连 → 目标地址:端口。
• SSH/SOCKS5：LinkPort → 连接资产的主机:端口 → 目标地址:端口。
• sing-box：LinkPort → sing-box <协议类型>（受控本地 SOCKS5 入口）→ 目标地址:端口。资产 JSON、binary 路径、随机本地凭据和 stderr 不进入路径或复制诊断。
• K8s：LinkPort → Kubeconfig 资产名/context → 命名空间/资源 → 容器内服务端口 → MongoDB 认证库（适用时）。

例如 wall-e-test/statefulset/mongo-shopee 会显示所选资源，不编造实际 Pod 名或 IP。K8s 不通过目标 IP 路由，非 TLS 路径不显示目标 IP；TLS/HTTPS 显示证书域名。资产缺失显示名称不可用，不用长 ID 代替可读名称。

这是配置路径，不是逐跳成功记录。显示 K8s 连接方式不证明 port-forward 已连通；显示认证库不证明认证已经开始。当前未输出 traceroute 或实际 Pod 探测结果。

MongoDB 错误区分

诊断代码	阶段 / 含义	优先检查
target_connect	直连 TCP 建立失败，未认证	地址、端口、监听、防火墙、网络
k8s_port_forward	K8s 转发建立失败	Kubeconfig、context、命名空间、资源、端口、权限
target_tls	TLS 握手或证书校验失败	TLS 开关、CA、证书域名；不要跳过证书校验
mongodb_handshake	未取得有效 hello 响应，尚未认证	转发链路、服务端口、协议/TLS 配置
mongodb_hello_unsupported	服务端明确拒绝 hello 命令	服务版本/协议兼容性，不是密码问题
mongodb_authentication	本地凭据不可用、SCRAM 被拒或验证失败	账号、密码、认证库、认证机制；不一定只是密码错误
mongodb_authentication_connection	SCRAM 交换中断或响应无效	网络、转发链路、服务器状态/协议；不能认定密码错误
mongodb_metadata_permission	已认证，但 buildInfo 查询被权限拒绝	查询命令权限，不必重置密码
mongodb_metadata_connection	已认证，读取版本信息时连接中断	网络、转发链路、服务器状态
mongodb_metadata	已认证，但服务器拒绝版本查询	命令权限或服务兼容性
target_connection_or_protocol	未能定位具体阶段	证据不足，不能判断是网络、协议还是账号问题

旧版本、未知代码也会明确显示“未能定位具体阶段”，不会把它当作密码错误，或宣称前置步骤成功。SSH/SOCKS5/sing-box 延续各自的连接、协商、身份或认证分类。

sing-box 错误区分

诊断代码	已观察的边界	不能据此断言
sing_box_start	外部 binary 已定位并尝试启动，或启动/本地端口就绪失败	不能证明远程代理或目标可达
sing_box_connect	linkport 连接受控 127.0.0.1 SOCKS5 入口	不能证明 outbound 建链成功
sing_box_negotiation	本地 SOCKS5 方法协商	不是远程协议或目标账号认证
sing_box_authentication	随机生成的本地 SOCKS5 凭据响应	不是资产中的代理凭据，也不是目标账号结论
target_connect	sing-box 返回目标 CONNECT 结果	成功后仍需目标 TLS、协议握手、认证和查询

资产页“检查配置”调用 sing-box check，只区分 binary 缺失、配置无效、超时和其他检查失败；失败响应只携带固定安全 error 类别和 durationMs，没有 diagnostics 或 sing_box_start。它不会启动长期 run、连接代理/目标或生成上述四个 sing-box 运行时阶段。要验证真实链路，必须在引用资产的目标上运行连接测试。失败不回退直连。完整部署与安全边界见 sing-box 连接资产。

实现与验证边界

MongoDB 的连接、TLS、hello、SCRAM、版本查询在发生错误的位置附加结构化阶段，管理 API 只输出白名单中的固定说明，底层服务器错误文本不回显。错误原因保留为内部 unwrap 链，供程序判断而非直接展示。

验证使用隔离 API 和本地 net.Pipe fixture，覆盖断连与认证拒绝的差异、权限失败及敏感文本不泄露；不代表实际 Kubernetes 或 MongoDB 集群已连通。当前仍需成功构建并部署新版前端/后端才能看到新阶段，旧错误代码不会自动补出历史连接的失败位置。