Record preview synchronization and runtime identity

apps/waterfall-wiki/src/pages/api/dev-preview.ts

@@ -7,7 +7,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
   res.setHeader('Cache-Control', 'no-store');
   try {
     const status = JSON.parse(await readFile('/preview-status/status.json', 'utf8'));
-    return req.method === 'HEAD' ? res.status(200).end() : res.status(200).json(status);
+    return req.method === 'HEAD' ? res.status(200).end() : res.status(200).json({ ...status, mode: 'development' });
   } catch {
     return res.status(503).json({ error: 'Preview source has not synchronized yet' });
   }

docs/remote-preview.md

@@ -0,0 +1,8 @@
+# 远程开发预览
+预览入口为 http://8.211.154.134:18136/。通过 /api/dev-preview 查看已同步分支和提交。单套预览默认跟随 codex/unified-web，可以通过仓库变量 PREVIEW_BRANCH 切换目标分支。
+
+初始化使用已验证的 CI 工具镜像，单独准备 PostgreSQL、S3、认证和缓存卷，然后启动长期运行的 pnpm dev。应用预览和生产使用不同 Cookie 名称。邮件发送与后台导出当前不在预览范围内。
+
+日常 push 触发浅检出与文件同步。同步按内容比较文件，保留依赖和 Next 缓存目录。源码到达后由 Next.js 处理增量编译。同步日志记录容器 ID、启动时间和同步耗时。
+
+锁文件、启动配置或数据库迁移发生变化时，同步中止并保留当前预览版本。管理员可在明确维护窗口用匹配的新工具镜像更新预览。当前预览和生产构建共享 ces-control runner，生产任务占用 runner 时同步仍可能排队。

scripts/preview/sync.sh

@@ -5,6 +5,7 @@ SHA=${2:?commit SHA required}
 BRANCH=${3:?branch required}
 [[ "$SHA" =~ ^[0-9a-f]{40}$ ]] || exit 2
 ROOT=/opt/prompt-preview
+started=$SECONDS
 exec 8>/var/lock/prompt-preview-sync.lock
 flock -w 30 8
 latest=$(git -C "$SOURCE" ls-remote origin "refs/heads/$BRANCH" | cut -f1)
@@ -44,4 +45,5 @@ temporary.write_text(json.dumps({'sha':os.environ['SHA'],'branch':os.environ['BR
 temporary.chmod(0o644)
 temporary.replace(destination)
 META
-echo "Preview synchronized: $BRANCH $SHA (container $id)"
+container_started=$(docker inspect --format '{{.State.StartedAt}}' "$id")
+echo "Preview synchronized: $BRANCH $SHA (container $id, started $container_started, sync ${SECONDS}s)"