# 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` 抓取等仍见对照表备注中的未测说明。