fix deploy backup blocking publish

2026-05-28 01:42:01 +08:00
parent 0eee0dd53e
commit 23f6317c8b
4 changed files with 70 additions and 25 deletions
--- a/.hermes/shared-memory/development-workflow.md
+++ b/.hermes/shared-memory/development-workflow.md
@@ -95,6 +95,8 @@ npm run dev:admin-web

 开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。

+生产 `Genarrative-Stdb-Module-Publish` 的备份默认使用 `DATABASE_BACKUP_MODE=async`：流水线在 publish 成功并退出维护模式后只触发服务器上的 `genarrative-database-backup.service`，避免低带宽 OSS 上传长时间占住部署窗口。需要强制在 publish 前等待备份并让失败阻断发布时，手动选择 `DATABASE_BACKUP_MODE=sync`；已有其他备份窗口且明确接受风险时才选择 `skip`。
+
 查看本地 Rust/SpacetimeDB 日志：

 ```bash
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -201,7 +201,7 @@ UI 相关修改要重点验证：
 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 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+脚本会将数据目录打包成 `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 成功并退出维护模式后通过 `systemctl start --no-block genarrative-database-backup.service` 触发服务器后台备份，不等待上传完成，也不因备份上传耗时阻塞发布；需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步执行，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。

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

--- a/jenkins/Jenkinsfile.production-stdb-module-publish
+++ b/jenkins/Jenkinsfile.production-stdb-module-publish
@@ -27,7 +27,7 @@ pipeline {
    string(name: 'SPACETIME_ROOT_DIR', defaultValue: '/stdb', description: 'spacetime CLI root-dir；需与自托管 spacetimedb.service 一致')
    string(name: 'SPACETIME_RUN_AS_USER', defaultValue: 'spacetimedb', description: '执行 spacetime publish 的本机用户，默认使用自托管服务用户')
    booleanParam(name: 'CLEAR_DATABASE', defaultValue: false, description: '是否清空数据库后发布')
-    booleanParam(name: 'SKIP_DATABASE_BACKUP', defaultValue: false, description: '是否跳过 publish 前 OSS 数据库备份；默认不跳过，备份失败会阻断发布')
+    choice(name: 'DATABASE_BACKUP_MODE', choices: ['async', 'sync', 'skip'], description: '数据库备份策略：async 在 publish 成功后触发服务器 systemd 备份并继续；sync 在 publish 前等待备份完成且失败阻断；skip 跳过')
  }

  stages {
@@ -139,7 +139,11 @@ pipeline {
      steps {
        script {
          def clearArg = params.CLEAR_DATABASE ? '--clear-database' : ''
-          def backupArg = params.SKIP_DATABASE_BACKUP ? '--skip-backup' : ''
+          def backupMode = params.DATABASE_BACKUP_MODE?.trim() ? params.DATABASE_BACKUP_MODE.trim() : 'async'
+          if (!(backupMode in ['async', 'sync', 'skip'])) {
+            error("DATABASE_BACKUP_MODE 只能是 async、sync 或 skip: ${backupMode}")
+          }
+          def backupArg = "--backup-mode \"${backupMode}\""
          def rootArg = "--root-dir \"${params.SPACETIME_ROOT_DIR?.trim() ? params.SPACETIME_ROOT_DIR.trim() : '/stdb'}\""
          def runAsArg = params.SPACETIME_RUN_AS_USER?.trim()
            ? "--run-as-user \"${params.SPACETIME_RUN_AS_USER.trim()}\""
--- a/scripts/deploy/production-stdb-publish.sh
+++ b/scripts/deploy/production-stdb-publish.sh
@@ -5,14 +5,15 @@ set -euo pipefail
 usage() {
  cat <<'EOF'
 用法:
-  ./scripts/deploy/production-stdb-publish.sh --source-dir build/<version> --database <database> [--server-url http://127.0.0.1:3101] [--server local] [--root-dir /stdb] [--run-as-user spacetimedb] [--clear-database] [--skip-backup]
+  ./scripts/deploy/production-stdb-publish.sh --source-dir build/<version> --database <database> [--server-url http://127.0.0.1:3101] [--server local] [--root-dir /stdb] [--run-as-user spacetimedb] [--clear-database] [--backup-mode async|sync|skip]

 说明:
  进入维护模式，校验 spacetime_module.wasm.sha256，并在生产实例本机执行 spacetime publish。
  默认使用 http://127.0.0.1:3101，避免与部署机本机 Git/Web 服务的 3000 端口冲突。
  默认使用 /stdb 作为 spacetime CLI root-dir，并以 spacetimedb 用户发布，避免 root CLI 身份污染自托管实例。
  发布时固定追加 --no-config，只使用显式参数，避免工作区或用户目录里的 spacetime 配置干扰目标。
-  publish 前默认执行一次 OSS 冷备份；备份失败会阻断 publish。仅明确传入 --skip-backup 时跳过。
+  默认在 publish 成功后异步触发 genarrative-database-backup.service，避免低带宽 OSS 上传阻塞部署。
+  如需强制等待备份完成并在失败时阻断 publish，传入 --backup-mode sync。
  失败时保留维护模式。
 EOF
 }
@@ -44,7 +45,7 @@ SERVER_URL="http://127.0.0.1:3101"
 SPACETIME_ROOT_DIR="/stdb"
 RUN_AS_USER="spacetimedb"
 CLEAR_DATABASE=0
-SKIP_BACKUP=0
+BACKUP_MODE="${GENARRATIVE_STDB_PUBLISH_BACKUP_MODE:-async}"
 DEPLOY_COMPLETED=0
 PUBLISH_TMP_DIR=""

@@ -84,9 +85,17 @@ while [[ $# -gt 0 ]]; do
      shift
      ;;
    --skip-backup)
-      SKIP_BACKUP=1
+      BACKUP_MODE="skip"
      shift
      ;;
+    --sync-backup)
+      BACKUP_MODE="sync"
+      shift
+      ;;
+    --backup-mode)
+      BACKUP_MODE="${2:?缺少 --backup-mode 的值}"
+      shift 2
+      ;;
    *)
      echo "[production-stdb-publish] 未知参数: $1" >&2
      usage >&2
@@ -104,6 +113,11 @@ if [[ ! "${SPACETIME_ROOT_DIR}" == /* || "${SPACETIME_ROOT_DIR}" == *".."* ]]; t
  exit 1
 fi

+if [[ ! "${BACKUP_MODE}" =~ ^(async|sync|skip)$ ]]; then
+  echo "[production-stdb-publish] --backup-mode 只能是 async、sync 或 skip: ${BACKUP_MODE}" >&2
+  exit 1
+fi
+
 if [[ -n "${RUN_AS_USER}" && ! "${RUN_AS_USER}" =~ ^[A-Za-z_][A-Za-z0-9_-]*$ ]]; then
  echo "[production-stdb-publish] --run-as-user 只能是本机用户名: ${RUN_AS_USER}" >&2
  exit 1
@@ -134,27 +148,47 @@ on_exit() {

 trap on_exit EXIT

+trigger_async_backup() {
+  # Jenkins 发布路径不能被低带宽 OSS 上传长时间占住；默认只把已安装的 systemd
+  # oneshot 备份任务排队启动。必须放在 publish 成功后，避免冷备份停止 SpacetimeDB
+  # 与 spacetime publish 同时争用 spacetimedb.service。
+  if command -v systemctl >/dev/null 2>&1 && systemctl list-unit-files genarrative-database-backup.service --no-legend | grep -q '^genarrative-database-backup\.service'; then
+    echo "[production-stdb-publish] 异步触发数据库 OSS 备份，不等待上传完成"
+    if ! systemctl start --no-block genarrative-database-backup.service; then
+      echo "[production-stdb-publish] 警告：异步触发数据库备份失败；继续发布，请检查 genarrative-database-backup.service 日志" >&2
+    fi
+  else
+    echo "[production-stdb-publish] 警告：未找到 genarrative-database-backup.service，跳过异步备份触发" >&2
+  fi
+}
+
 "${SCRIPT_DIR}/maintenance-on.sh" "spacetime module publish ${DATABASE}"

-if [[ "${SKIP_BACKUP}" -ne 1 ]]; then
-  BACKUP_SCRIPT="${SCRIPT_DIR}/../database-backup-to-oss.mjs"
-  if [[ ! -f "${BACKUP_SCRIPT}" ]]; then
-    BACKUP_SCRIPT="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
-  fi
-  if [[ ! -f "${BACKUP_SCRIPT}" ]]; then
-    echo "[production-stdb-publish] 缺少 publish 前数据库备份脚本: ${BACKUP_SCRIPT}" >&2
-    exit 1
-  fi
+case "${BACKUP_MODE}" in
+  async)
+    echo "[production-stdb-publish] 将在 publish 成功后异步触发数据库 OSS 备份"
+    ;;
+  sync)
+    BACKUP_SCRIPT="${SCRIPT_DIR}/../database-backup-to-oss.mjs"
+    if [[ ! -f "${BACKUP_SCRIPT}" ]]; then
+      BACKUP_SCRIPT="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
+    fi
+    if [[ ! -f "${BACKUP_SCRIPT}" ]]; then
+      echo "[production-stdb-publish] 缺少 publish 前数据库备份脚本: ${BACKUP_SCRIPT}" >&2
+      exit 1
+    fi

-  echo "[production-stdb-publish] publish 前执行 OSS 冷备份"
-  node "${BACKUP_SCRIPT}" \
-    --env-file /etc/genarrative/api-server.env \
-    --data-dir "${SPACETIME_ROOT_DIR}" \
-    --database "${DATABASE}" \
-    --stop-service spacetimedb.service
-else
-  echo "[production-stdb-publish] 已按参数跳过 publish 前数据库备份"
-fi
+    echo "[production-stdb-publish] publish 前同步执行 OSS 冷备份，失败会阻断发布"
+    node "${BACKUP_SCRIPT}" \
+      --env-file /etc/genarrative/api-server.env \
+      --data-dir "${SPACETIME_ROOT_DIR}" \
+      --database "${DATABASE}" \
+      --stop-service spacetimedb.service
+    ;;
+  skip)
+    echo "[production-stdb-publish] 已按参数跳过 publish 前数据库备份"
+    ;;
+esac

 echo "[production-stdb-publish] 校验 wasm"
 (
@@ -218,4 +252,9 @@ fi

 "${SCRIPT_DIR}/maintenance-off.sh"
 DEPLOY_COMPLETED=1
+
+if [[ "${BACKUP_MODE}" == "async" ]]; then
+  trigger_async_backup
+fi
+
 echo "[production-stdb-publish] 完成"