XiaDown网络出口契约揭秘:一个loopback网关如何统一管理全部出站流量
XiaDown网络出口契约揭秘:一个loopback网关如何统一管理全部出站流量
XiaDown(下蛋)是一款支持视频下载的资源库管理应用,集视频下载、嗅探下载、YouTube Music 与 RSS 客户端于一体。当它同时管理着后端 API 请求、媒体流、yt-dlp 子进程、managed Chromium 嗅探浏览器和 RSS 资源时,如何保证"改一次代理,处处生效"?答案藏在它的**网络出口契约(Network Egress Contract)**里:一个进程生命期的 loopback 网关,统一管理全部出站流量。
为什么需要统一全部出站流量 🧭
一个下载类应用内部的网络出口远比想象中多:
- Go 后端的 HTTP 客户端(API、歌词、元数据)
- 远程图片、头像、封面
- RSS 订阅、文章与媒体预览
- yt-dlp / ffmpeg 及其所有子进程
- managed Chromium/CDP 嗅探会话
- 遥测、通知、软件更新、依赖下载
如果每个组件各自为政,就会出现"有的走代理、有的直连"的混乱局面:用户切换网络模式时行为不可预测,代理凭据可能泄漏进子进程命令行和日志。XiaDown 的选择是:所有 App 管理的网络消费者(App-managed network consumer)必须经过同一个策略边界。完整的契约定义见 docs/network-egress-contract.md。
核心架构:一个稳定的 loopback 网关 🌐
契约的基石是一个绑定在 127.0.0.1 临时端口上的 HTTP CONNECT 网关,它从启动到退出地址不变(见 gateway.go#L66-L70):
Settings(代理设置)
└─▶ NetworkPolicy 代际(generation)
└─▶ 路由引擎
├─◀ Go HTTP 客户端(API、图片、歌词、RSS、媒体)
├─◀ yt-dlp / ffmpeg 等辅助子进程
└─◀ managed Chromium / CDP 会话
WKWebView / WebView2 / WebKitGTK ──▶ 平台自身网络策略(明确例外)
关键设计点:
| 机制 | 说明 |
|---|---|
| 仅绑定 loopback | 只监听 127.0.0.1,应用退出即关闭 |
| 进程内地址不变 | 子进程和浏览器始终指向同一个稳定 URL,切换代理无需重启 |
| 硬性资源限制 | 最多 256 个并发连接、64 KiB 请求头、15 秒头部超时(gateway.go#L31-L43) |
| 支持完整协议族 | HTTP、HTTPS CONNECT、WS/WSS、range 请求、HTTP/HTTPS 上游代理、带认证的 SOCKS5 |
也就是说,Go 客户端、yt-dlp、managed Chromium 看到的都是"同一个代理地址",真正的路由决策只发生在网关内部一处。
策略代际(Generation):可热切换的策略快照 🔁
XiaDown 同一时刻只有一份不可变的策略快照 NetworkPolicy,包含模式(none / system / manual)、上游端点、凭据、绕过规则、超时与 failover 策略。每次修改设置,就走一次原子热切换(manager.go#L104-L150):
- 校验并编译完整的候选策略,构建新的路由状态;
- 原子发布新代际,替换管理器持有的客户端句柄;
- 子进程与浏览器模板继续指向同一个网关 URL,此时它已解析到新策略;
- 同步取消旧代际——关闭所有直连/代理 socket、未完成的 CONNECT/认证/TLS 握手、活动隧道;
- 发出一次脱敏的路由变更事件。
这里有两个容易被忽视的语义细节:
none不等于"恢复系统默认",而是"强制直连"。它仍然要经过网关——因为绕过匹配、代际变更、隧道回收全都活在这一个策略边界里(manager.go#L378-L393);- 上游代理失败绝不静默回退直连,除非显式开启 failover。这保证了隐私行为可预期。
路线类别:每类出站流量都有明确身份 🚦
契约把每一个出站表面(surface)都归入一种路线类别,行为随之确定:
| 路线类别 | 典型流量 | 要求行为 |
|---|---|---|
public-internet |
YouTube API、歌词、遥测、更新 | 必须使用当前策略 |
public-untrusted |
RSS 远程资源、用户提交 URL | 策略 + DNS rebinding / SSRF 目的地址防护 |
loopback-internal |
本地媒体资产、WS 实时服务 | 仅直连 App 自有的 loopback 端点 |
local-file-tool |
本地 ffprobe/ffmpeg | 禁止任何网络出站,仅本地协议白名单 |
native-webview-system |
内嵌 WebView 播放 | 走平台自身网络策略,不注入网关 |
安全边界:防止网关被滥用为通用本地代理 🛡️
一个只听 loopback 的网关,天然是"本机任何人都能访问的代理"。XiaDown 用多层防线堵住这个风险:
1. 精确的内部端点注册表。 网关维护一份只含 App 自有 listener 的注册表(internal_loopback.go#L44-L58),拒绝一切未注册的 loopback 目标——包括解析回 127.0.0.1 的域名。这意味着即使配置了上游代理,本地媒体 token 和路径也绝不可能被转发出去;内部端点被强制直连,绕过用户所有 NoProxy 规则。
2. public-untrusted 的本地 DNS 固定。 不可信 URL 在本地解析一次,校验并固定最多 8 个公网 IP 字面量;私网、loopback、link-local、metadata 等特殊地址在连接建立之前就被拒绝,专防 DNS rebinding。
3. 网关路由证明(Attestation)。 网关会在进程内生成一个随机私有域名 <random>.attest.xiadown.invalid,managed Chromium 在加载任何公网页面前,必须先完成一个短生命周期、HMAC 签名的一次性 HTTPS CONNECT 挑战(gateway.go#L231-L259)。它证明的是"浏览器的 HTTP 与 HTTPS 请求确实进入了这个网关"——而非"代理可用",这个语义区分在诊断里被刻意保持。
4. 子进程环境变量治理。 每个受管子进程的环境都会被清洗:HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 全部指向网关,继承的代理变量大小写不敏感地删除,NO_PROXY 被显式清空(manager.go#L309-L334)。更妙的是:若网关不可用,变量会指向保证死掉的 127.0.0.1:1,让失败显性化,而不是"忘记设置变量 → 意外直连"。
5. 凭据永不外泄。 上游代理的用户名密码不出现在浏览器参数、子进程命令行、事件、诊断或日志里;错误信息中的凭据会被替换为 [redacted]。
明确的例外:原生 WebView 走平台网络 🧩
契约特意把 WKWebView、WebView2、WebKitGTK 划为兼容性边界:这些运行时自己选择系统/企业/VPN/PAC 路由,XiaDown 不向其注入内部网关。应用的 none 和 manual 模式只作用于 App 管理的消费者,不影响内嵌播放器的网络路线。
这看似"没管住",实则是有意的取舍:强制劫持 WebView 网络会破坏企业代理、系统认证、PAC 等真实环境行为;XiaDown 保留了对这些 WebView 的导航、弹窗、权限与 cookie 管控,只放开网络路由,并把这一边界写进了能力矩阵与诊断文案。
CI 强制:新增一个出站 API 就会让构建失败 ✅
契约不是文档口号,而是可执行的注册表。network_egress_registry_test.go 记录了生产代码中每一处默认 HTTP 客户端、WebView 构造器、managed Chromium 启动器的出现次数与路线类别。任何人新增一处底层网络 API,如果不在注册表中补上分类与理由,CI 直接失败。
对普通用户意味着什么?💡
回到体验层,这套契约带来三个朴素的好处:
- 改一次代理,全局生效:设置里切换
none/system/manual,无需重启应用,也不丢失 YouTube 会话 cookie; - 诊断可归因:设置页会展示生效的策略来源与代际号,失败信息区分 DNS、直连、本地网关、上游代理认证、TLS 等阶段,而不是笼统的"网络错误";
- 隐私行为确定:失败不回退、凭据不落盘日志、本地资源绝不经过上游代理。
对于一个要同时驱动 API、媒体流、子进程和浏览器的下载应用来说,XiaDown 的网络出口契约给出的答案是:不要信任每个组件都守规矩,而是把整个世界的出站流量收敛到一个可审计的、可热切换的、带身份证明的单一边界上。



