NixMsg/docs/OPS.md

NixMsg 运维手册

对应 DEVELOPMENT 第 11 节。本文不含任何密码或令牌样例。

1. 配置项

环境变量 NIXMSG_CONFIG 指向 YAML 配置，默认 ./config.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. 目录布局

config.yaml
data/nixmsg.db
data/backup/          # 迁移前自动备份、手工 backup 也可写到这里
data/listen.addr      # serve 写入实际监听地址（测试用端口 0 时需要）

Docker 约定：配置 /etc/nixmsg/config.yaml，数据 /data，证书 /certs（只读挂载）。

3. 备份

程序不做定时备份，用 cron 或 1Panel 计划任务调用：

# 宿主机（服务可在运行中）
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. 配置：

   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；勿把真实令牌写进仓库或脚本提交）：

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。
• 容器以 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 中下列项仍为未测，运维与交付说明须保持该状态，不得宣称通过：

编号	摘要
F03	断开后离线状态 / 目录全表
F04	presence 订阅通知
F07	256 KiB 边界与接收上限
F10	抖动宽限长短断线
F11	发送方离线后定时到点
F14	回执补送
F15	对话密码授权链路
F18	正文删除与记录天数 0
F19	四种 SDK 统一接入清单（属 SDK 线，本波未在 Q 对照表复测）

F22 标为通过的子集仅覆盖 init + 健康检查等；备份恢复、升级迁移、证书重载、Docker 全量、/metrics 抓取等仍见对照表备注中的未测说明。