OpenPencil 跨地域协作中继的嵌套 TLS 入口部署指南:Global 边缘到 CN 内网 Federation 全链路解析

原创2026-10-11 16:32:081,401 阅读

OpenPencil 跨地域协作中继的嵌套 TLS 入口部署指南:Global 边缘到 CN 内网 Federation 全链路解析

本文围绕仓库 deploy/collab-relay-edge/ 目录下的生产级部署脚手架展开,讲解如何在境外节点为连接中国境内(CN)协作中继的 OpenPencil 用户搭建一条"内层 TLS 透传 + 外层 mTLS 回程"的双层嵌套 TLS 入口链路。读完本文,你将掌握 Global L4 流代理与私有 CN federation 监听器的部署命令、全部环境变量与证书要求、nftables 新建连接速率门与 systemd 托管方式,以及基于原子 CRL 轮换的边缘证书撤销流程,并理解每一层防护背后的源码级实现依据。

一、场景与问题:为什么海外用户需要一个独立的边缘入口

OpenPencil 的协作中继(relay)通过端到端 Noise 握手和 GET /v1/tunnel WebSocket 隧道为参与者提供实时协作,认证由 CN 侧的 production authenticator 完成,签名 locator 中携带权威的 home_region=cn 归属信息。当使用者位于海外时,直接连接 CN 内网的协作中继会面临跨境网络质量、可达性与部署边界的约束。

deploy/collab-relay-edge/README.md 给出的解决方案,是在境外部署一个 Global L4 流代理(Nginx stream 模块),它只做字节转发,把客户端的内层 TLS 连接原封不动地封装进一条指向 CN 私有 federation 监听器的外层 mTLS 连接中;CN 侧再由 私有 CN federation 监听器 解掉外层 mTLS,把仍然加密的内层 TLS 字节流交给正常的 CN WSS terminator 完成 WebSocket 升级与认证。整套部署遵循"能少看到就少看到"的信任最小化原则。

二、端到端架构:嵌套 TLS 的分层信任边界

README 用如下分层示意描述了完整链路:

client
  └─ inner TLS/WSS (untouched)
       └─ Global Nginx L4 stream proxy
            └─ outer mTLS backhaul
                 └─ private CN federation listener
                      └─ unwrap outer mTLS only
                           └─ normal CN TLS/WSS terminator
                                └─ strict GET /v1/tunnel
                                     └─ CN relay authentication + pairing
                                          └─ end-to-end Noise

各层的信息可见性是这条链路安全设计的核心:

  • Global 流代理:永不终止客户端的内层 TLS,因此无法读取或记录 Authorization 头、签名 locator、bearer capability、WebSocket 头或任何协作帧。它只做四件事:接受客户端内层 TLS 连接、用固定目标建立外层 mTLS、字节级转发、按需丢弃超限连接。
  • CN federation 进程:解开外层 mTLS 之后,看到的仍是一整段未解密的 inner TLS 字节流,依然接触不到 HTTP 升级层。
  • 正常的 CN WSS terminator:唯一能读取 HTTP upgrade 的一层,且必须严格执行 deploy/collab-relay/nginx.conf 中的 location = /v1/tunnel 精确匹配策略,其余路径一律 404。
  • CN production authenticator:最终认证锚点。其源码实现 CollabTicketRelayAuthenticator 在 auth.rs 中持有 expected_home_region: RelayRegion 字段,并以 expected_home_region 构造(production() / new()),配合 RequireRelayChallengeProof(challenge 绑定)与 TicketDhBindingOnly 等 possession policy 完成票证到 DH 的绑定校验。README 明确:签名 locator 的 home_region=cn 始终是权威值,两级流代理既不解析也不改写它;其他 home region 的请求会在 CN authenticator 被拒绝。

三、固定路由与 fail-closed 占位符:先失败,再替换

两个 Nginx 配置文件刻意使用 RFC 5737 TEST-NET 地址作为占位符,任何未替换的占位符都会让链路失败关闭(fail closed),而不是把流量错误地转发到公网地址。

3.1 Global 侧必改项(global-nginx.conf)

  • upstream cn_federation_listener 中的 192.0.2.10:9443(L26-L30):必须替换为恰好一个私有或严格防火墙保护的 CN federation 监听器地址。
  • proxy_ssl_name cn-federation.example.cn(L50):必须替换为 CN 外层 mTLS 服务器证书的真实身份(DNS SAN)。

