NetBridge Remote 0.0.10

NetBridge Remote 是 NetBridge 的远程端插件，安装在 Remote-SSH 连接后的远程 VS Code 窗口里。它的目标不是代理整台远程服务器，而是尽可能覆盖从 VS Code 这棵进程树发起的网络请求，让 VS Code 插件、AI 助手、集成终端、以及 AI 助手拉起的命令行工具都尽量借用本地电脑的网络出口。

配套的本地端插件是：

aurorix-netbridge-local-0.0.10.vsix

远程端插件是：

aurorix-netbridge-remote-0.0.10.vsix

工作链路

远程 VS Code 插件 / 远程集成终端 / AI 助手拉起的子进程
        ↓
NetBridge Remote
        ↓
远程 localhost HTTP Proxy / SOCKS5 Proxy / PAC
        ↓
VS Code command bridge
        ↓
NetBridge Local
        ↓
本地电脑网络出口
        ↓
外网 AI 服务 / GitHub / npm / pip / 其他网络资源

适用场景

这套方案适合下面这种开发环境：

代码在公司内网编译服务器上。
本地 Windows / macOS / Linux 电脑可以访问外网。
通过 VS Code Remote-SSH 连接编译服务器写代码。
远程服务器本身不能直接访问外网，导致 Copilot、Cline、Codex、Continue、npm、pip、git 等工具联网失败。
希望只影响 VS Code 相关操作，不想改远程服务器的全局网络、iptables、路由表或系统代理。

默认开启的能力

0.0.5 默认“全亮”启用以下能力。

1. 启动级 preload 自动安装

远程插件激活时，会自动把启动注入写入远程 VS Code Server：

~/.vscode-server/server-env-setup
~/.netbridge/preload.cjs

核心机制是：

NODE_OPTIONS=--require ~/.netbridge/preload.cjs

这样新的 VS Code Extension Host 启动时，会在普通插件加载前先加载 NetBridge preload。

正常情况下不需要手动执行 NetBridge Remote: Install Startup Preload。这个命令保留为修复用。

2. VS Code 插件内部网络拦截

preload 会尽量提前 patch 常见 Node 网络 API：

fetch
http
https
node:http
node:https
undici.fetch
undici.request
undici.stream

因此，如果 AI 插件在 VS Code Extension Host 内部直接发 HTTP/HTTPS 请求，这些请求会被转给本地端插件出网。

3. 远程 HTTP/HTTPS 代理

远程端会自动启动一个只监听 localhost 的 HTTP 代理，支持：

HTTP 普通请求
HTTPS CONNECT 隧道

端口默认高位随机分配，并写入：

~/.netbridge/ports.json

这个代理用于 VS Code 集成终端里的常见工具，例如：

curl
git
npm
pnpm
yarn
pip
python requests
node
Go 工具链
Cargo 部分场景

4. 远程 SOCKS5 代理

远程端会自动启动 SOCKS5 代理，并为终端注入：

ALL_PROXY=socks5h://127.0.0.1:<socksPort>

注意这里使用的是 socks5h，不是普通 socks5。

区别：

socks5   ：可能由远程服务器解析 DNS
socks5h  ：域名交给代理出口侧解析，也就是本地电脑侧解析

在远程服务器外网 DNS 不通时，socks5h 更可靠。

5. PAC 服务

远程端会自动启动 PAC 服务：

http://127.0.0.1:<pacPort>/proxy.pac

PAC 内容会优先返回 HTTP Proxy，再返回 SOCKS5，最后 DIRECT。部分支持 PAC 的工具或嵌入式浏览器可使用它。

6. VS Code 新终端自动注入代理环境变量

插件通过 VS Code 的 environmentVariableCollection 给新开的集成终端自动注入代理变量。

典型变量如下：

HTTP_PROXY=http://127.0.0.1:<httpPort>
HTTPS_PROXY=http://127.0.0.1:<httpPort>
http_proxy=http://127.0.0.1:<httpPort>
https_proxy=http://127.0.0.1:<httpPort>

