treg 本地代理实战:一段没有 Key 的代码,如何被团队凭据悄悄喂饱
treg 本地代理实战:一段没有 Key 的代码,如何被团队凭据悄悄喂饱
导读:treg 的本地代理(local proxy)解决了"程序自己直连第三方 API"这一最隐蔽的接入场景——当一个脚本直接向 api.openai.com、api.stripe.com 发出 HTTPS 请求时,它既没有 key,也从未听说过 treg。本指南以 examples/proxy-demo 中的最小演示为核心,讲解如何用 treg node server.js 让同一份代码在服务端获得团队凭据注入,同时剖析 本地代理源码 的拦截、盲隧道与证书机制,帮你掌握"无需改一行代码即可为任意 HTTP 客户端注入凭据"的完整实战方案。
演示要旨:代码不变,凭据来自父进程
examples/proxy-demo/ 是一个故意做得极小的 web 应用:它会调用一个它没有 key 的真实 API。整个演示的核心主张可以用三句话概括:
server.js从头到尾没有提到过 treg;- 它不读取任何 secret;
- 它零依赖(只用 Node 内置模块)。
凭据之所以会出现,仅仅因为 treg 是它的父进程。这就是本地代理与 treg call、/call/ URL 等其它入口的本质区别——那些入口要求调用方"知道 treg";而本地代理在程序发起外呼的路上把它拦下来,让服务端去添加凭据。仓库架构文档 docs/context/architecture/local-proxy.md 对此有专门论述,源码实现集中在 src/treg/localproxy.py。
一分钟跑起来
在仓库的 examples/proxy-demo/ 目录下,用两种方式运行完全相同的代码:
node server.js # plain: the call goes out as-is
treg node server.js # the same code, credentialed by your team
打开 http://localhost:3000,点击 Call api.openai.com 按钮,两次运行的差异一目了然:
| 运行方式 | OpenAI 的答复 |
|---|---|
node server.js |
401 — Missing bearer authentication in header。没有 key,调用失败。 |
treg node server.js |
200 和真实的模型列表。treg 在服务端注入了你团队的 key。 |
页面顶部还有一个模式指示条:/mode 端点会返回 viaTreg 布尔值(实际逻辑是检测 HTTPS_PROXY/https_proxy 环境变量是否存在,见 server.js 第 235-238 行),告诉你当前这次运行是否处于 treg 保护之下。
前置条件:需要 api.openai.com 工具已在你的活跃团队中注册(可用 treg tool ls 确认)。任何已注册的主机都可以——直接编辑 server.js 顶部的 TARGETS 常量即可切换目标:
const TARGETS = {
openai: { url: "https://api.openai.com/v1/models", label: "api.openai.com", note: "registered with your team" },
example: { url: "https://example.com/", note: "not registered — goes straight out", label: "example.com" },
};
第二个按钮:两半承诺的另一半
演示页面上还有第二个按钮 Call example.com。example.com 是一个未注册的主机。它的结果无论哪种运行方式都是 200——因为一个 treg 不认识的地址会被原样隧道转发(blind tunnel),字节被复制但永不被解密,也不会为它签发任何证书。
这就是本地代理的两半承诺:
- 注册的主机 → 被拦截,TLS 终止于本地代理签发的叶证书,明文请求被重新寻址到 treg 的
/call/通道,凭据在服务端注入; - 未注册的主机 → 盲隧道直通,treg 看不见内容,也因此不可能读到程序自己的
api.anthropic.com之类的私有流量。
在 src/treg/localproxy.py 中,这由 ProxyConfig.intercepts(host) 决定:只有主机在 allow-list(来自 GET /tools,且已按成员权限过滤)且具备 CA 且具备 treg token 时才拦截——"终止了 TLS 却没有办法完成这次调用,比不拦截更糟,因为调用方会以一个它看不到原因的方式失败"。演示中的 example.com 走的是 _blind_tunnel 路径,对应测试 tests/test_localproxy.py 中的 test_tunnel_is_byte_faithful 与 test_tunnel_generates_no_certificate。
一个诚实的褶皱:Node 与代理
演示 README 明确指出了 Node 的一个历史问题:Node 内置的 fetch 会忽略 HTTPS_PROXY,直到 Node 24。在 Node 24 上,treg 设置的环境变量 NODE_USE_ENV_PROXY=1 会开启对代理变量的支持;而在 Node 23 及更早版本上,普通的 fetch() 会径直绕过代理,导致即使在 treg 下运行也得到同样的 401。
因此这个演示选择显式地对代理说话——先发 CONNECT,再在隧道之上跑 TLS——也就是 throughProxy() 函数,约 30 行,写出来只是为了让演示在任何 Node 版本上都能跑。它的实现要点(见 server.js 第 36-100 行):
- 解析代理 URL,用其中的用户名(
treg)与随机会话 token 构造Proxy-Authorization: Basic ...头; - 发起
CONNECT target-host:443; - 对 407 响应给出明确提示(
HTTPS_PROXY可能是早前会话残留,用eval "$(treg serve env --unset)"清除); - 对
ECONNREFUSED同样给出可操作的指引——这是最常见且最令人困惑的失败:变量指向一个已停掉的代理; - CONNECT 成功后,用
SSL_CERT_FILE或NODE_EXTRA_CA_CERTS指向的信任包建立 TLS 连接(这正是 treg 给我们的 bundle:系统根 + treg 本地 CA),再手写 HTTP/1.1 请求; - 由于是手写 HTTP,还需要一个
unchunk()函数手动解开 chunked 传输编码。
真实应用完全不需要这些。所有常见的 HTTP 客户端都已经会读环境变量:axios、got、undici 的 ProxyAgent、python-requests、httpx、curl、git。在 Node 24+ 上,fetch 也可以。检查方法:
node --version # 24 or newer → plain fetch() is captured
从源码看本地代理如何工作
演示背后的完整机制在 src/treg/localproxy.py(本地捕获端)与 src/treg/infra/upstream/relay.py(服务端注入端)之间协作完成。架构文档 docs/context/architecture/local-proxy.md 给出了整体链路:
a program that has never heard of treg
│ HTTPS_PROXY=http://treg:<session-token>@127.0.0.1:<port>
▼
local proxy (src/treg/localproxy.py)
│
├─ host NOT registered ──► blind tunnel. Bytes copied, never decrypted
│
└─ host IS registered ──► terminate TLS with a leaf we sign
re-address it, keeping method/path/query/body
│
▼
treg server POST /call/https://api.stripe.com/v1/charges
+ X-Treg-Token / X-Treg-Org / X-Treg-Client
│ relay() injects the credential
▼
api.stripe.com
│
◄─────────────── response streamed back, unchanged ──────────────────┘
关键点:本地代理携带的只有成员的 treg token,任何厂商 key 都不会落到这台机器上。因为被拦截的调用最终落在普通的 /call/ 路径上,已经建好的每成员工具列表、项目作用域、deny 规则、每日配额、审计记录、OAuth 刷新全部复用,无需第二套策略引擎——这正是这个模块能保持小巧的原因。
三个入口,同一个引擎
本地代理共有三种启动方式,由 src/treg/cli.py 的 cmd_with、cmd_shell_start、cmd_serve_start 分别实现:
| 入口 | 生效范围 | 适用场景 |
|---|---|---|
treg <command>(即 treg with <command>) |
该进程及其子进程 | 常规场景——treg claude、treg node app.js |
treg shell start --proxy |
一个子 shell | 希望团队 CLI 与裸调用在同一个会话内都生效 |
treg serve(配合 eval "$(treg serve env)") |
任何主动 opt-in 的终端 | 希望跨终端长期运行 |
treg <command> 是主打入口:treg 成为被启动进程的父进程,环境变量只到达该进程——treg claude 使用团队访问权限,而普通的 claude 不受影响、仍用成员自己的 key。而且不写任何配置文件,因此无需"撤销"任何东西。main() 通过 _looks_like_a_program() 实现这一短路:当第一个词(在 with 自己的 -q/--quiet 标志之后)不是 treg 子命令且存在于 PATH 上时,自动改写为 with <command>(src/treg/cli.py 第 6416-6431 行)。两个条件缺一不可:没有前者,一个恰好叫 call 的二进制会遮蔽 treg call;没有后者,treg toool ls 这种拼写错误会变成一次令人困惑的 exec 尝试而不是普通的参数错误。
cmd_with 的行为:如果已有 treg serve 守护进程在运行,就挂载到它上面并保持其运行;否则在端口 0 上启动一个私有代理——操作系统自动分配端口,并行会话永不冲突——并在命令退出时于 finally 中停止它。子进程通过 shell._run_subshell 运行,忽略 SIGINT/SIGQUIT 以便交互式 Agent 拥有终端,且子进程的退出码会成为 treg 的退出码。
环境变量:把进程指向我们并让它信任我们
proxy_env()(src/treg/localproxy.py 第 327-362 行)返回一组变量,其中两个是"能用"与"神秘地毫无反应"的分水岭:
NODE_USE_ENV_PROXY=1——Node 18 起内置fetch静默忽略HTTPS_PROXY,没有这个标志,所有 Node Agent 都会径直绕过代理,让整个功能看起来时好时坏;NO_PROXY——回环地址和 registry 主机本身绝不能经由我们回流,否则代理对 treg 的调用会绕回代理自己。
其余变量(HTTPS_PROXY/HTTP_PROXY 的大小写两种形式——curl 读小写、多数工具读大写)以及信任包的多重出口:NODE_EXTRA_CA_CERTS、SSL_CERT_FILE、REQUESTS_CA_BUNDLE、CURL_CA_BUNDLE、GIT_SSL_CAINFO、DENO_CERT、AWS_CA_BUNDLE。这保证了 Node、Python、curl、git、Deno、AWS CLI 都能验证本地 CA。代理 URL 形如 http://treg:<随机token>@127.0.0.1:<port>,token 由 mint_token() 用 secrets.token_urlsafe(24) 生成,防止本机其它进程借道消耗成员配额。
证书:每台机器一个 CA,系统信任库永不动
ensure_ca() 在首次使用时按机器生成 CA:ECDSA P-256、两年期、自签名、BasicConstraints(ca=True)。私有密钥文件以 0600 权限创建——而且是"先以 0600 打开再写入",避免"先写后 chmod"窗口期里私钥世界可读(源码注释明确说明了这一点)。当证书文件不可读或处于最后 30 天(_RENEW_WITHIN_DAYS)内时自动重新生成,这样过期永远不会以"莫名其妙的 TLS 错误"形式出现在会话中途。
build_bundle() 写入 系统根 + 我们自己的 CA(追加次序是重点:SSL_CERT_FILE 等变量是替换信任列表,若 bundle 里只有我们的 CA,调用方将无法验证真实互联网)。叶证书按需签发、按主机缓存为 ssl.SSLContext,因为 Python 的 load_cert_chain 只读文件,叶证书被写入一个 0600 临时文件、加载完成即刻删除(context_for(),src/treg/localproxy.py 第 182-209 行)。
系统信任库永远不会被触碰。信任通过环境变量限定作用域,因此只有被启动的进程树信任我们——不是浏览器,不是操作系统。
allow-list:继承成员权限的拦截清单
ProxyConfig.hosts 来自 GET /tools,而该接口已经按"此成员可用什么"过滤过,所以 allow-list 免费继承了每成员工具列表与项目作用域——一个成员用不了的主机,甚至不会被解密。两个失败模式被刻意处理(见架构文档与源码 docstring):抓取失败返回空集("没有答复"绝不能被解读为"拦截一切"),且刷新器绝不用空答案覆盖正在工作的列表——否则会在调用继续外发时静默停止注入。treg shell --proxy 与 treg <command> 两个入口都用已抓取的工具清单做种子,因此开启代理不产生额外请求。
服务端:一次调用、一个 /call/ 路径
被拦截的请求被重新寻址为 POST /call/<原URL>(URL-passthrough 形态),并携带 X-Treg-Token、X-Treg-Org、X-Treg-Client 控制头。服务端由 relay() 注入凭据(src/treg/infra/upstream/relay.py)。忠实中继契约只改动三样东西:hop-by-hop 传输头、treg 控制头、注入的凭据;方法、路径、全部查询参数(含重复项)、请求头、Cookie、body 字节一律原样转发。注入发生在多个绑定上——每个绑定只覆盖它指定的目标头/查询参数/顶层 JSON 字段。这意味着:拦截后的调用与 treg call 走完全相同的策略链(成员工具列表、项目作用域、deny 规则、每日配额、审计、OAuth 刷新),这就是"没有第二套策略引擎"的具体含义。
安全不变量:每一条对应一个会出的事故
架构文档 docs/context/architecture/local-proxy.md 以对照表形式列出了安全不变量,每条都对应一种具体事故形态:
| # | 不变量 | 它防止什么 |
|---|---|---|
| 1 | CA 私钥每机器一份、0600、永不外发 | 共享 CA 会让任何持有者向所有用户冒充任意站点 |
| 2 | 永不触碰系统信任库 | 拦截会蔓延到浏览器和整个操作系统,而非仅限被启动的进程 |
| 3 | 仅 allow-list 拦截 | 读到调用方自己的 api.anthropic.com / api.openai.com 流量 |
| 4 | 仅绑定 127.0.0.1(LISTEN_HOST) |
网络上任何人消耗成员的配额 |
| 5 | 随机会话 token + 禁止调用方伪造控制头 | 本机其它进程、或调用方自己的头,冒名顶替 |
| 6 | treg_client 使用 trust_env=False |
httpx 会读自己环境里的 HTTPS_PROXY——第一次调用就会绕回我们自己 |
| 7 | 日志只记主机与状态 | body、请求头或 token 出现在日志文件 |
其中第 6 条尤其微妙:代理自己的出站 HTTP 客户端如果信任环境变量,那么 HTTPS_PROXY 会让它的第一次调用循环回代理自身。因此它显式关闭了 trust_env。
测试如何证明这一切
tests/test_localproxy.py 覆盖了单元与集成两级、全程无网络依赖。值得知道的几条:
test_tunnel_is_byte_faithful/test_tunnel_generates_no_certificate——未注册主机字节原样转发、且永不为它生成叶证书(不变量 3);test_a_real_client_trusts_a_leaf_signed_by_our_ca与test_a_client_trusting_only_the_system_roots_rejects_our_leaf——真实 TLS 握手既验证我们签发的叶被信任、也验证只信任系统根的客户端会拒绝它(不变量 2);test_the_caller_cannot_speak_as_someone_else——调用方无法伪造x-treg-*头;test_ensure_ca_writes_a_private_key_only_the_owner_can_read、test_an_expiring_ca_is_regenerated、test_a_corrupt_ca_does_not_brick_the_proxy——证书生命周期与容错;test_proxy_env_carries_the_flags_that_matter——环境变量的关键标志位;- 端到端测试
test_the_agent_calls_the_vendor_and_treg_injects_the_key驱动一个普通的httpx.Client穿过代理直连真实的 FastAPI 应用——这正是演示页面背后那条链路的自动化版本。
treg serve 的守护进程形态由 write_state 在 ~/.treg/proxy/proxy.json(0600、先建权后写入)记录端口/pid/token/registry/捕获主机;running() 会在 pid 已死时把状态文件视为"未运行"并删除,否则 status 会永远声称代理在运行、start 也会拒绝替换一个已死的守护进程。pid_alive 在调用 os.kill 前拒绝非正 pid——因为 os.kill(0, …) 会向调用方的整个进程组发信号。
已知限制(值得先知道)
- 证书固定(pinning):只接受自己证书的客户端会拒绝我们的叶证书。它只会单独失败,需要一张"永不可拦截主机"清单(尚未构建)。
- 远程 MCP 服务器不在覆盖范围:托管型 MCP 从别人机器发起调用;本地 stdio 型 MCP 继承环境、会被捕获。
- 非 HTTPS 协议不覆盖:SSH、数据库线协议;WebSocket 被隧道化而非拦截。
- 每次被拦截的调用都多一跳 treg 往返,treg 宕机即失败——这是"key 永不落地"的代价。
- 部分厂商 CLI 仍需要
treg run:比如gh在发起任何网络调用前就拒绝执行,无内容可拦截。
小结
examples/proxy-demo 用约 30 行显式代理代码 + 一个零依赖的 HTTP 服务器,把 treg 本地代理的核心承诺压缩成了一次点击实验:同一份代码,node 运行即 401,treg node 运行即 200;已注册主机被服务端注入凭据,未注册主机被盲隧道原样直通。理解了这个演示,你就掌握了 treg <command>、treg shell start --proxy、treg serve 三个入口背后的同一台引擎,以及它"凭据只存在于服务端、本机仅持有会话 token"的安全模型。想继续深入,可以依次阅读 本地代理架构文档、代理模型与中继文档、本地运行文档,或直接在 tests/test_localproxy.py 里观看测试如何端到端驱动这条链路。