Kaotings/www_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
62dba45799
www_site/docs/OPERATIONS.md
flym 62dba45799 docs: correct offsite backup to /volume1/NetBackup via tar-over-SSH 
Moved the backup out of the NAS home dir to /volume1/NetBackup/kaotings per
request. Synology restricts rsync-over-SSH to registered shared folders and
scp/sftp yields root-owned files that the backup account cannot rotate, so the
backup now uses tar over SSH (kts_bak-owned, rotatable, encrypted, key auth).
Document the transport rationale and the DSM shared-folder upgrade path for
incremental rsync.
2026-09-10 16:25:45 +08:00

6.6 KiB
Raw Blame History

运维方案（OPERATIONS）

日期：2026-09-10 · 版本 8657f44 范围：音频容量/保留/清理/备份/恢复、数据库备份/恢复、Worker 与额度对账、告警。本轮不擅自删除任何既有音频。

1. 音频存储现状

  • 位置：/home/flym/kaotings-audio，布局 {user_id}/{task_id}.wav（私有本地目录，非对象存储）。
  • 元数据：audio_files（storage_key、mime_type、size_bytes、checksum、status、expires_at）。
  • 写入：成功结算时先写文件、再登记 audio_files（含 SHA256）。
  • 读取：回放/下载按 storage_key 取文件；文件缺失返回 404（优雅降级）。

2. 备份（已配置异地备份）

  • 本机暂存：/home/flym/backups/（仅存放 .dump）。
  • 异地备份目标：Synology NAS 103.40.14.100，账号 kts_bak，落盘 /volume1/NetBackup/kaotings/（db/ + audio/，不在 home 下），可用容量约 92 GiB。
  • 传输方式：tar over SSH（端口 52200，加密），密钥认证（/root/.ssh/id_ed25519_ktsbak，公钥已加入 NAS kts_bak 的 authorized_keys）。不使用 公网明文 rsync 守护端口 50873。
    • 为何不用 rsync：Synology 限制 rsync-over-SSH 仅能写入已注册的共享文件夹；/volume1/NetBackup 是普通目录（非 DSM 共享文件夹），rsync 会报 0 bytes received。而 scp/sftp 虽能写入，但会生成 root 属主文件，kts_bak 无法轮转删除。tar over SSH（ssh exec） 生成的文件属主为 kts_bak，可正常轮转。
    • 升级路径：若在 DSM 中将 NetBackup 建为共享文件夹（控制面板→共享文件夹，授予 kts_bak 读写），即可改回 rsync -a --delete 获得增量传输。
  • 脚本：/usr/local/sbin/kaotings-backup.sh（root 运行）：
    1. pg_dump --format=custom 业务库（/etc/kaotings/api.env → DATABASE_URL）与 CMS 库（/etc/kaotings/cms.env → DATABASE_URI）。
    2. 每库本机保留最近 7 份（按序列独立轮转）。
    3. tar over SSH 传 db/ 与 audio/（AUDIO_STORAGE_DIR）到 NAS；再在远端按序列保留 7 份（ssh exec，可删除 kts_bak 属主文件）。
  • 定时：systemd kaotings-backup.timer，每日 03:00（Persistent=true，RandomizedDelaySec=30min）触发 kaotings-backup.service。
  • 验证：备份已落盘 /volume1/NetBackup/kaotings（db 5+6 份、音频 22 文件，共 5.4M，属主 kts_bak）；pg_restore --list 确认归档可恢复。
对象 工具 本机 异地（NAS /volume1/NetBackup/kaotings）
业务库 kaotings pg_dump --format=custom + tar /home/flym/backups/kaotings_<ts>.dump …/kaotings/db/
CMS 库 kaotings_cms pg_dump --format=custom + tar /home/flym/backups/kaotings_cms_<ts>.dump …/kaotings/db/
音频目录 tar over SSH /home/flym/kaotings-audio/ …/kaotings/audio/

