通过 SSH 反向代理让服务器借用本机网络访问 GitHub 的最佳实践

背景与痛点

这次折腾测试服务器，起因很简单：我想让本机在使用 Codex 或其他智能体修复问题时，少承担一些构建和验证的负担。

让智能体改代码，只是修复过程的一部分。一次修改完成后，还要编译、跑测试、打包，有时还要启动依赖服务做回归。验证没有通过，智能体就带着日志继续分析、继续修改，再执行下一轮检查。原本偶尔手动运行的构建任务，逐渐变成了一个持续重复的验证循环。

问题也跟着这个循环变得明显：智能体调用的编译器、构建守护进程、测试进程和容器，都在同一台个人电脑上运行。大型 Java 项目的多模块构建、多版本测试和制品打包，会持续占用 CPU、内存与磁盘 I/O；本机同时还要支撑 IDE、浏览器、文档和日常沟通。后台任务在执行，我仍需要阅读代码、查看日志、评审下一轮修改，两边很容易争用资源。

于是，我决定把资源消耗较重的执行环节放到服务器上。这次在广州开了一台 4 核、16GiB 内存、300GiB 系统盘的测试机，安装 Ubuntu 24.04 和 Git，并配置了本机到服务器的 SSH 免密登录。接下来的分工也很明确：本机保留智能体交互、代码阅读和结果评审，服务器承接编译、测试、打包及临时服务运行。

设想中的工作方式是：智能体在本机发起操作，通过 SSH 调用远程命令，再把日志、测试结果和制品信息带回来。这样，每一轮修复都有地方执行验证，本机也能为持续的交互工作留出资源。服务器已经准备好了，接下来该把代码拉下来，看看这套流程能否真正跑通。

图 1 智能体驱动多轮修复，本机保留交互与决策，服务器承担构建、测试、打包和回归验证，通过 SSH 交换任务与结果。

• 减少本机资源争用。 将持续占用 CPU、内存和磁盘的验证任务迁出，给交互式工作留出资源。

• 隔离项目环境。 在服务器上管理 JDK、构建工具、容器和依赖服务，降低不同项目的配置互相影响、个人电脑环境被反复改动的概率。

• 保留验证现场。 独立的工作目录、日志和制品可以在多轮修复间持续保留，方便回看失败原因和对比修复结果。

• 为并行验证提供空间。 不同分支或任务可以使用独立目录或 worktree，并按服务器容量控制并发，减少对同一工作区的争用。

这种分工追求的是整体协作效率，而不是假定每次远程构建都一定更快。服务器规格、任务并发、依赖缓存和代码同步方式仍需匹配实际负载；频繁传输大目录也可能抵消收益。实践中可以让代码和构建缓存在服务器侧持续保留，日常主要传递修改、命令和结果。

服务器准备好了 却卡在了代码拉取

接下来，我在服务器上尝试克隆 beacon-observability/beacon-java。机器可以登录，Git 也已经装好，但克隆没有顺利完成：终端先显示正在克隆，随后报出 GitHub 443 端口连接超时。还没开始验证代码，新的卡点就出现在了环境准备的第一步。

这时，远程验证的另一个前提变得很具体：服务器有可用的计算资源，还需要拿得到代码和依赖。代码拉不下来，后面的构建、测试和回归就都接不上。反复重试可以碰运气，却很难成为一套能在下一次问题修复中继续使用的工作方式。

• 环境已经交付，代码却没有到位。 服务器可以登录，甚至 GitHub 首页偶尔能打开，但完整仓库传输仍可能中断。

• 个人开发机可用，云服务器出口不稳定。 两端网络条件不同，同一条命令在本机成功，在服务器上却不断超时。

• 临时办法可以救急，重复操作难以复用。 手工下载、反复重试和临时开代理，一旦重启或断线，就需要重新排查。

图 2 代码拉取是环境准备的前置环节，连接波动会逐步传递到构建、联调和测试交付。

当时执行的克隆命令是 git clone https://github.com/beacon-observability/beacon-java.git，终端给出的关键错误如下：

error: RPC failed; curl 28 Failed to connect to github.com port 443
fatal: expected 'packfile'

进一步排查后发现，服务器并非始终无法访问 GitHub：DNS 能解析，HTTPS 和仓库引用查询也曾成功，但完整克隆时传输速度波动明显。首条错误指向 GitHub 443 端口连接超时，后面的 expected 'packfile' 则是 Git 没有收到预期仓库数据的后续错误。

与此同时，本机当时能够访问 GitHub，本机到服务器的 SSH 登录也已经打通。接下来的方向就清楚了：利用这条现成的 SSH 连接，把服务器的 GitHub 请求送回本机，再借用本机出口完成访问。把代码拉下来之后，还要把通道的启动、重连和排障方式一起固定下来，才能让远程验证流程在下一次修复中继续复用。

