docs(vscode): 补充 SSH 远程连接配置实例

mudssky · mudssky · commit 3c11df89e081 · 2026-05-13T08:48:50.000+08:00
diff --git a/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/check.jsonl b/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".trellis/spec/guides/index.md", "reason": "检查文档/配置改动是否保持最小变量与可回滚。"}
+{"file": ".trellis/tasks/05-12-ssh-remoteforward-vscode-docs/research/openssh-client-options.md", "reason": "校验文档建议与 OpenSSH 选项语义一致。"}
diff --git a/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/implement.jsonl b/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/implement.jsonl
@@ -0,0 +1,2 @@
+{"file": ".trellis/spec/guides/index.md", "reason": "通用修改前检查与变更边界提醒。"}
+{"file": ".trellis/tasks/05-12-ssh-remoteforward-vscode-docs/research/openssh-client-options.md", "reason": "OpenSSH 客户端配置选项语义依据。"}
diff --git a/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/prd.md b/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/prd.md
@@ -0,0 +1,65 @@
+# SSH RemoteForward 断联与 VS Code 文档优化
+
+## Goal
+
+排查 Windows 侧 SSH 连接 Linux 服务器时的间歇断联问题，先通过关闭常规连接里的 `RemoteForward` 来观察是否由多个客户端抢占同一个远端端口触发，同时更新 VS Code Remote SSH 文档，避免后续配置继续把代理隧道混入 VS Code 或 zellij 会话。
+
+## What I already know
+
+* 本机 `C:\Users\mudssky\.ssh\config` 中多个普通 Host 曾直接配置 `RemoteForward 7890 127.0.0.1:7890` 或 `RemoteForward 7890 localhost:7890`。
+* zellij 项目 Host 使用 `RequestTTY yes` 与 `RemoteCommand ... zellij attach -c ...`。
+* 用户确认当前不确定断联是否由 `RemoteForward` 引发，策略是先关掉观察。
+* 用户希望 VS Code 侧加 `ServerAliveInterval 60`、`ServerAliveCountMax 3`、`ConnectTimeout 30`，zellij 侧暂不加，避免混淆观察结果。
+* `docs/cheatsheet/vscode/remote/ssh-proxy.md` 已有 RemoteForward、VS Code、zellij 混用断联排查说明，但当前“VS Code 自动化配置”部分仍容易鼓励把 `RemoteForward` 放入 VS Code Host。
+
+## Requirements
+
+* 注释掉普通 Host 中现有 `RemoteForward 7890`，保留原配置作为可恢复记录。
+* 只给普通/VS Code 连接 Host 增加 `ServerAliveInterval 60`、`ServerAliveCountMax 3`、`ConnectTimeout 30`。
+* 暂不修改 zellij Host 的保活参数，保留其原有 `RequestTTY` 与 `RemoteCommand` 行为。
+* 更新 VS Code Remote SSH 文档：默认建议不要让 VS Code Host 直接声明 `RemoteForward`；如需代理，优先使用独立隧道 Host 或临时 `ssh -N -R`。
+* 文档补充本次观察法：先关闭 `RemoteForward`，仅给 VS Code Host 加保活，观察断联是否缓解。
+* 文档补充可直接套用的 SSH config 实例，覆盖 VS Code、zellij、独立代理隧道三种入口。
+
+## Acceptance Criteria
+
+* [x] 本机 SSH config 中普通 Host 不再启用 `RemoteForward 7890`。
+* [x] 本机 SSH config 中普通/VS Code Host 具备 `ServerAliveInterval 60`、`ServerAliveCountMax 3`、`ConnectTimeout 30`。
+* [x] zellij Host 未新增保活参数。
+* [x] VS Code SSH 反向代理文档不再把 `RemoteForward` 放入 VS Code Host 作为默认推荐。
+* [x] VS Code SSH 反向代理文档包含 VS Code、zellij、独立 tunnel 三种配置实例。
+* [x] 可通过 `ssh -G` 验证关键 Host 配置解析结果。
+
+## Definition of Done
+
+* 文档与本机配置改动完成。
+* 配置解析验证通过。
+* 仅修改文档/配置，不执行根目录 `pnpm qa`。
+
+## Out of Scope
+
+* 不修改远端 `sshd_config`。
+* 不调整 zellij Host 的 `RemoteCommand` 写法。
+* 不新增单元测试。
+* 不直接判定断联根因，保留观察结论。
+
+## Research References
+
+* [`research/openssh-client-options.md`](research/openssh-client-options.md) — OpenSSH 客户端选项语义确认。
+
+## Technical Approach
+
+采用最小变量实验：关闭 `RemoteForward`，只在普通/VS Code Host 上增加客户端保活与连接超时参数；zellij Host 保持原状。文档同步改为“独立隧道优先、VS Code Host 保持干净”的建议。
+
+## Decision (ADR-lite)
+
+**Context**: 当前断联根因未确认，`RemoteForward` 多连接冲突只是候选原因之一。
+
+**Decision**: 不一次性重构全部 Host；先注释普通 Host 的 `RemoteForward` 并给 VS Code 侧增加连接参数，zellij 侧不动。
+
+**Consequences**: 观察期内远端 `127.0.0.1:7890` 代理不会自动随普通连接建立；如果断联仍出现，后续再排查网络空闲超时、VS Code 重连、远端 sshd 限制或 zellij attach 生命周期。
+
+## Technical Notes
+
+* 涉及文件：`C:\Users\mudssky\.ssh\config`、`docs/cheatsheet/vscode/remote/ssh-proxy.md`。
+* Context7 查询 OpenSSH 文档，确认 `RemoteForward`、`-R`、`ServerAliveInterval`、`ServerAliveCountMax`、`TCPKeepAlive` 等选项语义。
diff --git a/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/research/openssh-client-options.md b/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/research/openssh-client-options.md
@@ -0,0 +1,19 @@
+# OpenSSH 客户端选项语义确认
+
+## 来源
+
+* Context7：`/openssh/openssh-portable`
+* 查询主题：`ssh_config RemoteForward ExitOnForwardFailure ServerAliveInterval ServerAliveCountMax TCPKeepAlive RequestTTY RemoteCommand VS Code Remote SSH 多连接 端口转发配置建议`
+
+## 结论
+
+* `RemoteForward`/`ssh -R` 用于把远端监听端口转发到客户端侧可访问的目标地址与端口。
+* `ServerAliveInterval` 与 `ServerAliveCountMax` 是客户端侧保活配置；例如 `60` 与 `3` 表示每 60 秒发送一次服务端保活探测，连续 3 次无响应后客户端认为连接不可用。
+* `ConnectTimeout` 只影响建立连接阶段，适合避免网络异常时长时间卡住，不用于保持已建立连接。
+* `ExitOnForwardFailure yes` 可让端口转发绑定失败时直接失败，避免进入“SSH 已连接但代理未建立”的半成功状态；本轮先关闭 `RemoteForward`，所以不作为活跃配置重点。
+
+## 对本仓库任务的约束
+
+* 当前目标是定位问题，不宜同时修改 zellij Host 的生命周期参数。
+* VS Code Remote SSH 常会建立多条连接，文档应避免把同一个 `RemoteForward 7890` 放进 VS Code Host 作为默认方案。
+* 如果后续需要恢复代理，优先使用专用隧道 Host 或临时 `ssh -N -R`，并配合 `ExitOnForwardFailure yes` 做显性失败。
diff --git a/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/task.json b/.trellis/tasks/05-12-ssh-remoteforward-vscode-docs/task.json
@@ -0,0 +1,26 @@
+{
+  "id": "ssh-remoteforward-vscode-docs",
+  "name": "ssh-remoteforward-vscode-docs",
+  "title": "brainstorm: SSH RemoteForward 断联与 VS Code 文档优化",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "mudssky",
+  "assignee": "mudssky",
+  "createdAt": "2026-05-12",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
diff --git a/docs/cheatsheet/vscode/remote/ssh-proxy.md b/docs/cheatsheet/vscode/remote/ssh-proxy.md
@@ -61,17 +61,18 @@ killall ssh
 
 ---
 
-### 2. 配置文件方式 (推荐/永久生效)
+### 2. 配置文件方式：专用隧道 Host
 
-*配置一次，以后直接 `ssh alias` 即可自动建立隧道。*
+*配置一次，以后直接 `ssh alias` 即可建立隧道。建议把隧道放在专用 Host 中，不要和 VS Code Remote SSH 或 zellij 登录 Host 混用。*
 
 编辑文件：`~/.ssh/config` (Mac/Linux) 或 `%USERPROFILE%\.ssh\config` (Windows)
 
-```ssh
-Host my-cloud-server             # 别名
+```sshconfig
+Host my-cloud-server-tunnel      # 专用隧道别名
     HostName 1.2.3.4             # 服务器公网 IP
     User root                    # 用户名
     Port 22                      # SSH 端口
+    ExitOnForwardFailure yes     # 转发端口绑定失败时直接失败，避免半成功连接
     # ↓↓↓ 核心配置 ↓↓↓
     # 格式：RemoteForward <服务器监听端口> <本地视角的目标IP>:<目标端口>
 
@@ -82,16 +83,34 @@ Host my-cloud-server             # 别名
     # RemoteForward 7890 192.168.50.1:7890
 ```
 
+连接时用：
+
+```bash
+ssh -N my-cloud-server-tunnel
+```
+
+`-N` 表示不打开远程 Shell，只维护代理隧道。这样 VS Code、普通终端、zellij 登录都可以复用远端 `127.0.0.1:7890`，但不会各自抢占同一个远端监听端口。
+
 ---
 
-### 3. VS Code 自动化配置 (终极方案)
+### 3. VS Code 配置：保持 SSH Host 干净
 
-*实现：连接即代理，终端自动生效环境变量。*
+*目标：VS Code 连接稳定，远程终端按需使用已存在的代理端口。*
 
-#### 第一步：配置隧道 (同上)
+#### 第一步：VS Code Host 只放连接稳定性配置
 
-确保你的 SSH Config 文件中已经添加了 `RemoteForward` (参考第 2 点)。
-*VS Code 会自动读取这个 SSH 配置建立连接。*
+VS Code Remote SSH 通常会建立多条 SSH 连接。如果这些连接都带同一个 `RemoteForward 7890`，后续连接可能绑定失败，甚至让排查断联时难以判断根因。建议 VS Code 使用不带 `RemoteForward`、`RemoteCommand`、`RequestTTY` 的 Host：
+
+```sshconfig
+Host my-cloud-server-vscode
+    HostName 1.2.3.4
+    User root
+    ServerAliveInterval 60
+    ServerAliveCountMax 3
+    ConnectTimeout 30
+```
+
+如果正在排查十几分钟后断联的问题，可以先注释掉普通 Host 中的 `RemoteForward`，只保留上面三个 VS Code 侧参数观察一段时间。这样能把“代理端口冲突”和“连接空闲/网络抖动”拆开看。
 
 #### 第二步：配置终端自动注入变量
 
@@ -112,6 +131,54 @@ Host my-cloud-server             # 别名
 }
 ```
 
+如果远程 `127.0.0.1:7890` 没有监听，说明当前没有独立隧道在运行。此时先启动第 2 节的 `*-tunnel` Host，而不是把 `RemoteForward` 重新放回 VS Code Host。
+
+#### 第三步：常用配置实例
+
+下面这组配置把同一台服务器拆成三个入口：VS Code 只负责非交互开发连接，zellij 只负责人工终端会话，tunnel 只负责代理端口转发。
+
+```sshconfig
+# VS Code Remote SSH 入口：保持非交互，不带 RemoteCommand / RequestTTY / RemoteForward。
+Host ai-admin-vscode
+  HostName 192.168.27.77
+  User administrator
+  ServerAliveInterval 60
+  ServerAliveCountMax 3
+  ConnectTimeout 30
+
+# zellij 人工入口：保留 TTY 与远程命令，排查期先不加保活参数。
+Host ai-admin-zellij
+  HostName 192.168.27.77
+  User administrator
+  RequestTTY yes
+  RemoteCommand bash -lc 'cd ~/projects/env/powershellScripts && exec /home/linuxbrew/.linuxbrew/bin/zellij attach -c powershellScripts'
+
+# 独立代理入口：只在需要远端 127.0.0.1:7890 代理时手动启动。
+Host ai-admin-tunnel
+  HostName 192.168.27.77
+  User administrator
+  ExitOnForwardFailure yes
+  RemoteForward 7890 127.0.0.1:7890
+```
+
+使用方式：
+
+```bash
+# VS Code 里选择 ai-admin-vscode
+
+# 终端里进入 zellij 工作区
+ssh ai-admin-zellij
+
+# 需要代理时单独开一个窗口维持隧道
+ssh -N ai-admin-tunnel
+```
+
+如果代理目标不是本机 Clash，而是局域网软路由，把 `RemoteForward` 的目标地址换成软路由 IP：
+
+```sshconfig
+RemoteForward 7890 192.168.50.1:7890
+```
+
 ---
 
 ### 4. 服务器端验证与手动激活
@@ -255,32 +322,38 @@ RemoteCommand bash -lc 'cd ~/projects/ai/java/xhgj-ai-platform && exec /home/lin
 
 #### 拆分 VS Code Host 与人工 zellij Host
 
-不要让 VS Code Remote SSH 复用带 `RemoteCommand` 的 Host。VS Code 需要非交互连接，`RemoteCommand`、`RequestTTY`、`RemoteForward` 都可能干扰它的连接管理。
+不要让 VS Code Remote SSH 复用带 `RemoteCommand` 的 Host。VS Code 需要非交互连接，`RemoteCommand`、`RequestTTY`、`RemoteForward` 都可能干扰它的连接管理。排查期间建议只给 VS Code Host 加客户端侧保活与连接超时，zellij Host 先保持原样，避免一次改变太多变量。
 
 ```sshconfig
+# VS Code Remote SSH 入口：非交互连接，只放保活与连接超时。
 Host proj-xhgj-ai-platform-vscode
   HostName 192.168.27.77
   User administrator
-  ServerAliveInterval 30
+  ServerAliveInterval 60
   ServerAliveCountMax 3
-  TCPKeepAlive yes
+  ConnectTimeout 30
 
+# zellij 人工入口：保留 TTY 与 RemoteCommand，排查期先不加保活参数。
 Host proj-xhgj-ai-platform-zellij
   HostName 192.168.27.77
   User administrator
   RequestTTY yes
-  ServerAliveInterval 30
-  ServerAliveCountMax 3
-  TCPKeepAlive yes
+  RemoteCommand bash -lc 'cd ~/projects/ai/java/xhgj-ai-platform && exec /home/linuxbrew/.linuxbrew/bin/zellij attach -c proj-xhgj-ai-platform'
+
+# 独立代理入口：需要代理时用 ssh -N 启动，避免 VS Code 多连接抢端口。
+Host proj-xhgj-ai-platform-tunnel
+  HostName 192.168.27.77
+  User administrator
   ExitOnForwardFailure yes
   RemoteForward 7890 192.168.21.108:7890
-  RemoteCommand bash -lc 'cd ~/projects/ai/java/xhgj-ai-platform && exec /home/linuxbrew/.linuxbrew/bin/zellij attach -c proj-xhgj-ai-platform'
 ```
 
 如果 VS Code 也需要代理，建议只保留一个连接负责 `RemoteForward 7890`。可以先用独立终端维持隧道：
 
 ```bash
 ssh -N -o ExitOnForwardFailure=yes -R 7890:192.168.21.108:7890 administrator@192.168.27.77
+# 或者使用上面的专用 Host
+ssh -N proj-xhgj-ai-platform-tunnel
 ```
 
 然后 VS Code Host 不再声明同一个 `RemoteForward 7890`，避免多连接抢同一端口。
@@ -296,5 +369,5 @@ ssh -N -o ExitOnForwardFailure=yes -R 7890:192.168.21.108:7890 administrator@192
 | **端口被占用** | 服务器上已有程序占用了 7890 | 修改 `RemoteForward` 的第一个端口号 (如 `8888 127.0.0.1:7890`) |
 | **Git 依然慢** | Git 有单独的配置 | 运行 `git config --global http.proxy http://127.0.0.1:7890` |
 | **后台隧道无法关闭** | 使用了 `-f` 参数，进程在后台运行 | `ps aux | grep "ssh -NfR"`查找进程，`kill <PID>` 关闭 |
-| **隧道自动断开** | SSH 连接超时或网络不稳定 | 在 SSH 配置中添加 `ServerAliveInterval 60` 保持心跳 |
-| **VS Code / zellij 十几分钟后断开** | 客户端主动断开、网络空闲超时、多连接抢 `RemoteForward`、`RemoteCommand` 退出都可能触发 | 先查近 7 天历史日志，再拆分 VS Code Host 与 zellij Host，并加 `ExitOnForwardFailure yes` |
+| **隧道自动断开** | SSH 连接超时或网络不稳定 | 在专用隧道 Host 中添加 `ServerAliveInterval 60` 保持心跳，或先用前台 `ssh -N` 观察日志 |
+| **VS Code / zellij 十几分钟后断开** | 客户端主动断开、网络空闲超时、多连接抢 `RemoteForward`、`RemoteCommand` 退出都可能触发 | 先查近 7 天历史日志；排查期先注释普通 Host 的 `RemoteForward`，只给 VS Code Host 加 `ServerAliveInterval 60`、`ServerAliveCountMax 3`、`ConnectTimeout 30`，zellij Host 暂不加保活参数 |

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+{"file": ".trellis/spec/guides/index.md", "reason": "检查文档/配置改动是否保持最小变量与可回滚。"}`
	`2`	`+{"file": ".trellis/tasks/05-12-ssh-remoteforward-vscode-docs/research/openssh-client-options.md", "reason": "校验文档建议与 OpenSSH 选项语义一致。"}`