3.2 CN federation 侧必改项(cn-federation-nginx.conf)

  • upstream cn_inner_wss 中的 192.0.2.20:8444(L29-L34):必须替换为恰好一个私有正常的 CN WSS terminator 专用 federation 监听地址。仓库内 deploy/collab-relay/nginx.conf 已为该监听器配置了 512 连接的聚合上限(limit_conn relay_federation_connections 512)和聚合握手速率(limit_req zone=relay_federation_handshakes burst=500 nodelay,3000r/m);不要把共享的 federation 来源流量送入公共端口 443 的每客户端 8 连接限制(limit_conn relay_connections 8)。

3.3 被明令禁止的路由行为

无论哪一级,都禁止以下做法:使用请求派生变量(request-derived variables)、读取 locator 字段做路由、开放正向代理、动态目标选择、备用 upstream、proxy_next_upstream。原因很直接:独立的 relay 副本之间不共享配对状态,任意的 fallback 可能把 owner 和 guest 送到不同的配对表,导致无法配对。代码层面,validate.sh 会正则检查两个配置文件:proxy_pass $ 动态转发、proxy_next_upstream (on|error|timeout|http_)、include 指令、ssl_preread、proxy_protocol、set_real_ip_from 等模式一旦出现即校验失败(见 L136-L149),同时强制两个 upstream 块各自只允许恰好一条 server 指令(require_single_upstream_server,L27-L55)。

3.4 CN federation 端口的访问控制

CN federation 端口(默认 9443)不是公共 WSS 端点。必须:

  1. 通过 OPENPENCIL_RELAY_CN_FEDERATION_BIND_IP 绑定到私有地址;
  2. 在防火墙层只放行经批准的 Global 出口地址;
  3. 要求 Global 侧持有专用 Global edge client CA 签发的客户端证书,并启用该 CA 的当前 CRL。

外层 mTLS 只认证回程一跳(backhaul hop),永远不能替代以下任何一层安全机制:签名 locator、bearer ticket、票证到 DH 的绑定(ticket-to-DH binding)、逐连接 challenge 绑定的 X25519 PoP v2、以及端到端 Noise。

四、内层 TLS 身份设计:客户端始终直连 CN terminator

这是一个容易被忽视的细节:客户端在整个链路中,无论经过 Global 还是 CN federation 两级字节代理,其 TLS 握手对象始终是正常的 CN WSS terminator。因此:

  • 客户端 wss:// URL 中的主机名必须在该内层证书上是有效的(证书 SAN 覆盖该主机名)。
  • 如果要为海外用户提供专属 DNS 名,应把该名称加入 CN WSS 证书,并把该地址的流量路由到 Global 入口。
  • Global 主机本身不持有任何面向客户端的 TLS 私钥——它没有终止内层 TLS,自然也没有对应私钥,这从根上消除了境外节点窃听协作流量的可能性。

五、Secrets 与容器加固:密钥永不进镜像

5.1 外层 mTLS 材料清单

所有外层 mTLS 材料一律从外部文件挂载,密钥不得出现在 Git、镜像层、环境变量或 Nginx 配置中:

部署侧 需要的材料 Compose secret 目标路径
Global 专用 mTLS 客户端证书/私钥 global-edge-client-cert.pem / global-edge-client-key.pem
Global 窄钉(pinned)的 CN federation 服务器 CA cn-federation-ca.pem
CN federation 外层服务器证书/私钥 cn-federation-server-cert.pem / cn-federation-server-key.pem
CN federation 可信的 Global edge 客户端 CA global-edge-client-ca.pem
CN federation 该 CA 签发的当前完整 PEM CRL global-edge-client-crl.pem

5.2 证书签发要求(EKU 与 SAN)

  • CN federation 服务器证书:使用固定的 federation DNS SAN,EKU 必须包含 serverAuth。
  • 每个 Global 身份:EKU 必须包含 clientAuth,并且由仅用于这些入口客户端的独立 CA 签发。
  • Global 身份之间应独立轮换,互不影响。

5.3 容器运行时加固