解决方案

让服务器借用本机的可用出口

方案的核心是 SSH 反向 SOCKS 代理 ：由本机主动连接服务器，并让服务器在 127.0.0.1:18080 提供代理入口。服务器上的 Git 将 GitHub HTTPS 请求发给这个入口，请求沿已建立的 SSH 通道回到本机，再由本机访问 GitHub。

图 3 绿色虚线表示本机主动建立 SSH 连接，蓝色箭头表示服务器 Git 请求通过通道借用本机出口。

这里需要分清两个方向：SSH 连接由本机发起，Git 业务请求则从服务器进入通道。本机即使位于家庭网络或 NAT 后面，也无需提供可被服务器主动访问的公网地址。服务器只需允许本机连接 SSH 端口，代理入口保留在服务器回环地址上即可。

OpenSSH 的 -R 在省略目标地址时可以提供反向 SOCKS 代理；-D 则把代理监听在本机，常用于本机借用远端出口。理解这个区别，可以避免搭建了一条方向相反的通道。OpenSSH 官方手册

使用 socks5h:// 时，目标域名交给代理端解析。在本方案中，最终负责解析并建立 GitHub 连接的是本机 SSH 客户端，这也让 GitHub 的域名解析与访问出口保持在同一端。curl 官方代理说明

根据本机网络选择连接方式

"本机能访问 GitHub"也需要进一步区分：如果本机能够直接访问，SSH 自身提供 SOCKS 就够了；如果只有通过 Clash 等本地代理才能访问，则应把那个已有代理的端口转发给服务器。SSH 不会自动继承浏览器代理或 HTTP_PROXY 设置。

本机网络条件	本机 SSH 转发参数	服务器 Git 代理地址
本机直接联网可访问 GitHub	-R 127.0.0.1:18080	socks5h://127.0.0.1:18080
借助本机 HTTP 代理，示例端口为 7890	-R 127.0.0.1:18080:127.0.0.1:7890	http://127.0.0.1:18080
借助本机已有 SOCKS5 代理	-R 127.0.0.1:18080:127.0.0.1:实际端口	socks5h://127.0.0.1:18080

下文按照第一种方式展开，其他方式只需调整转发参数和代理协议。如果选择转发已有代理，本机代理本身也必须在开机后可用，两条通道不要同时占用服务器的同一个监听端口。

这条路径仍然依赖本机在线、本机能够访问 GitHub，以及本机到服务器的 SSH 连接可用。把这些前提明确写进配置和运维说明，才能让临时可用的方案变成可复用的实践。

实践与验证

第一步 先确认两端连接条件

落地之前，先分别测试本机和服务器。这样可以把"无法访问 GitHub"拆成几个具体问题，避免一开始就调整 Git 参数，却没有检查真正发生超时的链路。

# 在服务器执行
getent ahostsv4 github.com
curl -I --connect-timeout 8 --max-time 20 https://github.com
timeout 30 git ls-remote \
  https://github.com/beacon-observability/beacon-java.git HEAD

# 在本机执行
curl -I --connect-timeout 8 --max-time 20 https://github.com
git ls-remote https://github.com/beacon-observability/beacon-java.git HEAD

DNS 有结果只说明取得了 IP，HTTP 响应成功也不能证明大仓库传输稳定。只有确认本机出口可用，借用它才有实际意义；如果本机自身也连接超时，应先处理本机网络。

第二步 准备可非交互使用的 SSH 登录

在本机 ~/.ssh/config 中增加或合并以下配置，保留已有内容。203.0.113.10 是文档示例地址，deploy 是示例登录用户，部署前替换成实际服务器地址和已有账号：

Host volce-test
    HostName 203.0.113.10
    User deploy
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

将对应公钥加入服务器账号的 authorized_keys，已经配置免密登录时可跳过。首次连接应通过云控制台等可信渠道核对主机指纹，再保存到 known_hosts。

ssh-copy-id -i ~/.ssh/id_ed25519.pub volce-test

ssh -o BatchMode=yes \
    -o IdentityAgent=none \
    -o StrictHostKeyChecking=yes \
    volce-test 'id -un'

第二条命令很重要：它验证登录不依赖当前桌面已经解锁的 SSH agent。交互式登录成功，并不意味着开机时的后台服务也能成功。如果这里失败，应检查私钥路径、权限和口令加载方式。长期使用可为代理配置专用密钥和受限账号，私钥只保存在本机。

本次实测使用 OpenSSH 9.6p1。复用到旧系统时，先确认客户端支持不带目标地址的反向 SOCKS 模式。

第三步 建立通道并配置 Git

先在本机以前台方式启动临时通道，保持终端运行。此时优先验证连通性，暂不引入后台管理，出现问题时更容易观察 SSH 的错误输出。

