docs: 定稿 Q4 Docker 与 Q5 运维文档

2026-09-30 09:24:32 +08:00
parent b75b67928b
commit 2ebcb6e1b8
6 changed files with 333 additions and 18 deletions
@@ -1025,3 +1025,40 @@
   - 原因：隔离目录约束。  
   - 备选方案：扩展 harness.Restart（需总控改）。  
   - 影响：Q 线自带启停辅助。
+
+### Q4 定稿 + Q5 文档 2026-09-30
+
+1. **多架构 buildx 本波不执行推送与双架构验证**  
+   - 原条款：DEVELOPMENT 11.4 / TASKS Q4「两个架构的镜像都能初始化、启动并通过健康检查」；`docker buildx` 一次推送 amd64+arm64。  
+   - 实际做法：完善 Dockerfile（`TARGETOS`/`TARGETARCH`）、compose、`task q:docker-build` / `q:docker-push` / `q:docker-buildx`；本机只对当前架构（linux/amd64）`docker build` 并冒烟 `/healthz`；**不** `docker push`、**不**打版本 git 标签、**不**发布 SDK。本机 `docker buildx` 已列出 `linux/arm64`，但本波按总控指示不执行多架构构建与推送，留给 Z3。  
+   - 原因：总控本波明确禁止真正 push / 打标签 / 发 SDK；双架构留给 Z3。  
+   - 备选方案：在 Linux 宿主或已装 binfmt 的环境执行 `task q:docker-buildx`。  
+   - 影响：交付标准「两架构镜像」与仓库推送仍待阶段 3。
+
+2. **交叉编译三平台，本波至少验证 windows/amd64**  
+   - 原条款：DEVELOPMENT 11.2 三平台二进制。  
+   - 实际做法：`task q:release-bins`（`CGO_ENABLED=0`）产出 `bin/nixmsg-linux-amd64`、`nixmsg-linux-arm64`、`nixmsg-windows-amd64.exe`；说明写入 README；二进制不提交。  
+   - 原因：纯 Go + embed，交叉编译可行。  
+   - 备选方案：仅本机 `task build`。  
+   - 影响：发布物打包在 Z3。
+
+3. **compose 容器/卷名带 q4 前缀**  
+   - 原条款：DEVELOPMENT 11.4 示例无固定 `container_name`；测试隔离要求名字带线前缀。  
+   - 实际做法：`deploy/docker-compose.yml` 使用 `q4-nixmsg` / `q4-nixmsg-data`；正式部署可去掉 `container_name`。  
+   - 原因：多 Agent 并行不抢容器名。  
+   - 备选方案：compose 用项目名 `-p` 隔离而不写死 container_name。  
+   - 影响：与文档示例略有差异，行为等价。
+
+4. **验收未测项保持未测**  
+   - 原条款：交付标准要求 F01–F23 有结果；TASKS 本波 Q4/Q5 不做假装通过。  
+   - 实际做法：`ACCEPTANCE.md` / `docs/OPS.md` 第 9 节明示 F03、F04、F07、F10、F11、F14、F15、F18、F19 仍为未测；不改对照表状态。  
+   - 原因：本波范围是 Docker 定稿与文档。  
+   - 备选方案：无。  
+   - 影响：阶段 3 / 负责人审阅时须看到未测清单。
+
+5. **Q5 文档落点**  
+   - 原条款：README、运维手册、SDK 文档汇总。  
+   - 实际做法：重写根 `README.md`；新增 `docs/OPS.md`；SDK 汇总为 README 链到已有 `sdk/{go,js,python,java}/README.md`（各 SDK 已有最短使用说明，本波不重复扩写）。  
+   - 原因：避免四份说明与 SDK 线漂移。  
+   - 备选方案：在 docs/ 再建 SDK 汇总页。  
+   - 影响：无。