OpenPencil 协作中继(collab relay)部署与生产认证实践:盲转发架构、Challenge-Bound X25519 证明与 CN/Global 双区域拓扑
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),客户端流程如下:
- 保留该次升级使用的确切 bearer(票据字节);
- 用自己已有的设备 X25519 私钥与挑战中 pinned 的中继公钥执行 X25519;
- 用 HKDF-SHA256 从共享秘密派生会话密钥;
- 发送一个固定 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运行(distrolessnonroot),因此宿主文件必须对该身份实际可读,并且对 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),因为该值同时决定 WebSocketmax_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 协作基础设施中最关键的一环。