From 38ae9d7d076b1282feb3ea6327b40f281673b5fc Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 17 Aug 2026 12:42:29 +0800
Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E9=A2=84=E8=A7=88=E5=8F=91?=
 =?UTF-8?q?=E5=B8=83=E8=AE=B0=E5=BD=95=E7=AE=A1=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

发布记录改用 Jenkins 构建编号并展示

失败与停止记录增加自动清理期限

构建详情改为局域网 Jenkins 地址

同步测试、部署配置和运维文档
---
 .../src/PreviewDeployerApp.test.tsx           |   9 +-
 .../src/PreviewDeployerApp.tsx                |  13 ++-
 apps/preview-deployer-web/src/styles.css      |   5 +
 apps/preview-deployer-web/src/types.ts        |   2 +-
 deploy/env/preview-deployer.env.example       |   2 +
 .../shared-memory/decision-log.md             |   6 ++
 ...�Jenkins容器预览部署控制面技术方案-2026-08-15.md |   4 +-
 ...发运维】本地开发验证与生产运维-2026-05-15.md |   2 +-
 scripts/check-preview-deployer.mjs            |  19 ++++
 .../preview-deployer-server/src/config.rs     |  25 +++++
 .../preview-deployer-server/src/jenkins.rs    |  48 ++++++++-
 .../crates/preview-deployer-server/src/lib.rs | 101 ++++++++++++++----
 .../preview-deployer-server/src/tests.rs      | 100 ++++++++++++++++-
 13 files changed, 300 insertions(+), 36 deletions(-)