ssh -NT \
  -o BatchMode=yes \
  -o StrictHostKeyChecking=yes \
  -o ExitOnForwardFailure=yes \
  -o ServerAliveInterval=30 \
  -o ServerAliveCountMax=3 \
  -R 127.0.0.1:18080 \
  volce-test

-N 表示只转发连接，-T 表示不分配终端；ExitOnForwardFailure=yes 让监听失败立即暴露出来，便于发现端口冲突。然后登录服务器，检查代理端口及 GitHub HTTPS 请求：

# 在服务器执行
ss -ltn | awk '$4 ~ /:18080$/ {print}'

curl --proxy socks5h://127.0.0.1:18080 \
  --connect-timeout 8 --max-time 30 \
  -I https://github.com

确认代理只监听 127.0.0.1:18080，且获得正常 HTTP 响应后，以服务器上实际执行 Git 的用户配置 GitHub 专用代理：

git config --global \
  http.https://github.com/.proxy \
  socks5h://127.0.0.1:18080

git config --get-urlmatch http.proxy \
  https://github.com/beacon-observability/beacon-java.git

git clone https://github.com/beacon-observability/beacon-java.git

按 URL 匹配代理，使这项设置集中作用于当前用户的 GitHub HTTPS 请求。切换账号、使用 sudo git 或进入容器后，Git 配置与回环地址所在环境可能不同，需要分别检查。Git 官方配置说明

如果本机依赖一个监听在 127.0.0.1:7890 的 HTTP 代理，先确认本机通过它访问 GitHub 正常，再改用下面的组合，端口按实际配置替换：

# 在本机执行，先结束原来的临时通道
ssh -NT -o ExitOnForwardFailure=yes \
  -R 127.0.0.1:18080:127.0.0.1:7890 volce-test

# 在服务器执行
git config --global \
  http.https://github.com/.proxy \
  http://127.0.0.1:18080

这一步完成后，GitHub HTTPS 的 clone、fetch 和 pull 就有了明确的访问路径。浏览器、Gradle、Maven、GitHub SSH URL，以及 Git LFS 或 Release 下载的其他端点不会因此全部自动生效，应按实际工具和域名单独配置。私有仓库也仍需正常认证。

第四步 固定启动方式和重连策略

临时通道能跑通之后，下一步是解决"下次开机还要不要再操作一遍"。把通道交给 systemd 管理，可以固定启动参数、统一查看日志，并在 SSH 进程退出后重新尝试连接。

先在本机临时通道所在终端按 Ctrl+C，释放服务器的代理端口，然后创建 ~/.config/systemd/user/volce-github-proxy.service：

[Unit]
Description=GitHub SOCKS proxy for test server over SSH
StartLimitIntervalSec=0

[Service]
Type=simple
ExecStart=/usr/bin/ssh -NT -M -S %h/.ssh/volce-github-proxy.sock -o BatchMode=yes -o IdentityAgent=none -o StrictHostKeyChecking=yes -o ExitOnForwardFailure=yes -o ConnectTimeout=15 -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -R 127.0.0.1:18080 volce-test
Restart=always
RestartSec=10
TimeoutStopSec=15
UMask=0077

[Install]
WantedBy=default.target

如果选择转发本机已有代理，替换 ExecStart 中的 -R 参数，并保持服务器 Git 的代理协议与本机代理一致。systemd 管理前台 SSH 进程，因此这里不加入 -f。Restart=always 在进程退出后重启，RestartSec=10 设置重试间隔；取消启动频率限制可允许开机暂未联网时持续重试。systemd 官方服务文档

# 在本机以普通用户执行
systemd-analyze --user verify \
  ~/.config/systemd/user/volce-github-proxy.service
systemctl --user daemon-reload
systemctl --user enable --now volce-github-proxy.service

# 开启并检查无需登录即可运行用户服务
sudo loginctl enable-linger "$(id -un)"
loginctl show-user "$(id -un)" -p Linger

预期为 Linger=yes。linger 使该用户的管理器在开机时启动，并在退出登录后继续运行。systemd 官方 linger 说明

主目录和私钥还必须在开机时可读取。若主目录需要登录后解密，或私钥需要人工解锁，应先解决无人值守加载方式。SSH 保活连续没有响应时，当前参数大约需要 90 秒发现异常，再进入重启流程；已失败的 Git 操作仍需重新执行。OpenSSH 保活说明

第五步 从进程状态验证到完整克隆

后台服务显示 active 是一个起点，却不是业务验收结果。我们真正需要的是代码能够完整到达服务器，因此验证要沿着实际请求路径往下走。

图 4 依次验证 SSH 通道、代理端口、GitHub HTTPS 和 Git 仓库传输，先定位失败层，再调整对应配置。

# 在本机执行
systemctl --user is-enabled volce-github-proxy.service
systemctl --user is-active volce-github-proxy.service
ssh -S ~/.ssh/volce-github-proxy.sock -O check volce-test

