合并最新 master 分支

带入 SpacetimeDB 2.7.0（hotfix3）工具链升级、后台灰度发布控制面恢复、精选顺序分列瀑布流及后台素材预览统一。冲突仅三处文档：decision-log 与 pitfalls 双方条目并存，运维文档更新时间取新值。BgFilter 分支代码与部署脚本零冲突；依赖升级后 bgfilter 46 测试全过。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-23 07:02:17 +00:00
parent 65a36e4c97 b72e2163d7
commit 19a8fc2df0
187 changed files with 11561 additions and 883 deletions
@@ -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,