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

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)。源代码和发布物公开可读，不代表授予使用许可。