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

2026-09-30 09:10:33 +08:00
parent a22912d95a
commit d86729d1b3
6 changed files with 333 additions and 18 deletions
@@ -2,17 +2,114 @@

 自建的消息中转服务。设备、程序、App 作为「端」连到同一台服务器，端之间互发消息或群发。单个 Go 程序，内置 MQTT，SQLite 存储，自带管理后台，提供 Go、JS/TS、Python、Java/Android SDK。

+## 功能概览
+
+- 端登录、会话令牌、在线目录、单聊与群发
+- 离线保留、延迟、定时、撤回、回执
+- 管理后台（网页 + API）、自助注册、Prometheus `/metrics`
+- 单文件二进制或 Docker 部署
+
+## 构建
+
+需要：Go、Node.js LTS、pnpm、[Task](https://taskfile.dev)。
+
+```bash
+task check          # 构建前端、编译、lint、单元测试
+task build          # 产出 bin/nixmsg（Windows 为 bin/nixmsg.exe）
+```
+
+交叉编译三个发布平台（`CGO_ENABLED=0`，产物在 `bin/`，勿提交）：
+
+```bash
+task q:release-bins
+# 等价于：
+# CGO_ENABLED=0 GOOS=linux   GOARCH=amd64 go build -tags embeddist -o bin/nixmsg-linux-amd64 ./cmd/nixmsg
+# CGO_ENABLED=0 GOOS=linux   GOARCH=arm64 go build -tags embeddist -o bin/nixmsg-linux-arm64 ./cmd/nixmsg
+# CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -tags embeddist -o bin/nixmsg-windows-amd64.exe ./cmd/nixmsg
+```
+
+Docker 当前架构镜像（不推送）：
+
+```bash
+task q:docker-build
+# 镜像名 git.asio.asia/nixevol/nixmsg:0.1.0
+```
+
+推送当前架构镜像（阶段 3 正式执行；推送前先 `docker login git.asio.asia`）：
+
+```bash
+task q:docker-push
+```
+
+多架构 `linux/amd64` + `linux/arm64`（需 Docker buildx / QEMU）：
+
+```bash
+task q:docker-buildx
+```
+
+## 配置文件
+
+默认读取当前目录的 `config.yaml`；也可用环境变量 `NIXMSG_CONFIG` 指定路径。
+
+- 完整示例：[deploy/config.example.yaml](deploy/config.example.yaml)
+- 容器内示例：[deploy/config.docker.yaml](deploy/config.docker.yaml)（`data_dir: /data`）
+- 字段说明见 [docs/OPS.md](docs/OPS.md)
+
+## 初始化与启动
+
+1. 复制并编辑配置：
+
+   ```bash
+   copy deploy\config.example.yaml config.yaml   # Windows
+   # cp deploy/config.example.yaml config.yaml  # Linux/macOS
+   ```
+
+2. 生成管理员密码（只打印一次，请自行保存）：
+
+   ```bash
+   # Windows PowerShell
+   $env:NIXMSG_CONFIG="config.yaml"; .\bin\nixmsg.exe admin init
+
+   # Linux / macOS
+   NIXMSG_CONFIG=config.yaml ./bin/nixmsg admin init
+   ```
+
+3. 启动服务：
+
+   ```bash
+   $env:NIXMSG_CONFIG="config.yaml"; .\bin\nixmsg.exe serve
+   # NIXMSG_CONFIG=config.yaml ./bin/nixmsg serve
+   ```
+
+4. 浏览器打开 `http://127.0.0.1:7443/`（或你配置的 `listen` / `admin_listen`）登录管理后台。健康检查：`GET /healthz`。
+
+Docker Compose 示例见 [deploy/docker-compose.yml](deploy/docker-compose.yml)。首次需保证数据目录对 uid `65532` 可写，再：
+
+```bash
+docker compose -f deploy/docker-compose.yml run --rm nixmsg admin init
+docker compose -f deploy/docker-compose.yml up -d
+```
+
+## SDK
+
+| SDK | 说明 |
+|---|---|
+| [sdk/go](sdk/go/README.md) | Go 模块 `git.asio.asia/nixevol/NixMsg/sdk/go` |
+| [sdk/js](sdk/js/README.md) | npm `@nixevol/nixmsg` |
+| [sdk/python](sdk/python/README.md) | PyPI `nixmsg` |
+| [sdk/java](sdk/java/README.md) | Maven `asia.asio.nixmsg:nixmsg-sdk` |
+
+包正式发布在阶段 3；开发期可按各 README 本地引用。
+
 ## 文档

 - [产品需求](docs/PRD.md)
 - [开发说明](docs/DEVELOPMENT.md)
- [开发任务拆分与多 Agent 协作](docs/TASKS.md)
+- [运维手册](docs/OPS.md)
+- [验收对照表](test/accept/ACCEPTANCE.md)（含未测项）
+- [开发任务](docs/TASKS.md)
 - [与文档的偏差](docs/DEVIATIONS.md)

-## 状态
-
-需求和设计已完成，正在开发。构建、运行和部署说明在开发完成后补充。
-
 ## 许可证

 专有软件，见 [LICENSE](LICENSE)。源代码和发布物公开可读，不代表授予使用许可。
@@ -1,5 +1,7 @@
 # 多阶段构建：Node 构建前端 → Go 编译（嵌入前端）→ distroless static nonroot。
-# 镜像名 git.asio.asia/nixevol/nixmsg；多架构 buildx 推送留给 Q4 定稿，本骨架先单架构可构建。
+# 镜像名 git.asio.asia/nixevol/nixmsg；入口 /nixmsg。
+# 单架构：task q:docker-build 或 q:docker-push（含推送）。
+# 多架构：task q:docker-buildx（linux/amd64 + linux/arm64，需 buildx；正式推送在 Z3）。

 FROM node:24-bookworm AS web
 WORKDIR /src/web
@@ -9,13 +11,15 @@ COPY web/ ./
 RUN pnpm build

 FROM golang:1.27-bookworm AS build
+ARG TARGETOS=linux
+ARG TARGETARCH=amd64
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 COPY --from=web /src/web/dist ./web/dist
 ENV CGO_ENABLED=0
-RUN go build -tags embeddist -o /out/nixmsg ./cmd/nixmsg
+RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -tags embeddist -o /out/nixmsg ./cmd/nixmsg

 FROM gcr.io/distroless/static:nonroot
 COPY --from=build /out/nixmsg /nixmsg
@@ -1,11 +1,16 @@
-# Docker Compose 示例（DEVELOPMENT 第 11.4 节骨架）
-# 本地冒烟：先 docker build -t git.asio.asia/nixevol/nixmsg:0.1.0 -f deploy/Dockerfile .
-# 容器名带 q 前缀便于多 Agent 隔离；正式部署可去掉 container_name。
+# Docker Compose 示例（对齐 DEVELOPMENT 第 11.4 节）
+# 构建：task q:docker-build（当前架构）或 task q:docker-buildx（多架构，正式推送在 Z3）
+# 首次：保证数据目录对 uid 65532 可写，再 admin init，然后 up。
+#
+# 命名卷首次授权示例：
+#   docker run --rm -v q4-nixmsg-data:/data busybox chown -R 65532:65532 /data
+# 宿主机目录挂载时：在宿主机 chown 65532:65532 ./data

 services:
  nixmsg:
    image: git.asio.asia/nixevol/nixmsg:0.1.0
-    container_name: q-nixmsg
+    # 本地/并行测试可加 container_name；正式部署可去掉
+    container_name: q4-nixmsg
    restart: unless-stopped
    command: ["serve"]
    environment:
@@ -14,7 +19,7 @@ services:
      - "7443:7443"
    volumes:
      - ./config.docker.yaml:/etc/nixmsg/config.yaml:ro
-      - q-nixmsg-data:/data
+      - q4-nixmsg-data:/data
      # 生产环境挂载证书目录，例如：
      # - /opt/nixmsg/certs:/certs:ro
    healthcheck:
@@ -24,8 +29,5 @@ services:
      retries: 3

 volumes:
-  q-nixmsg-data:
-    name: q-nixmsg-data
-
-# 首次使用命名卷时，需保证 /data 对 uid 65532 可写，例如：
-# docker run --rm -v q-nixmsg-data:/data busybox chown -R 65532:65532 /data
+  q4-nixmsg-data:
+    name: q4-nixmsg-data
@@ -1002,3 +1002,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 汇总页。  
+   - 影响：无。
@@ -0,0 +1,136 @@
+# NixMsg 运维手册
+
+对应 DEVELOPMENT 第 11 节。本文不含任何密码或令牌样例。
+
+## 1. 配置项
+
+环境变量 `NIXMSG_CONFIG` 指向 YAML 配置，默认 `./config.yaml`。完整字段见 [deploy/config.example.yaml](../deploy/config.example.yaml)。
+
+| 项 | 说明 |
+|---|---|
+| `listen` | 端接入端口，如 `":7443"` |
+| `admin_listen` | 后台单独监听，如 `"127.0.0.1:7444"`；空表示后台与端共用 `listen` |
+| `tls.cert_file` / `tls.key_file` | 证书与私钥路径；空表示明文 |
+| `tls.allow_plaintext` | 配了证书时是否仍接受明文；生产建议 `false` |
+| `trusted_proxies` | 可信反向代理网段，用于解析真实客户端 IP |
+| `data_dir` | 数据目录（库文件、`listen.addr`、迁移备份） |
+| `limits.*` | 正文/帧大小、TTL、群人数、宽限、确认超时、配额等；`max_body_bytes` 只能调小，上限 262144 |
+| `session_idle_days` | 会话令牌闲置失效天数；`0` 不失效 |
+| `record_retention_days` | 完成后消息记录保留天数；`0` 表示完成后不留记录 |
+| `idempotency_hours` | 防重窗口 |
+| `receipt_retention_days` | 回执保留天数 |
+| `sqlite_synchronous` | `FULL` 或 `NORMAL` |
+| `metrics.token` | 共用端口时访问 `/metrics` 所需 Bearer 令牌；空则共用端口不提供 `/metrics` |
+| `log.level` | 日志级别，如 `info` |
+
+注册开关、注册安全码、API 令牌存在数据库，在管理后台修改，不在配置文件里。
+
+校验配置：`nixmsg check-config`。
+
+## 2. 目录布局
+
+```text
+config.yaml
+data/nixmsg.db
+data/backup/          # 迁移前自动备份、手工 backup 也可写到这里
+data/listen.addr      # serve 写入实际监听地址（测试用端口 0 时需要）
+```
+
+Docker 约定：配置 `/etc/nixmsg/config.yaml`，数据 `/data`，证书 `/certs`（只读挂载）。
+
+## 3. 备份
+
+程序不做定时备份，用 cron 或 1Panel 计划任务调用：
+
+```bash
+# 宿主机（服务可在运行中）
+NIXMSG_CONFIG=/path/to/config.yaml nixmsg backup --out /path/to/data/backup/manual-$(date +%Y%m%d).db
+
+# Docker Compose
+docker compose -f deploy/docker-compose.yml exec nixmsg /nixmsg backup --out /data/backup/manual.db
+```
+
+备份文件含当时未送完的正文，按敏感数据保管。旧备份自行清理。
+
+恢复：停服务，用备份文件替换 `data/nixmsg.db`（或拷到新 `data_dir`），再启动；勿在半迁移状态硬切。
+
+## 4. 升级与自动迁移
+
+1. 换上新二进制或拉新镜像。
+2. 启动时若有未应用的嵌入迁移版本，会先 `VACUUM INTO` 到  
+   `<data_dir>/backup/pre-migrate-<UTC时间>.db`，再执行迁移。
+3. 迁移失败则进程退出，不带半新半旧库继续服务；运维可从备份恢复后排查。
+4. 空库首次建表不会产生迁移前备份。
+
+无需手工跑迁移命令。
+
+## 5. 证书与 1Panel
+
+程序只读证书文件，不做 ACME。装有 1Panel 时：
+
+1. 在 1Panel 证书管理申请证书（DNS 或 HTTP 验证），打开自动续签。
+2. 勾选「推送证书到本地目录」，例如 `/opt/nixmsg/certs`。申请与续签后写入 `fullchain.pem`、`privkey.pem`。
+3. 配置：
+
+   ```yaml
+   tls:
+     cert_file: /opt/nixmsg/certs/fullchain.pem
+     key_file: /opt/nixmsg/certs/privkey.pem
+     allow_plaintext: false
+   ```
+
+4. 私钥须让 NixMsg 进程可读。Docker 容器用户为 nonroot（uid `65532`）；可在 1Panel「申请证书后执行脚本」里调整属主/权限。
+5. 程序每小时检查文件修改时间，续签后新连接自动用新证书，已有连接不断开。
+
+不要用 1Panel OpenResty 终止 TLS 再转发裸 TCP：TCP/UDP 代理不做 TLS，设备会被拆端口。仅当全部端走 WebSocket 时，才可改成「OpenResty 终止 HTTPS/WSS，NixMsg 本机明文」；此时配置 `trusted_proxies`，并设置 `proxy_http_version 1.1`、`Upgrade`、`Connection`，`Host` 用 `$http_host`。
+
+## 6. 服务器时钟
+
+- 开启 NTP 对时。
+- 服务器时钟被人为大改时，定时消息按新时钟触发。
+- 宽限、确认超时、会话闲置等也依赖系统时间。
+
+## 7. 抓取 `/metrics`
+
+Prometheus 文本格式，只含计数和耗时，不含正文与编号明细。
+
+- **后台单独监听**（`admin_listen` 非空）：在后台端口直接  
+  `GET http://<admin_host>:<port>/metrics`，无需令牌。
+- **共用端口**：请求头必须带 `Authorization: Bearer <metrics.token>`。  
+  - 未配置 `metrics.token` → `404`  
+  - 令牌错误 → `401`
+
+示例（共用端口且已配置 token；勿把真实令牌写进仓库或脚本提交）：
+
+```bash
+curl -sS -H "Authorization: Bearer $NIXMSG_METRICS_TOKEN" http://127.0.0.1:7443/metrics
+```
+
+健康检查：`GET /healthz`、`GET /readyz`（Docker HEALTHCHECK 用镜像内 `/nixmsg healthcheck`）。
+
+## 8. Docker 要点
+
+- 镜像：`git.asio.asia/nixevol/nixmsg`（版本标签与 `latest`）。
+- Compose 示例：[deploy/docker-compose.yml](../deploy/docker-compose.yml)。
+- 容器以 uid `65532` 运行：挂载数据目录须可写；命名卷首次可  
+  `docker run --rm -v <卷名>:/data busybox chown -R 65532:65532 /data`。
+- 首次：`docker compose run --rm nixmsg admin init`，再 `up -d`。
+- 构建/推送 Task 目标见根目录 README（`q:docker-build` / `q:docker-push` / `q:docker-buildx`）。正式仓库推送在阶段 3。
+
+## 9. 验收未测项（勿当作已通过）
+
+截至 Q4/Q5 文档定稿，对照表 [test/accept/ACCEPTANCE.md](../test/accept/ACCEPTANCE.md) 中下列项仍为**未测**，运维与交付说明须保持该状态，不得宣称通过：
+
+| 编号 | 摘要 |
+|---|---|
+| F03 | 断开后离线状态 / 目录全表 |
+| F04 | presence 订阅通知 |
+| F07 | 256 KiB 边界与接收上限 |
+| F10 | 抖动宽限长短断线 |
+| F11 | 发送方离线后定时到点 |
+| F14 | 回执补送 |
+| F15 | 对话密码授权链路 |
+| F18 | 正文删除与记录天数 0 |
+| F19 | 四种 SDK 统一接入清单（属 SDK 线，本波未在 Q 对照表复测） |
+
+F22 标为通过的子集仅覆盖 init + 健康检查等；备份恢复、升级迁移、证书重载、Docker 全量、`/metrics` 抓取等仍见对照表备注中的未测说明。
@@ -1,5 +1,10 @@
 version: "3"

+vars:
+  IMAGE: git.asio.asia/nixevol/nixmsg
+  IMAGE_TAG: "0.1.0"
+  BIN_DIR: bin
+
 tasks:
  q:accept:
    desc: 跑 Q2 验收集成测试并写入 F01–F23 对照表
@@ -41,4 +46,38 @@ tasks:
  q:docker-build:
    desc: 构建当前架构镜像（不推送）
    cmds:
-      - docker build -t git.asio.asia/nixevol/nixmsg:0.1.0 -f deploy/Dockerfile .
+      - docker build -t {{.IMAGE}}:{{.IMAGE_TAG}} -t {{.IMAGE}}:latest -f deploy/Dockerfile .
+
+  q:docker-push:
+    desc: 构建并推送当前架构镜像到 git.asio.asia/nixevol/nixmsg（正式推送在 Z3）
+    cmds:
+      - task: q:docker-build
+      - docker push {{.IMAGE}}:{{.IMAGE_TAG}}
+      - docker push {{.IMAGE}}:latest
+
+  q:docker-buildx:
+    desc: 多架构 buildx 构建并推送 linux/amd64+arm64（需 QEMU；正式推送在 Z3）
+    cmds:
+      - docker buildx build --platform linux/amd64,linux/arm64 -t {{.IMAGE}}:{{.IMAGE_TAG}} -t {{.IMAGE}}:latest -f deploy/Dockerfile --push .
+
+  q:release-bins:
+    desc: 交叉编译三平台二进制到 bin/（CGO_ENABLED=0，不提交）
+    deps: [web:build]
+    cmds:
+      - |
+        {{if eq OS "windows"}}powershell -NoProfile -Command "New-Item -ItemType Directory -Force -Path '{{.BIN_DIR}}' | Out-Null"{{else}}mkdir -p {{.BIN_DIR}}{{end}}
+      - cmd: go build -tags embeddist -o {{.BIN_DIR}}/nixmsg-linux-amd64 ./cmd/nixmsg
+        env:
+          CGO_ENABLED: "0"
+          GOOS: linux
+          GOARCH: amd64
+      - cmd: go build -tags embeddist -o {{.BIN_DIR}}/nixmsg-linux-arm64 ./cmd/nixmsg
+        env:
+          CGO_ENABLED: "0"
+          GOOS: linux
+          GOARCH: arm64
+      - cmd: go build -tags embeddist -o {{.BIN_DIR}}/nixmsg-windows-amd64.exe ./cmd/nixmsg
+        env:
+          CGO_ENABLED: "0"
+          GOOS: windows
+          GOARCH: amd64