OpenPencil 跨地域协作中继的嵌套 TLS 入口部署指南:Global 边缘到 CN 内网 Federation 全链路解析
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 端点。必须:
- 通过
OPENPENCIL_RELAY_CN_FEDERATION_BIND_IP绑定到私有地址; - 在防火墙层只放行经批准的 Global 出口地址;
- 要求 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 特别强调两个容易被忽略的机制性事实:
- Docker Compose file-backed secrets 本质是 bind mount,不会遵守服务级
uid、gid、mode元数据。因此在up之前,必须手工保证每个挂载文件实际归属于映射到容器101:101的宿主 UID/GID 且可读;私钥保持0400(或经评审的组可读0440)。 - 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 是严格的状态机式脚本,按序执行:
- 前置检查:必须以 root 运行;所有路径必须为绝对路径、常规文件、非符号链接;候选与活动路径必须不同;先前备份
*.previous存在则拒绝再次轮换;校验docker/openssl/date/stat/mktemp/cp/mv/chmod/chown/sed/tr/grep/sort/comm工具齐备。 - owner/mode 硬性校验:活动 CRL、活动 CA 及其所在目录必须
root所有,文件 group101、模式0440,目录不得对 group/other 可写((dir_mode & 0022) == 0)。 - 部署契约校验:以
OPENPENCIL_RELAY_EDGE_VALIDATION_MODE=production运行validate.sh并docker compose config -q,在改动活动文件之前先验证完整 Compose 环境。 - 冻结字节:用
cp把候选 CRL 与被撤销证书复制到 staged 临时文件,后续所有校验都基于这些固定字节(防 TOCTOU)。 - 密码学校验:
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 中。 - 原子发布:
cp -p保留活动文件属性备份为.previous,对 staged 文件chmod/chown到与活动文件一致的 owner/mode,重校验 staged inode 后mv -f原子替换(同文件系统 rename)。 - 容器重建:
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。 - 失败回滚:任何一步失败,
rollback()会从.previous恢复活动文件并 force-recreate 之前的容器;成功后故意保留global-edge-client-crl.pem.previous。
9.4 宣布撤销完成前的双探针
在宣布撤销完成之前,必须:
- 用被撤销的 client 证书连接私有监听器,确认 TLS 握手被拒绝;
- 用未撤销的 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 项)
- 先运行脚手架校验器(
bash deploy/collab-relay-edge/validate.sh,scaffold 模式),再替换静态目标/名称、设置三个OPENPENCIL_RELAY_EDGE_EXPECTED_*值,并以OPENPENCIL_RELAY_EDGE_VALIDATION_MODE=production重跑。 - 确切的 nftables 表名匹配 Compose 的 IPv4;拒绝单源连接抖动测试;重启后速率表先于被监督服务激活。
- 两个 Nginx 配置在挂载真实证书后都通过
nginx -t。 - Global 在客户端证书缺失、过期或由不受信 CA 签发时无法连接;按文档完成原子 CRL 轮换与容器重建后,被撤销证书被拒绝而未被撤销的 edge 仍可连接。
- Global 拒绝名称或证书链错误的 CN federation 证书。
- 公共流量无法直达 CN federation 监听器。
- 在 Global 抓包/日志只能看到不透明的内层 TLS 字节,永远看不到 Bearer/capability 材料。
- 正常 CN terminator 仍拒绝除严格
GET /v1/tunnelWebSocket 升级边界外的所有路径。 - 海外 owner 与 guest 到达同一张 CN 内存配对表,并完成既有端到端 Noise 握手。
- 签名 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 监督启动。