129 lines
5.8 KiB
Markdown
129 lines
5.8 KiB
Markdown
# 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. 验收与仍跳过的长时项
|
||
|
||
F01–F23 短时间验收对照表见 [test/accept/ACCEPTANCE.md](../test/accept/ACCEPTANCE.md)（汇总通过 23，失败 0，未测 0）。下列因环境或时长限制**未测**，不得宣称已通过：
|
||
|
||
- F03：1000 端全表 1 秒内返回、真拔网线后心跳超时离线
|
||
- F08 / Q3：Linux netem 20% 丢包（本机 Windows）
|
||
- 压测：1000 连接保持 10 分钟、每秒 200 条
|
||
|
||
F22 通过的子集仅覆盖 init + 健康检查等；备份恢复、升级迁移、证书重载、Docker 全量、`/metrics` 抓取等仍见对照表备注。
|