代理场景：浏览器、Git 与 SSH
本页说明如何将 wssocks-ustb 客户端提供的本地 SOCKS5/HTTP(S) 监听端口接入浏览器、Git 和 SSH，覆盖应用级代理、命令行代理与协议选择。文档中的地址、端口和参数均来自仓库内的中文使用文档。
Purpose and Scope
本页聚焦“客户端已经启动后，具体应用如何通过本地代理访问校内浏览器站点、Git 服务和 SSH 服务”这一使用场景：
- 浏览器：Firefox 的 SOCKS5 配置、Chromium 系浏览器启动参数，以及 ZeroOmega 应用级规则。
- Git：SSH 协议的
ProxyCommand、HTTP/HTTPS 协议的 Git proxy 配置，以及 Git LFS 使用 HTTP(S) 代理的方式。 - SSH：macOS、Windows Git Bash 和其他 SSH 客户端如何指向 SOCKS5 监听端口。
- 端口语义：默认 SOCKS5 监听端口、可选 HTTP 监听端口，以及它们和客户端参数的对应关系。
本页不展开服务端部署、VPN 登录流程、GUI 界面或 wssocks 核心传输协议实现；这些属于客户端启动/安装和系统架构等相邻主题。若需要先启动客户端，请参阅仓库中的客户端使用说明；若需要了解整体网络拓扑，请参阅 tech-overview.md。
Overview
wssocks-ustb 客户端在本机提供代理入口，应用只需要把代理服务器设置为该入口即可。仓库文档明确区分两类入口：默认 SOCKS5 地址（示例为 127.0.0.1:1080），以及通过 --http 开启的 HTTP/HTTPS 代理地址（--http-addr 默认 :1086）。SOCKS5 更适合 SSH、需要 SOCKS5 的浏览器配置和 Git SSH；HTTP/HTTPS 更适合 Git 的 HTTP(S) URL、Git LFS 和系统 HTTP 代理。
一个典型链路是：应用产生目标主机和端口 → 本地代理入口接收连接 → wssocks 客户端通过 --remote 指定的服务器转发 → 目标校内服务。浏览器通常只需代理规则；SSH 和 Git SSH 则需要显式地把连接命令包装到 ProxyCommand 中。
Architecture
图中的 Socks5 与 HttpProxy 是客户端暴露给本机应用的两个不同协议入口，不代表两个独立的远端服务。文档说明默认本地监听为 :1080，启用 --http 后由 --http-addr 指定 HTTP 代理端口，默认 :1086；应用侧必须使用与协议匹配的入口。所有入口最终都由 wssocks-ustb client 通过 --remote 连接到服务端。
端口与协议选择
| 使用对象 | 推荐入口 | 仓库中的典型地址 | 关键原因 |
|---|---|---|---|
| Firefox / Chromium 浏览器 SOCKS5 规则 | SOCKS5 | 127.0.0.1:1080 | 浏览器直接以 SOCKS5 连接本地客户端 |
SSH ProxyCommand | SOCKS5 | 127.0.0.1:1080 | nc -x 或 connect -S 负责建立 SOCKS5 通道 |
| Git SSH URL | SOCKS5 | 127.0.0.1:1080 | Git 复用 SSH 的 ProxyCommand |
| Git HTTP/HTTPS URL | HTTP proxy 或 SOCKS5 | HTTP 示例 127.0.0.1:1080；通用示例也使用 socks5://127.0.0.1:1080 | Git 的 http.*.proxy 决定代理协议 |
| Git LFS | HTTP/HTTPS | 文档示例 http://127.0.0.1:1080 与 http://127.0.0.1:1086 | LFS 数据通过 HTTP/HTTPS 传输，需要客户端启用 HTTP(S) 代理 |
仓库不同文档中的示例端口取决于具体启动参数：README.md 将 HTTP 端口默认描述为 :1086，而 git.md 的 Git HTTP 代理示例使用 127.0.0.1:1080。因此不要把示例端口当作固定协议事实；应以当前 wssocks-ustb client 的 --addr 和 --http-addr 配置为准，并保证 Git 配置中的代理协议与监听端口一致。
客户端启动前提
客户端启动示例开启了 HTTP 代理并指定远端；未显式指定 --addr 时，文档说明 SOCKS5 默认监听 :1080：
wssocks-ustb client --remote=ws://proxy.gensh.me --http -http-addr=:1086 --vpn-enable --vpn-host=n.ustb.edu.cn --vpn-force-logout --vpn-host-encryptSource: README.md
其中 --remote 指向服务端，--http 开启 HTTP/HTTPS 代理，--http-addr 指定 HTTP 代理监听地址；--vpn-* 参数属于 VPN 登录/插件能力，只有启用 VPN 模式时才有意义。若只使用 SOCKS5 场景，可以根据实际客户端参数不启用 HTTP 入口，但本页涉及 Git HTTP(S) 或 Git LFS 时必须确认 HTTP(S) 代理已开启。
浏览器代理
Firefox
Firefox 可以在浏览器自身的网络设置中启用 SOCKS5。该方式是应用级配置，只影响 Firefox，不会自动改变其他应用的网络路径。配置时将 SOCKS5 服务器填写为客户端实际的 socks5 address，仓库示例使用 127.0.0.1:1080。
Chrome、新版 Edge 与 ZeroOmega
Chromium 系浏览器可以使用命令行参数启动独立的代理实例。仓库示例同时设置 --proxy-server 和 --host-resolver-rules：前者让浏览器使用 SOCKS5，后者将域名解析行为映射到 0.0.0.0，并排除 localhost。这意味着启动参数不只是“填一个代理地址”，还明确改变了浏览器的主机解析规则；复制命令时应保留两个参数。
1# chrome on macOS
2/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --show-app-list --proxy-server="socks5://127.0.0.1:1080" --host-resolver-rules="MAP * 0.0.0.0 , EXCLUDE localhost"
3
4# new Edge on macOS
5/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge --show-app-list --proxy-server="socks5://127.0.0.1:1080" --host-resolver-rules="MAP * 0.0.0.0 , EXCLUDE localhost"Source: broswer.md
对于日常切换代理，仓库推荐基于 ZeroOmega 的浏览器扩展。其配置核心是选择 SOCKS5 协议，并将代理服务器和端口设置为 wssocks 客户端的 SOCKS5 地址；这比每次重启浏览器更适合在直连与代理之间切换。ZeroOmega 的安装渠道和扩展版本信息见浏览器文档中的链接。
Sources: broswer.md, broswer.md
浏览器边界与排错
- 浏览器代理是应用级还是系统级，取决于配置位置；Firefox 的设置只影响 Firefox，ZeroOmega 只影响安装并启用该扩展规则的浏览器实例。
127.0.0.1:1080只是文档示例。若启动时修改了--addr，浏览器必须同步修改。- Chromium 命令中的 Windows、macOS 可执行文件路径不同；文档没有给出 Linux 启动命令，因此不能从仓库内容推导 Linux 的具体路径。
- 若浏览器无法访问而 SSH 正常，应优先检查扩展规则/浏览器启动参数和本地 SOCKS5 地址，而不是修改 SSH 配置。
SSH 代理
SSH 的关键是让 SSH 客户端把“连接目标主机和端口”的动作交给 SOCKS5 工具。macOS 使用 nc -x，Windows Git Bash 使用 connect -S；%h 和 %p 是 SSH 传给 ProxyCommand 的目标主机和目标端口占位符。
1# macOS
2ssh -o ProxyCommand='nc -x 127.0.0.1:1080 %h %p' user@ssh.hpcer.dev
3
4# Windows Git Bash
5ssh -o ProxyCommand='connect -S 127.0.0.1:1080 %h %p' user@ssh.hpcer.devSource: ssh.md
Windows 文档特别提示，部分环境中应为 connect.exe 使用完整绝对路径；因此如果命令格式正确但连接失败，不能只检查 SOCKS5 地址，也要检查 connect.exe 是否可被当前 Git Bash 找到。其他 shell 客户端则需要在其连接配置中选择 SOCKS5，并填入同一个客户端 SOCKS5 地址。
Core Flow
该顺序解释了为什么应用端配置必须先于访问生效：代理设置只负责把本地连接交给客户端，远端连通性仍取决于 --remote 服务端、目标地址、服务端端口和网络环境。仓库文档没有描述 wssocks 内部重试、连接池或并发调度实现，因此本页不对这些内部行为作推断。