From 62dba457993aaf215a8c2ae408a0715fb21aeae2 Mon Sep 17 00:00:00 2001 From: flym Date: Thu, 10 Sep 2026 16:25:45 +0800 Subject: [PATCH] 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. --- docs/OPERATIONS.md | 24 +++++++++++++----------- docs/phase-5-report.md | 9 +++++---- 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 61c9187..b5f050f 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -13,22 +13,24 @@ ## 2. 备份（已配置异地备份） - 本机暂存：`/home/flym/backups/`（仅存放 `.dump`）。 -- 异地备份目标：**Synology NAS** `103.40.14.100`（Synology DSM），账号 `kts_bak`，落盘 `/var/services/homes/kts_bak/backup/kaotings/`（`db/` + `audio/`），可用容量约 92 GiB。 -- 传输方式：**rsync over SSH**（端口 `52200`，**加密**），密钥认证（`/root/.ssh/id_ed25519_ktsbak`，公钥已加入 NAS `kts_bak` 的 `authorized_keys`）。**不使用** 公网明文 rsync 守护端口 `50873`。 +- 异地备份目标：**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. `rsync -a --delete` 增量镜像 `db/` 与 `audio/`（`AUDIO_STORAGE_DIR`）到 NAS。 + 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`。 -- 验证：首份备份已落盘（业务库 54K、CMS 48K、音频 22 文件 4.8M）；`pg_restore --list` 确认归档可恢复。 +- 验证：备份已落盘 `/volume1/NetBackup/kaotings`（db 5+6 份、音频 22 文件，共 5.4M，属主 `kts_bak`）；`pg_restore --list` 确认归档可恢复。 -| 对象 | 工具 | 本机 | 异地（NAS） | +| 对象 | 工具 | 本机 | 异地（NAS `/volume1/NetBackup/kaotings`） | | --- | --- | --- | --- | -| 业务库 `kaotings` | `pg_dump --format=custom` | `/home/flym/backups/kaotings_.dump` | `…/backup/kaotings/db/` | -| CMS 库 `kaotings_cms` | `pg_dump --format=custom` | `/home/flym/backups/kaotings_cms_.dump` | `…/backup/kaotings/db/` | -| 音频目录 | `rsync -a --delete` | `/home/flym/kaotings-audio/` | `…/backup/kaotings/audio/` | +| 业务库 `kaotings` | `pg_dump --format=custom` + tar | `/home/flym/backups/kaotings_.dump` | `…/kaotings/db/` | +| CMS 库 `kaotings_cms` | `pg_dump --format=custom` + tar | `/home/flym/backups/kaotings_cms_.dump` | `…/kaotings/db/` | +| 音频目录 | tar over SSH | `/home/flym/kaotings-audio/` | `…/kaotings/audio/` | -> 仍待用户确认：音频保留期、磁盘告警阈值、是否启用按 `expires_at` 的定时清理（见 §5）。备份保留份数当前=7，可按需调整脚本 `KEEP`。 +> 仍待用户确认：音频保留期、磁盘告警阈值、是否启用按 `expires_at` 的定时清理（见 §5）；备份保留份数当前=7（可调脚本 `KEEP`）。如希望增量传输，请在 DSM 将 `NetBackup` 建为共享文件夹（见上“升级路径”）。 ## 3. 容量 / 保留 / 清理（需用户决定的参数集中列出） @@ -51,7 +53,7 @@ 1. 停止写入（可选，视 RPO）：`systemctl stop kaotings-api`。 2. 建空库 → `pg_restore --clean --if-exists` 业务库 / CMS 库。 -3. 音频：从 NAS 异地备份 `rsync`/`scp` 回 `/home/flym/kaotings-audio`（源：`…/backup/kaotings/audio/`）。 +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` 复核。 diff --git a/docs/phase-5-report.md b/docs/phase-5-report.md index 500893c..20aa146 100644 --- a/docs/phase-5-report.md +++ b/docs/phase-5-report.md @@ -92,10 +92,11 @@ ### 3.3 异地备份（本阶段后续配置，已落地） -- 用户提供异地 NAS（Synology）`103.40.14.100`（SSH `52200` / rsync 守护 `50873`）。 -- 采用 **rsync over SSH（52200，加密 + 密钥认证）**，不使用公网明文 rsync 守护端口；密钥 `/root/.ssh/id_ed25519_ktsbak`，公钥加入 NAS `kts_bak`。 -- 脚本 `/usr/local/sbin/kaotings-backup.sh`（root）：`pg_dump` 业务库 + CMS 库（每库保留 7 份）+ `rsync -a --delete` 音频目录 → `…/backup/kaotings/{db,audio}/`；systemd `kaotings-backup.timer` 每日 03:00 触发。 -- 首份备份已落盘并 `pg_restore --list` 验证可恢复；详见 `OPERATIONS.md` §2。 +- 用户提供异地 NAS（Synology）`103.40.14.100`（SSH `52200` / rsync 守护 `50873`）。按要求**不放 home**，落盘 `/volume1/NetBackup/kaotings/`（`db/`+`audio/`）。 +- 采用 **tar over SSH（52200，加密 + 密钥认证）**，不使用公网明文 rsync 守护端口；密钥 `/root/.ssh/id_ed25519_ktsbak`，公钥加入 NAS `kts_bak`。 + - 说明：`/volume1/NetBackup` 为普通目录（非 DSM 共享文件夹），Synology 限制 rsync-over-SSH 仅写共享文件夹，且 `scp` 生成 root 属主文件不可轮转，故选 tar over SSH（文件属主 `kts_bak`，可轮转）。若后续在 DSM 建为共享文件夹，可改回 rsync 增量。 +- 脚本 `/usr/local/sbin/kaotings-backup.sh`（root）：`pg_dump` 业务库 + CMS 库（每库保留 7 份）+ `tar` 传音频目录 → `/volume1/NetBackup/kaotings/{db,audio}/`；systemd `kaotings-backup.timer` 每日 03:00 触发。 +- 已验证：备份落盘（db 5+6 份、音频 22 文件，5.4M，属主 `kts_bak`），`pg_restore --list` 确认可恢复；详见 `OPERATIONS.md` §2。 - 仍待确认：保留份数/周期、磁盘告警阈值、责任人（`OPERATIONS.md` §5）。 ## 4. 上游安全改造（上线阻断，待外部条件）