开发板通过 VSCode Remote-SSH 反向转发复用 PC 代理排障总结

1. 问题背景

• 使用场景：本地 Windows PC 通过 VSCode Remote-SSH 连接开发板，在开发板终端运行 Codex/相关工具链。
• 网络环境：校园网；PC 侧配置了代理（本机 127.0.0.1:7897 监听）。开发板默认直连外网。
• 现象/报错：
  • Codex 执行失败：codex exec failed (code null) 等非结构化错误。
  • 伴随出现：mcp startup: no servers（工具链能力未就绪的提示之一）。
• 初始判断误区：以为"PC 有代理，开发板也会自动走代理"。实际上 SSH 远端环境不会继承 PC 的代理设置，开发板仍按自身网络策略直连，导致在校园网环境下访问外部服务失败或不稳定。

---

2. 定位过程与关键证据

2.1 环境变量已生效但端口不可达（第一阶段）

• 在开发板设置 HTTP(S)_PROXY 指向 PC 的局域网地址 192.168.137.1:7897 后：
  • env 能看到变量已设置；
  • 但使用 /dev/tcp/192.168.137.1/7897 测试返回 fail。
• 结论：开发板无法访问 PC 上的代理端口。常见原因是代理仅监听 127.0.0.1（不对 LAN 开放）或被防火墙阻断。

2.2 选择方案二：SSH 反向转发（避免开放局域网代理端口）

• 方案目标：让开发板访问 127.0.0.1:<端口> 时，通过 SSH 隧道转到 PC 的 127.0.0.1:7897，无需让代理对局域网开放。
• 初次尝试手动 ssh -R ... 出现：
  • Warning: remote port forwarding failed for listen port 7897
• 但开发板侧 ss -lntp 显示 7897 not listening，说明远端监听并未建立，导致 curl 走代理超时。

2.3 修复关键：显式绑定 + 换远端端口 + 让 VSCode 自动建立转发（第二阶段）

• 将转发写入 Windows ~/.ssh/config，并显式绑定回环地址，避免歧义；同时换用不易冲突的远端端口 17897。
• 连接后，开发板验证：
  • sudo ss -lntp | grep ':17897' 返回 LISTEN ... users:(("sshd",pid=...,fd=...))
• 结论：反向转发已成功建立。

---

3. 最终处理方式（最终配置）

3.1 Windows（~/.ssh/config）

核心配置思想：开发板上监听 127.0.0.1:17897，转发到 PC 的 127.0.0.1:7897。

示例：

Host xxx
  HostName 192.168.xxx.xxx
  User xxx
  RemoteForward 127.0.0.1:17897 127.0.0.1:7897
  ExitOnForwardFailure yes
  ServerAliveInterval 30
  ServerAliveCountMax 3

3.2 开发板（~/.bashrc）

将代理指向开发板本地回环的转发端口：

# BEGIN CODEX PROXY
export HTTP_PROXY=http://127.0.0.1:17897
export HTTPS_PROXY=http://127.0.0.1:17897
export NO_PROXY=localhost,127.0.0.1
# END CODEX PROXY

---

4. 最终验证效果

4.1 隧道监听验证（开发板）

• sudo ss -lntp | grep ':17897' 显示 sshd 在 127.0.0.1:17897 上 LISTEN
  说明 VSCode/SSH 已自动建立 RemoteForward。

4.2 代理可用性验证（开发板）

执行：

curl -I -x http://127.0.0.1:17897 https://api.openai.com --max-time 8

返回：

• HTTP/1.1 200 Connection established
• HTTP/1.1 200 OK

解释：

• 200 Connection established 表示 HTTP 代理成功完成对 HTTPS 的 CONNECT 建链；
• 200 OK 表示实际 HTTPS 请求也已成功完成。

结论：开发板已能稳定通过 PC 的代理出网；Codex/相关外部访问问题具备解决条件。

---

5. 学到的东西

1. "PC 有代理"不等于"SSH 远端自动走代理"
   远端程序只看远端的网络与环境变量；除非你明确把流量引到 PC 侧（LAN 开放代理或 SSH 隧道）。
2. 优先用 SSH 隧道而不是开放 LAN 代理端口

• LAN 开放需要代理软件允许局域网访问、还要处理防火墙；风险与复杂度更高。
• SSH RemoteForward 在安全边界内完成转发，且只对远端回环开放，控制面更清晰。

4. 端口通不通要分两层验证

• 传输层：ss -lntp 看远端是否真的 LISTEN；/dev/tcp/host/port 看是否可连。
• 应用层：curl -x 看代理 CONNECT 是否成功。传输层通不代表代理协议对，应用层验证不可省。

4. 在 SSH 配置中加入 ExitOnForwardFailure yes 很关键
   否则可能出现"SSH 看似连上，但转发没建立"的隐蔽失败状态，排查成本高。
5. .bashrc 只对交互式 bash 稳定生效
   如果后续发现某些非交互进程/扩展不吃代理变量，需要把变量放到更通用的登录配置（如 ~/.profile）或在启动命令处显式 export。

---

6. 结论

本次问题的根因不是"开发板网络坏了"，而是校园网环境下外部访问受限 + 代理只在 PC 本机可用 + SSH 远端不继承代理 导致工具调用失败。通过 VSCode Remote-SSH 的 RemoteForward 建立反向转发，再将开发板代理指向本地回环端口，最终实现开发板稳定复用 PC 代理出网，验证成功。