两份 Compose 定义(compose.global.yaml 与 compose.cn.yaml)采用一致的加固基线:

  • 以 user: "101:101" 运行(非 root);
  • cap_drop: [ALL] 丢弃全部 capability;
  • security_opt: [no-new-privileges:true];
  • read_only: true 只读根文件系统;
  • 仅暴露一个小的 noexec 的 /tmp(tmpfs: /tmp:rw,noexec,nosuid,nodev,size=16m,uid=101,gid=101,mode=0700);
  • pids_limit: 64、mem_limit: 128m、cpus: 0.50、ulimits nofile 4096;
  • 镜像引用为"独立仓库 + 强制 sha256: 摘要"(@sha256:${OPENPENCIL_RELAY_EDGE_IMAGE_SHA256:?set its reviewed 64-hex digest}),可变 tag 无法满足部署契约;
  • 需要审计过的 Nginx-unprivileged 构建,且必须包含 stream、stream SSL、stream limit-connection 三个模块;
  • healthcheck 使用 nginx -t -q,Global 侧 restart: "no"(L45),CN federation 侧 restart: unless-stopped(L47)。

5.4 Compose file-backed secret 的 inode 陷阱与 CRL 激活语义

README 特别强调两个容易被忽略的机制性事实:

  1. Docker Compose file-backed secrets 本质是 bind mount,不会遵守服务级 uid、gid、mode 元数据。因此在 up 之前,必须手工保证每个挂载文件实际归属于映射到容器 101:101 的宿主 UID/GID 且可读;私钥保持 0400(或经评审的组可读 0440)。
  2. Nginx 在创建 SSL context 时读取 ssl_crl,而 file-backed secret 保持的是挂载时的 inode。因此仅仅替换宿主上的 CRL 文件不会激活新 CRL——必须强制重建(force-recreate)CN federation 容器,让新的 SSL context 打开新的 inode。这正是下一节 CRL 轮换脚本存在的原因。

CRL 轮换辅助脚本(rotate-cn-crl.sh)还额外要求:活动 client CA 与活动 CRL 必须位于 root 所有、非可写的目录中,文件归属 root:101,模式 0440。容器创建完成后,应检查挂载的实际 owner/mode,并以 UID 101 的身份运行 nginx -t;任何读取失败都必须停止部署,不得用 root、追加 capability 或可写根文件系统来绕过。

六、必选 Global IPv4 新建连接速率门:L4 代理之外的主机级防线

L4 stream Nginx 没有 HTTP 请求速率限制器,因此仓库引入了一个独立于容器的主机级 nftables 速率门作为部署前置条件。

6.1 适用范围与前提

  • 当前 Global 监听器只支持一个专用公共 IPv4、固定端口 443(Compose 中 target: 8443 映射到 published: 443,绑定 host_ip: ${OPENPENCIL_RELAY_EDGE_PUBLIC_BIND_IP})。
  • 禁止发布 IPv6,直到存在经评审的 ip6 saddr 计量规则。

6.2 安装与独立验证

export OPENPENCIL_RELAY_EDGE_PUBLIC_BIND_IP='<real-dedicated-public-ipv4>'
sudo deploy/collab-relay-edge/install-global-new-connection-rate.sh \
  "$OPENPENCIL_RELAY_EDGE_PUBLIC_BIND_IP"
sudo deploy/collab-relay-edge/verify-global-new-connection-rate.sh \
  "$OPENPENCIL_RELAY_EDGE_PUBLIC_BIND_IP"

安装脚本(install-global-new-connection-rate.sh)只接受规范的全局限路由 IPv4;它在 root 所有的临时文件(/run/...,umask 077 + chmod 0600)中生成一个固定 nftables 事务,先 nft --check --file 再 nft --file 应用,最后调用验证脚本;从不执行调用方提供的规则文件。

生成的规则(参考文件 global-new-connection-rate.nft)形如:

table inet openpencil_relay_edge_rate {
    chain prerouting {
        type filter hook prerouting priority mangle; policy accept;
        ip daddr <PUBLIC_IP> tcp dport 443 tcp flags & (fin | syn | rst | ack) == syn
        ct state new meter relay_edge_new_v4 { ip saddr timeout 2m limit rate over 60/minute burst 20 packets }
        counter drop
    }
}