ALL_PROXY=socks5h://127.0.0.1:<socksPort>
all_proxy=socks5h://127.0.0.1:<socksPort>

npm_config_proxy=http://127.0.0.1:<httpPort>
npm_config_https_proxy=http://127.0.0.1:<httpPort>
CARGO_HTTP_PROXY=http://127.0.0.1:<httpPort>

NO_PROXY=localhost,127.0.0.1,::1
no_proxy=localhost,127.0.0.1,::1

注意：已经打开的终端不会自动获得新环境变量。请关闭旧终端并新开一个。

7. AI 插件拉起的子进程自动注入代理

0.0.5 会 patch：

child_process.spawn
child_process.exec
child_process.execFile
child_process.fork

如果 AI 插件从 VS Code Extension Host 里启动 CLI、curl、python、node、git、npm 等命令，这些子进程会自动继承 NetBridge 代理环境。

这对 Codex、Cline、Continue 这类“插件界面 + 外部 CLI/子进程”的结构尤其重要。

安装步骤

1. 本地端安装

在本地 VS Code 安装：

aurorix-netbridge-local-0.0.10.vsix

本地端负责真正出网，必须安装在本地 VS Code UI 侧。

2. 远程端安装

通过 Remote-SSH 连接远程主机后，在远程窗口安装：

aurorix-netbridge-remote-0.0.10.vsix

远程端负责拦截远程 VS Code 插件请求，并在远程 localhost 上启动 HTTP/SOCKS/PAC 代理入口。

3. 首次安装后重连一次远程窗口

首次安装后建议执行一次：

Remote-SSH: Kill VS Code Server on Host...

然后重新连接。

原因是启动级 preload 必须在新的 Extension Host 进程启动时加载。插件会自动安装 preload，但无法让已经启动的进程“回到启动前”。

后续正常使用不需要重复执行安装命令。

验证方式

查看代理状态

在命令面板执行：

NetBridge Remote: Proxy Status

可以看到当前 HTTP、SOCKS5、PAC 地址。

测试 VS Code 终端联网

新开一个远程 VS Code 终端，执行：

env | grep -i proxy
curl -I https://github.com --connect-timeout 10

如果看到代理环境变量，并且 curl 返回 HTTP 响应头，说明终端代理已生效。

测试显式 HTTP 代理

source ~/.netbridge/proxy-env.sh
curl -x "$HTTP_PROXY" -I https://github.com --connect-timeout 10

测试 SOCKS5

source ~/.netbridge/proxy-env.sh
curl --socks5-hostname 127.0.0.1:$(node -e "console.log(require(require('os').homedir() + '/.netbridge/ports.json').socksProxy)") -I https://github.com --connect-timeout 10

Codex / 独立 CLI 类插件能不能被注入

大概率可以，但要看它的启动路径。

可以覆盖的情况

如果 Codex 插件或类似 AI 插件是在 VS Code 侧边栏里点击按钮后，由 VS Code Extension Host 通过 Node 的 child_process 拉起 CLI，例如：

spawn('codex', ...)
execFile('codex', ...)
exec('codex ...')
fork(...)

那么 0.0.5 会给这个 CLI 自动注入：

HTTP_PROXY
HTTPS_PROXY
ALL_PROXY=socks5h://...
NO_PROXY
npm_config_proxy
npm_config_https_proxy

只要 CLI 或它内部调用的 HTTP 库读取这些标准代理变量，就会走 NetBridge。

CLI 首次下载安装也可能被覆盖

如果插件安装 CLI 时使用的是 Extension Host 内部的 fetch/http/https/undici，会被 preload 拦截。

如果插件安装 CLI 时是通过 child_process 拉起 npm、curl、node 等命令，0.0.5 也会给这些子进程注入代理环境。

需要重启/重连的情况

如果 Codex CLI 或某个 AI CLI 在安装 0.0.5 前已经启动成常驻后台进程，它已经继承不到新环境变量。

