VPN 英文镜像补齐与 multiStatements 遗留说法清理
VPN 英文镜像补齐与 multiStatements 遗留说法清理
- 状态:已实施(本分支),等待 review
- 类型:docs / chore(ci)
- 补记说明:本节计划写在实现之后,只记录已验证事实。
目标分支
main(源分支 codex/vpn-phase6-server-data-plane)。
摘要
上一轮 review 留下两条待办,本轮把它们做完:
docs/en/完全没有 VPN 内容——中文已有docs/user-guide/vpn.md、docs/deployment/vpn-gateway.md、docs/operations/vpn.md三份深文档,英文读者却无从入口。.github/workflows/ci.yml与docs/development/testing.md仍宣称multiStatements=true是 MySQL 测试 DSN 的必需参数,而该前提在 main 的4fc8213/e8b7c0d把整段 DDL 改成逐句执行后已经不成立。
改动明细
英文镜像
docs/en/ 的定位是简明入口、中文为权威深文档(docs/development/documentation.md),
因此按主题补段,不整页翻译:
docs/en/user-guide/server-admin.md:新增## VPN gateway peers,覆盖签发对象与可见性过滤、 管理面随本版本发布、数据面取决于构建变体这一口径、表单与服务端逐字对齐的校验、 ICMP 能力门禁与icmpCapability: unverified的集群限制、轮换/吊销的终态语义、 reveal 的三重确认与no-store、活跃流抽屉的快照语义与501的区别、IP 池概览不从前缀推算。docs/en/user-guide/agent.md:新增## ICMP echo for the VPN gateway,给出agent.streams.icmp_enabled的默认关闭、net.ipv4.ping_group_range与agent icmp echo is unavailable这条启动期 Error、只处理 echo、目标仍受 Agent policy 约束, 以及中文agent.md同款的排障顺序(最后落到 Server 构建变体)。docs/en/user-guide/client.md:UDP 段补一句——forward udp公网侧没有对应监听, Server 的 WireGuard 入口是独立通道且仅-tags vpn构建提供。docs/en/README.md:显式说明 VPN 尚无英文页并给出三份中文深文档链接,避免英文读者以为不存在该能力。
未翻译 docs/user-guide/vpn.md 整页:它是终端用户的 wg-quick 操作手册,与后台文案、
docs/deployment/vpn-gateway.md 的体积实测和放行步骤连在一起,整页翻译会立即产生一份
需要与中文同步维护的第二事实源。若需要,另立一轮把它升级为正式英文页。
multiStatements 清理
- 先确认前提:全仓扫描 MySQL 门控路径,
raw.Exec(多语句)只剩 SQLite 夹具 (account_repository_test.go、sqlite_test.go、vpn_repository_test.go全部sql.Open("sqlite"),MySQL 侧与 auto-init 都走applySchemaStatements单语句执行。 .github/workflows/ci.yml:DSN 去掉&multiStatements=true,注释改为说明该参数为何曾必需、 现在由TestMySQLGatedTestsNeverExecWholeDDLScripts防止回归,并明确不要为「保险」加回。docs/development/testing.md:本地复跑命令同步去掉该参数,要点从「是必需的」改为「不需要」并保留因果。- 未改动:pull-requests 与 plans 两处目录下同名的
2026-09-24-mysql56-contract-ci-gate.md仍保留当时的旧说法,按时点记录不可改写原则不动。
用户影响
英文读者第一次能在英文页面里读到 VPN 网关的管理面范围与构建变体前提; 无功能与接口变化。
API / Schema / 配置影响
无。生产 DSN 无需 multiStatements,此前也未被任何文档要求,因此不存在需要变更的部署。
安全与授权影响
无新增暴露。英文镜像沿用已统一的交付状态口径,不宣称发行版包含数据面。
测试证据
本地实测(darwin/arm64,go1.27.1):
go build ./... ; go vet ./... # 通过
go test ./deploy/... ./scripts/ ./internal/storage/ ./internal/config/ -count=1 # 全 ok
go test ./... -count=1 # 无 FAIL(含 internal/e2e、internal/server)
python3 scripts/gen_doc_index.py # 幂等
git diff --check # 干净
相对链接检查 # 5 个 md,0 死链
ruby -e 'YAML.load_file(".github/workflows/ci.yml")' # 解析通过,DSN 读回正确
deploy/mysql56/mysql56_service_test.go 直接读取 ci.yml,它的通过说明 workflow 形状未破。
仍需 CI 确认:去掉 multiStatements 后的 mysql56 job 是该参数真正的使用现场;
本地无 docker/MySQL,无法执行。若它在 CI 变红,说明还有一条我未扫到的多语句路径,
恢复该参数即可,无数据风险。
发布步骤
无。
回滚步骤
git revert 本轮提交。ci.yml 与 testing.md 可单独回滚(恢复 DSN 参数即完全复原旧行为)。
Reviewer 关注点
- 英文镜像刻意只补到「主题级摘要」,若判断应整页翻译
docs/user-guide/vpn.md,请指明后另起一轮。 ci.yml去参数这条依赖 CI 的mysql56job 绿;这是本轮唯一未被本地证明的断言。docs/en/user-guide/server-admin.md新增段落的口径必须与中文保持一致,后续改中文时要同步。
集成状态
已推送到 origin/codex/vpn-phase6-server-data-plane。