修复冷备份后 API 恢复

备份脚本支持冷备份后重启依赖服务生产备份与发布脚本恢复 genarrative-api 服务 api-server 启动恢复 SpacetimeDB 超时后持续重试同步更新后端与运维文档口径
2026-06-09 12:35:27 +08:00
parent c9c66f046b
commit 568509027c
6 changed files with 60 additions and 10 deletions
--- a/deploy/systemd/genarrative-database-backup.service
+++ b/deploy/systemd/genarrative-database-backup.service
@@ -9,10 +9,9 @@ User=root
 Group=root
 WorkingDirectory=/opt/genarrative/current
 EnvironmentFile=/etc/genarrative/api-server.env
-ExecStart=/usr/bin/node /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --stop-service spacetimedb.service
+ExecStart=/usr/bin/node /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --stop-service spacetimedb.service --restart-service-after genarrative-api.service

 # 备份需要停止 / 启动 spacetimedb.service，并读取 /stdb、写入 /var/lib/genarrative/database-backups。
 PrivateTmp=true
 ProtectSystem=full
 ReadWritePaths=/stdb /var/lib/genarrative
-
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -254,7 +254,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`AuthStoreSnapshot`
 - 源码：`server-rs/crates/spacetime-module/src/auth/tables.rs`

-认证恢复策略：`api-server` 启动时只从 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）投影恢复进程内认证工作集；运行中若 Bearer `sid` 或 refresh cookie 在本进程工作集内未命中，会先从 SpacetimeDB 正式认证表按需刷新一次认证工作集再复查，避免多实例或滚动重启时新登录设备只被签发它的进程认识。`auth_store_snapshot` 只保留行级快照备查，不再作为启动兜底来源。`module-auth` 只保留内存工作集和 JSON 导入 / 导出能力，不再写本地持久化文件；`auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 不再是兼容恢复源，也不得在启动时回写覆盖 `auth_identity` / `user_account`。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB 正式认证表；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动恢复阶段 SpacetimeDB 不可连接或超时，`api-server` 进入依赖不可用模式并对请求返回 `503 SERVICE_UNAVAILABLE`，直到运维恢复 SpacetimeDB 并重启服务。
+认证恢复策略：`api-server` 启动时只从 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）投影恢复进程内认证工作集；运行中若 Bearer `sid` 或 refresh cookie 在本进程工作集内未命中，会先从 SpacetimeDB 正式认证表按需刷新一次认证工作集再复查，避免多实例或滚动重启时新登录设备只被签发它的进程认识。`auth_store_snapshot` 只保留行级快照备查，不再作为启动兜底来源。`module-auth` 只保留内存工作集和 JSON 导入 / 导出能力，不再写本地持久化文件；`auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 不再是兼容恢复源，也不得在启动时回写覆盖 `auth_identity` / `user_account`。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB 正式认证表；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动恢复阶段 SpacetimeDB 不可连接或超时，`api-server` 会按固定间隔持续重试认证工作集恢复，恢复成功后才开始监听 HTTP，避免一次短超时让进程永久停留在依赖不可用状态。

 `auth_store_snapshot` 禁止再写单行 `snapshot_id = "default"` 聚合 JSON。认证同步入口收到 `module-auth` 整份快照后必须拆成行级记录写入同一张表，当前行键前缀包括：`meta/next_user_id`、`user/<user_id>`、`phone/<phone+user>`、`session/<session_id>`、`session_hash/<hash+session>`、`wechat/<provider_uid+user>`、`union/<union+user>`。SpacetimeDB 模块只保留 `import_auth_store_snapshot_json` 与 `export_auth_store_snapshot_from_tables` 两个认证快照过程；旧 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot` 兼容入口已删除。导入正式表时只按主键 upsert 本次快照包含的用户、身份和会话，避免过期快照把其他用户整表删除。

--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -214,10 +214,10 @@ UI 相关修改要重点验证：
 数据库备份不放进 `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
+npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service
 ```

-脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service` 依赖 `spacetimedb.service`，生产定时冷备份还必须传入 `--restart-service-after genarrative-api.service`，确保备份后 API 随数据库一起恢复。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。

 生产环境变量模板在 `deploy/env/api-server.env.example`：

