fix: 修复写队列 busy 恢复、关闭安全、备份与配置构建问题

2026-09-30 15:06:11 +08:00
parent 4059a1576b
commit b6908cfba4
23 changed files with 825 additions and 101 deletions
@@ -297,6 +297,49 @@
   - 备选方案：更短前缀或 HistogramVec。  
   - 影响：仪表盘按上述名字配置。

+### 复审修复 D-01 2026-09-30
+
+1. **写队列 busy 后恢复 IsReady**  
+   - 原条款：DEVELOPMENT 4.3 `/readyz` 已能读写数据库；DEVIATIONS P2 只写失败时 `IsReady()=false`。  
+   - 实际做法：`runBatch` 提交成功后在锁内 `ready=true` 并清除 `lastWriteErr`。  
+   - 原因：短暂 busy_timeout / 磁盘瞬时错误后不应永久 503。  
+   - 备选方案：要求最近 30 秒无失败才恢复（防抖动）。  
+   - 影响：`/readyz` 在随后一次成功写入后恢复。
+
+### 复审修复 D-02 2026-09-30
+
+1. **写队列关闭安全与非事务执行**  
+   - 原条款：DEVELOPMENT 7.6 清理后 `PRAGMA wal_checkpoint(TRUNCATE)`；L-03 / C-03 依赖存储层能力。  
+   - 实际做法：`Close` 先置 `closed`，再在写锁内关闭数据通道，并发 `Do` 不会向已关闭 channel 发送；关闭后返回已有的 `ErrQueueClosed`。新增 `ExecOnWriter` / `Checkpoint` / `Optimize`，在写 goroutine 上、事务外执行。不改 `message` 包，不在此调用 checkpoint（留给 C-03）。  
+   - 原因：避免停机 panic，并为 C-03 提供非事务接口。  
+   - 备选方案：只关 stop 通道、永不 close 数据通道。  
+   - 影响：L-03 可安全 Close；C-03 可调用 `DB.Checkpoint`。
+
+### 复审修复 D-04 2026-09-30
+
+1. **backup 空库与恢复步骤**  
+   - 原条款：PRD F22；OPS 第 3 节。  
+   - 实际做法：备份前检查 `nixmsg.db` 绝对路径，不存在则报错且不创建数据目录/空库；成功打印源库绝对路径；输出文件 chmod 0600。OPS 示例 `data_dir` 改为绝对路径；恢复改为同时移走 `-wal`/`-shm`。未做 `nixmsg restore` 命令（允许文件清单未含 restore.go）。  
+   - 原因：cron 相对路径会在错误位置新建空库并当成功备份。  
+   - 备选方案：增加 `restore --from` 命令。  
+   - 影响：空目录 backup 失败；运维按 OPS 恢复时不会叠旧 WAL。
+
+### 复审修复 D-05 2026-09-30
+
+1. **迁移备份按版本命名**  
+   - 原条款：DEVELOPMENT 7.7 迁移前 VACUUM INTO。  
+   - 实际做法：`pre-migrate-v{当前}-to-v{目标}.db`，已存在则复用；复制前尽力检查剩余磁盘空间。  
+   - 原因：迁移稳定失败时 `restart: unless-stopped` 会写满磁盘。  
+   - 备选方案：按秒时间戳并在启动失败时删除本次备份。  
+   - 影响：同一版本区间反复失败只保留一份备份。
+
+2. **构建注入 Version；grace_seconds: 0 按 0 生效**  
+   - 原条款：DEVELOPMENT 6.1 `server_version`；11.1 `grace_seconds` Validate `>= 0`。  
+   - 实际做法：Taskfile / q.yml / Dockerfile 用 `-ldflags -X main.Version=…`（默认 `git describe`）。去掉 `applyEmptyDefaults` 对数值 0 的回填；显式 `grace_seconds: 0` 表示无宽限（不在 Validate 里报错）。`max_frame_bytes` 上限 786432。`admin set-password` 清空全部 `admin_sessions`。TLS 仅明文关闭时 `healthcheck` 走 HTTPS（本机跳过证书校验）。K-05 是 SDK 打包，与本次 ldflags 无冲突。  
+   - 原因：显式 0 被改回 60 会让运维误以为关掉了宽限；hello 的 max_frame 不能超过 broker 包长。  
+   - 备选方案：`grace_seconds: 0` 在 Validate 报错，强制至少 1 秒。  
+   - 影响：未写该字段仍为默认 60；命令行改密后旧 Cookie 一律 401。
+
 ## 连接 N

 ### N1 / N2 2026-09-30
@@ -42,23 +42,30 @@ Docker 约定：配置 `/etc/nixmsg/config.yaml`，数据 `/data`，证书 `/cer

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

+配置里的 `data_dir` 必须写成绝对路径。cron 的工作目录通常是家目录，相对路径会指到错误位置，甚至在空目录里新建空库并当成功备份。
+
 ```bash
-# 宿主机（服务可在运行中）
-NIXMSG_CONFIG=/path/to/config.yaml nixmsg backup --out /path/to/data/backup/manual-$(date +%Y%m%d).db
+# 宿主机（服务可在运行中；NIXMSG_CONFIG 与 data_dir 都用绝对路径）
+NIXMSG_CONFIG=/opt/nixmsg/config.yaml nixmsg backup --out /opt/nixmsg/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
 ```

-备份文件含当时未送完的正文，按敏感数据保管。旧备份自行清理。
+备份文件含当时未送完的正文，按敏感数据保管（文件权限 0600）。旧备份自行清理。库文件不存在时 backup 报错并打印解析后的绝对路径，不会新建空库。

-恢复：停服务，用备份文件替换 `data/nixmsg.db`（或拷到新 `data_dir`），再启动；勿在半迁移状态硬切。
+恢复：
+
+1. 停服务。
+2. 把 `nixmsg.db`、`nixmsg.db-wal`、`nixmsg.db-shm` 三个文件一起移走（不要只替换 `.db`，残留 WAL 会叠到恢复库上）。
+3. 把备份文件复制成 `nixmsg.db`。
+4. 启动。勿在半迁移状态硬切。

 ## 4. 升级与自动迁移

 1. 换上新二进制或拉新镜像。
 2. 启动时若有未应用的嵌入迁移版本，会先 `VACUUM INTO` 到  
-   `<data_dir>/backup/pre-migrate-<UTC时间>.db`，再执行迁移。
+   `<data_dir>/backup/pre-migrate-v{当前版本}-to-v{目标版本}.db`，再执行迁移。已有同名备份则复用，避免迁移反复失败时写满磁盘。
 3. 迁移失败则进程退出，不带半新半旧库继续服务；运维可从备份恢复后排查。
 4. 空库首次建表不会产生迁移前备份。