Merge remote-tracking branch 'origin/master' into codex/wechat-mini-program-virtual-payment

# Conflicts:
#	.hermes/shared-memory/decision-log.md

scripts/build-production-release.sh

@@ -461,6 +461,7 @@ copy_required_file "${SCRIPT_DIR}/spacetime-import-migration-json.mjs" "${TARGET
 copy_required_file "${SCRIPT_DIR}/spacetime-migration-common.mjs" "${TARGET_DIR}/scripts/spacetime-migration-common.mjs" "数据库迁移公共脚本"
 copy_required_file "${SCRIPT_DIR}/spacetime-authorize-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-authorize-migration-operator.mjs" "数据库迁移授权脚本"
 copy_required_file "${SCRIPT_DIR}/spacetime-revoke-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-revoke-migration-operator.mjs" "数据库迁移撤权脚本"
+copy_required_file "${SCRIPT_DIR}/database-backup-to-oss.mjs" "${TARGET_DIR}/scripts/database-backup-to-oss.mjs" "数据库 OSS 备份脚本"
 
 copy_required_dir "${REPO_ROOT}/deploy/systemd" "${TARGET_DIR}/deploy/systemd" "systemd 配置"
 copy_required_dir "${REPO_ROOT}/deploy/nginx" "${TARGET_DIR}/deploy/nginx" "Nginx 配置"