@@ -414,7 +414,7 @@ systemctl restart genarrative-api.service
 journalctl -u genarrative-api.service --since '30 seconds ago' --no-pager | grep -E 'tracking outbox|Permission denied|os error 13'
 ```

-`Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox` 归属 `genarrative:genarrative`。用户认证真相源只允许在 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）恢复；不要再配置或依赖 `GENARRATIVE_AUTH_STORE_PATH` / `auth-store.json`，`module-auth` 也不再维护本地文件持久化；`auth_store_snapshot` 只保留行级记录，不再保存为单行 `default` 聚合快照，且旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 入口已经删除。如果 `api-server` 启动时连不上 SpacetimeDB，会等待启动恢复，超时后继续监听但进入依赖不可用模式，所有请求统一返回 `503 SERVICE_UNAVAILABLE`，错误详情包含 `reason=spacetime_startup_unavailable`，以避免用空本地状态或旧快照覆盖认证表。
+`Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox` 归属 `genarrative:genarrative`。用户认证真相源只允许在 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）恢复；不要再配置或依赖 `GENARRATIVE_AUTH_STORE_PATH` / `auth-store.json`，`module-auth` 也不再维护本地文件持久化；`auth_store_snapshot` 只保留行级记录，不再保存为单行 `default` 聚合快照，且旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 入口已经删除。如果 `api-server` 启动时连不上 SpacetimeDB，会持续重试启动恢复，直到认证工作集从 SpacetimeDB 正式表恢复成功后才开始监听 HTTP，以避免用空本地状态或旧快照覆盖认证表。

 常用检查思路：

--- a/scripts/database-backup-to-oss.mjs
+++ b/scripts/database-backup-to-oss.mjs
@@ -20,7 +20,7 @@ const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
 function usage() {
  console.log(`用法:
  npm run database:backup:oss -- [--data-dir <path>] [--work-dir <path>] [--bucket <bucket>] [--object-prefix <prefix>] [--keep-local]
-  node scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--defer-upload]
+  node scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--restart-service-after genarrative-api.service] [--defer-upload]
  node scripts/database-backup-to-oss.mjs --upload-archive <path>

 说明:
