OpenPencil 协作中继(collab relay)部署与生产认证实践:盲转发架构、Challenge-Bound X25519 证明与 CN/Global 双区域拓扑

原创2026-10-11 19:53:511,759 阅读

OpenPencil 协作中继(collab relay)部署与生产认证实践:盲转发架构、Challenge-Bound X25519 证明与 CN/Global 双区域拓扑

OpenPencil 的协作中继(collaboration relay)是一个刻意设计为"不受信任、盲转发"的 WebSocket 字节转发器:TLS 在边缘终止,Rust 进程只负责把已配对的双方字节流原样搬移,文档流量仍由端到端的 Noise 会话加密,中继永远接触不到明文文档操作。本文基于 deploy/collab-relay/README.md 展开,结合仓库内 op-collab-relay-server 的源码与全部部署产物,完整讲解其安全模型、生产认证协议(签名票据 + 签名定位器 + 挑战绑定 X25519 证明)、必填环境变量与密钥文件格式,以及 Global / CN 双区域直接路径与面向海外对等方的 L4 嵌套 TLS 边缘拓扑。读完本文,你将能够独立完成一个区域生产中继的密钥准备、容器部署、Nginx 编排与上线前检查。

一、设计定位:为什么中继可以"盲"转发

中继在整个 OpenPencil 协作体系中的角色非常收敛,可以从 README 原文 与源码相互印证:

  • 盲转发:中继是 untrusted、blind 的 WebSocket 字节转发器。TLS 在边缘(Nginx)终止,Rust 进程默认只监听 127.0.0.1:8091(见 crates/op-collab-relay-server/src/config.rs 的 Default 实现)。
  • 端到端加密:即使 TLS 在中继之外的边缘终止,客户端之间已有的 Noise 会话仍然对文档流量做端到端加密,因此中继永远收不到明文文档操作。
  • 只开放一条路径:中继只接受 GET /v1/tunnel 升级(crates/op-collab-relay-server/src/connection.rs 在握手回调中严格校验 request.uri()),其他路径一律 404。
  • 路由隔离:路由使用 domain-separated 的 BLAKE3 map key,不同会话的 RouteCapability 彼此隔离。
  • 最小可见性:capabilities、tickets、challenges、proofs、payloads 永不写日志。这不仅是隐私承诺,也直接写进了代码:RelayBearerCredential 在 Debug 输出中只会显示 <a href="https://link.gitcode.com/i/c5aed26539f5151210a44edb1cc7ab95" target="_blank">REDACTED],Drop 时对字节做 zeroize() 擦除,且类型本身不可克隆、不可打印([crates/op-collab-relay-server/src/auth.rs)。

这一设计使得中继可以在不持有任何业务身份的前提下,为跨网络、跨区域的配对提供转发服务,同时把信任锚点全部收敛到签名票据、签名定位器和设备密钥上。

二、生产认证:签名票据 + 签名定位器 + Challenge-Bound X25519 证明

2.1 启动模式:默认 Fail Closed

独立二进制在未显式选择模式时直接拒绝启动(fail closed)。命令行为主程序 crates/op-collab-relay-server/src/main.rs 中的 parse_args 解析:

启动参数 语义
(无参数) Fail Closed,不启动监听
--production 启用签名票据、签名定位器、区域、Owner 密钥与挑战绑定 X25519 证明的全部验证
--production --allow-ticket-binding-only 显式降级为"仅票据绑定"(reduced assurance),见下文
--allow-unauthenticated-dev 仅限本地开发的 capability-only 模式
--check-production 校验挂载的生产信任输入后打印 ready 并退出,不打开监听

参数之间存在互斥校验:--production 与 --allow-unauthenticated-dev 冲突;--allow-ticket-binding-only 必须搭配 --production;--check-production 不能与其他启动模式组合。这些约束都有对应的单元测试(main.rs)。

日志级别同样被严格收口:只接受 OPENPENCIL_COLLAB_RELAY_LOG_LEVEL=error|warn|info|debug(默认 info),任意 RUST_LOG 依赖级过滤器和 trace 都会被拒绝启动(main.rs),从而避免依赖库把敏感中间状态刷进日志。

2.2 每次升级签发一个新鲜 Challenge

对每个认证成功的 WebSocket 升级,中继在 101 响应中携带恰好一个新鲜挑战头:

OpenPencil-Relay-Challenge: oprc1_<canonical-base64url>

协议层定义见 crates/op-collab-relay-protocol/src/challenge.rs:头名 openpencil-relay-challenge,前缀 oprc1_。挑战体包含一个 pinned relay key id 和一个新鲜的 32 字节 nonce。

挑战是"单次使用"的服务器状态:

  • 类型 RelayUpgradeChallenge 在 auth.rs 中被设计为不可克隆;
  • 它随有界的 hello deadline 过期(握手阶段整体受 handshake_timeout 约束,默认 5 秒);
  • 它被第一次认证尝试消费——即使验证失败也会被消耗,杜绝重放。

2.3 认证模式 2:33 字节 HMAC 证明如何绑定一切

在完整生产模式下(认证模式 2,RelayHelloAuthMode::ChallengeBoundX25519V2),客户端流程如下:

  1. 保留该次升级使用的确切 bearer(票据字节);
  2. 用自己已有的设备 X25519 私钥与挑战中 pinned 的中继公钥执行 X25519;
  3. 用 HKDF-SHA256 从共享秘密派生会话密钥;
  4. 发送一个固定 33 字节的 HMAC-SHA256 证明(possession proof)。

该证明在密码学上绑定以下全部要素:

  • 完整挑战与协议版本;
  • bearer 票据字节的 SHA-256(而不是票据内容本身,中继无需也不应读取票据内容);
  • 角色与 caller 设备公钥(Owner 还额外要求 caller 的 X25519 公钥与定位器中 owner_noise_static 静态密钥恒定时间相等,见 auth.rs);
  • route capability 与完整签名定位器。

因此,把证明重放到另一条连接、换用刷新后的 bearer、或者迁移到另一个角色/路由/定位器,都会以 AuthenticationFailed 拒绝。实现上,RequireRelayChallengeProof 在 auth.rs 中依次校验:认证模式必须匹配、挑战必须新鲜且存在、hello 中必须携带可解码的 proof,最后把验证委托给 X25519 边界。

2.4 RelayServerX25519ProofBoundary:HSM 可插拔验证边界

RelayServerX25519ProofBoundary(crates/op-collab-relay-server/src/x25519_boundary.rs)是 trait 定义的验证边界,只暴露两个能力:返回当前 active key id、判定固定大小证明是否有效。HSM 适配器可以把中继私钥与派生共享秘密完全保留在 HSM 内部,中继只提交公开 transcript 询问布尔结果。

仓库内置的 PinnedX25519ProofBoundary 是密封文件适配器,供尚未接 HSM 的部署使用。它从 JSON 文件加载密钥集,并做了多层防御:

  • 文件必须是非符号链接的常规文件,打开时使用 O_NOFOLLOW | O_CLOEXEC(x25519_boundary.rs);
  • 在 Unix 上不得有任何 group/other 权限位(mode & 0o077 != 0 即拒绝),且必须由运行中继的用户本人持有(root 例外),防止"0600 文件属于他人账户"这类权限位无法表达的所有权漏洞;
  • 私钥编码、共享秘密、派生密钥全部经 Zeroizing 包装,读取后即擦除;Debug 只暴露密钥数量;
  • 校验 DH 结果必须满足 contributory(非贡献性对等点直接拒绝,防小群攻击),见 x25519_boundary.rs。

结论:任何私钥都不应进入源码仓库或镜像层。长生命周期的公网部署应优先使用平台托管 secret 或 HSM 支持的 RelayServerX25519ProofBoundary。

2.5 认证期间的资源隔离

阻塞式策略加载、签名与证明验证都在 Tokio worker 之外的 spawn_blocking 线程池中执行(connection.rs),并以 OPENPENCIL_COLLAB_RELAY_MAX_AUTH_IN_FLIGHT 信号量限流。该 permit 从签发挑战一直持有到 WebSocket 升级、hello 接收与真正验证完成,防止未认证连接洪泛占满异步工作线程。

三、必填配置与密钥文件格式

3.1 环境变量清单

环境变量 必填 说明
OPENPENCIL_COLLAB_RELAY_HOME_REGION 必填 取值 cn 或 global,其他值在启动时 fail closed(crates/op-collab-relay-server/src/production.rs)
OPENPENCIL_COLLAB_RELAY_TICKET_POLICY_FILE 必填 pinned 签名联合策略(union-policy)JSON 的绝对路径
OPENPENCIL_COLLAB_RELAY_LOCATOR_KEYS_FILE 必填 定位器 Ed25519 公钥文件的绝对路径
OPENPENCIL_COLLAB_RELAY_X25519_KEYS_FILE 完整模式必填 密封的中继 X25519 密钥集绝对路径;降级模式可不配
OPENPENCIL_COLLAB_RELAY_POLICY_MAX_AGE_SECONDS 可选 策略最大缓存龄期,1..=3600 秒,默认 60;超范围直接配置失败
OPENPENCIL_COLLAB_RELAY_LOG_LEVEL 可选 `error
OPENPENCIL_COLLAB_RELAY_LEGACY_TICKET_BEARER 可选 迁移开关:accept(默认,双接受最小化中继 token 与旧版完整协作票据)或 reject(只接受最小化 token);其他值 fail closed(production.rs)

从源码看,ProductionRelayAuthConfig::new 还强制所有密钥/策略路径必须是绝对路径,并且做了如下互斥校验(production.rs):

  • 未配置 RELAY_X25519_KEYS_FILE 且未显式 --allow-ticket-binding-only → ChallengeProofRequired,拒绝启动;
  • 两者同时存在 → ConflictingProofPolicy,拒绝启动。

也就是说,完整挑战证明模式与降级模式在配置上互斥,绝不可能"顺便都开"。

3.2 定位器公钥文件(公共,可分发)

{
  "version": 1,
  "keys": [
    {
      "kid": "locator-key-2026-07",
      "public_key_ed25519": "canonical-base64url-no-padding"
    }
  ]
}

这是公共验证材料,可由根或中继有效 UID 持有。解析上限与版本校验由 crates/op-collab-policy-file/src/lib.rs 提供(MAX_PINNED_VERIFIER_KEYS、MAX_PINNED_VERIFIER_KEY_FILE_BYTES、PINNED_VERIFIER_KEY_FILE_VERSION),并通过 lib.rs 对外复用。

3.3 密封的中继 X25519 密钥文件(私有)

{
  "version": 1,
  "active_kid": "relay-pop-2026-07",
  "keys": [
    {
      "kid": "relay-pop-2026-07",
      "private_key_x25519": "canonical-base64url-no-padding",
      "public_key_x25519": "canonical-base64url-no-padding"
    }
  ]
}

要点:

  • active_kid 必须出现在 keys 中,否则 MissingActiveKey 拒绝(x25519_boundary.rs);
  • 每个记录中公钥必须与私钥推导结果恒定时间相等(防止误填导致密钥错位);
  • kid 不可重复,密钥数上限 8,文件上限 16 KiB;
  • 文件中的私钥与公钥编码必须是 URL-safe 无填充 base64,且要求规范化编码——非规范化编码会被 InvalidKey 拒绝(x25519_boundary.rs),这保证了挑战头中 base64url 的 canonical 性质。

该文件的公钥值和 key id 会被分发给客户端,作为 pinned relay keys 参与挑战验证。

在 Unix 上,该密封文件必须是常规非符号链接文件、无 group/other 权限位;读取是有界的并使用 O_NOFOLLOW | O_CLOEXEC;私钥编码、共享秘密与派生密钥一律 zeroize。

四、部署实战:从密钥准备到容器上线

4.1 信任输入文件的权限纪律

  • 签名策略文件(公共):Unix 上可归属中继有效 UID 或 root;必须是常规非符号链接文件、不可 group/world 可写。因为内容是公共验证材料,root 持有的 0440(容器身份有组读权限时)或 0444 均可接受;任何可写模式一律 fail closed。
  • 定位器公钥文件(公共):同上,属于公共材料。
  • 中继 X25519 密钥文件(私有):必须由运行身份持有、0400 级权限、无 group/other 位,任何违规直接拒绝加载。

4.2 Global 生产部署(完整挑战证明模式)

export OPENPENCIL_COLLAB_POLICY_HOST_FILE=/secure/public/collab-policy.json
export OPENPENCIL_RELAY_LOCATOR_KEYS_HOST_FILE=/secure/public/locator-keys.json
export OPENPENCIL_RELAY_X25519_KEYS_HOST_FILE=/secure/private/relay-x25519-keys.json
sudo chown 65532:65532 "$OPENPENCIL_RELAY_X25519_KEYS_HOST_FILE"
sudo chmod 0400 "$OPENPENCIL_RELAY_X25519_KEYS_HOST_FILE"
docker compose \
  -f deploy/collab-relay/compose.yaml \
  -f deploy/collab-relay/compose.production.yaml \
  -f deploy/collab-relay/compose.production.global.yaml \
  up --build

CN 部署只把最后一个 overlay 换成 compose.production.cn.yaml,其余命令结构相同。两个区域 overlay 绝不组合使用。

各 overlay 的分工:

  • deploy/collab-relay/compose.yaml:公共底座。定义监听 0.0.0.0:8091(容器内)、资源配额(read_only: true、cap_drop: ALL、no-new-privileges: true、pids_limit: 256、mem_limit: 512m)、进程级上限(MAX_PENDING=1024、MAX_AUTH_IN_FLIGHT=128、MAX_ACTIVE=10000、MAX_WAITING_PER_ROUTE=4、QUEUE_CAPACITY=32、MAX_QUEUED_BYTES=67108864、MAX_QUEUED_BYTES_PER_ROUTE=1048576)。不发布主机端口。
  • compose.production.yaml:--production 启动,把三个信任文件以 secret 形式挂到 /run/secrets/openpencil-{collab-policy,relay-locator-keys,relay-x25519-keys}.json,并配置 POLICY_MAX_AGE_SECONDS=60。
  • compose.production.global.yaml:HOME_REGION=global,MAX_PENDING_PER_SOURCE=1024,端口只发布到 127.0.0.1:8091。
  • compose.production.cn.yaml:HOME_REGION=cn,MAX_PENDING_PER_SOURCE=1024,端口只发布到 10.0.0.10:8091。

4.3 关于 Secret 与 UID 的坑

  • secret 以只读方式挂载到 /run/secrets;
  • 打包镜像以 UID/GID 65532 运行(distroless nonroot),因此宿主文件必须对该身份实际可读,并且对 group/other 不可访问;
  • Docker Compose 对 file-backed secret 会静默忽略 uid、gid、mode 属性——它们是 bind mount,overlay 因此不声明这些无效属性。必须在目标 Linux 主机上实测有效所有权、权限与可读性后再启动生产;
  • 密钥读取失败或权限违规必须阻止中继启动(fail closed),而不是降级运行。

4.4 镜像基线的可重复性

Dockerfile 的两个基础镜像(rust:1.94-bookworm 构建阶段与 gcr.io/distroless/cc-debian12:nonroot 运行阶段)都按多架构 manifest digest 固定,并注明于 2026-07-29 从上游注册表验证。升级流程被文档明确固化:先解析上游注册表中目标 Rust / distroless tag,审查新 manifest/平台与安全差异,替换两个 FROM 的 tag-plus-digest,再用 --pull --no-cache 重建,最后重跑部署与工作区安全 gate。运行二进制为 op-collab-relay-server,EXPOSE 8091,入口即该二进制。

4.5 降级模式与开发模式(各有明确边界)

Reduced-assurance(显式降级,非默认):

export OPENPENCIL_COLLAB_POLICY_HOST_FILE=/secure/public/collab-policy.json
export OPENPENCIL_RELAY_LOCATOR_KEYS_HOST_FILE=/secure/public/locator-keys.json
docker compose \
  -f deploy/collab-relay/compose.yaml \
  -f deploy/collab-relay/compose.reduced-assurance.yaml \
  up --build

compose.reduced-assurance.yaml 的 command 为 --production --allow-ticket-binding-only,只挂载策略与定位器密钥(无 X25519 密钥)。该模式仍然验证:票据到设备 DH 的绑定、定位器签名、区域、过期时间与 Owner 静态绑定;但它没有挑战证明,只接受认证模式 1(SignedLocatorAndBearerTicketV1)且不带 possession proof。它永远不会成为默认,TicketDhBindingOnly 策略在 auth.rs 中明确要求"必须无挑战、必须无 proof"。

本地开发模式:

docker compose \
  -f deploy/collab-relay/compose.yaml \
  -f deploy/collab-relay/compose.dev.yaml \
  up --build

compose.dev.yaml 只追加 --allow-unauthenticated-dev(capability-only 路由)。该模式绝不暴露到公网,也绝不能与公共端口或面向公网的反向代理组合——文件内注释与 main.rs 的警告日志都反复强调这一点。

五、直接区域公共路径与 Nginx 编排

5.1 默认双区域拓扑

默认部署是每区域一个公共应用主机,两条协作路径都在该主机上:

CN       https://<cn-public-host>/v1/locator
         wss://<cn-public-host>/v1/tunnel
Global   https://<global-public-host>/v1/locator
         wss://<global-public-host>/v1/tunnel

具体的公共主机名保存在私有部署清单与签名桌面 bootstrap 中,不进入本公开仓库。两个 Compose 项目使用独立网络,因此主机 Nginx 绝不能把 Docker 服务名(如 relay、locator)当作 upstream——各区域 overlay 里 nginx-http-direct*.conf 的 upstream 都是显式 IP。

5.2 为什么区域 overlay 把 per-source 上限固定为 1024

区域 overlay 固定 OPENPENCIL_COLLAB_RELAY_MAX_PENDING_PER_SOURCE=1024,恰好等于进程级 pending 上限(MAX_PENDING=1024)。这是有意为之:跨 Docker 发布的宿主机端口进入中继的连接,会以 Docker NAT peer 地址出现,独立的公网客户端可能坍缩成同一个应用可见源。此时中继不能对该共享地址应用常规 per-source 配额桶。真正的"可信真实源边界"是宿主机 Nginx:它的握手限速 zone 与连接 zone 在代理前先施加每客户端限制,而中继仍强制执行全局 1024 pending 上限。若 Nginx 之前还有负载均衡器,只从该均衡器的固定可信地址恢复客户端地址,绝不信任任意 forwarded-address 头(公共 Compose 文件本身不设置此生产覆盖项)。

5.3 各区域主机的 Nginx 文件拼装

Global 应用主机只允许使用:

deploy/collab-relay/compose.production.global.yaml
deploy/collab-relay-locator/compose.production.global.yaml

两者硬编码 home_region=global 与回环端口 127.0.0.1:8091(relay)、127.0.0.1:8092(locator)。Global Nginx http 作用域恰好一次 include:deploy/collab-relay-locator/nginx-http-limits.conf、deploy/collab-relay/nginx-http-direct.conf、deploy/collab-relay-locator/nginx-http-direct.conf。

CN 应用服务主机只允许使用:

deploy/collab-relay/compose.production.cn.yaml
deploy/collab-relay-locator/compose.production.cn.yaml

两者硬编码 home_region=cn 与私有端口 10.0.0.10:8091(relay)、10.0.0.10:8092(locator)。CN 前端网关 include 相同的 locator limits,外加 deploy/collab-relay/nginx-http-direct-cn-gateway.conf 与 deploy/collab-relay-locator/nginx-http-direct-cn-gateway.conf,upstream 显式为 10.0.0.10:8091 / 10.0.0.10:8092。

CN 服务主机的防火墙纪律:两个端口(8091/8092)必须限制为已配置的前端网关源地址;绝不绑定 0.0.0.0、绝不暴露在公共接口;不把区域 overlay 复制到另一区域、不组合两个 overlay、不加 Compose ports override。

应用 TLS 虚拟主机内部:每个区域的 TLS 虚拟主机 include deploy/collab-relay-locator/nginx-location-direct.conf(/v1/locator)与 deploy/collab-relay/nginx-location.conf(/v1/tunnel)。这两份文件只定义两条精确协作路径,不会覆盖应用自身其他路由。独立中继主机的 nginx.conf 与专用定位器主机的 nginx-location.conf 不能与上述 direct-host 片段混用。

5.4 关键 Nginx 语义:挑战头与有界缓冲

  • nginx.conf 显式设置 proxy_pass_header OpenPencil-Relay-Challenge;(nginx.conf)——严格客户端在中继返回的任何认证挑战头缺失、重复、畸形、未知密钥或非规范化编码时,都会在发送 hello 之前失败关闭;
  • 公共与联邦 TLS 服务器都使用有界 64 KiB 客户端请求头缓冲(client_header_buffer_size 64k; large_client_header_buffers 2 64k;),让合法上限 48 KiB 的票据能放进 Authorization 头,同时不让请求头无界膨胀;
  • location = /v1/tunnel 内做 limit_req(握手 zone 30r/m、burst 10)、limit_conn(每连接 8)、关闭 access_log、proxy_buffering off、超时 43210s;联邦监听器(listen 8444 ssl,仅供 CN 联邦流代理)使用按 $server_port 聚合的 zone(3000r/m、burst 500、512 连接),避免把共享回程源套进公共每客户端上限。

5.5 Global 用户显式选择 CN

当 Global 用户显式选择 CN 区域时,两条路径都直接走 CN 应用主机;签名定位器保持 home_region=cn,Global 中继既不是 fallback,也不代理该会话。这种拓扑不需要 L4 联邦边缘。上线前必须从私有清单确认两个对外发布的 URL 对及其证书。

六、面向海外对等方的中国中继(可选 L4 边缘拓扑)

该拓扑不属于上述直接区域部署,只有在单独部署并评审 L4 边缘后才可使用。对 home_region=cn 的定位器:境内客户端走常规 CN WSS 端点;海外客户端可解析一个仅做 L4 透传的 Global 入口:

overseas client inner TLS/WSS
  -> Global L4 stream proxy
  -> fixed outer-mTLS backhaul
  -> private CN federation listener
  -> normal CN TLS/WSS terminator
  -> the same CN relay process

关键约束(详见 deploy/collab-relay-edge/README.md):

  • Global hop 从不终止或检查内部 TLS 流,也不是 Global home relay 或 fallback;
  • 双方对等方仍汇聚到同一个 CN pairing table,CN authenticator 对签名 home_region=cn 保持权威;
  • 内部证书仍由 CN terminator 呈现,必须覆盖客户端 wss:// URL 中的主机名(对 Global 专用 DNS 名,需把该名加到 CN WSS 证书上并把地址路由到 Global 入口);
  • 外层 mTLS 认证回程一跳,但绝不替代签名定位器、bearer 票据、票据-DH 绑定、逐连接挑战绑定 X25519 PoP v2 与 Noise。

6.1 客户端配置语义

在海外桌面上,把逻辑 CN 端点 OPENPENCIL_COLLAB_RELAY_CN_URL 配置为 Global 入口的 WSS 主机名;或者用 GeoDNS/split DNS,让同一 CN 端点主机名在海外解析到 Global 入口、境内解析到直接 CN terminator。OPENPENCIL_COLLAB_RELAY_GLOBAL_URL 始终保留给签名 home region 实际为 global 的定位器,绝不是 CN 定位器的隐式 fallback。

因此境内与海外对等方可以走不同网络路径,却收敛到同一个 CN 中继进程/分片。必须注意:这会刻意制造跨境数据路径,需要适用的传输、延迟、可达性与可用性评审;同时 CN 中继会拒绝为 Global home region 签名的定位器。

6.2 配对状态的分片警告

服务器当前在单个进程中维护 pairing 状态。不要在没有稳定 route-key 分片或共享 rendezvous 层的情况下,跨独立副本对中继主机名做 round-robin——任意回退可能把 Owner 与 Guest 送进不同的配对表。

七、源码视角:中继运行时的配额、超时与抗放大设计

在部署之外,理解运行时默认值有助于调优与排障。全部默认值定义在 crates/op-collab-relay-server/src/config.rs,且 validate() 强制所有预算为正、max_message_bytes ≤ 64 KiB、max_queued_bytes_per_route ≤ max_queued_bytes、max_pending_per_source ≤ max_pending(config.rs):

配置(环境变量) 默认值 含义
OPENPENCIL_COLLAB_RELAY_LISTEN 127.0.0.1:8091 监听地址(生产 overlay 覆盖为容器内 0.0.0.0:8091,主机侧仅绑定区域私有地址)
handshake_timeout 5s 升级、挑战、hello 与首次认证的总体截止
waiting_timeout 60s 等待对端配对的截止
idle_timeout 90s 无流量空闲断开
tunnel_lifetime 12h 隧道绝对生命周期
OPENPENCIL_COLLAB_RELAY_MAX_PENDING 1024 进程级未配对连接上限
OPENPENCIL_COLLAB_RELAY_MAX_PENDING_PER_SOURCE 16 单源未配对配额(区域 overlay 固定为 1024 以适配 NAT 语义)
OPENPENCIL_COLLAB_RELAY_MAX_AUTH_IN_FLIGHT 128 并发认证(阻塞验证)上限
OPENPENCIL_COLLAB_RELAY_MAX_REAUTH_IN_FLIGHT 128 并发续证上限,与认证池分离以免未认证洪泛饿死在线会话续证
OPENPENCIL_COLLAB_RELAY_MAX_ACTIVE 10000 已配对活跃对上限
OPENPENCIL_COLLAB_RELAY_MAX_WAITING_PER_ROUTE 4 每条路由等待者上限
OPENPENCIL_COLLAB_RELAY_QUEUE_CAPACITY 32 每连接转发 mpsc 队列容量
OPENPENCIL_COLLAB_RELAY_MAX_QUEUED_BYTES 64 MiB 全局排队字节预算(按字节计信号量)
OPENPENCIL_COLLAB_RELAY_MAX_QUEUED_BYTES_PER_ROUTE 1 MiB 每路由排队字节预算

几个值得注意的源码细节:

  • 按字节背压:已配对阶段每条二进制消息都以字节数换取信号量 permit(全局 + 路由双预算,见 connection.rs),队列满时以 CloseCode::Again 关闭,且只接受二进制消息,文本消息直接 Unsupported 关闭——这与"盲字节转发"定位完全一致。
  • 握手期不处理业务载荷:配对完成前任何 Binary/Text 帧都以 MalformedHello 拒绝(connection.rs)。
  • 拒绝日志防放大:被容量拒绝的连接恰恰是洪泛最可能产生的日志源,server.rs 的 RejectionLog 把拒绝计数并最多每 60 秒汇总一次(首次拒绝仍立即记录),避免把洪泛变成无界日志写放大。
  • 票据上限的前向兼容断言:MAX_RELAY_BEARER_BYTES 通过编译期 assert! 不低于完整协作票据与最小化中继 token 的上限(connection.rs),因为该值同时决定 WebSocket max_message_size 两侧,不能单侧收缩,否则在线续证会因容量错误失败。
  • 上线自检:--check-production 会真实解析签名策略(而不只是打开文件)、校验 OPENPENCIL_COLLAB_EXPECTED_POLICY_SHA256(64 位 hex,格式非法即失败)、加载定位器密钥与 X25519 边界并读取 active key id(production.rs),全部通过后打印 ready 退出,可作为容器启动前探针。

八、部署前自检清单

  • [ ] 三个信任文件就位:签名策略(公共)、定位器公钥(公共)、中继 X25519 密钥(私有,0400、无 group/other 位、属主 65532 或运行身份);
  • [ ] OPENPENCIL_COLLAB_RELAY_HOME_REGION 与区域 overlay 匹配,且 CN / Global 两个 overlay 从未混用;
  • [ ] 宿主机实测 secret 文件的 ownership/mode/可读性(Docker Compose 不传播这些属性);
  • [ ] Nginx http 作用域按 5.3 节恰好 include 各片段一次,proxy_pass_header OpenPencil-Relay-Challenge; 存在,请求头缓冲为有界 64 KiB;
  • [ ] 主机 Nginx 使用显式 IP upstream,未使用 Docker 服务名;CN 两个端口已按前端网关源地址收紧防火墙且未绑 0.0.0.0;
  • [ ] 若启用联邦拓扑:已单独评审 deploy/collab-relay-edge/README.md 的嵌套 TLS、证书、CRL 与限速配置,并确认内部证书覆盖客户端 WSS 主机名;
  • [ ] 上线前在目标主机执行 --check-production 或等价的容器化自检,确认打印 ready;
  • [ ] 基础镜像 digest 与安全基线符合组织策略;升级时按 4.4 节流程重建并重跑安全 gate。

中继的正确姿势是"足够小、足够盲、足够硬":只转字节、不读内容、不写敏感日志,同时用签名票据 + 签名定位器 + 逐连接挑战绑定的 X25519 证明把每条隧道钉死在明确的角色、路由与区域内。理解 deploy/collab-relay/README.md 与 op-collab-relay-server 的实现,就掌握了这套生产级 P2P 协作基础设施中最关键的一环。

登录后查看全文
openpencil