From 2ebcb6e1b85a8997c48de2711b013c83fa0440fc Mon Sep 17 00:00:00 2001 From: Nixevol Date: Wed, 30 Sep 2026 09:10:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=9A=E7=A8=BF=20Q4=20Docker=20?= =?UTF-8?q?=E4=B8=8E=20Q5=20=E8=BF=90=E7=BB=B4=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 107 ++++++++++++++++++++++++++++-- deploy/Dockerfile | 8 ++- deploy/docker-compose.yml | 22 +++--- docs/DEVIATIONS.md | 37 +++++++++++ docs/OPS.md | 136 ++++++++++++++++++++++++++++++++++++++ taskfiles/q.yml | 41 +++++++++++- 6 files changed, 333 insertions(+), 18 deletions(-) create mode 100644 docs/OPS.md diff --git a/README.md b/README.md index 722fdbb..e1486a6 100644 --- a/README.md +++ b/README.md @@ -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)。源代码和发布物公开可读，不代表授予使用许可。 diff --git a/deploy/Dockerfile b/deploy/Dockerfile index b65bf7d..2021ed8 100644 --- a/deploy/Dockerfile +++ b/deploy/Dockerfile @@ -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 diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml index 50a83dd..7a197cf 100644 --- a/deploy/docker-compose.yml +++ b/deploy/docker-compose.yml @@ -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 diff --git a/docs/DEVIATIONS.md b/docs/DEVIATIONS.md index dc72abd..2289b7d 100644 --- a/docs/DEVIATIONS.md +++ b/docs/DEVIATIONS.md @@ -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 汇总页。 + - 影响：无。 diff --git a/docs/OPS.md b/docs/OPS.md new file mode 100644 index 0000000..8215153 --- /dev/null +++ b/docs/OPS.md @@ -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` 到 + `/backup/pre-migrate-.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://:/metrics`，无需令牌。 +- **共用端口**：请求头必须带 `Authorization: Bearer `。 + - 未配置 `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` 抓取等仍见对照表备注中的未测说明。 diff --git a/taskfiles/q.yml b/taskfiles/q.yml index 5f10161..17ce7fe 100644 --- a/taskfiles/q.yml +++ b/taskfiles/q.yml @@ -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