仍待用户确认：音频保留期、磁盘告警阈值、是否启用按 expires_at 的定时清理（见 §5）；备份保留份数当前=7（可调脚本 KEEP）。如希望增量传输，请在 DSM 将 NetBackup 建为共享文件夹（见上“升级路径”）。

3. 容量 / 保留 / 清理（需用户决定的参数集中列出）

参数 当前值 需用户决定
音频保留期 AUDIO_RETENTION_SECONDS 7 天（默认） 是（产品/隐私/存储预算）
磁盘容量上限 / 告警阈值 根盘约 48 GiB 可用，无上限告警 是（阈值 + 通知方式）
保留期清理策略 未启用定时清理（仅启动时清孤儿） 是（是否按 expires_at 定时删除）
原始文本保留期 存于 tts_tasks.text 是（产品/隐私）
备份保留份数 / 周期 已配置：每库 7 份 · 每日 03:00 · 异地 NAS 否（可调脚本 KEEP 与 timer）
  • 清理安全边界：
    • 启动时 cleanup_orphan_audio 仅删除“无 available 记录且 mtime>1h”的孤儿文件。
    • 保留期清理在参数确认并实现后启用；在此之前不删除任何既有音频。
  • 告警：磁盘使用率超阈值、audio_files 与磁盘文件数量长期不一致、Worker 长期无 queued 消化。

4. 恢复（含隔离演练结果）

4.1 流程

  1. 停止写入（可选，视 RPO）：systemctl stop kaotings-api。
  2. 建空库 → pg_restore --clean --if-exists 业务库 / CMS 库。
  3. 音频：从 NAS 用 tar over SSH 拉回 /home/flym/kaotings-audio（源：/volume1/NetBackup/kaotings/audio/）。
  4. 校验：行数、音频文件↔audio_files 关联、checksum、额度↔流水一致（见 §4.2 校验 SQL）。
  5. systemctl start kaotings-api，/healthz 复核。

4.2 校验（隔离演练已执行）

  • 业务库行数源=恢复：users 35 / quota 34 / tasks 28 / audio 26 / usage 61 / grants 10。
  • 额度↔流水：used 与 consume、reserved 与 reserve-consume-release 均 0 不符。
  • 音频：磁盘 22 文件全部被 available 引用（无孤儿）。
  • 发现：4 条 status=available 且任务 succeeded 的 audio_files 行在磁盘无文件（既有不一致，回放 404 降级）。待调查根因（见 §6）。

4.3 Worker 重启 / 额度对账

  • 单 Worker（systemd 单进程），原子领取（FOR UPDATE SKIP LOCKED）+ 5 分钟租约 + 过期 running 回收（WORKER_LEASE_EXPIRED，释放冻结）。
  • 对账：GET /admin/usage/summary 汇总 quota_accounts 与 usage_records 口径；GET /admin/tts/tasks 查结算状态（consumed/released/pending）。
  • 不变式（每账户恒成立）：limit_snapshot + adjustment - used - reserved >= 0（由 Phase 5 异常矩阵 S3/S4 保证）。

5. 待用户确认清单（集中）

  1. 音频保留期（AUDIO_RETENTION_SECONDS）。
  2. 磁盘容量上限与告警阈值、通知方式。
  3. 是否启用按 expires_at 的定时保留期清理。
  4. 原始文本保留期。
  5. 备份：异地 NAS 已配置（103.40.14.100，每日 03:00，每库 7 份）；剩余待确认：保留份数/周期是否调整、备份责任人。
  6. 上游 HTTPS/加密端点、允许来源网段、凭据轮换（见 DEPLOYMENT.md §4）。

6. 待调查 / 未闭环项（不标为完成）

  • 4 条 available 音频行无对应文件：既有 DB/文件系统不一致，待定位根因（文件被外部删除 or 写入路径异常）；恢复流程本身通过。
  • 上游公网 HTTP：上线阻断，待加密 + 来源限制 + 外部复测（DEPLOYMENT.md §4）。
  • 音频容量/保留/清理参数：待用户确认（§5）。