feat: automate database OSS backups

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -1,4 +1,4 @@
-# 本地开发验证与生产运维
+# 本地开发验证与生产运维
 
 更新时间：`2026-05-15`
 
@@ -193,6 +193,31 @@ UI 相关修改要重点验证：
 6. Jenkins 数据库导入 / 导出流水线会先加载 `scripts/jenkins-prepare-toolchain-env.sh`，显式补齐 Jenkins 用户的 Node、Cargo、SpacetimeDB 工具链目录；如果目标机器安装路径不同，用 `GENARRATIVE_JENKINS_TOOL_PATHS` 传入额外 `bin` 目录。
 7. 本地 `npm run dev` / `npm run dev:api-server` 若没有显式 `GENARRATIVE_SPACETIME_TOKEN`，会在 SpacetimeDB 就绪后调用 `/v1/identity` 创建当前进程专用 Web API identity token，并只注入本次 `api-server` 环境，不写回 `.env.local`。启动日志只打印 identity 前缀，禁止打印 token 明文；若仍出现 `subscribe ... 401 Unauthorized`，先确认是否绕过了项目 dev 脚本或是否连接到非本次启动的 SpacetimeDB server。
 
+### SpacetimeDB 数据目录 OSS 备份
+
+数据库备份不放进 `spacetime-module` reducer / procedure：备份属于文件系统与 OSS 外部副作用，必须由运维脚本在 SpacetimeDB 宿主外执行。当前统一脚本为；生产 provision 还会安装 `genarrative-database-backup.timer`，每天 `03:20` 左右自动执行一次 OSS 冷备份：
+
+```bash
+npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service
+```
+
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS。`Genarrative-Stdb-Module-Publish` 默认也会在 `spacetime publish` 前执行同一脚本；备份失败会阻断 publish，只有显式勾选 `SKIP_DATABASE_BACKUP` 或脚本参数 `--skip-backup` 才跳过。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+
+生产环境变量模板在 `deploy/env/api-server.env.example`：
+
+```env
+GENARRATIVE_DATABASE_BACKUP_DATA_DIR=/stdb
+GENARRATIVE_DATABASE_BACKUP_WORK_DIR=/var/lib/genarrative/database-backups
+GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET=
+GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com
+GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX=database-backups
+GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL=false
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
+```
+
+`GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET` 为空时会回退 `ALIYUN_OSS_BUCKET`；AccessKey 默认复用 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，也可用 `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID` / `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET` 为备份 bucket 单独配置最小权限账号。`Genarrative-Server-Provision` 会创建 `/var/lib/genarrative/database-backups` 并归属 `genarrative:genarrative`，同时安装并启用 `genarrative-database-backup.timer`。手动检查定时器：`systemctl list-timers genarrative-database-backup.timer`；手动触发一次：`systemctl start genarrative-database-backup.service`。
+
 ## 生产运维
 
 生产部署当前口径：
@@ -264,6 +289,7 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
 - `GENARRATIVE_SPACETIME_SERVER_URL`
 - `GENARRATIVE_SPACETIME_DATABASE`
 - `GENARRATIVE_SPACETIME_TOKEN`
+- `GENARRATIVE_DATABASE_BACKUP_*`
 - `GENARRATIVE_LLM_*`
 - `APIMART_*`
 - `VECTOR_ENGINE_*`
@@ -386,3 +412,5 @@ SELECT * FROM profile_recharge_product_config ORDER BY sort_order ASC;
 ## 文档维护
 
 当前 `docs/` 只保留少量融合文档。新增稳定知识时优先更新现有文档；只有现有文档无法容纳时才新增带 `【标签名】` 的 Markdown。阶段性流水账、一次性修复记录和已关闭实验不要再新增成长期文档。
+
+