# 在服务器执行
git ls-remote \
  https://github.com/beacon-observability/beacon-java.git HEAD

git -C beacon-java remote get-url origin
git -C beacon-java status --short
git -C beacon-java rev-parse --is-shallow-repository

完整克隆在未使用 --depth 时应返回 false。如果只需要最新代码，可用 --depth 1 减少下载量，但它保留的历史范围不同。验证自动重启应避开传输时段：在本机结束服务主进程，等待重连后检查 PID 和重启计数，并再次验证 GitHub 访问。

systemctl --user kill \
  --kill-whom=main --signal=SIGTERM \
  volce-github-proxy.service

# 等待重连后检查
systemctl --user show volce-github-proxy.service \
  -p MainPID -p NRestarts -p ActiveState

本次于 2026 年 10 月 15 日完成的验收结果包括：服务器通过代理访问 GitHub 成功；beacon-observability/beacon-java 完整克隆到 /root/beacon/beacon-java，分支为 main，当时提交为 9f8193c170，工作区干净且非浅克隆；用户服务已启用，Linger=yes；结束 SSH 主进程后服务自动重启，重连后再次取得 GitHub HTTP 200。

这些结果分别覆盖了代码可获取、服务可管理和进程退出后可恢复。真实断网还要经历保活超时与网络恢复过程，因此自动重启也不等于对所有网络异常都能立即恢复。

第六步 把排障与退出方式一起留下

日常运维中，最有价值的往往不是更多参数，而是知道下一步该查哪里。当连接再次波动时，先从链路和日志入手，比同时修改 DNS、Git 和 SSH 配置更容易形成清晰结论。

现象	优先检查	处理方向
SSH 端口连接超时	本机到服务器的网络与 SSH 服务	先恢复 SSH 连接
公钥登录失败或开机失败	私钥路径、权限、agent 依赖和 linger	按服务的非交互参数重测登录
remote port forwarding failed	端口占用和账号转发权限	停止旧通道或检查所需远程转发权限
服务 active 但 GitHub 超时	本机到 GitHub 的网络和 DNS	在本机直接测试，或检查原有本地代理
curl 成功但 Git 失败	URL、运行用户、代理匹配和仓库认证	先检查首条错误与 get-urlmatch 结果
主机密钥校验失败	主机重装或密钥变化	核实指纹后更新 known_hosts

# 在本机管理服务与查看日志
systemctl --user status --no-pager volce-github-proxy.service
journalctl --user -u volce-github-proxy.service -n 50 --no-pager
systemctl --user restart volce-github-proxy.service

本次环境另有 ~/.local/bin/volce-github-proxy 便利脚本，支持 status、logs、restart 等操作；其他环境使用 systemctl 即可。连接超时应先处理链路，增大 http.postBuffer 不能解决 TCP 443 连接失败，关闭 TLS 或主机密钥校验也不应作为修复方法。克隆失败留下的目录应先检查，再使用新目标目录重试。

恢复直连时，先在服务器上用原来配置 Git 的用户取消代理，再在本机停用服务。这样可以避免 Git 继续连接一个已经停止的代理端口：

# 在服务器执行
git config --global --unset-all http.https://github.com/.proxy

# 在本机执行
systemctl --user disable --now volce-github-proxy.service

总结

这次实践把一个容易被当成偶发问题的 GitHub 连接超时，转化成了一条可以解释、管理和验证的访问路径：本机提供可用出口，SSH 负责传输通道，Git 按域名选择代理，systemd 管理启动和重连。每个环节的职责明确，后续复用和交接也更容易。

从智能体辅助开发的角度看，这套实践服务于一个更完整的工作分工：本机负责交互和决策，服务器负责资源密集的执行与验证，SSH 通道补齐服务器取得代码所需的网络条件。这样，构建、测试和打包可以在独立环境中持续进行，开发者也能在本机保持阅读、分析和评审的工作节奏。

它带来的价值既包括让环境准备继续推进，也包括把重复性的操作沉淀下来。对于问题修复、项目联调和演示准备，把"哪些任务放到服务器、代码怎样取得、验证结果怎样返回、失败时怎样检查"一起记录，比只保留一条成功过的命令更便于复用和交接。

使用时仍要控制范围：代理只监听回环地址，保留 SSH 与 HTTPS 校验；服务器上的其他本地进程仍可能访问这个端口。SSH 自带的反向 SOCKS 可用 PermitRemoteOpen=github.com:443 限制目标；若转发的是已有 HTTP 或 SOCKS 代理，则应在原代理中控制目标访问范围。OpenSSH 目标限制说明

这套配置适合开发和测试场景。需要全天候、不依赖个人电脑的持续构建时，应把出口放到稳定在线且能访问 GitHub 的受管网络节点，并对依赖下载采用适当的缓存。