合并最新 master 分支

带入 SpacetimeDB 2.7.0（hotfix3）工具链升级、后台灰度发布控制面恢复、
精选顺序分列瀑布流及后台素材预览统一。冲突仅三处文档：decision-log 与
pitfalls 双方条目并存，运维文档更新时间取新值。BgFilter 分支代码与部署
脚本零冲突；依赖升级后 bgfilter 46 测试全过。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

scripts/check-admin-account-procedures.mjs

@@ -20,7 +20,7 @@ const repoRoot = path.resolve(
   '..',
 );
 const database = 'admin-account-smoke';
-const expectedSpacetimeVersion = '2.6.1';
+const expectedSpacetimeVersion = '2.7.0';
 const commandTimeoutMs = 5 * 60 * 1000;
 
 function assert(condition, message) {

scripts/check-server-provision-tools.sh

@@ -37,11 +37,15 @@ chmod +x "${TARGET_BIN_DIR}/otelcol-contrib"
 
 cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" <<'EOF'
 #!/usr/bin/env bash
-echo "spacetimedb-cli 2.6.1"
+cat <<'VERSION'
+spacetime Path: /tmp/spacetimedb-cli
+Commit: d220349adb7af7eefa810eb08a185609356b83f6
+spacetimedb tool version 2.7.0; spacetimedb-lib version 2.7.0;
+VERSION
 EOF
 cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-standalone" <<'EOF'
 #!/usr/bin/env bash
-echo "spacetimedb-standalone 2.6.1"
+echo "spacetimedb-standalone 2.7.0"
 EOF
 chmod +x \
   "${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" \
@@ -58,7 +62,6 @@ if ! (
     OTELCOL_TARGET_BIN="${TARGET_BIN_DIR}/otelcol-contrib" \
     OTELCOL_VERSION="0.151.0" \
     SPACETIME_ROOT="${SPACETIME_ROOT_DIR}" \
-    SPACETIME_EXPECTED_VERSION="2.6.1" \
     "${REPO_ROOT}/scripts/prepare-server-provision-tools.sh" \
     >"${OUTPUT_LOG}" 2>&1
 ); then
@@ -83,4 +86,82 @@ if grep -q "下载 " "${OUTPUT_LOG}"; then
   exit 1
 fi
 
+BARE_TAG_ROOT_DIR="${TMP_ROOT}/bare-tag-stdb"
+BARE_TAG_WORK_DIR="${TMP_ROOT}/bare-tag-workspace"
+BARE_TAG_LOG="${TMP_ROOT}/bare-tag.log"
+mkdir -p "${BARE_TAG_ROOT_DIR}/bin/current" "${BARE_TAG_WORK_DIR}"
+cat >"${BARE_TAG_ROOT_DIR}/bin/current/spacetimedb-cli" <<'EOF'
+#!/usr/bin/env bash
+cat <<'VERSION'
+spacetime Path: /tmp/spacetimedb-cli
+Commit: a08663c7b94688a2542577532d472f751e641f5b
+spacetimedb tool version 2.7.0; spacetimedb-lib version 2.7.0;
+VERSION
+EOF
+cat >"${BARE_TAG_ROOT_DIR}/bin/current/spacetimedb-standalone" <<'EOF'
+#!/usr/bin/env bash
+echo "spacetimedb-standalone 2.7.0"
+EOF
+chmod +x \
+  "${BARE_TAG_ROOT_DIR}/bin/current/spacetimedb-cli" \
+  "${BARE_TAG_ROOT_DIR}/bin/current/spacetimedb-standalone"
+
+if (
+  cd "${BARE_TAG_WORK_DIR}"
+  PATH="${FAKE_BIN_DIR}:${PATH}" \
+    WORKSPACE="${BARE_TAG_WORK_DIR}" \
+    PROVISION_TOOLS_DIR="provision-tools" \
+    PROVISION_DOWNLOADS_DIR="downloads" \
+    PROVISION_TOOLS_TMP_PARENT="${BARE_TAG_WORK_DIR}/.tmp/server-provision-tools" \
+    PROVISION_REQUIRE_LOCAL_DOWNLOADS="true" \
+    PREPARE_OTELCOL="false" \
+    SPACETIME_ROOT="${BARE_TAG_ROOT_DIR}" \
+    "${REPO_ROOT}/scripts/prepare-server-provision-tools.sh" \
+    >"${BARE_TAG_LOG}" 2>&1
+); then
+  echo "[check-server-provision-tools] 裸 v2.7.0 tag 不应通过 hotfix3 复用门禁。" >&2
+  cat "${BARE_TAG_LOG}" >&2
+  exit 1
+fi
+
+grep -q "SpacetimeDB commit 不匹配" "${BARE_TAG_LOG}"
+if grep -q "复用目标机已有 SpacetimeDB 安装" "${BARE_TAG_LOG}"; then
+  echo "[check-server-provision-tools] 裸 v2.7.0 tag 被错误复用。" >&2
+  cat "${BARE_TAG_LOG}" >&2
+  exit 1
+fi
+
+BARE_ARCHIVE_DIR="${TMP_ROOT}/bare-archive"
+BARE_ARCHIVE_PATH="${TMP_ROOT}/bare-spacetime.tar.gz"
+BARE_ARCHIVE_WORK_DIR="${TMP_ROOT}/bare-archive-workspace"
+BARE_ARCHIVE_LOG="${TMP_ROOT}/bare-archive.log"
+mkdir -p "${BARE_ARCHIVE_DIR}" "${BARE_ARCHIVE_WORK_DIR}"
+cp \
+  "${BARE_TAG_ROOT_DIR}/bin/current/spacetimedb-cli" \
+  "${BARE_TAG_ROOT_DIR}/bin/current/spacetimedb-standalone" \
+  "${BARE_ARCHIVE_DIR}/"
+tar -czf "${BARE_ARCHIVE_PATH}" -C "${BARE_ARCHIVE_DIR}" \
+  spacetimedb-cli spacetimedb-standalone
+
+if (
+  cd "${BARE_ARCHIVE_WORK_DIR}"
+  PATH="${FAKE_BIN_DIR}:${PATH}" \
+    WORKSPACE="${BARE_ARCHIVE_WORK_DIR}" \
+    PROVISION_TOOLS_DIR="provision-tools" \
+    PROVISION_DOWNLOADS_DIR="downloads" \
+    PROVISION_TOOLS_TMP_PARENT="${BARE_ARCHIVE_WORK_DIR}/.tmp/server-provision-tools" \
+    PROVISION_REQUIRE_LOCAL_DOWNLOADS="true" \
+    PREPARE_OTELCOL="false" \
+    SPACETIME_ROOT="${TMP_ROOT}/missing-target-stdb" \
+    SPACETIME_ARCHIVE_PATH="${BARE_ARCHIVE_PATH}" \
+    "${REPO_ROOT}/scripts/prepare-server-provision-tools.sh" \
+    >"${BARE_ARCHIVE_LOG}" 2>&1
+); then
+  echo "[check-server-provision-tools] 裸 v2.7.0 archive 不应通过 hotfix3 安装结果门禁。" >&2
+  cat "${BARE_ARCHIVE_LOG}" >&2
+  exit 1
+fi
+
+grep -q "安装结果 commit 不匹配" "${BARE_ARCHIVE_LOG}"
+
 echo "[check-server-provision-tools] OK"

scripts/container-worker-smoke.mjs

@@ -759,7 +759,7 @@ function composeEnv() {
 }
 
 function localSpacetimeImageName() {
-  return `${projectName}-spacetimedb:2.6.1`;
+  return `${projectName}-spacetimedb:2.7.0`;
 }
 
 function spacetimeServerUrl(state) {

scripts/dev.mjs

@@ -605,7 +605,27 @@ function parseSpacetimeToolVersion(output) {
   return match?.[1] ?? '';
 }
 
-function readSpacetimeToolVersion() {
+function parseSpacetimeToolCommit(output) {
+  const match = /^Commit:\s*([0-9a-f]{40})\s*$/imu.exec(output);
+  return match?.[1]?.toLowerCase() ?? '';
+}
+
+function expectedSpacetimeToolCommit(workspaceVersion) {
+  if (workspaceVersion === '2.7.0') {
+    return 'd220349adb7af7eefa810eb08a185609356b83f6';
+  }
+  return '';
+}
+
+function buildSpacetimeUpgradeInstruction(workspaceVersion) {
+  const expectedCommit = expectedSpacetimeToolCommit(workspaceVersion);
+  if (expectedCommit) {
+    return `请安装官方 v${workspaceVersion}-hotfix3 发行包并确认 spacetime --version 的 Commit 为 ${expectedCommit}，然后重新运行本命令。`;
+  }
+  return `请先直接升级并切换到锁定版本: spacetime version install ${workspaceVersion} && spacetime version use ${workspaceVersion}，然后重新运行本命令。`;
+}
+
+function readSpacetimeToolProvenance() {
   const result = spawnSync('spacetime', ['--version'], {
     cwd: repoRoot,
     encoding: 'utf8',
@@ -621,33 +641,43 @@ function readSpacetimeToolVersion() {
   if (!version) {
     throw new Error(`无法解析 spacetime 版本输出: ${trimPreview(output)}`);
   }
-  return version;
+  return { version, commit: parseSpacetimeToolCommit(output) };
 }
 
 function assertSpacetimeToolVersionMatchesWorkspace({
   toolVersion,
+  toolCommit = '',
   workspaceVersion,
 }) {
-  if (toolVersion === workspaceVersion) {
-    return;
+  if (toolVersion !== workspaceVersion) {
+    throw new Error(
+      [
+        `本机 spacetime CLI/standalone 版本 ${toolVersion} 与 server-rs 锁定的 SpacetimeDB ${workspaceVersion} 不一致。`,
+        '版本错位会导致 procedure 返回值 BSATN 反序列化失败，前端表现为 SpacetimeDB procedure 调用超时。',
+        buildSpacetimeUpgradeInstruction(workspaceVersion),
+      ].join(''),
+    );
   }
 
-  throw new Error(
-    [
-      `本机 spacetime CLI/standalone 版本 ${toolVersion} 与 server-rs 锁定的 SpacetimeDB ${workspaceVersion} 不一致。`,
-      '版本错位会导致 procedure 返回值 BSATN 反序列化失败，前端表现为 SpacetimeDB procedure 调用超时。',
-      `请先直接升级并切换到锁定版本: spacetime version install ${workspaceVersion} && spacetime version use ${workspaceVersion}，然后重新运行本命令。`,
-    ].join(''),
-  );
+  const expectedCommit = expectedSpacetimeToolCommit(workspaceVersion);
+  if (expectedCommit && toolCommit.toLowerCase() !== expectedCommit) {
+    throw new Error(
+      [
+        `本机 spacetime CLI/standalone 虽报告 ${toolVersion}，但构建 commit ${toolCommit || 'unknown'} 不是项目锁定的 ${expectedCommit}。`,
+        '同版本号的裸 tag 缺少后续 hotfix，不能用于本地 SpacetimeDB。',
+        buildSpacetimeUpgradeInstruction(workspaceVersion),
+      ].join(''),
+    );
+  }
 }
 
 function assertReusableSpacetimeProcessVersionMatchesWorkspace({
   dataDir,
   serverUrl,
 }) {
-  const recordedVersion = readRecordedSpacetimeToolVersion(dataDir);
+  const recordedProvenance = readRecordedSpacetimeToolProvenance(dataDir);
   const workspaceVersion = readWorkspaceSpacetimeVersion();
-  if (!recordedVersion) {
+  if (!recordedProvenance.version) {
     throw new Error(
       [
         `检测到正在运行的本地 SpacetimeDB: ${serverUrl}，但缺少 SpacetimeDB 版本记录。`,
@@ -656,26 +686,25 @@ function assertReusableSpacetimeProcessVersionMatchesWorkspace({
     );
   }
 
-  if (recordedVersion === workspaceVersion) {
-    return;
+  try {
+    assertSpacetimeToolVersionMatchesWorkspace({
+      toolVersion: recordedProvenance.version,
+      toolCommit: recordedProvenance.commit,
+      workspaceVersion,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `正在运行的本地 SpacetimeDB standalone provenance 不符合项目锁定要求: ${message}请停止当前 SpacetimeDB 进程后重新运行 npm run dev:spacetime。`,
+    );
   }
-
-  throw new Error(
-    [
-      `正在运行的本地 SpacetimeDB standalone 版本 ${recordedVersion} 与 server-rs 锁定的 SpacetimeDB ${workspaceVersion} 不一致。`,
-      '版本错位会导致 procedure 返回值 BSATN 反序列化失败，前端表现为 SpacetimeDB procedure 调用超时。',
-      '请停止当前 SpacetimeDB 进程，先直接升级并切换到锁定版本: spacetime version install ',
-      workspaceVersion,
-      ' && spacetime version use ',
-      workspaceVersion,
-      '，然后重新运行 npm run dev:spacetime。',
-    ].join(''),
-  );
 }
 
 function ensureSpacetimeToolVersionMatchesWorkspace() {
+  const toolProvenance = readSpacetimeToolProvenance();
   assertSpacetimeToolVersionMatchesWorkspace({
-    toolVersion: readSpacetimeToolVersion(),
+    toolVersion: toolProvenance.version,
+    toolCommit: toolProvenance.commit,
     workspaceVersion: readWorkspaceSpacetimeVersion(),
   });
 }
@@ -1639,12 +1668,16 @@ class DevRunner {
       encoding: 'utf8',
     });
     service.logStream = logStream;
-    const spacetimeToolVersion = readSpacetimeToolVersion();
+    const spacetimeToolProvenance = readSpacetimeToolProvenance();
     assertSpacetimeToolVersionMatchesWorkspace({
-      toolVersion: spacetimeToolVersion,
+      toolVersion: spacetimeToolProvenance.version,
+      toolCommit: spacetimeToolProvenance.commit,
       workspaceVersion: readWorkspaceSpacetimeVersion(),
     });
-    recordSpacetimeToolVersion(options.spacetimeDataDir, spacetimeToolVersion);
+    recordSpacetimeToolVersion(
+      options.spacetimeDataDir,
+      spacetimeToolProvenance,
+    );
 
     console.log(`[dev:spacetime] log: ${logFile}`);
     service.updateRuntimeState({
@@ -2630,13 +2663,16 @@ function readRecordedSpacetimeUrl(dataDir) {
   return '';
 }
 
-function readRecordedSpacetimeToolVersion(dataDir) {
+function readRecordedSpacetimeToolProvenance(dataDir) {
   const versionPath = resolve(dataDir, 'dev-spacetime-tool-version');
   if (!existsSync(versionPath)) {
-    return '';
+    return { version: '', commit: '' };
   }
 
-  return readFileSync(versionPath, 'utf8').split(/\r?\n/u)[0]?.trim() ?? '';
+  const [version = '', commit = ''] = readFileSync(versionPath, 'utf8').split(
+    /\r?\n/u,
+  );
+  return { version: version.trim(), commit: commit.trim().toLowerCase() };
 }
 
 function readRecordedSpacetimePidState(dataDir) {
@@ -2911,11 +2947,15 @@ function writeLocalSpacetimeApiIdentity({
   }
 }
 
-function recordSpacetimeToolVersion(dataDir, version) {
+function recordSpacetimeToolVersion(dataDir, provenance) {
   const versionPath = resolve(dataDir, 'dev-spacetime-tool-version');
   ensureParentDir(versionPath);
   try {
-    writeFileSync(versionPath, `${version}\n`, 'utf8');
+    writeFileSync(
+      versionPath,
+      `${provenance.version}\n${provenance.commit}\n`,
+      'utf8',
+    );
   } catch (error) {
     console.warn(
       `[dev:spacetime] 写入版本记录失败 ${versionPath}: ${error.message}`,
@@ -3292,6 +3332,7 @@ export {
   normalizeCargoVersionRequirement,
   parseArgs,
   parseProcessEnvBlock,
+  parseSpacetimeToolCommit,
   parseSpacetimeToolVersion,
   resolveBgfilterWorkerLogFile,
   resolveCurrentSpacetimeCliToken,

scripts/dev.test.ts

@@ -33,6 +33,7 @@ import {
   normalizeCargoVersionRequirement,
   parseArgs,
   parseProcessEnvBlock,
+  parseSpacetimeToolCommit,
   parseSpacetimeToolVersion,
   resolveDevStackStatePath,
   resolveLocalSpacetimeApiIdentityPath,
@@ -737,7 +738,7 @@ describe('dev scheduler spacetime reuse guard', () => {
       writeFileSync(join(tempDir, 'spacetime.pid'), `${process.pid}\n`, 'utf8');
       writeFileSync(
         join(tempDir, 'dev-spacetime-tool-version'),
-        `${workspaceSpacetimeVersionForTest()}\n`,
+        `${workspaceSpacetimeVersionForTest()}\nd220349adb7af7eefa810eb08a185609356b83f6\n`,
         'utf8',
       );
       globalThis.fetch = vi.fn(async () => ({
@@ -766,7 +767,7 @@ describe('dev scheduler spacetime reuse guard', () => {
       writeFileSync(join(tempDir, 'spacetime.pid'), `${process.pid}\n`, 'utf8');
       writeFileSync(
         join(tempDir, 'dev-spacetime-tool-version'),
-        `${workspaceSpacetimeVersionForTest()}\n`,
+        `${workspaceSpacetimeVersionForTest()}\nd220349adb7af7eefa810eb08a185609356b83f6\n`,
         'utf8',
       );
       globalThis.fetch = vi.fn(async () => ({
@@ -877,12 +878,34 @@ describe('dev scheduler spacetime refresh', () => {
   });
 
   test('解析 spacetime --version 输出里的 tool version', () => {
-    const version = parseSpacetimeToolVersion(`
+    const output = `
 A new version of SpacetimeDB is available: v2.6.1 (current: v2.5.0)
-spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
-`);
+Commit: d220349adb7af7eefa810eb08a185609356b83f6
+spacetimedb tool version 2.7.0; spacetimedb-lib version 2.7.0;
+`;
 
-    expect(version).toBe('2.6.0');
+    expect(parseSpacetimeToolVersion(output)).toBe('2.7.0');
+    expect(parseSpacetimeToolCommit(output)).toBe(
+      'd220349adb7af7eefa810eb08a185609356b83f6',
+    );
+  });
+
+  test('同为 2.7.0 时拒绝裸 tag 并接受 hotfix3 commit', () => {
+    expect(() =>
+      assertSpacetimeToolVersionMatchesWorkspace({
+        toolVersion: '2.7.0',
+        toolCommit: 'a08663c7b94688a2542577532d472f751e641f5b',
+        workspaceVersion: '2.7.0',
+      }),
+    ).toThrow('裸 tag');
+
+    expect(() =>
+      assertSpacetimeToolVersionMatchesWorkspace({
+        toolVersion: '2.7.0',
+        toolCommit: 'd220349adb7af7eefa810eb08a185609356b83f6',
+        workspaceVersion: '2.7.0',
+      }),
+    ).not.toThrow();
   });
 
   test('本机 spacetime 版本和 workspace 锁定版本不一致时直接报清楚', () => {
@@ -916,6 +939,28 @@ spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
     }
   });
 
+  test('复用本地 SpacetimeDB standalone 时拒绝同版本裸 tag 记录', () => {
+    const tempDir = mkdtempSync(
+      join(tmpdir(), 'genarrative-spacetime-commit-'),
+    );
+    try {
+      writeFileSync(
+        join(tempDir, 'dev-spacetime-tool-version'),
+        '2.7.0\na08663c7b94688a2542577532d472f751e641f5b\n',
+        'utf8',
+      );
+
+      expect(() =>
+        assertReusableSpacetimeProcessVersionMatchesWorkspace({
+          dataDir: tempDir,
+          serverUrl: 'http://127.0.0.1:3101',
+        }),
+      ).toThrow('裸 tag');
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test('本地发布 403 时识别为身份权限问题，避免误杀 standalone', () => {
     const error = new Error(
       'Pre-publish check failed with status 403 Forbidden: c200... is not authorized to perform action on database c200...: update database',

scripts/prepare-server-provision-tools.sh

@@ -9,10 +9,11 @@ OTELCOL_DOWNLOAD_ROOT="${OTELCOL_DOWNLOAD_ROOT:-https://github.com/open-telemetr
 OTELCOL_ARCHIVE_PATH="${OTELCOL_ARCHIVE_PATH:-}"
 OTELCOL_TARGET_BIN="${OTELCOL_TARGET_BIN:-/usr/local/bin/otelcol-contrib}"
 SPACETIME_INSTALLER_URL="${SPACETIME_INSTALLER_URL:-https://install.spacetimedb.com}"
-SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.6.1}"
+SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.7.0-hotfix3}"
 SPACETIME_TARGET_HOST="${SPACETIME_TARGET_HOST:-x86_64-unknown-linux-gnu}"
 SPACETIME_ROOT="${SPACETIME_ROOT:-/stdb}"
 SPACETIME_EXPECTED_VERSION="${SPACETIME_EXPECTED_VERSION:-}"
+SPACETIME_EXPECTED_COMMIT="${SPACETIME_EXPECTED_COMMIT:-d220349adb7af7eefa810eb08a185609356b83f6}"
 SPACETIME_ARCHIVE_PATH="${SPACETIME_ARCHIVE_PATH:-}"
 SPACETIME_INSTALLER_PATH="${SPACETIME_INSTALLER_PATH:-}"
 SPACETIME_UPDATE_INSTALLER_PATH="${SPACETIME_UPDATE_INSTALLER_PATH:-}"
@@ -76,7 +77,7 @@ resolve_spacetime_expected_version() {
     return
   fi
 
-  if [[ "${download_root}" =~ /v([0-9]+(\.[0-9]+){1,2})$ ]]; then
+  if [[ "${download_root}" =~ /v([0-9]+(\.[0-9]+){1,2})(-hotfix[0-9]+)?$ ]]; then
     printf "%s" "${BASH_REMATCH[1]}"
   fi
 }
@@ -117,6 +118,10 @@ target_spacetime_ready() {
     echo "[prepare-provision-tools] 目标机 SpacetimeDB 版本不匹配，期望 ${expected_version}，当前: ${version_output:-unknown}"
     return 1
   fi
+  if [[ -n "${SPACETIME_EXPECTED_COMMIT}" && "${version_output}" != *"Commit: ${SPACETIME_EXPECTED_COMMIT}"* ]]; then
+    echo "[prepare-provision-tools] 目标机 SpacetimeDB commit 不匹配，期望 ${SPACETIME_EXPECTED_COMMIT}，当前: ${version_output:-unknown}"
+    return 1
+  fi
 
   echo "[prepare-provision-tools] 目标机 SpacetimeDB 已满足要求: ${version_output:-version unknown}"
   return 0
@@ -284,6 +289,18 @@ prepare_spacetime() {
     exit 1
   fi
 
+  local installed_version_output expected_version
+  expected_version="$(resolve_spacetime_expected_version)"
+  installed_version_output="$("${install_root}/bin/current/spacetimedb-cli" --version 2>/dev/null || true)"
+  if [[ -n "${expected_version}" && "${installed_version_output}" != *"${expected_version}"* ]]; then
+    echo "[prepare-provision-tools] SpacetimeDB 安装结果版本不匹配，期望 ${expected_version}，当前: ${installed_version_output:-unknown}" >&2
+    exit 1
+  fi
+  if [[ -n "${SPACETIME_EXPECTED_COMMIT}" && "${installed_version_output}" != *"Commit: ${SPACETIME_EXPECTED_COMMIT}"* ]]; then
+    echo "[prepare-provision-tools] SpacetimeDB 安装结果 commit 不匹配，期望 ${SPACETIME_EXPECTED_COMMIT}，当前: ${installed_version_output:-unknown}" >&2
+    exit 1
+  fi
+
   mkdir -p "${target_dir}"
   cp -a "${install_root}/bin" "${target_dir}/bin"
   make_spacetime_wrapper "${target_dir}/spacetime"