即:对目标为边缘公共 IP、TCP 443 的初始 SYN,按源地址计量,超过 60 次/分钟(突发 20 包)则丢弃,源条目 2 分钟超时。

验证脚本(verify-global-new-connection-rate.sh)通过 nft --json --numeric list table 读取内核实际规则,交给 verify-rate-rules.py 逐字段核对:地址必须是规范且 is_global 的 IPv4、表内只能有恰好一个 table/chain/rule、链必须为 type filter hook prerouting priority mangle (-150) policy accept、规则必须精确包含 7 个表达式(目的 IP 匹配、目的端口 443、TCP flags 掩码 {1,2,4,16} 且值等于 SYN、ct state new、meter 的 key 为源地址且 timeout 120、limit rate 60 burst 20 per minute inv true、终态 drop)。内核模型与预期不符即失败关闭。

注意:数据面 relay 使用 openpencil_relay_edge_rate 表;locator 控制面使用独立的表(openpencil_locator_edge_rate,见 deploy/collab-relay-locator-edge/README.md),两者不得混用。

6.3 持久化与监督式启动

  • 通过宿主的 nftables 服务持久化该表,并确保其在 Docker 之前恢复。
  • Global Compose 刻意设置 restart: "no",直接 docker compose up 启动 Global 不是生产路径。
  • 生产路径是安装经评审的 openpencil-collab-relay-global.service.example(替换其中的不可变 release 路径 /opt/openpencil 后使用)。该 unit 声明 Requires=docker.service nftables.service、After=network-online.target nftables.service docker.service,ExecStart 指向 deploy-global.sh,Restart=always;它在每次初始启动或崩溃重启前重新安装并独立验证速率表,确保 Docker 容器绝不会先于速率门发布。

七、部署 Global 入口

deploy-global.sh 是 Global 侧的监督式前台包装器,它会先安装速率门、以 production 模式跑校验、做 Compose 配置解析,再以前台 exec docker compose up --abort-on-container-exit --exit-code-from global-edge 运行。

export OPENPENCIL_RELAY_EDGE_IMAGE_REPOSITORY='registry.example/nginx-unprivileged'
export OPENPENCIL_RELAY_EDGE_IMAGE_SHA256='<reviewed-64-lowercase-hex-digest>'
export OPENPENCIL_RELAY_EDGE_PUBLIC_BIND_IP='<real-dedicated-public-ipv4>'
export OPENPENCIL_RELAY_EDGE_CLIENT_CERT=/secure/global/cn-client.pem
export OPENPENCIL_RELAY_EDGE_CLIENT_KEY=/secure/global/cn-client-key.pem
export OPENPENCIL_RELAY_CN_FEDERATION_CA=/secure/global/cn-federation-ca.pem
export OPENPENCIL_RELAY_EDGE_EXPECTED_CN_FEDERATION_UPSTREAM=10.0.8.12:9443
export OPENPENCIL_RELAY_EDGE_EXPECTED_CN_INNER_WSS_UPSTREAM=10.0.8.13:8444
export OPENPENCIL_RELAY_EDGE_EXPECTED_CN_FEDERATION_NAME=relay-federation.collab.your-company.cn

deploy/collab-relay-edge/deploy-global.sh

环境变量一览:

变量 含义 约束
OPENPENCIL_RELAY_EDGE_IMAGE_REPOSITORY 审计过的 nginx-unprivileged 镜像仓库 与摘要分离,防可变 tag 顶替
OPENPENCIL_RELAY_EDGE_IMAGE_SHA256 经评审的 64 位小写十六进制摘要 必须匹配 ^[0-9a-f]{64}$
OPENPENCIL_RELAY_EDGE_PUBLIC_BIND_IP 专用境外公共 IPv4 必须为规范全局 IPv4
OPENPENCIL_RELAY_EDGE_CLIENT_CERT / _KEY Global 的 mTLS 客户端证书/私钥 绝对路径,0400/0440
OPENPENCIL_RELAY_CN_FEDERATION_CA 窄钉的 CN federation 服务器 CA 绝对路径
OPENPENCIL_RELAY_EDGE_EXPECTED_CN_FEDERATION_UPSTREAM 固定的 CN federation 目标 IPv4:port 字面量,禁域名/动态
OPENPENCIL_RELAY_EDGE_EXPECTED_CN_INNER_WSS_UPSTREAM 固定的 CN 内层 WSS 目标 IPv4:port 字面量
OPENPENCIL_RELAY_EDGE_EXPECTED_CN_FEDERATION_NAME 外层 mTLS 的 DNS 身份 小写、非 example.*

