补齐 API 构建产物中的数据库备份脚本

API 构建归档加入 scripts/database-backup-to-oss.mjs。

API 发布拉取上游构建产物时同步复制数据库备份脚本。

API 部署优先从构建产物写入 current release 的备份脚本，旧产物仅警告回退。

更新生产运维文档，记录 API release 必须携带备份脚本。

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

@@ -248,6 +248,8 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 
 `Genarrative-Web-Build` 会把 `build/<version>/web.tar.gz`、`web.tar.gz.sha256` 和 `release-manifest.json` 直接归档为 Jenkins 构建产物；`Genarrative-Web-Deploy` 只通过 `copyArtifacts` 从指定上游构建复制这些产物，再执行 `scripts/deploy/production-web-deploy.sh`。Web 发布不再读取构建机本地缓存目录，也不再通过 release agent `rsync` 回构建机拉取大包；如果 deploy 找不到 `web.tar.gz`，应先检查上游 Web Build 是否按同一 `BUILD_VERSION` 成功归档产物。
 
+`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json` 和 `scripts/database-backup-to-oss.mjs`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`Genarrative-Api-Deploy` 会优先从上游 API 构建产物复制该脚本到新的 API release 目录；如果 API 发布后 current release 中缺少该脚本，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/scripts/database-backup-to-oss.mjs`，不要只在部署机工作区手工补文件。
+
 `Genarrative-Web-Build` 打包 `web.tar.gz` 前、`Genarrative-Web-Deploy` 解包后都会把 Web 静态目录规范为目录 `755`、文件 `644`。如果前端页面能打开但 public 图片、字体或音频返回 `403 Forbidden`，优先检查当前 `/srv/genarrative/web` 指向的 release 中对应文件权限是否被异常归档为 `600`，临时恢复可对该 release 的 `web` 目录执行目录 `755`、文件 `644` 的权限修正。
 
 生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。其它构建 / 发布流水线仍按各自 Jenkinsfile 的 checkout 口径执行；所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。

jenkins/Jenkinsfile.production-api-build

@@ -104,7 +104,7 @@ pipeline {
 
     stage('Archive') {
       steps {
-        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json", fingerprint: true
+        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs", fingerprint: true
       }
     }
 

jenkins/Jenkinsfile.production-api-deploy

@@ -112,7 +112,7 @@ pipeline {
         copyArtifacts(
           projectName: params.BUILD_JOB_NAME,
           selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
-          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json",
+          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs",
           target: '.',
           fingerprintArtifacts: true
         )

scripts/deploy/production-api-deploy.sh

@@ -332,14 +332,20 @@ mkdir -p "${RELEASE_DIR}"
 cp "${SOURCE_DIR}/api-server" "${RELEASE_DIR}/api-server"
 chmod +x "${RELEASE_DIR}/api-server"
 
-SCRIPT_SOURCE_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts"
+BACKUP_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
+WORKSPACE_BACKUP_SCRIPT_SOURCE="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts/database-backup-to-oss.mjs"
 mkdir -p "${RELEASE_DIR}/scripts"
-if [[ -f "${SCRIPT_SOURCE_DIR}/database-backup-to-oss.mjs" ]]; then
-  cp "${SCRIPT_SOURCE_DIR}/database-backup-to-oss.mjs" "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
-  chmod 0644 "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
-else
-  echo "[production-api-deploy] 未找到数据库备份脚本，release 目录不会包含 scripts/database-backup-to-oss.mjs" >&2
+if [[ ! -f "${BACKUP_SCRIPT_SOURCE}" ]]; then
+  if [[ -f "${WORKSPACE_BACKUP_SCRIPT_SOURCE}" ]]; then
+    echo "[production-api-deploy] 发布产物缺少 scripts/database-backup-to-oss.mjs，回退使用部署工作区脚本；请重新触发包含该脚本的 API 构建。" >&2
+    BACKUP_SCRIPT_SOURCE="${WORKSPACE_BACKUP_SCRIPT_SOURCE}"
+  else
+    echo "[production-api-deploy] 缺少数据库备份脚本: ${SOURCE_DIR}/scripts/database-backup-to-oss.mjs" >&2
+    exit 1
+  fi
 fi
+cp "${BACKUP_SCRIPT_SOURCE}" "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
+chmod 0644 "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
 
 if [[ -f "${SOURCE_DIR}/release-manifest.json" ]]; then
   cp "${SOURCE_DIR}/release-manifest.json" "${RELEASE_DIR}/release-manifest.api-server.json"