docs(deploy): 跨网部署运维 runbook + Tailscale ACL 模板 + 修附录 E 端口 bug (§7)#199
Open
raysonmeng wants to merge 2 commits into
Open
docs(deploy): 跨网部署运维 runbook + Tailscale ACL 模板 + 修附录 E 端口 bug (§7)#199raysonmeng wants to merge 2 commits into
raysonmeng wants to merge 2 commits into
Conversation
added 2 commits
June 26, 2026 13:13
…§7,§11.1) v3 §11.1 bullet 11 + §7 文档落地。连接层代码(broker 绑可配 host、resolveBrokerUrl、 PSK)已就绪,本 PR 把规格的 what 接成可执行的 how,并修一个真实配置 bug。 v3 §11.1 bullet 11 + §7 docs. The connection layer is already in code; this PR turns the spec's "what" into an executable runbook and fixes a real config bug. - 修真实 bug:docs/09 附录 E 的 ACL 模板端口 tcp:4500 → tcp:4700(broker 实际 DEFAULT_BROKER_PORT=4700,docker-compose/sim 都是 4700)。照旧模板配 ACL 会放行 4500、4700 仍被默认 deny 挡死 → ACL 整个失效。 - examples/tailscale-acl.hujson(新):可直接粘进 Tailscale 管理台的完整 ACL 模板 (端口 4700,含"先删 allow-all""端口须与 broker 一致"提示)。 - docs/10-跨网部署与运维.md(新):部署形态选型、双层鉴权(网络层 ACL + 应用层 PSK,且显式声明"鉴权≠room授权"扁平信任模型)、Tailscale 装机/ACL、绑 100.x 不绑 0.0.0.0、无内置 TLS(WireGuard 加密 / 公网需反代)、PSK 签发分发、AGENTBRIDGE_BROKER_URL 连远端(真实机制,非 abg join <host> 语法糖)、git 数据面前提、§13 跨机验收清单、 排障、systemd 常开 Restart=always。 - docs/README.md:编年史加第 10 行。 - src/unit-test/tailscale-acl.test.ts(新,唯一 src/ 改动):防漂测试——解析 HuJSON + 断言 grants 端口 === DEFAULT_BROKER_PORT(钉死到代码常量,杜绝 4500/4700 再漂)+ tagOwners 齐全。正是它能防住这次的端口 bug 复发。 check 全绿 1817 pass。Backlog(文档已点明,推后):PSK revoke/rotation CLI、 0.0.0.0 告警改阻断(--allow-lan 确认旗标)、tailscale whois tags 校验(冗余信号)。 🤖 Generated with [Claude Code](https://claude.com/claude-code)
把 docs/09 §13 验收做成可一键重复的 Docker 场景:6 个 agent 容器(claude/codex/ gemini 异构标签)+ 常开 broker,按真实业务时间线协作并自检。一次 run 覆盖完成事件 扇出 / DM 定向 / 新成员白板 / 离线补投 / 身份消歧(同名不同 id)/ PSK 拒绝 / 会话 连续性 —— 全部 PASS(可复现)。 A one-command, reproducible Docker scenario for docs/09 §13 acceptance: 6 agent containers (heterogeneous claude/codex/gemini labels) + an always-on broker act out a real business timeline and self-assert. One run covers completion fan-out, DM targeting, new-member whiteboard, offline replay, identity disambiguation (same displayName / different id), PSK rejection, session continuity — all PASS. - docker/provision-scenario.ts:注册 5 身份(含双 Bob)+ 建房间加成员 + §13#5 会话连续性断言。 - docker/scenario-agent.ts:角色驱动的替身 agent(基于真实 src/broker-client.ts),事件驱动 + 自检。 - docker/docker-compose.scenario.yml:编排 broker + provision + 6 agent。 - docker/run-acceptance.sh:一键 build→up→等→生成报告→拆。 - docs/test-plans/13-acceptance.md:永久测试方案文档。 - docs/test-plans/13-acceptance-results.md:本次实跑全 PASS 记录。 诚实边界:Docker 证控制面协议跨「机」正确;真实 Claude/Codex 交互式会话注入由 bun room-bridge.test.ts 覆盖、Tailscale 网络层 ACL 由 docs/10 真机 runbook 验。 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要 / Summary
v3 §11.1 bullet 11 + §7 文档落地（stacked base =
feat/v3-ledger）。连接层代码已就绪，本 PR 把规格的 what 接成可执行的 how，并修一个真实配置 bug。改动
tcp:4500→tcp:4700（broker 实际 DEFAULT_BROKER_PORT=4700）。照旧模板配 ACL 会放行 4500、4700 仍被默认 deny 挡死 → ACL 整个失效。examples/tailscale-acl.hujson（新）：可直接粘进 Tailscale 管理台的完整 ACL 模板（端口 4700，含「先删 allow-all」「端口须与 broker 一致」提示）。docs/10-跨网部署与运维.md（新）：部署形态选型、双层鉴权（网络层 ACL + 应用层 PSK，显式声明「鉴权≠room授权」扁平信任）、绑 100.x 不绑 0.0.0.0、无内置 TLS、AGENTBRIDGE_BROKER_URL 连远端、git 数据面前提、§13 跨机验收清单、systemd 常开。src/unit-test/tailscale-acl.test.ts（唯一 src/ 改动）：防漂测试——解析 HuJSON + 断言端口 === DEFAULT_BROKER_PORT（钉死代码常量，杜绝再漂）。Cross-review
2 轮 4 reviewer：reviewer 逐条实证 docs/10 对代码的全部断言（无 TLS / subscribe 无 room 校验 / resolveBrokerUrl / healthz / 优雅关 / 端口），抓出 1 LOW（「空串」告警描述失真）已修（连同根源 cli/broker.ts 注释），连续两轮 0 真实 issue。check 1817 pass。
🤖 Generated with Claude Code