替换所有尖括号与 your-company 示例后再运行;包装器保持前台运行以便 systemd 监督。

八、部署私有 CN federation 监听器

export OPENPENCIL_RELAY_EDGE_IMAGE_REPOSITORY='registry.example/nginx-unprivileged'
export OPENPENCIL_RELAY_EDGE_IMAGE_SHA256='<reviewed-64-lowercase-hex-digest>'
export OPENPENCIL_RELAY_CN_FEDERATION_BIND_IP=10.0.8.12
export OPENPENCIL_RELAY_CN_FEDERATION_CERT=/secure/cn/federation-server.pem
export OPENPENCIL_RELAY_CN_FEDERATION_KEY=/secure/cn/federation-server-key.pem
export OPENPENCIL_RELAY_EDGE_CLIENT_CA=/secure/cn/global-edge-client-ca.pem
export OPENPENCIL_RELAY_EDGE_CLIENT_CRL=/secure/cn/global-edge-client-crl.pem

docker compose \
  -f deploy/collab-relay-edge/compose.cn.yaml \
  config -q
docker compose \
  -f deploy/collab-relay-edge/compose.cn.yaml \
  up -d

config -q 会在缺变量时通过 :? 语法直接失败。部署后必须验证 bind-mount 的实际 owner/mode 与 UID 101 的密钥可读性;不要用 root、追加 capability 或可写根文件系统来绕过密钥读取失败。

该监听器的 cn-federation-nginx.conf 关键参数:listen 9443 ssl、ssl_verify_client on、ssl_verify_depth 2、ssl_crl /run/secrets/global-edge-client-crl.pem、ssl_handshake_timeout 5s、ssl_session_cache off + ssl_session_tickets off(禁用会话缓存,强制每次回程连接走完整证书校验,配合 Global 侧 proxy_ssl_session_reuse off)、聚合上限 limit_conn trusted_global_edges 512。

九、轮换或撤销一个 Global edge 证书

9.1 新 CRL 必须满足的条件

生成一张重新签发的完整 CRL,放在不同的绝对路径:

  • CRLNumber 必须严格大于当前活动 CRL 的编号;
  • lastUpdate 与 nextUpdate 必须在当前有效时间窗内;
  • 必须包含被泄露 edge 证书的序列号;
  • 必须是完整 CRL(禁止 delta CRL);
  • 必须保留此前所有已撤销序列号。

9.2 执行轮换

加载与 CN federation 服务相同的部署环境(或受保护的 .env 文件),然后以 root 运行:

export OPENPENCIL_RELAY_EDGE_IMAGE_REPOSITORY='registry.example/nginx-unprivileged'
export OPENPENCIL_RELAY_EDGE_IMAGE_SHA256='<reviewed-64-lowercase-hex-digest>'
export OPENPENCIL_RELAY_CN_FEDERATION_BIND_IP=10.0.8.12
export OPENPENCIL_RELAY_CN_FEDERATION_CERT=/secure/cn/federation-server.pem
export OPENPENCIL_RELAY_CN_FEDERATION_KEY=/secure/cn/federation-server-key.pem
export OPENPENCIL_RELAY_EDGE_CLIENT_CRL=/secure/cn/global-edge-client-crl.pem
export OPENPENCIL_RELAY_EDGE_CLIENT_CA=/secure/cn/global-edge-client-ca.pem
export OPENPENCIL_RELAY_EDGE_EXPECTED_CN_FEDERATION_UPSTREAM=10.0.8.12:9443
export OPENPENCIL_RELAY_EDGE_EXPECTED_CN_INNER_WSS_UPSTREAM=10.0.8.13:8444
export OPENPENCIL_RELAY_EDGE_EXPECTED_CN_FEDERATION_NAME=relay-federation.collab.your-company.cn
bash deploy/collab-relay-edge/rotate-cn-crl.sh \
  /secure/cn/global-edge-client-crl.next.pem \
  /secure/cn/revoked-global-edge-client-cert.pem

9.3 轮换脚本的内部流程(源码级)