处理方式：

退出该 AI 插件或停止它的后台 CLI。
重连 VS Code Remote 窗口。
重新从 VS Code 侧边栏启动该插件。

不能保证覆盖的情况

以下情况纯 VS Code 作用域代理无法保证：

CLI 完全不读取 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY
CLI 是静态二进制并直接 syscall connect
CLI 被 systemd、cron、手工 SSH shell 等 VS Code 之外的进程启动
CLI 自己清空 env 后再联网
CLI 使用非 TCP/HTTP 协议且不支持代理

这种要靠系统级透明代理或 TUN/tun2socks，但那会修改远程系统网络，不属于 NetBridge 0.0.5 默认目标。

配置项

默认配置已经全亮。一般不需要手动改。

代理服务

{
  "netbridge.remote.proxyServer.enabled": true,
  "netbridge.remote.proxyServer.host": "127.0.0.1",
  "netbridge.remote.proxyServer.httpPort": 0,
  "netbridge.remote.proxyServer.socksPort": 0
}

端口为 0 表示随机选择高位端口并持久化。

PAC 服务

{
  "netbridge.remote.pacServer.enabled": true,
  "netbridge.remote.pacServer.port": 0
}

终端环境变量

{
  "netbridge.remote.terminal.autoConfigureEnv": true,
  "netbridge.remote.terminal.noProxy": "localhost,127.0.0.1,::1"
}

子进程代理注入

{
  "netbridge.remote.childProcess.injectProxyEnv": true
}

远端文件说明

~/.netbridge/preload.cjs       启动级 preload 文件
~/.netbridge/ports.json        当前 HTTP/SOCKS/PAC 实际端口
~/.netbridge/proxy-env.sh      可手动 source 的代理环境变量
~/.netbridge/preload.log       preload 日志
~/.vscode-server/server-env-setup  VS Code Server 启动环境注入点

故障排查

1. 终端没有代理变量

关闭旧终端，重新打开一个新终端。

检查：

env | grep -i proxy

2. 插件请求可以走，但终端不走

确认远程代理服务已启动：

NetBridge Remote: Proxy Status

然后新开终端测试：

source ~/.netbridge/proxy-env.sh
curl -I https://github.com --connect-timeout 10

3. AI CLI 还是不能联网

优先判断它是不是安装前已经启动的常驻进程。

处理：

重连远程 VS Code
关闭旧 AI 会话
重新点击侧边栏启动 AI 插件

如果它仍然不走，说明该 CLI 可能不读代理环境变量，或自己清理了环境变量。

4. 端口冲突

0.0.5 会自动随机高位端口并重试。

当前端口查看：

cat ~/.netbridge/ports.json

5. preload 没生效

检查：

cat ~/.vscode-server/server-env-setup
ls -l ~/.netbridge/preload.cjs
cat ~/.netbridge/preload.log

如果缺失，可执行修复命令：

NetBridge Remote: Install Startup Preload

然后重连远程窗口。

安全边界

远程代理默认只监听 127.0.0.1。
不默认暴露到局域网或公网。
不修改远程系统全局网络。
不写 /etc、iptables、路由表。
不默认修改 git/npm/pip 全局配置。
日志应避免记录 Authorization、token、key 等敏感信息。

版本说明

0.0.5

默认全亮启用 HTTP Proxy、SOCKS5 Proxy、PAC。
代理端口高位随机并持久化。
自动安装 startup preload。
自动注入 VS Code 新终端代理环境。
自动为 AI 插件拉起的子进程注入代理环境。
preload 阶段也 patch child_process。
保留命令作为排障和修复入口。

Marketplace ID

本版本使用新的 Marketplace 扩展 ID：

Aurorix.aurorix-netbridge-remote

旧的 netbridge.* 或 Aurorix.netbridge-* 包不会自动升级到这个新 ID；如果本机已经装过旧包，建议先卸载旧扩展，再安装本版本。