diff --git a/apps/preview-deployer-web/src/PreviewDeployerApp.test.tsx b/apps/preview-deployer-web/src/PreviewDeployerApp.test.tsx
index 21f2b900d..4a366fdaa 100644
--- a/apps/preview-deployer-web/src/PreviewDeployerApp.test.tsx
+++ b/apps/preview-deployer-web/src/PreviewDeployerApp.test.tsx
@@ -27,7 +27,7 @@ beforeEach(() => {
   vi.mocked(api.searchBranches).mockResolvedValue([]);
   vi.mocked(api.searchCommits).mockResolvedValue([]);
   vi.mocked(api.createDeployment).mockResolvedValue({
-    id: 'preview-1',
+    id: null,
     branch: 'master',
     status: 'queued',
     health: 'pending',
@@ -35,7 +35,7 @@ beforeEach(() => {
     updatedAt: '2026-08-15T00:00:00Z',
   });
   vi.mocked(api.uninstallDeployment).mockResolvedValue({
-    id: 'preview-1',
+    id: '1',
     branch: 'master',
     status: 'uninstalling',
     health: 'pending',
@@ -83,7 +83,7 @@ test('submits a branch with an optional commit hash', async () => {
 test('shows health and web url, then confirms uninstall', async () => {
   vi.mocked(api.listDeployments).mockResolvedValue([
     {
-      id: 'preview-2',
+      id: '42',
       branch: 'feature/demo',
       resolvedCommit: '1234567890abcdef',
       status: 'running',
@@ -98,6 +98,7 @@ test('shows health and web url, then confirms uninstall', async () => {
 
   expect(await screen.findByText('健康')).toBeTruthy();
   expect(screen.getByText('端口 8400')).toBeTruthy();
+  expect(screen.getByText('构建 #42')).toBeTruthy();
   expect(
     screen.getByRole('link', { name: /打开 Web/u }).getAttribute('href'),
   ).toBe('http://192.168.35.82:8400');
@@ -107,7 +108,7 @@ test('shows health and web url, then confirms uninstall', async () => {
   fireEvent.click(screen.getByRole('button', { name: '确认卸载' }));
 
   await waitFor(() => {
-    expect(api.uninstallDeployment).toHaveBeenCalledWith('preview-2');
+    expect(api.uninstallDeployment).toHaveBeenCalledWith('42');
   });
 });
 
diff --git a/apps/preview-deployer-web/src/PreviewDeployerApp.tsx b/apps/preview-deployer-web/src/PreviewDeployerApp.tsx
index 45f7e7d80..ec5e30773 100644
--- a/apps/preview-deployer-web/src/PreviewDeployerApp.tsx
+++ b/apps/preview-deployer-web/src/PreviewDeployerApp.tsx
@@ -289,6 +289,9 @@ export function PreviewDeployerApp() {
       return;
     }
     const deployment = pendingUninstall;
+    if (!deployment.id) {
+      return;
+    }
     setPendingUninstall(null);
     setUninstallingId(deployment.id);
     setError('');
@@ -676,7 +679,10 @@ export function PreviewDeployerApp() {
             <div className="deployment-list">
               {deployments.map((deployment) => (
                 <DeploymentCard
-                  key={deployment.id}
+                  key={
+                    deployment.id ??
+                    `${deployment.branch}-${deployment.createdAt}`
+                  }
                   deployment={deployment}
                   uninstalling={uninstallingId === deployment.id}
                   onUninstall={() => setPendingUninstall(deployment)}
@@ -774,6 +780,9 @@ function DeploymentCard({
           {deployment.webPort ? (
             <span className="badge port-badge">端口 {deployment.webPort}</span>
           ) : null}
+          <span className="badge record-badge">
+            构建 #{deployment.id || '待分配'}
+          </span>
         </div>
       </div>
 
@@ -811,7 +820,7 @@ function DeploymentCard({
               构建详情 <ExternalLink size={13} />
             </a>
           ) : null}
-          {canUninstall ? (
+          {canUninstall && deployment.id ? (
             <button
               className="icon-danger-button"
               type="button"
diff --git a/apps/preview-deployer-web/src/styles.css b/apps/preview-deployer-web/src/styles.css
index cb3ccb9df..d552998c2 100644
--- a/apps/preview-deployer-web/src/styles.css
+++ b/apps/preview-deployer-web/src/styles.css
@@ -449,6 +449,11 @@ a {
   background: #f1f5f9;
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
 }
+.record-badge {
+  color: #475569;
+  background: #f8fafc;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
 .badge-running {
   color: #14734a;
   background: #e9f9f0;
diff --git a/apps/preview-deployer-web/src/types.ts b/apps/preview-deployer-web/src/types.ts
index da08df216..6a3feb88a 100644
--- a/apps/preview-deployer-web/src/types.ts
+++ b/apps/preview-deployer-web/src/types.ts
@@ -11,7 +11,7 @@ export type DeploymentStatus =
 export type DeploymentHealth = 'pending' | 'healthy' | 'unhealthy' | 'unknown';
 
 export interface PreviewDeployment {
-  id: string;
+  id?: string | null;
   branch: string;
   commitHash?: string | null;
   resolvedCommit?: string | null;
diff --git a/deploy/env/preview-deployer.env.example b/deploy/env/preview-deployer.env.example
index d76e4e62f..ca6a726db 100644
--- a/deploy/env/preview-deployer.env.example
+++ b/deploy/env/preview-deployer.env.example
@@ -1,6 +1,8 @@
 # 仅部署在本机内网 HTTP 入口 http://192.168.35.82/build/。
 GENARRATIVE_PREVIEW_DEPLOYER_BIND=127.0.0.1:8410
 GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_BASE_URL=http://127.0.0.1:8080/jenkins/
+# 页面“构建详情”链接使用局域网地址，内部请求仍使用上面的 loopback 地址。
+GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_PUBLIC_BASE_URL=http://192.168.35.82:8080/jenkins/
 GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_USERNAME=preview-deployer-service
 GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_API_TOKEN=<由Jenkins管理员生成的专用API Token>
 # 只读源码查询固定使用本机 Gitea SSH 入口，控制服务不接受客户端传入 remote。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index bc671a867..c76f2d5da 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -14161,3 +14161,9 @@
 - 实例与端口：分支规范化后形成稳定 `deploymentId`，同一分支换 commit 复用实例和 Web 端口；不同分支使用独立 Compose project。Web 端口在全局文件锁内从 `8400..8499` 分配，状态表与宿主监听同时空闲才可占用，卸载后释放。SpacetimeDB 与 OTLP 不映射宿主端口，Jenkins 通过受控 Compose 网络发布模块；页面只展示 Web 内网地址。
 - 来源与卸载：部署只接受 `SOURCE_BRANCH` 和可选 `COMMIT_HASH`，Jenkins 必须证明 commit 属于目标分支。卸载只接受受控状态中存在的 `deploymentId`，客户端不能传 Jenkins URL、Job、Compose project、容器名或端口。状态通过固定 `preview-result.json` artifact 返回，不解析或向浏览器暴露完整 console。
 - 关联文档：`docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-08-17 预览发布记录使用 Jenkins 构建编号并有限保留
+
+- 决策：内部稳定 `deploymentId` 继续绑定分支、Compose project 和端口租约；页面/API 记录 ID 在 Jenkins 分配执行器后改为构建编号，排队阶段为“待分配”。卸载通过构建编号找到内部实例，再向固定 Job 传内部 ID。
+- 清理：失败或取消且不存在可卸载实例的记录保留 7 天；成功卸载的内部审计记录保留 30 天；仍可卸载的失败记录永久保留到人工卸载。服务启动、读取列表和创建部署时执行清理并原子落盘。
+- 链接：服务内部仍通过 Jenkins loopback 轮询；只向浏览器返回由 `GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_PUBLIC_BASE_URL` 构造的局域网构建详情地址，禁止回传 loopback URL。
diff --git a/docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md b/docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md
index fd4943e0d..93d5fa629 100644
--- a/docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md
+++ b/docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md
@@ -25,7 +25,7 @@
 
 ## 部署身份与端口
 
-`deploymentId` 由规范化分支名与分支名摘要确定，同一分支稳定得到同一 ID；commit 不进入 ID，因此同一分支重新构建或指定不同 commit 时复用同一预览实例和 Web 端口。
+预览实例 ID（`deploymentId`）由规范化分支名与分支名摘要确定，只在控制服务内部和 Jenkins 参数中使用；commit 不进入该 ID，因此同一分支重新构建或指定不同 commit 时复用同一预览实例和 Web 端口。页面发布记录的公开 ID 使用 Jenkins 构建编号：排队期间尚未分配编号，显示“待分配”，构建开始后立即显示真实编号。
 
 Web 端口池固定为 `8400..8499`：
 
@@ -94,7 +94,7 @@ SpacetimeDB 2.7 CLI 发布到受控 Compose 网络地址时固定使用 `--yes=r
 
 页面状态统一为 `queued / building / deploying / running / uninstalling / stopped / failed / cancelled`，健康状态统一为 `pending / healthy / unhealthy / unknown`。
 
-发布记录卡片直接展示后端校验后的 `webPort`。卸载成功的 `stopped` 记录仍保留在服务端持久状态中用于审计和所有权校验，但列表 API 不再返回，页面刷新后立即从发布记录中消失。
+发布记录卡片直接展示 Jenkins 构建编号、后端校验后的 `webPort` 和由控制服务转换的 Jenkins 局域网构建详情地址；内部 loopback Jenkins 地址不得返回浏览器。失败或取消且不存在可卸载实例的记录保留 7 天，成功卸载的内部记录保留 30 天，清理会在服务启动、读取列表和创建新构建时执行。仍可卸载的失败记录不会自动清理。`stopped` 记录仍保留在服务端持久状态中用于审计和所有权校验，但列表 API 不再返回，页面刷新后立即从发布记录中消失。
 
 分支名和 commit 输入框采用 300ms 防抖搜索，并在输入框下方显示服务端结果；分支变化时清空已输入的 commit，避免把旧分支 commit 带入新请求。搜索结果只负责辅助填写，不作为构建授权或存在性真相。`POST /deployments` 在写入排队状态和触发 Jenkins 前必须重新查询固定远端：分支不存在时拒绝；填写 commit 时必须确认它可解析为 commit object 且是目标分支 HEAD 的祖先。远端查询失败时失败关闭，不得触发 Jenkins。Jenkins checkout 继续执行相同的最终归属校验，以覆盖预检到排队之间的分支变化。
 
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 5d47dab93..16de6919b 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -675,7 +675,7 @@ npm run container:down
 容器方案默认暴露 `http://127.0.0.1:18080`，`api-server` 在容器内监听 `0.0.0.0:8082`，Nginx 通过 `api-server:8082` upstream 反代 `/api/` 和 `/admin/api/`。SpacetimeDB 也纳入 compose，容器内由 `spacetimedb:3101` 提供服务，宿主机通过 `http://127.0.0.1:13101` 进行模块发布；Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。生产 provision 侧现在由目标 dev / release agent 自己准备 `provision-tools/otelcol-contrib`，并安装本机 `otelcol-contrib.service`，真实库名、token 和外部服务密钥只写本地 `deploy/container/api-server.env`，不提交 Git。旧 gallery K6 profile 已退役；当前容器拓扑（明确不含 BgFilter worker）、端口和 OTLP debug exporter 使用方法见 `deploy/container/README.md`。
 `npm run container:config` 默认只做 quiet 校验，避免把本地 env 中的 token 展开到终端；确需排查完整 compose 时再传 `-- --print`。
 
-多人内网预览入口固定为 `http://192.168.35.82/build/`，不配置公网域名。该独立 Jenkins 容器预览部署控制面不让浏览器直接操作 Docker 或持有 Jenkins Token；SPA 通过同源代理触发固定 `shared/Genarrative-Preview-Deployer` Job。分支和 commit 输入框通过受认证的控制服务搜索固定内网 Git 仓库并展示下拉结果；提交构建前控制服务重新确认分支存在、可选 commit 存在且属于目标分支，失败时不触发 Jenkins，Jenkins checkout 仍保留最终复核。每个分支使用稳定 `deploymentId` 和独立 Compose project，Web 端口从 `8400..8499` 在文件锁内分配，同一分支换 commit 优先复用端口，卸载后释放。Jenkins 用 `preview-result.json` 向页面提供 resolved commit、发布结果和内网 Web URL，页面刷新时由控制服务实时复核 Web 健康。安装资产为 `deploy/systemd/genarrative-preview-deployer.service`、`deploy/env/preview-deployer.env.example` 和 `deploy/nginx/genarrative-preview-deployer-lan.conf`；完整合同见 `docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md`。
+多人内网预览入口固定为 `http://192.168.35.82/build/`，不配置公网域名。该独立 Jenkins 容器预览部署控制面不让浏览器直接操作 Docker 或持有 Jenkins Token；SPA 通过同源代理触发固定 `shared/Genarrative-Preview-Deployer` Job。分支和 commit 输入框通过受认证的控制服务搜索固定内网 Git 仓库并展示下拉结果；提交构建前控制服务重新确认分支存在、可选 commit 存在且属于目标分支，失败时不触发 Jenkins，Jenkins checkout 仍保留最终复核。每个分支使用稳定的内部 `deploymentId` 和独立 Compose project，Web 端口从 `8400..8499` 在文件锁内分配，同一分支换 commit 优先复用端口，卸载后释放；页面记录 ID 使用 Jenkins 构建编号。Jenkins 用 `preview-result.json` 向页面提供 resolved commit、发布结果和内网 Web URL，页面刷新时由控制服务实时复核 Web 健康；构建详情链接固定使用局域网 Jenkins 地址，不暴露 loopback 地址。失败/取消且不可卸载的记录保留 7 天，停止记录保留 30 天，仍可卸载的失败记录不会自动清理。安装资产为 `deploy/systemd/genarrative-preview-deployer.service`、`deploy/env/preview-deployer.env.example` 和 `deploy/nginx/genarrative-preview-deployer-lan.conf`；完整合同见 `docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md`。
 隔离验证 worker 队列和 API-only 更新时使用 `npm run container:worker-smoke -- smoke`。该命令不复用 `deploy/container/api-server.env`，会在 `deploy/container/worker-smoke/` 生成本机专用 env 与端口 state，并且只使用 unsupported job 验证 worker claim / fail 回写，不覆盖 BgFilter 成功、失败或 fallback 链路，也不需要真实外部生成密钥；本机 crates.io 网络不稳时使用 `--local-binary`，由容器内 Cargo 复用本机 Cargo 缓存构建，并把产物放进 Debian bookworm smoke runtime。
 
 独立 BgFilter worker 的本机全进程验证先运行 `cargo build -p api-server --manifest-path server-rs/Cargo.toml`，再依次运行 `npm run bgfilter-worker:smoke-test`、`npm run bgfilter-worker:load-smoke` 和 `npm run bgfilter-worker:fault-smoke`。三条命令只使用动态 loopback 端口、假 OSS 签名配置和本地 mock provider；不会读取仓库 `.env*` 或请求真实 BgFilter / OSS。自定义或 WSL binary 通过 `GENARRATIVE_BGFILTER_SMOKE_BINARY` 指定。当前 fault 范围包含 overload、queue deadline、两类 HTTP 状态顺序重试结果，以及 provider 成功响应 body 中途 reset 后第二次 attempt 串行成功；慢读、大响应、父侧客户端断连与 SIGTERM 排空另行验证。
diff --git a/scripts/check-preview-deployer.mjs b/scripts/check-preview-deployer.mjs
index 4680d1d0a..5cee19342 100644
--- a/scripts/check-preview-deployer.mjs
+++ b/scripts/check-preview-deployer.mjs
@@ -21,6 +21,10 @@ const systemd = readFileSync(
   'deploy/systemd/genarrative-preview-deployer.service',
   'utf8',
 );
+const environmentExample = readFileSync(
+  'deploy/env/preview-deployer.env.example',
+  'utf8',
+);
 const server = readFileSync(
   'server-rs/crates/preview-deployer-server/src/lib.rs',
   'utf8',
@@ -162,6 +166,21 @@ assertIncludes(
   '.nest_service("/build/assets", ServeDir::new(static_dir.join("assets")))',
   '控制服务必须原生托管 /build 子路径，不能依赖 Nginx 隐式改写。',
 );
+assertIncludes(
+  server,
+  'FAILED_RECORD_TTL_SECS',
+  '控制服务必须清理过期且不可卸载的失败/取消记录。',
+);
+assertIncludes(
+  server,
+  'STOPPED_RECORD_TTL_SECS',
+  '控制服务必须为已卸载记录配置有限审计保留期。',
+);
+assertIncludes(
+  environmentExample,
+  'GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_PUBLIC_BASE_URL=http://192.168.35.82:8080/jenkins/',
+  '构建详情必须使用局域网 Jenkins 地址而非 loopback。',
+);
 assertIncludes(
   jobConfig,
   '<scriptPath>jenkins/Jenkinsfile.preview-deployer</scriptPath>',
diff --git a/server-rs/crates/preview-deployer-server/src/config.rs b/server-rs/crates/preview-deployer-server/src/config.rs
index 25fc36449..f693697bb 100644
--- a/server-rs/crates/preview-deployer-server/src/config.rs
+++ b/server-rs/crates/preview-deployer-server/src/config.rs
@@ -9,6 +9,7 @@ pub struct Config {
     pub bind_address: String,
     pub jenkins_root_url: Url,
     pub jenkins_base_url: Url,
+    pub jenkins_public_base_url: Url,
     pub jenkins_username: String,
     pub jenkins_api_token: String,
     pub git_remote_url: String,
@@ -30,6 +31,7 @@ impl fmt::Debug for Config {
             .field("bind_address", &self.bind_address)
             .field("jenkins_root_url", &self.jenkins_root_url)
             .field("jenkins_base_url", &self.jenkins_base_url)
+            .field("jenkins_public_base_url", &self.jenkins_public_base_url)
             .field(
                 "jenkins_username_configured",
                 &!self.jenkins_username.is_empty(),
@@ -79,6 +81,28 @@ impl Config {
         let jenkins_base_url = jenkins_root_url
             .join(JOB_PATH)
             .map_err(|_| "无法构造固定 Jenkins Job URL".to_string())?;
+        let mut jenkins_public_root_url = Url::parse(&required(
+            "GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_PUBLIC_BASE_URL",
+        )?)
+        .map_err(|_| {
+            "GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_PUBLIC_BASE_URL 不是有效 URL".to_string()
+        })?;
+        if !matches!(jenkins_public_root_url.scheme(), "http" | "https")
+            || jenkins_public_root_url.host_str().is_none()
+            || !jenkins_public_root_url.username().is_empty()
+            || jenkins_public_root_url.password().is_some()
+        {
+            return Err("Jenkins public base URL 必须是无凭据的 http/https 绝对 URL".to_string());
+        }
+        jenkins_public_root_url.set_query(None);
+        jenkins_public_root_url.set_fragment(None);
+        if !jenkins_public_root_url.path().ends_with('/') {
+            let path = format!("{}/", jenkins_public_root_url.path());
+            jenkins_public_root_url.set_path(&path);
+        }
+        let jenkins_public_base_url = jenkins_public_root_url
+            .join(JOB_PATH)
+            .map_err(|_| "无法构造固定 Jenkins 内网 Job URL".to_string())?;
         let access_token = required("GENARRATIVE_PREVIEW_DEPLOYER_ACCESS_TOKEN")?;
         if access_token.len() < 24 {
             return Err("GENARRATIVE_PREVIEW_DEPLOYER_ACCESS_TOKEN 至少需要 24 个字符".to_string());
@@ -124,6 +148,7 @@ impl Config {
             bind_address,
             jenkins_root_url,
             jenkins_base_url,
+            jenkins_public_base_url,
             jenkins_username: required("GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_USERNAME")?,
             jenkins_api_token: required("GENARRATIVE_PREVIEW_DEPLOYER_JENKINS_API_TOKEN")?,
             git_remote_url: validate_git_remote_url(&required(
diff --git a/server-rs/crates/preview-deployer-server/src/jenkins.rs b/server-rs/crates/preview-deployer-server/src/jenkins.rs
index 9bb553a68..04b8deb10 100644
--- a/server-rs/crates/preview-deployer-server/src/jenkins.rs
+++ b/server-rs/crates/preview-deployer-server/src/jenkins.rs
@@ -11,6 +11,7 @@ pub struct JenkinsClient {
     http: Client,
     root_url: Url,
     job_url: Url,
+    public_job_url: Url,
     username: String,
     api_token: String,
     poll_interval: Duration,
@@ -32,6 +33,11 @@ pub struct BuildReference {
     queue_url: Url,
 }
 
+pub struct BuildStarted {
+    pub number: u64,
+    pub public_url: String,
+}
+
 impl BuildReference {
     pub fn as_str(&self) -> &str {
         self.queue_url.as_str()
@@ -98,6 +104,7 @@ impl JenkinsClient {
             http,
             root_url: config.jenkins_root_url.clone(),
             job_url: config.jenkins_base_url.clone(),
+            public_job_url: config.jenkins_public_base_url.clone(),
             username: config.jenkins_username.clone(),
             api_token: config.jenkins_api_token.clone(),
             poll_interval: config.poll_interval,
@@ -200,7 +207,7 @@ impl JenkinsClient {
         mut on_build: F,
     ) -> Result<JenkinsOutcome, String>
     where
-        F: FnMut(&str) -> Fut,
+        F: FnMut(BuildStarted) -> Fut,
         Fut: Future<Output = ()>,
     {
         let build_url = loop {
@@ -226,7 +233,13 @@ impl JenkinsClient {
             tokio::time::sleep(self.poll_interval).await;
         };
 
-        on_build(build_url.as_str()).await;
+        let build_number = parse_build_number(&build_url, &self.job_url)?;
+        let public_url = self.public_build_url(&build_url)?;
+        on_build(BuildStarted {
+            number: build_number,
+            public_url: public_url.to_string(),
+        })
+        .await;
         let successful = loop {
             let mut state_url = build_url
                 .join("api/json")
@@ -331,4 +344,35 @@ impl JenkinsClient {
             Err("Jenkins 返回了非受信源 URL".to_string())
         }
     }
+
+    fn public_build_url(&self, internal: &Url) -> Result<Url, String> {
+        self.ensure_same_origin(internal)?;
+        let relative = internal
+            .path()
+            .strip_prefix(self.job_url.path())
+            .ok_or_else(|| "Jenkins build URL 路径无效".to_string())?;
+        let mut public = self
+            .public_job_url
+            .join(relative)
+            .map_err(|_| "无法构造 Jenkins 内网构建详情地址".to_string())?;
+        public.set_query(None);
+        public.set_fragment(None);
+        Ok(public)
+    }
+}
+
+fn parse_build_number(build_url: &Url, job_url: &Url) -> Result<u64, String> {
+    let relative = build_url
+        .path()
+        .strip_prefix(job_url.path())
+        .ok_or_else(|| "Jenkins build URL 路径无效".to_string())?
+        .trim_end_matches('/');
+    if relative.is_empty() || relative.contains('/') {
+        return Err("Jenkins build URL 缺少构建编号".to_string());
+    }
+    relative
+        .parse::<u64>()
+        .ok()
+        .filter(|number| *number > 0)
+        .ok_or_else(|| "Jenkins build 编号无效".to_string())
 }
diff --git a/server-rs/crates/preview-deployer-server/src/lib.rs b/server-rs/crates/preview-deployer-server/src/lib.rs
index e5b57e7d6..b397ed480 100644
--- a/server-rs/crates/preview-deployer-server/src/lib.rs
+++ b/server-rs/crates/preview-deployer-server/src/lib.rs
@@ -34,6 +34,8 @@ use jenkins::{BuildAction, BuildReference, JenkinsClient, JenkinsOutcome};
 
 const SESSION_COOKIE: &str = "genarrative_preview_session";
 const SESSION_TTL: Duration = Duration::from_secs(12 * 60 * 60);
+const FAILED_RECORD_TTL_SECS: u64 = 7 * 24 * 60 * 60;
+const STOPPED_RECORD_TTL_SECS: u64 = 30 * 24 * 60 * 60;
 
 #[derive(Clone)]
 pub struct AppState {
@@ -100,7 +102,8 @@ pub enum HealthStatus {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Deployment {
-    pub id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
     pub branch: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub commit_hash: Option<String>,
@@ -124,6 +127,8 @@ pub struct Deployment {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct DeploymentRecord {
     public: Deployment,
+    #[serde(default)]
+    instance_id: String,
     operation: Operation,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     queue_url: Option<String>,
@@ -448,6 +453,7 @@ async fn list_deployments(
     headers: HeaderMap,
 ) -> Result<Json<DeploymentList>, ApiError> {
     require_session(&state, &headers).await?;
+    prune_expired_records(&state).await;
     refresh_running_health(&state).await;
     let mut deployments: Vec<_> = state
         .deployments
@@ -506,13 +512,14 @@ async fn get_deployment(
     Path(id): Path<String>,
 ) -> Result<Json<Deployment>, ApiError> {
     require_session(&state, &headers).await?;
-    validate_deployment_id(&id)?;
+    validate_record_id(&id)?;
     refresh_running_health(&state).await;
     let deployment = state
         .deployments
         .read()
         .await
-        .get(&id)
+        .values()
+        .find(|record| record.public.id.as_deref() == Some(id.as_str()))
         .map(|record| record.public.clone())
         .ok_or_else(ApiError::not_found)?;
     Ok(Json(deployment))
@@ -588,6 +595,7 @@ async fn create_deployment(
     Json(payload): Json<DeployRequest>,
 ) -> Result<(StatusCode, Json<Deployment>), ApiError> {
     require_session(&state, &headers).await?;
+    prune_expired_records(&state).await;
     let branch = validate_branch(&payload.branch)?;
     let commit_hash = payload
         .commit_hash
@@ -617,7 +625,7 @@ async fn create_deployment(
     let id = derive_deployment_id(&branch);
     let now = unix_now();
     let deployment = Deployment {
-        id: id.clone(),
+        id: None,
         branch: branch.clone(),
         commit_hash: commit_hash.clone(),
         resolved_commit: None,
@@ -648,6 +656,7 @@ async fn create_deployment(
             id.clone(),
             DeploymentRecord {
                 public: deployment.clone(),
+                instance_id: id.clone(),
                 operation: Operation::Deploy,
                 queue_url: None,
             },
@@ -684,10 +693,13 @@ async fn uninstall_deployment(
     Path(id): Path<String>,
 ) -> Result<(StatusCode, Json<Deployment>), ApiError> {
     require_session(&state, &headers).await?;
-    validate_deployment_id(&id)?;
-    let branch = {
+    validate_record_id(&id)?;
+    let (record_key, instance_id, branch) = {
         let mut deployments = state.deployments.write().await;
-        let record = deployments.get_mut(&id).ok_or_else(ApiError::not_found)?;
+        let (record_key, record) = deployments
+            .iter_mut()
+            .find(|(_, record)| record.public.id.as_deref() == Some(id.as_str()))
+            .ok_or_else(ApiError::not_found)?;
         if matches!(
             record.public.status,
             DeploymentStatus::Queued
@@ -707,7 +719,11 @@ async fn uninstall_deployment(
         record.public.message = Some("等待 Jenkins 卸载".to_string());
         record.operation = Operation::Uninstall;
         record.queue_url = None;
-        record.public.branch.clone()
+        (
+            record_key.clone(),
+            record.instance_id.clone(),
+            record.public.branch.clone(),
+        )
     };
     persist_deployments(&state)
         .await
@@ -716,7 +732,7 @@ async fn uninstall_deployment(
     let reference = match state
         .jenkins
         .trigger(BuildAction::Uninstall {
-            deployment_id: &id,
+            deployment_id: &instance_id,
             branch: &branch,
         })
         .await
@@ -724,7 +740,7 @@ async fn uninstall_deployment(
         Ok(reference) => reference,
         Err(cause) => {
             let mut deployments = state.deployments.write().await;
-            if let Some(record) = deployments.get_mut(&id) {
+            if let Some(record) = deployments.get_mut(&record_key) {
                 record.public.status = DeploymentStatus::Failed;
                 record.public.health = HealthStatus::Unknown;
                 record.public.can_uninstall = true;
@@ -744,11 +760,11 @@ async fn uninstall_deployment(
         .deployments
         .read()
         .await
-        .get(&id)
+        .get(&record_key)
         .expect("deployment exists")
         .public
         .clone();
-    spawn_monitor(state, id, reference);
+    spawn_monitor(state, record_key, reference);
     Ok((StatusCode::ACCEPTED, Json(deployment)))
 }
 
@@ -776,6 +792,7 @@ fn spawn_monitor(state: AppState, id: String, reference: BuildReference) {
 fn resume_monitors(state: &AppState) {
     let state = state.clone();
     tokio::spawn(async move {
+        prune_expired_records(&state).await;
         let pending: Vec<_> = state
             .deployments
             .read()
@@ -824,18 +841,18 @@ async fn monitor_build(
 ) -> Result<(), String> {
     let outcome = state
         .jenkins
-        .wait_for_outcome(reference, |build_url| {
+        .wait_for_outcome(reference, |build| {
             let state = state.clone();
             let id = id.to_string();
-            let build_url = build_url.to_string();
             async move {
                 let mut deployments = state.deployments.write().await;
                 if let Some(record) = deployments.get_mut(&id) {
+                    record.public.id = Some(build.number.to_string());
                     record.public.status = match record.operation {
                         Operation::Deploy => DeploymentStatus::Building,
                         Operation::Uninstall => DeploymentStatus::Uninstalling,
                     };
-                    record.public.jenkins_build_url = Some(build_url);
+                    record.public.jenkins_build_url = Some(build.public_url);
                     record.public.updated_at = unix_now();
                     record.public.message = Some(match record.operation {
                         Operation::Deploy => "Jenkins 正在构建".to_string(),
@@ -1027,12 +1044,18 @@ fn load_deployments(config: &Config) -> Result<HashMap<String, DeploymentRecord>
     }
     let mut deployments = HashMap::new();
     for mut record in persisted.deployments {
-        validate_deployment_id(&record.public.id)
-            .map_err(|_| "状态文件包含无效部署 ID".to_string())?;
         let branch = validate_branch(&record.public.branch)
             .map_err(|_| "状态文件包含无效分支名".to_string())?;
-        if derive_deployment_id(&branch) != record.public.id {
-            return Err("状态文件部署 ID 与分支不匹配".to_string());
+        if record.instance_id.is_empty() {
+            record.instance_id = derive_deployment_id(&branch);
+        }
+        if record.public.id.as_deref() == Some(record.instance_id.as_str()) {
+            record.public.id = None;
+        }
+        validate_deployment_id(&record.instance_id)
+            .map_err(|_| "状态文件包含无效预览实例 ID".to_string())?;
+        if let Some(build_id) = record.public.id.as_deref() {
+            validate_record_id(build_id).map_err(|_| "状态文件包含无效构建编号".to_string())?;
         }
         if let Some(commit) = record.public.commit_hash.as_deref() {
             validate_commit(commit).map_err(|_| "状态文件包含无效 commit".to_string())?;
@@ -1067,10 +1090,10 @@ fn load_deployments(config: &Config) -> Result<HashMap<String, DeploymentRecord>
             record.public.web_port = url_port;
         }
         if deployments
-            .insert(record.public.id.clone(), record)
+            .insert(record.instance_id.clone(), record)
             .is_some()
         {
-            return Err("状态文件包含重复部署 ID".to_string());
+            return Err("状态文件包含重复预览实例 ID".to_string());
         }
     }
     Ok(deployments)
@@ -1078,7 +1101,7 @@ fn load_deployments(config: &Config) -> Result<HashMap<String, DeploymentRecord>
 
 async fn persist_deployments(state: &AppState) -> Result<(), String> {
     let mut deployments: Vec<_> = state.deployments.read().await.values().cloned().collect();
-    deployments.sort_by(|left, right| left.public.id.cmp(&right.public.id));
+    deployments.sort_by(|left, right| left.public.created_at.cmp(&right.public.created_at));
     let bytes = serde_json::to_vec_pretty(&PersistedState {
         schema_version: 1,
         deployments,
@@ -1110,6 +1133,31 @@ async fn persist_deployments(state: &AppState) -> Result<(), String> {
     Ok(())
 }
 
+async fn prune_expired_records(state: &AppState) {
+    let now = unix_now();
+    let mut deployments = state.deployments.write().await;
+    let count_before = deployments.len();
+    deployments.retain(|_, record| {
+        let age = now.saturating_sub(record.public.updated_at);
+        match record.public.status {
+            DeploymentStatus::Failed | DeploymentStatus::Cancelled
+                if !record.public.can_uninstall =>
+            {
+                age < FAILED_RECORD_TTL_SECS
+            }
+            DeploymentStatus::Stopped => age < STOPPED_RECORD_TTL_SECS,
+            _ => true,
+        }
+    });
+    let changed = deployments.len() != count_before;
+    drop(deployments);
+    if changed {
+        if let Err(cause) = persist_deployments(state).await {
+            error!(error = %cause, "failed to persist preview record cleanup");
+        }
+    }
+}
+
 async fn require_session(state: &AppState, headers: &HeaderMap) -> Result<(), ApiError> {
     if authenticated(state, headers).await {
         Ok(())
@@ -1212,6 +1260,15 @@ fn validate_deployment_id(value: &str) -> Result<(), ApiError> {
     Ok(())
 }
 
+fn validate_record_id(value: &str) -> Result<(), ApiError> {
+    value
+        .parse::<u64>()
+        .ok()
+        .filter(|number| *number > 0)
+        .map(|_| ())
+        .ok_or_else(|| ApiError::bad_request("构建编号无效"))
+}
+
 fn map_artifact_status(value: &str) -> Option<DeploymentStatus> {
     match value.to_ascii_uppercase().as_str() {
         "QUEUED" => Some(DeploymentStatus::Queued),
diff --git a/server-rs/crates/preview-deployer-server/src/tests.rs b/server-rs/crates/preview-deployer-server/src/tests.rs
index 9a4cb9bfb..b22bd6e12 100644
--- a/server-rs/crates/preview-deployer-server/src/tests.rs
+++ b/server-rs/crates/preview-deployer-server/src/tests.rs
@@ -159,6 +159,10 @@ fn test_config(jenkins_base_url: Url) -> Config {
         bind_address: "127.0.0.1:0".to_string(),
         jenkins_root_url: jenkins_base_url.clone(),
         jenkins_base_url: job_url,
+        jenkins_public_base_url: Url::parse(
+            "http://192.168.35.82:8080/jenkins/job/shared/job/Genarrative-Preview-Deployer/",
+        )
+        .unwrap(),
         jenkins_username: "preview-service".to_string(),
         jenkins_api_token: "server-only-jenkins-token".to_string(),
         git_remote_url: "test://preview-repository".to_string(),
@@ -367,6 +371,11 @@ async fn deploy_and_uninstall_use_fixed_job_and_apply_owned_artifacts() {
         .public
         .clone();
     assert_eq!(deployment.status, super::DeploymentStatus::Running);
+    assert_eq!(deployment.id.as_deref(), Some("1"));
+    assert_eq!(
+        deployment.jenkins_build_url.as_deref(),
+        Some("http://192.168.35.82:8080/jenkins/job/shared/job/Genarrative-Preview-Deployer/1/")
+    );
     assert_eq!(deployment.health, super::HealthStatus::Healthy);
     assert_eq!(deployment.web_port, Some(8400));
     assert_eq!(
@@ -381,7 +390,7 @@ async fn deploy_and_uninstall_use_fixed_job_and_apply_owned_artifacts() {
 
     let uninstall_request = axum::http::Request::builder()
         .method("POST")
-        .uri(format!("/api/preview-deployer/deployments/{id}/uninstall"))
+        .uri("/api/preview-deployer/deployments/1/uninstall")
         .header(header::HOST, HOST)
         .header(header::ORIGIN, ORIGIN)
         .header(header::COOKIE, &cookie)
@@ -588,7 +597,7 @@ async fn duplicate_active_branch_is_rejected_without_second_jenkins_trigger() {
         id.clone(),
         super::DeploymentRecord {
             public: super::Deployment {
-                id,
+                id: None,
                 branch: "feature/busy".to_string(),
                 commit_hash: None,
                 resolved_commit: None,
@@ -602,6 +611,7 @@ async fn duplicate_active_branch_is_rejected_without_second_jenkins_trigger() {
                 message: None,
                 can_uninstall: false,
             },
+            instance_id: id,
             operation: super::Operation::Deploy,
             queue_url: None,
         },
@@ -712,3 +722,89 @@ fn legacy_running_state_recovers_web_port_from_validated_url() {
     );
     std::fs::remove_file(&state.config.state_file).unwrap();
 }
+
+#[tokio::test]
+async fn expired_terminal_records_are_pruned_but_uninstallable_failures_are_retained() {
+    let (jenkins_url, _) = start_mock_jenkins().await;
+    let state = AppState::new(test_config(jenkins_url)).unwrap();
+    let app = build_router(state.clone());
+    let cookie = login_cookie(&app).await;
+    let old = super::unix_now().saturating_sub(super::FAILED_RECORD_TTL_SECS + 1);
+    let failed_id = super::derive_deployment_id("feature/old-failure");
+    let uninstallable_id = super::derive_deployment_id("feature/failed-uninstall");
+    state.deployments.write().await.extend([
+        (
+            failed_id.clone(),
+            super::DeploymentRecord {
+                public: super::Deployment {
+                    id: Some("91".to_string()),
+                    branch: "feature/old-failure".to_string(),
+                    commit_hash: None,
+                    resolved_commit: None,
+                    status: super::DeploymentStatus::Failed,
+                    health: super::HealthStatus::Unknown,
+                    web_port: None,
+                    web_url: None,
+                    jenkins_build_url: None,
+                    created_at: old,
+                    updated_at: old,
+                    message: None,
+                    can_uninstall: false,
+                },
+                instance_id: failed_id.clone(),
+                operation: super::Operation::Deploy,
+                queue_url: None,
+            },
+        ),
+        (
+            uninstallable_id.clone(),
+            super::DeploymentRecord {
+                public: super::Deployment {
+                    id: Some("92".to_string()),
+                    branch: "feature/failed-uninstall".to_string(),
+                    commit_hash: None,
+                    resolved_commit: None,
+                    status: super::DeploymentStatus::Failed,
+                    health: super::HealthStatus::Unknown,
+                    web_port: Some(8401),
+                    web_url: Some("http://192.168.35.82:8401".to_string()),
+                    jenkins_build_url: None,
+                    created_at: old,
+                    updated_at: old,
+                    message: None,
+                    can_uninstall: true,
+                },
+                instance_id: uninstallable_id.clone(),
+                operation: super::Operation::Uninstall,
+                queue_url: None,
+            },
+        ),
+    ]);
+
+    let response = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("GET")
+                .uri("/api/preview-deployer/deployments")
+                .header(header::HOST, HOST)
+                .header(header::COOKIE, &cookie)
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = response.into_body().collect().await.unwrap().to_bytes();
+    let listed: Value = serde_json::from_slice(&body).unwrap();
+    assert_eq!(listed["deployments"].as_array().unwrap().len(), 1);
+    assert_eq!(listed["deployments"][0]["id"], "92");
+    assert!(!state.deployments.read().await.contains_key(&failed_id));
+    assert!(
+        state
+            .deployments
+            .read()
+            .await
+            .contains_key(&uninstallable_id)
+    );
+    std::fs::remove_file(&state.config.state_file).unwrap();
+}