rotate-cn-crl.sh 是严格的状态机式脚本,按序执行:

  1. 前置检查:必须以 root 运行;所有路径必须为绝对路径、常规文件、非符号链接;候选与活动路径必须不同;先前备份 *.previous 存在则拒绝再次轮换;校验 docker/openssl/date/stat/mktemp/cp/mv/chmod/chown/sed/tr/grep/sort/comm 工具齐备。
  2. owner/mode 硬性校验:活动 CRL、活动 CA 及其所在目录必须 root 所有,文件 group 101、模式 0440,目录不得对 group/other 可写((dir_mode & 0022) == 0)。
  3. 部署契约校验:以 OPENPENCIL_RELAY_EDGE_VALIDATION_MODE=production 运行 validate.sh 并 docker compose config -q,在改动活动文件之前先验证完整 Compose 环境。
  4. 冻结字节:用 cp 把候选 CRL 与被撤销证书复制到 staged 临时文件,后续所有校验都基于这些固定字节(防 TOCTOU)。
  5. 密码学校验:openssl crl -verify -CAfile <client_ca>(仅针对专用 client CA,-no-CApath -no-CAstore);openssl verify 目标被撤销证书;要求 CRLNumber 严格单调递增(十六进制规范化后按位比较,L161-L169);时间窗校验带 300 秒时钟偏移容差(lastUpdate 不得在未来,nextUpdate 不得过早过期);grep 'X509v3 Delta CRL Indicator' 拒绝 delta CRL;comm -23 确认候选 CRL 未丢失任何既有撤销序列号;最后确认新序列号确实出现在候选 CRL 中。
  6. 原子发布:cp -p 保留活动文件属性备份为 .previous,对 staged 文件 chmod/chown 到与活动文件一致的 owner/mode,重校验 staged inode 后 mv -f 原子替换(同文件系统 rename)。
  7. 容器重建:docker compose up -d --no-deps --force-recreate cn-federation(只重建 federation 容器,让 bind mount 与 Nginx SSL context 都加载新 inode 上的 CRL),随后 docker compose exec -T cn-federation nginx -t。
  8. 失败回滚:任何一步失败,rollback() 会从 .previous 恢复活动文件并 force-recreate 之前的容器;成功后故意保留 global-edge-client-crl.pem.previous。

9.4 宣布撤销完成前的双探针

在宣布撤销完成之前,必须:

  1. 用被撤销的 client 证书连接私有监听器,确认 TLS 握手被拒绝;
  2. 用未撤销的 edge 证书连接,确认仍可正常连通。

只有两项探针都通过,才允许删除保留的备份文件。

十、限额、日志与源归属:可观测性与速率策略的边界

10.1 日志纪律

两个 stream 代理的 access_log 均已关闭。声明的 redacted 日志格式只包含字节数、状态和持续时间(log_format redacted '$time_local transport=$protocol status=$status bytes_in=$bytes_received bytes_out=$bytes_sent session_time=$session_time'),且未启用。生产中禁止添加 ssl_preread 载荷捕获、原始流转储或 debug 日志——这些会破坏"Global 看不到协作内容"的核心保证。

10.2 连接与带宽上限

两级 hop 统一采用:单一静态 upstream、禁用 retry(proxy_next_upstream off)、有界文件描述符(worker_rlimit_nofile 4096)、worker 连接数(Global 1024 / CN federation 2048)、缓冲(proxy_buffer_size 16k)、带宽(上下行各 16m)、连接数上限,以及 180 秒空闲超时(proxy_timeout 180s,Global 连接超时 5s、CN federation 3s)。同时启用 proxy_socket_keepalive on 与 proxy_half_close off。

Global 每源地址上限为 32:一个 owner 会保持四条 warm relay lanes,而企业出口/CGNAT 地址下可能有多个用户共享同一源 IP;内层 TLS 内的客户端心跳流量会让健康的流保持活跃。

10.3 无 PROXY protocol 时的源归属

在没有 PROXY protocol 的情况下,正常的 CN WSS terminator 会把 CN federation 代理的地址当作 TCP 来源。为此,deploy/collab-relay/nginx.conf 提供独立的私有 8444 内层 TLS 监听器,使用 $server_port 维度做聚合握手/连接上限(relay_federation_handshakes、relay_federation_connections),而公共 443 保留每客户端 IP 的限制(relay_handshakes、relay_connections 8)。Global Nginx 依然能看到真实客户端 IP 用于其连接上限。8444 必须保持私有并被防火墙限定只对 federation 代理开放,且保留上游的账户/票证/设备级速率限制。

