From 568509027c119b57df42179915422094c0e6752c Mon Sep 17 00:00:00 2001 From: kdletters <61648117+kdletters@users.noreply.github.com> Date: Tue, 9 Jun 2026 12:35:27 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=86=B7=E5=A4=87=E4=BB=BD?= =?UTF-8?q?=E5=90=8E=20API=20=E6=81=A2=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 备份脚本支持冷备份后重启依赖服务 生产备份与发布脚本恢复 genarrative-api 服务 api-server 启动恢复 SpacetimeDB 超时后持续重试 同步更新后端与运维文档口径 --- .../genarrative-database-backup.service | 3 +- ...】server-rs与SpacetimeDB数据契约-2026-05-15.md | 2 +- ...发运维】本地开发验证与生产运维-2026-05-15.md | 6 ++-- scripts/database-backup-to-oss.mjs | 23 ++++++++++++- scripts/deploy/production-stdb-publish.sh | 4 ++- server-rs/crates/api-server/src/main.rs | 32 +++++++++++++++++-- 6 files changed, 60 insertions(+), 10 deletions(-) diff --git a/deploy/systemd/genarrative-database-backup.service b/deploy/systemd/genarrative-database-backup.service index cde294e2..a19481b6 100644 --- 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 - diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md index ed2a1676..2be25228 100644 --- 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/`、`phone/`、`session/`、`session_hash/`、`wechat/`、`union/`。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 本次快照包含的用户、身份和会话，避免过期快照把其他用户整表删除。 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index ac61896e..222508ea 100644 --- 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://///-.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 ` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 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://///-.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 ` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 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，以避免用空本地状态或旧快照覆盖认证表。 常用检查思路： diff --git a/scripts/database-backup-to-oss.mjs b/scripts/database-backup-to-oss.mjs index 5eac405b..b01cf557 100644 --- 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 ] [--work-dir ] [--bucket ] [--object-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 说明: @@ -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({ diff --git a/scripts/deploy/production-stdb-publish.sh b/scripts/deploy/production-stdb-publish.sh index 64f4e9dd..cdd60d41 100644 --- 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 前数据库备份" diff --git a/server-rs/crates/api-server/src/main.rs b/server-rs/crates/api-server/src/main.rs index 480d88db..1867c754 100644 --- 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 { + 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 { 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); + } }