@@ -100,6 +100,7 @@ function parseArgs(argv) {
    envFiles: [],
    keepLocal: false,
    stopService: '',
+    restartServicesAfter: [],
    database: '',
    dryRun: false,
    deferUpload: false,
@@ -159,6 +160,9 @@ function parseArgs(argv) {
      case '--stop-service':
        options.stopService = readValue();
        break;
+      case '--restart-service-after':
+        options.restartServicesAfter.push(readValue());
+        break;
      case '--keep-local':
        options.keepLocal = true;
        break;
@@ -266,6 +270,16 @@ function startServiceIfNeeded(serviceName, wasStopped) {
  runCommand('systemctl', ['start', serviceName], {stdio: 'inherit'});
 }

+function restartServicesAfterBackup(serviceNames) {
+  for (const serviceName of serviceNames) {
+    if (!serviceName) {
+      continue;
+    }
+    console.log(`[database-backup] 冷备份后重启依赖服务: ${serviceName}`);
+    runCommand('systemctl', ['restart', serviceName], {stdio: 'inherit'});
+  }
+}
+
 function createArchive({dataDir, workDir, fileName}) {
  if (!existsSync(dataDir)) {
    throw new Error(`数据库数据目录不存在: ${dataDir}`);
@@ -510,6 +524,13 @@ async function main() {
  } finally {
    startServiceIfNeeded(args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE), serviceStopped);
  }
+  restartServicesAfterBackup([
+    ...String(env.GENARRATIVE_DATABASE_BACKUP_RESTART_SERVICE_AFTER ?? '')
+      .split(',')
+      .map((value) => value.trim())
+      .filter(Boolean),
+    ...args.restartServicesAfter,
+  ]);

  const manifestPath = `${archivePath}.manifest.json`;
  writeManifest({
--- a/scripts/deploy/production-stdb-publish.sh
+++ b/scripts/deploy/production-stdb-publish.sh
@@ -179,6 +179,7 @@ prepare_async_backup() {
    --data-dir "${SPACETIME_ROOT_DIR}" \
    --database "${DATABASE}" \
    --stop-service spacetimedb.service \
+    --restart-service-after genarrative-api.service \
    --defer-upload \
    --result-file "${ASYNC_BACKUP_STATUS_FILE}"
 }
@@ -257,7 +258,8 @@ case "${BACKUP_MODE}" in
      --env-file /etc/genarrative/api-server.env \
      --data-dir "${SPACETIME_ROOT_DIR}" \
      --database "${DATABASE}" \
-      --stop-service spacetimedb.service
+      --stop-service spacetimedb.service \
+      --restart-service-after genarrative-api.service
    ;;
  skip)
    echo "[production-stdb-publish] 已按参数跳过 publish 前数据库备份"
--- a/server-rs/crates/api-server/src/main.rs
+++ b/server-rs/crates/api-server/src/main.rs
@@ -119,6 +119,7 @@ use crate::{

 const API_SERVER_STARTUP_STACK_SIZE_BYTES: usize = 32 * 1024 * 1024;
 const AUTH_STORE_STARTUP_RESTORE_TIMEOUT: Duration = Duration::from_secs(8);
+const AUTH_STORE_STARTUP_RETRY_INTERVAL: Duration = Duration::from_secs(5);

 #[derive(Clone)]
 struct ShutdownContext {
@@ -318,6 +319,25 @@ fn build_tcp_listener(

 async fn restore_app_state_for_startup(
    config: AppConfig,
+) -> Result<AppState, state::AppStateInitError> {
+    loop {
+        match try_restore_app_state_for_startup(config.clone()).await {
+            Ok(state) => return Ok(state),
+            Err(state::AppStateInitError::DependencyUnavailable(message)) => {
+                warn!(
+                    retry_after_seconds = AUTH_STORE_STARTUP_RETRY_INTERVAL.as_secs(),
+                    error = %message,
+                    "启动恢复 SpacetimeDB 认证快照暂不可用，api-server 将继续重试"
+                );
+                tokio::time::sleep(AUTH_STORE_STARTUP_RETRY_INTERVAL).await;
+            }
+            Err(error) => return Err(error),
+        }
+    }
+}
+
+async fn try_restore_app_state_for_startup(
+    config: AppConfig,
 ) -> Result<AppState, state::AppStateInitError> {
    match timeout(
        AUTH_STORE_STARTUP_RESTORE_TIMEOUT,
@@ -329,7 +349,7 @@ async fn restore_app_state_for_startup(
        Err(_) => {
            error!(
                timeout_seconds = AUTH_STORE_STARTUP_RESTORE_TIMEOUT.as_secs(),
-                "启动等待 SpacetimeDB 恢复认证快照超时，api-server 将进入依赖不可用模式"
+                "启动等待 SpacetimeDB 恢复认证快照超时"
            );
            Err(state::AppStateInitError::DependencyUnavailable(
                "SpacetimeDB 启动恢复认证快照超时".to_string(),
@@ -412,7 +432,10 @@ fn is_valid_env_key(key: &str) -> bool {

 #[cfg(test)]
 mod tests {
-    use super::{is_valid_env_key, protected_env_keys_from, strip_env_value};
+    use super::{
+        AUTH_STORE_STARTUP_RETRY_INTERVAL, is_valid_env_key, protected_env_keys_from,
+        strip_env_value,
+    };

    #[test]
    fn strip_env_value_removes_wrapping_quotes() {
@@ -453,4 +476,9 @@ mod tests {
        assert!(!protected.contains("ALIYUN_OSS_ENDPOINT"));
        assert!(protected.contains("ALIYUN_OSS_ACCESS_KEY_ID"));
    }
+
+    #[test]
+    fn startup_dependency_retry_interval_is_short_enough_for_service_recovery() {
+        assert_eq!(AUTH_STORE_STARTUP_RETRY_INTERVAL.as_secs(), 5);
+    }
 }