不要随意引入 PROXY protocol:只有当 federation 出口与内层 WSS 监听器被配置为可信对时才能使用,否则不可信客户端可以伪造源地址。

十一、验收检查清单(10 项)

  1. 先运行脚手架校验器(bash deploy/collab-relay-edge/validate.sh,scaffold 模式),再替换静态目标/名称、设置三个 OPENPENCIL_RELAY_EDGE_EXPECTED_* 值,并以 OPENPENCIL_RELAY_EDGE_VALIDATION_MODE=production 重跑。
  2. 确切的 nftables 表名匹配 Compose 的 IPv4;拒绝单源连接抖动测试;重启后速率表先于被监督服务激活。
  3. 两个 Nginx 配置在挂载真实证书后都通过 nginx -t。
  4. Global 在客户端证书缺失、过期或由不受信 CA 签发时无法连接;按文档完成原子 CRL 轮换与容器重建后,被撤销证书被拒绝而未被撤销的 edge 仍可连接。
  5. Global 拒绝名称或证书链错误的 CN federation 证书。
  6. 公共流量无法直达 CN federation 监听器。
  7. 在 Global 抓包/日志只能看到不透明的内层 TLS 字节,永远看不到 Bearer/capability 材料。
  8. 正常 CN terminator 仍拒绝除严格 GET /v1/tunnel WebSocket 升级边界外的所有路径。
  9. 海外 owner 与 guest 到达同一张 CN 内存配对表,并完成既有端到端 Noise 握手。
  10. 签名 home region 非 CN 的请求仍在 CN authenticator 被拒绝。

十二、校验器如何防止配置漂移:validate.sh 的防呆设计

validate.sh 是整个脚手架的"契约守护者",它的 scaffold 模式硬编码期望 TEST-NET 占位符(192.0.2.10:9443、192.0.2.20:8444、cn-federation.example.cn),用于在替换前验证目录完整性;production 模式则强制读取三个 OPENPENCIL_RELAY_EDGE_EXPECTED_* 变量,并要求 upstream 是正则匹配的 IPv4:port 字面量、DNS 名小写且不得是 example.*。它还会核对:

  • Global/CN 配置中的全部关键指令字面量(如 proxy_ssl_session_reuse off、ssl_verify_client on、limit_conn global_clients 32 等);
  • 每个 upstream 块恰好一个 server、全文件恰好一个 proxy_pass;
  • 禁止 include、动态/回退 upstream、ssl_preread、PROXY protocol 相关指令;
  • CN terminator 配置必须含 location = /v1/tunnel {、proxy_set_header Authorization $http_authorization;、proxy_pass_header OpenPencil-Relay-Challenge; 以及两组 64k 头缓冲;
  • relay Dockerfile 的两个 FROM 必须带固定 sha256: 摘要;
  • nftables 参考规则、安装/验证脚本、速率规则校验器、systemd 服务、CRL 轮换脚本的关键字符串逐条比对;
  • OPENPENCIL_RELAY_EDGE_IMAGE_SHA256 必须为 64 位小写十六进制;
  • 若本机有 docker,还会用测试仓库/摘要//dev/null 路径跑一次 compose config -q 冒烟。

这套校验让"先失败再替换"的占位符策略真正可执行:任何一环被误改,production 校验都会在容器启动前终止部署。

总结

deploy/collab-relay-edge/ 提供了一条完整的、生产导向的跨地域协作中继入口方案:两级 L4 字节代理实现嵌套 TLS 回程,Global 侧零 TLS 终止能力保证了境外节点对协作内容完全不可见;固定路由、fail-closed 占位符与强校验器共同消灭了配置漂移;主机级 nftables 速率门补足了 L4 代理无 HTTP 限流的短板;原子 CRL 轮换脚本让边缘证书撤销成为可验证、可回滚的操作。部署时应始终记住三条铁律:密钥不进镜像、CRL 换文件必须重建容器、Global 只允许通过 systemd 监督启动。

登录后查看全文
openpencil