@@ -480,7 +481,7 @@ cat >"${TARGET_DIR}/README.md" <<EOF
 - \`migration-bootstrap-secret.txt\`：构建 \`spacetime_module.wasm\` 时注入的迁移引导密钥，仅用于创建首个迁移操作员；请作为敏感文件保存到 Jenkins Secret Text，授权完成后不要长期留在公开归档中。
 - \`*.sha256\`：发布产物 checksum，用于部署前校验。
 - \`release-manifest.json\`：发布版本、源码 commit 与产物清单。
-- \`scripts/\`：维护模式脚本、数据库导入导出脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
+- \`scripts/\`：维护模式脚本、数据库导入导出脚本、数据库 OSS 备份脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
 - \`deploy/\`：systemd、Nginx 和生产环境变量示例；\`deploy/nginx/genarrative-dev-http.conf\` 仅供无域名开发服初始化使用。
 
 ## 生产部署口径

scripts/database-backup-to-oss.mjs

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+import {spawnSync} from 'node:child_process';
+import {createHash, createHmac} from 'node:crypto';
+import {createReadStream, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {basename, dirname, isAbsolute, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, '..');
+const DEFAULT_LOCAL_DATA_DIR = resolve(REPO_ROOT, 'server-rs/.spacetimedb/local/data');
+const DEFAULT_LOCAL_WORK_DIR = resolve(REPO_ROOT, 'server-rs/.data/database-backups');
+const DEFAULT_PRODUCTION_DATA_DIR = '/stdb';
+const DEFAULT_PRODUCTION_WORK_DIR = '/var/lib/genarrative/database-backups';
+const OSS_ALGORITHM = 'OSS4-HMAC-SHA256';
+const OSS_SERVICE = 'oss';
+const OSS_REQUEST = 'aliyun_v4_request';
+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]
+
+说明:
+  将 SpacetimeDB 数据目录打包成 .tar.gz，并上传到阿里云 OSS 指定 bucket。
+  默认读取 .env / .env.local / .env.secrets.local；生产服务可传 --env-file /etc/genarrative/api-server.env。
+  shell 环境变量优先级最高，不会被 env 文件覆盖。
+
+常用环境变量:
+  GENARRATIVE_DATABASE_BACKUP_DATA_DIR        数据目录；生产建议 /stdb
+  GENARRATIVE_DATABASE_BACKUP_WORK_DIR        本地临时备份目录；生产建议 /var/lib/genarrative/database-backups
+  GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET      备份 bucket；未设置时回退 ALIYUN_OSS_BUCKET
+  GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX      对象前缀，默认 database-backups
+  GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT    OSS endpoint；未设置时回退 ALIYUN_OSS_ENDPOINT
+  GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL      true 时保留本地 tar.gz
+  ALIYUN_OSS_ACCESS_KEY_ID / ALIYUN_OSS_ACCESS_KEY_SECRET
+`);
+}
+
+function loadEnvFile(filePath, target, protectedKeys) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  const rawText = readFileSync(filePath, 'utf8');
+  for (const rawLine of rawText.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u);
+    if (!match) {
+      continue;
+    }
+    const [, key, rawValue] = match;
+    if (protectedKeys.has(key)) {
+      continue;
+    }
+    target[key] = rawValue.replace(/^['"]|['"]$/gu, '');
+  }
+}
+
+function loadRepoEnv() {
+  const env = {...process.env};
+  const protectedKeys = new Set(
+    Object.entries(process.env)
+      .filter(([, value]) => String(value ?? '').trim())
+      .map(([key]) => key),
+  );
+  for (const fileName of ['.env', '.env.local', '.env.secrets.local']) {
+    loadEnvFile(resolve(REPO_ROOT, fileName), env, protectedKeys);
+  }
+  return env;
+}
+
+function loadEffectiveEnv(envFiles) {
+  const env = loadRepoEnv();
+  const protectedKeys = new Set(
+    Object.entries(process.env)
+      .filter(([, value]) => String(value ?? '').trim())
+      .map(([key]) => key),
+  );
+  for (const filePath of envFiles) {
+    loadEnvFile(resolvePath(filePath), env, protectedKeys);
+  }
+  return env;
+}
+
+function parseArgs(argv) {
+  const options = {
+    dataDir: '',
+    workDir: '',
+    bucket: '',
+    endpoint: '',
+    objectPrefix: '',
+    accessKeyId: '',
+    accessKeySecret: '',
+    envFiles: [],
+    keepLocal: false,
+    stopService: '',
+    database: '',
+    dryRun: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const readValue = () => {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${arg} 缺少参数值`);
+      }
+      index += 1;
+      return value;
+    };
+
+    switch (arg) {
+      case '--help':
+      case '-h':
+        usage();
+        process.exit(0);
+        break;
+      case '--data-dir':
+        options.dataDir = readValue();
+        break;
+      case '--work-dir':
+        options.workDir = readValue();
+        break;
+      case '--bucket':
+        options.bucket = readValue();
+        break;
+      case '--endpoint':
+        options.endpoint = readValue();
+        break;
+      case '--object-prefix':
+        options.objectPrefix = readValue();
+        break;
+      case '--access-key-id':
+        options.accessKeyId = readValue();
+        break;
+      case '--access-key-secret':
+        options.accessKeySecret = readValue();
+        break;
+      case '--env-file':
+        options.envFiles.push(readValue());
+        break;
+      case '--database':
+        options.database = readValue();
+        break;
+      case '--stop-service':
+        options.stopService = readValue();
+        break;
+      case '--keep-local':
+        options.keepLocal = true;
+        break;
+      case '--dry-run':
+        options.dryRun = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function firstNonEmpty(...values) {
+  return values.map((value) => String(value ?? '').trim()).find(Boolean) ?? '';
+}
+
+function resolvePath(value) {
+  return isAbsolute(value) ? value : resolve(REPO_ROOT, value);
+}
+
+function normalizeEndpoint(raw) {
+  return String(raw ?? '')
+    .trim()
+    .replace(/^https?:\/\//u, '')
+    .replace(/\/+$/u, '');
+}
+
+function sanitizeObjectPart(value, fallback) {
+  const sanitized = String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/gu, '-')
+    .replace(/-+/gu, '-')
+    .replace(/^-|-$/gu, '');
+  return sanitized || fallback;
+}
+
+function timestampForFile(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}T${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}Z`;
+}
+
+function buildBackupNames({database, dataDir, objectPrefix}) {
+  const timestamp = timestampForFile();
+  const databasePart = sanitizeObjectPart(database || basename(dataDir), 'spacetimedb');
+  const fileName = `${databasePart}-${timestamp}.tar.gz`;
+  const prefix = String(objectPrefix || 'database-backups')
+    .trim()
+    .replace(/^\/+|\/+$/gu, '')
+    .split('/')
+    .filter(Boolean)
+    .map((part) => sanitizeObjectPart(part, 'backup'))
+    .join('/');
+  const objectKey = [prefix, databasePart, fileName].filter(Boolean).join('/');
+  return {fileName, objectKey};
+}
+
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd ?? REPO_ROOT,
+    env: options.env ?? process.env,
+    encoding: 'utf8',
+    stdio: options.stdio ?? 'pipe',
+    shell: process.platform === 'win32',
+  });
+  if (result.error) {
+    throw new Error(`${command} 启动失败: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    throw new Error(`${command} 退出码 ${result.status}: ${output}`);
+  }
+  return result;
+}
+
+function stopServiceIfNeeded(serviceName) {
+  if (!serviceName) {
+    return false;
+  }
+  console.log(`[database-backup] 停止服务以获取冷备份: ${serviceName}`);
+  runCommand('systemctl', ['stop', serviceName], {stdio: 'inherit'});
+  return true;
+}
+
+function startServiceIfNeeded(serviceName, wasStopped) {
+  if (!serviceName || !wasStopped) {
+    return;
+  }
+  console.log(`[database-backup] 恢复服务: ${serviceName}`);
+  runCommand('systemctl', ['start', serviceName], {stdio: 'inherit'});
+}
+
+function createArchive({dataDir, workDir, fileName}) {
+  if (!existsSync(dataDir)) {
+    throw new Error(`数据库数据目录不存在: ${dataDir}`);
+  }
+  const stat = statSync(dataDir);
+  if (!stat.isDirectory()) {
+    throw new Error(`数据库数据路径不是目录: ${dataDir}`);
+  }
+  mkdirSync(workDir, {recursive: true});
+  const archivePath = resolve(workDir, fileName);
+  const parentDir = dirname(dataDir);
+  const entryName = basename(dataDir);
+  console.log(`[database-backup] 打包: ${dataDir} -> ${archivePath}`);
+  runCommand('tar', ['-czf', archivePath, '-C', parentDir, entryName], {stdio: 'inherit'});
+  return archivePath;
+}
+
+function hmac(key, content, encoding) {
+  return createHmac('sha256', key).update(content).digest(encoding);
+}
+
+function sha256Hex(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function regionFromEndpoint(endpoint) {
+  const match = /^oss-([a-z0-9-]+)\./u.exec(endpoint);
+  if (!match) {
+    throw new Error(`无法从 OSS endpoint 推断 region: ${endpoint}`);
+  }
+  return match[1];
+}
+
+function formatScopeDate(date) {
+  return timestampForFile(date).slice(0, 8);
+}
+
+function formatOssDate(date) {
+  return timestampForFile(date).replace(/[-:]/gu, '');
+}
+
+function encodePath(path) {
+  return path
+    .split('/')
+    .map((segment) => encodeURIComponent(segment).replace(/[!'()*]/gu, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`))
+    .join('/');
+}
+
+function canonicalHeaderValue(value) {
+  return String(value).trim().replace(/\s+/gu, ' ');
+}
+
+function buildAuthorization({method, bucket, endpoint, objectKey, accessKeyId, accessKeySecret, headers, date}) {
+  const region = regionFromEndpoint(endpoint);
+  const scopeDate = formatScopeDate(date);
+  const scope = `${scopeDate}/${region}/${OSS_SERVICE}/${OSS_REQUEST}`;
+  const canonicalUri = `/${encodeURIComponent(bucket)}/${encodePath(objectKey)}`;
+  const signedHeaders = Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [key.toLowerCase(), canonicalHeaderValue(value)]),
+  );
+  const canonicalHeaders = Object.entries(signedHeaders)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `${key}:${value}\n`)
+    .join('');
+  const additionalHeaders = 'host';
+  const canonicalRequest = [
+    method,
+    canonicalUri,
+    '',
+    canonicalHeaders,
+    additionalHeaders,
+    UNSIGNED_PAYLOAD,
+  ].join('\n');
+  const stringToSign = [OSS_ALGORITHM, headers['x-oss-date'], scope, sha256Hex(canonicalRequest)].join('\n');
+  const signature = hmac(Buffer.from(`aliyun_v4${accessKeySecret}`, 'utf8'), scopeDate);
+  const regionKey = hmac(signature, region);
+  const serviceKey = hmac(regionKey, OSS_SERVICE);
+  const signingKey = hmac(serviceKey, OSS_REQUEST);
+  const finalSignature = hmac(signingKey, stringToSign, 'hex');
+  return `${OSS_ALGORITHM} Credential=${accessKeyId}/${scope},AdditionalHeaders=${additionalHeaders},Signature=${finalSignature}`;
+}
+
+async function uploadArchive({archivePath, bucket, endpoint, objectKey, accessKeyId, accessKeySecret}) {
+  const fileStat = statSync(archivePath);
+  const now = new Date();
+  const targetUrl = `https://${bucket}.${endpoint}/${encodePath(objectKey)}`;
+  const headers = {
+    host: `${bucket}.${endpoint}`,
+    'content-type': 'application/gzip',
+    'x-oss-content-sha256': UNSIGNED_PAYLOAD,
+    'x-oss-date': formatOssDate(now),
+    'x-oss-meta-backup-kind': 'spacetimedb-data-dir',
+  };
+  const authorization = buildAuthorization({
+    method: 'PUT',
+    bucket,
+    endpoint,
+    objectKey,
+    accessKeyId,
+    accessKeySecret,
+    headers,
+    date: now,
+  });
+
+  console.log(`[database-backup] 上传 OSS: oss://${bucket}/${objectKey}`);
+  const response = await fetch(targetUrl, {
+    method: 'PUT',
+    headers: {
+      ...headers,
+      authorization,
+      'content-length': String(fileStat.size),
+    },
+    body: createReadStream(archivePath),
+    duplex: 'half',
+  });
+
+  const responseText = await response.text();
+  if (!response.ok) {
+    throw new Error(`OSS 上传失败 HTTP ${response.status}: ${responseText.slice(0, 500)}`);
+  }
+
+  return {
+    bucket,
+    objectKey,
+    contentLength: fileStat.size,
+    etag: response.headers.get('etag')?.replace(/^"|"$/gu, '') ?? '',
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const env = loadEffectiveEnv(args.envFiles);
+  const isProductionLike = existsSync(DEFAULT_PRODUCTION_DATA_DIR) && process.platform !== 'win32';
+  const dataDir = resolvePath(firstNonEmpty(
+    args.dataDir,
+    env.GENARRATIVE_DATABASE_BACKUP_DATA_DIR,
+    isProductionLike ? DEFAULT_PRODUCTION_DATA_DIR : DEFAULT_LOCAL_DATA_DIR,
+  ));
+  const workDir = resolvePath(firstNonEmpty(
+    args.workDir,
+    env.GENARRATIVE_DATABASE_BACKUP_WORK_DIR,
+    isProductionLike ? DEFAULT_PRODUCTION_WORK_DIR : DEFAULT_LOCAL_WORK_DIR,
+  ));
+  const bucket = firstNonEmpty(args.bucket, env.GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET, env.ALIYUN_OSS_BUCKET);
+  const endpoint = normalizeEndpoint(firstNonEmpty(args.endpoint, env.GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT, env.ALIYUN_OSS_ENDPOINT));
+  const accessKeyId = firstNonEmpty(args.accessKeyId, env.GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID, env.ALIYUN_OSS_ACCESS_KEY_ID);
+  const accessKeySecret = firstNonEmpty(args.accessKeySecret, env.GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET, env.ALIYUN_OSS_ACCESS_KEY_SECRET);
+  const objectPrefix = firstNonEmpty(args.objectPrefix, env.GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX, 'database-backups');
+  const database = firstNonEmpty(args.database, env.GENARRATIVE_SPACETIME_DATABASE, basename(dataDir));
+  const keepLocal = args.keepLocal || String(env.GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL ?? '').trim().toLowerCase() === 'true';
+
+  for (const [label, value] of Object.entries({bucket, endpoint, accessKeyId, accessKeySecret})) {
+    if (!value) {
+      throw new Error(`缺少 ${label} 配置`);
+    }
+  }
+
+  const {fileName, objectKey} = buildBackupNames({database, dataDir, objectPrefix});
+  console.log(`[database-backup] 数据目录: ${dataDir}`);
+  console.log(`[database-backup] 本地临时目录: ${workDir}`);
+  console.log(`[database-backup] 目标对象: oss://${bucket}/${objectKey}`);
+
+  if (args.dryRun) {
+    console.log('[database-backup] dry-run，仅校验配置，不打包上传。');
+    return;
+  }
+
+  let archivePath = '';
+  let serviceStopped = false;
+  try {
+    serviceStopped = stopServiceIfNeeded(args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE));
+    archivePath = createArchive({dataDir, workDir, fileName});
+  } finally {
+    startServiceIfNeeded(args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE), serviceStopped);
+  }
+
+  const result = await uploadArchive({archivePath, bucket, endpoint, objectKey, accessKeyId, accessKeySecret});
+  console.log(`[database-backup] 上传完成: ${JSON.stringify(result)}`);
+
+  const manifestPath = `${archivePath}.manifest.json`;
+  writeFileSync(
+    manifestPath,
+    `${JSON.stringify({
+      createdAt: new Date().toISOString(),
+      dataDir,
+      bucket: result.bucket,
+      objectKey: result.objectKey,
+      contentLength: result.contentLength,
+      etag: result.etag,
+    }, null, 2)}\n`,
+    'utf8',
+  );
+
+  if (!keepLocal) {
+    rmSync(archivePath, {force: true});
+    rmSync(manifestPath, {force: true});
+    console.log('[database-backup] 已删除本地临时备份文件；如需保留请设置 --keep-local。');
+  } else {
+    console.log(`[database-backup] 已保留本地备份: ${archivePath}`);
+    console.log(`[database-backup] 已保留备份清单: ${manifestPath}`);
+  }
+}
+
+main().catch((error) => {
+  console.error(`[database-backup] ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

scripts/deploy/production-api-deploy.sh

@@ -205,7 +205,7 @@ ensure_runtime_dir() {
 
 ensure_runtime_env_and_dirs() {
   local api_env_file="$1"
-  local tracking_enabled tracking_outbox_dir auth_store_path auth_store_dir
+  local tracking_enabled tracking_outbox_dir
 
   # 旧生产环境文件会被 server-provision 保留，不一定包含新增的运行态写入路径。
   # 发布前只补缺省值，不覆盖线上已经定制过的目录或开关。
@@ -214,19 +214,12 @@ ensure_runtime_env_and_dirs() {
   ensure_env_value "${api_env_file}" "GENARRATIVE_TRACKING_OUTBOX_BATCH_SIZE" "500"
   ensure_env_value "${api_env_file}" "GENARRATIVE_TRACKING_OUTBOX_FLUSH_INTERVAL_MS" "1000"
   ensure_env_value "${api_env_file}" "GENARRATIVE_TRACKING_OUTBOX_MAX_BYTES" "268435456"
-  ensure_env_value "${api_env_file}" "GENARRATIVE_AUTH_STORE_PATH" "/var/lib/genarrative/auth/auth-store.json"
 
   tracking_enabled="$(read_env_value "${api_env_file}" "GENARRATIVE_TRACKING_OUTBOX_ENABLED")"
   tracking_outbox_dir="$(read_env_value "${api_env_file}" "GENARRATIVE_TRACKING_OUTBOX_DIR")"
   if [[ "$(printf "%s" "${tracking_enabled}" | tr '[:upper:]' '[:lower:]')" != "false" ]]; then
     ensure_runtime_dir "${tracking_outbox_dir}" "0750"
   fi
-
-  auth_store_path="$(read_env_value "${api_env_file}" "GENARRATIVE_AUTH_STORE_PATH")"
-  if [[ -n "${auth_store_path}" ]]; then
-    auth_store_dir="$(dirname "${auth_store_path}")"
-    ensure_runtime_dir "${auth_store_dir}" "0750"
-  fi
 }
 
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"

scripts/deploy/production-stdb-publish.sh

@@ -5,13 +5,14 @@ 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]
+  ./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]
 
 说明:
   进入维护模式，校验 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 时跳过。
   失败时保留维护模式。
 EOF
 }
@@ -43,6 +44,7 @@ SERVER_URL="http://127.0.0.1:3101"
 SPACETIME_ROOT_DIR="/stdb"
 RUN_AS_USER="spacetimedb"
 CLEAR_DATABASE=0
+SKIP_BACKUP=0
 DEPLOY_COMPLETED=0
 PUBLISH_TMP_DIR=""
 
@@ -81,6 +83,10 @@ while [[ $# -gt 0 ]]; do
       CLEAR_DATABASE=1
       shift
       ;;
+    --skip-backup)
+      SKIP_BACKUP=1
+      shift
+      ;;
     *)
       echo "[production-stdb-publish] 未知参数: $1" >&2
       usage >&2
@@ -130,6 +136,26 @@ trap on_exit EXIT
 
 "${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
+
+  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] 校验 wasm"
 (
   cd "${SOURCE_DIR}"

scripts/jenkins-server-provision.sh

@@ -325,7 +325,6 @@ ensure_api_runtime_env_defaults() {
   ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_TRACKING_OUTBOX_BATCH_SIZE" "500"
   ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_TRACKING_OUTBOX_FLUSH_INTERVAL_MS" "1000"
   ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_TRACKING_OUTBOX_MAX_BYTES" "268435456"
-  ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_AUTH_STORE_PATH" "/var/lib/genarrative/auth/auth-store.json"
 }
 
 parse_json_string_field() {
@@ -642,8 +641,20 @@ render_api_service() {
     deploy/systemd/genarrative-api.service
 }
 
+render_database_backup_service() {
+  local current_escaped env_escaped
+  current_escaped="$(escape_sed_replacement "${CURRENT_LINK}")"
+  env_escaped="$(escape_sed_replacement "${API_ENV_FILE}")"
+  sed \
+    -e "s|/opt/genarrative/current|${current_escaped}|g" \
+    -e "s|/etc/genarrative/api-server.env|${env_escaped}|g" \
+    deploy/systemd/genarrative-database-backup.service
+}
+
 require_path deploy/systemd/spacetimedb.service
 require_path deploy/systemd/genarrative-api.service
+require_path deploy/systemd/genarrative-database-backup.service
+require_path deploy/systemd/genarrative-database-backup.timer
 require_path deploy/systemd/otelcol-contrib.service
 require_path deploy/otelcol/genarrative-debug.yaml
 require_path deploy/nginx/genarrative.conf
@@ -663,7 +674,7 @@ run_cmd id
 install_build_dependencies
 install_nginx_brotli_modules
 install_sccache
-run_cmd mkdir -p "${SPACETIME_ROOT}" "${RELEASE_ROOT}" "$(dirname "${CURRENT_LINK}")" "$(dirname "${WEB_LINK}")" /etc/genarrative /var/lib/genarrative/maintenance /var/lib/genarrative/auth /var/lib/genarrative/tracking-outbox
+run_cmd mkdir -p "${SPACETIME_ROOT}" "${RELEASE_ROOT}" "$(dirname "${CURRENT_LINK}")" "$(dirname "${WEB_LINK}")" /etc/genarrative /var/lib/genarrative/maintenance /var/lib/genarrative/auth /var/lib/genarrative/tracking-outbox /var/lib/genarrative/database-backups
 
 if ! id spacetimedb >/dev/null 2>&1; then
   run_cmd useradd --system --home-dir "${SPACETIME_ROOT}" --shell /usr/sbin/nologin spacetimedb
@@ -693,11 +704,15 @@ sync_spacetime_install "${SPACETIME_ROOT}"
 
 spacetimedb_service="$(mktemp)"
 api_service="$(mktemp)"
+database_backup_service="$(mktemp)"
 render_spacetimedb_service >"${spacetimedb_service}"
 render_api_service >"${api_service}"
+render_database_backup_service >"${database_backup_service}"
 install_file "${spacetimedb_service}" /etc/systemd/system/spacetimedb.service 0644
 install_file "${api_service}" /etc/systemd/system/genarrative-api.service 0644
-rm -f "${spacetimedb_service}" "${api_service}"
+install_file "${database_backup_service}" /etc/systemd/system/genarrative-database-backup.service 0644
+install_file deploy/systemd/genarrative-database-backup.timer /etc/systemd/system/genarrative-database-backup.timer 0644
+rm -f "${spacetimedb_service}" "${api_service}" "${database_backup_service}"
 
 if [[ ! -f "${API_ENV_FILE}" ]]; then
   echo "+ create ${API_ENV_FILE} from example"
@@ -732,7 +747,7 @@ if [[ "${ENABLE_SERVICES}" == "true" ]]; then
   if [[ "${ENABLE_OTELCOL:-true}" == "true" ]]; then
     run_cmd systemctl enable otelcol-contrib.service
   fi
-  run_cmd systemctl enable spacetimedb.service genarrative-api.service
+  run_cmd systemctl enable spacetimedb.service genarrative-api.service genarrative-database-backup.timer
   if [[ "${ENABLE_OTELCOL:-true}" == "true" ]]; then
     run_cmd systemctl restart otelcol-contrib.service
   fi

scripts/rebind-orphan-work-owners.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_ORPHAN_WORK_OWNER_USER_ID = 'wx-openid-placeholder';
+
+export const WORK_OWNER_TABLES = [
+  'custom_world_profile',
+  'custom_world_gallery_entry',
+  'custom_world_session',
+  'custom_world_agent_session',
+  'custom_world_draft_card',
+  'puzzle_agent_session',
+  'puzzle_work_profile',
+  'bark_battle_draft_config',
+  'bark_battle_published_config',
+  'match3d_agent_session',
+  'match3d_work_profile',
+  'jump_hop_agent_session',
+  'jump_hop_work_profile',
+  'wooden_fish_agent_session',
+  'wooden_fish_work_profile',
+  'square_hole_agent_session',
+  'square_hole_work_profile',
+  'visual_novel_agent_session',
+  'visual_novel_work_profile',
+  'big_fish_creation_session',
+];
+
+const ROW_KEY_FIELDS = ['profile_id', 'work_id', 'session_id', 'draft_id', 'gallery_entry_id', 'id'];
+
+if (isCliEntry()) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    console.error(
+      `[rebind-orphan-work-owners] ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  });
+}
+
+export function rebindOrphanWorkOwnersInMigration(
+  migration,
+  { placeholderUserId = DEFAULT_ORPHAN_WORK_OWNER_USER_ID, validUserIds = [] } = {},
+) {
+  if (!migration || !Array.isArray(migration.tables)) {
+    throw new Error('迁移 JSON 必须包含 tables 数组。');
+  }
+
+  const normalizedPlaceholderUserId = placeholderUserId.trim();
+  const validUserIdSet = new Set(
+    (Array.isArray(validUserIds) ? validUserIds : [])
+      .map((value) => String(value).trim())
+      .filter(Boolean),
+  );
+  validUserIdSet.add(normalizedPlaceholderUserId);
+
+  const reboundRows = [];
+  for (const table of migration.tables) {
+    if (!table || !WORK_OWNER_TABLES.includes(table.name) || !Array.isArray(table.rows)) {
+      continue;
+    }
+
+    for (const row of table.rows) {
+      if (!row || typeof row !== 'object') {
+        continue;
+      }
+      const currentOwner = typeof row.owner_user_id === 'string' ? row.owner_user_id.trim() : '';
+      if (currentOwner === normalizedPlaceholderUserId || validUserIdSet.has(currentOwner)) {
+        continue;
+      }
+
+      const originalOwner = typeof row.owner_user_id === 'string' ? row.owner_user_id : '';
+      row.owner_user_id = normalizedPlaceholderUserId;
+      reboundRows.push({
+        table: table.name,
+        rowKey: resolveRowKey(row),
+        from: originalOwner,
+        to: normalizedPlaceholderUserId,
+      });
+    }
+  }
+
+  return { reboundRows, validUserCount: validUserIdSet.size };
+}
+
+function resolveRowKey(row) {
+  for (const field of ROW_KEY_FIELDS) {
+    const value = row[field];
+    if (typeof value === 'string' && value.trim()) {
+      return value;
+    }
+  }
+  return '<unknown>';
+}
+
+async function runCli(argv) {
+  const options = parseCliArgs(argv);
+  const inputPath = path.resolve(options.in);
+  const outputPath = path.resolve(options.out);
+  const migration = JSON.parse(await readFile(inputPath, 'utf8'));
+  const result = rebindOrphanWorkOwnersInMigration(migration, {
+    placeholderUserId: options.placeholderUserId,
+    validUserIds: collectValidUserIds(migration),
+  });
+
+  if (!options.dryRun) {
+    await writeFile(outputPath, `${JSON.stringify(migration, null, 2)}\n`, 'utf8');
+  }
+
+  console.log(
+    `[rebind-orphan-work-owners] ${options.dryRun ? 'dry-run' : `已写入 ${outputPath}`}，回填 ${result.reboundRows.length} 行`,
+  );
+}
+
+function parseCliArgs(argv) {
+  const options = {
+    in: '',
+    out: '',
+    placeholderUserId: DEFAULT_ORPHAN_WORK_OWNER_USER_ID,
+    dryRun: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const readValue = (name) => {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${name} 缺少参数值。`);
+      }
+      index += 1;
+      return value;
+    };
+
+    if (arg === '--in') {
+      options.in = readValue(arg);
+    } else if (arg === '--out') {
+      options.out = readValue(arg);
+    } else if (arg === '--placeholder-user-id') {
+      options.placeholderUserId = readValue(arg);
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else {
+      throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!options.in) {
+    throw new Error('必须传入 --in。');
+  }
+  if (!options.out && !options.dryRun) {
+    throw new Error('非 dry-run 必须传入 --out。');
+  }
+  return options;
+}
+
+function collectValidUserIds(migration) {
+  const result = new Set();
+  for (const table of migration.tables ?? []) {
+    if (!table || !Array.isArray(table.rows)) {
+      continue;
+    }
+    if (table.name === 'user_account') {
+      for (const row of table.rows) {
+        if (typeof row?.user_id === 'string' && row.user_id.trim()) {
+          result.add(row.user_id.trim());
+        }
+      }
+    }
+  }
+  return result;
+}
+
+function isCliEntry() {
+  const entry = process.argv[1];
+  return entry ? import.meta.url === `file://${entry.replace(/\\/gu, '/')}` : false;
+}

scripts/rebind-orphan-work-owners.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { rebindOrphanWorkOwnersInMigration } from './rebind-orphan-work-owners.mjs';
+
+const placeholderUserId = 'wx-openid-placeholder';
+
+function table(name, rows) {
+  return { name, rows };
+}
+
+describe('rebindOrphanWorkOwnersInMigration', () => {
+  it('把作品表里认证表不存在的 owner_user_id 回填到占位用户', () => {
+    const migration = {
+      schema_version: 1,
+      exported_at_micros: 1,
+      tables: [
+        table('user_account', [{ user_id: 'user_alive' }, { user_id: placeholderUserId }]),
+        table('puzzle_work_profile', [
+          { profile_id: 'p1', owner_user_id: 'user_missing' },
+          { profile_id: 'p2', owner_user_id: 'user_alive' },
+          { profile_id: 'p3', owner_user_id: placeholderUserId },
+        ]),
+        table('puzzle_agent_session', [{ session_id: 'draft-1', owner_user_id: '' }]),
+        table('tracking_event', [{ event_id: 't1', owner_user_id: 'user_missing' }]),
+      ],
+    };
+
+    const result = rebindOrphanWorkOwnersInMigration(migration, {
+      placeholderUserId,
+      validUserIds: ['user_alive'],
+    });
+
+    expect(result.reboundRows).toEqual([
+      { table: 'puzzle_work_profile', rowKey: 'p1', from: 'user_missing', to: placeholderUserId },
+      { table: 'puzzle_agent_session', rowKey: 'draft-1', from: '', to: placeholderUserId },
+    ]);
+    expect(migration.tables[1].rows[0].owner_user_id).toBe(placeholderUserId);
+    expect(migration.tables[1].rows[1].owner_user_id).toBe('user_alive');
+    expect(migration.tables[1].rows[2].owner_user_id).toBe(placeholderUserId);
+    expect(migration.tables[2].rows[0].owner_user_id).toBe(placeholderUserId);
+    expect(migration.tables[3].rows[0].owner_user_id).toBe('user_missing');
+  });
+});