Deploy 6590d91 to Docker Space

.env.example

@@ -151,6 +151,11 @@ OPENAI_API_BASE_URL=
 # 可选：给网页加一个访问码。公网部署时建议一定要设置。
 APP_PASSWORD=
 
+# Compose 默认只发布到 127.0.0.1:4783。需要局域网或公网访问时，在 shell 或 Compose 的 .env
+# 文件显式设置非回环地址，并同时在 .env.local 设置上面的 APP_PASSWORD；未设置访问码时容器会拒绝启动。
+# GIP_BIND_HOST=0.0.0.0
+# GIP_PORT=4783
+
 # 可选：给 /api/agent/* 使用的 Bearer token。公网或内网共享部署时建议设置。
 # AGENT_API_TOKEN=
 
@@ -158,6 +163,8 @@ APP_PASSWORD=
 # AGENT_STATE_BACKEND=sqlite
 # AGENT_SQLITE_PATH=generated-images/.agent-state/agent.sqlite
 # AGENT_DATABASE_URL=postgres://gpt_image:<database-password>@localhost:5432/gpt_image_playground
+# docker-compose.postgres.yml 从 shell 或 Compose 的 .env 读取此 Secret，不要把真实值写进 .env.local 或仓库文件。
+# GPT_IMAGE_POSTGRES_PASSWORD=
 # AGENT_REQUEST_LEASE_MS=600000
 # AGENT_REQUEST_TTL_SECONDS=86400
 

.github/workflows/ci.yml

@@ -96,22 +96,34 @@ jobs:
           persist-credentials: false
 
       - name: Build production image
-        run: docker build --tag gpt-image-playground-customer:ci .
+        run: docker build --build-arg VCS_REF="${GITHUB_SHA}" --tag gpt-image-playground-customer:ci .
 
       - name: Start production container
-        run: docker run --detach --name gpt-image-playground-customer-ci --publish 127.0.0.1:4783:4783 gpt-image-playground-customer:ci
+        run: >-
+          docker run --detach --name gpt-image-playground-customer-ci
+          --env GIP_COMPOSE_DEPLOYMENT=true --env GIP_BIND_HOST=127.0.0.1
+          --publish 127.0.0.1:4783:4783 gpt-image-playground-customer:ci
 
       - name: Verify production endpoint
         shell: bash
         run: |
           set -euo pipefail
-          for attempt in {1..30}; do
-            if curl --fail --silent --max-time 5 http://127.0.0.1:4783/api/auth-status >/tmp/auth-status.json; then
+          for attempt in {1..120}; do
+            health_status="$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}missing{{end}}' gpt-image-playground-customer-ci)"
+            if [[ "$health_status" == "healthy" ]] && curl --fail --silent --max-time 5 http://127.0.0.1:4783/api/auth-status >/tmp/auth-status.json; then
               node --input-type=module -e "import { readFileSync } from 'node:fs'; const response = JSON.parse(readFileSync('/tmp/auth-status.json', 'utf8')); if (response.passwordRequired !== false) throw new Error('Expected the CI container auth-status endpoint to report passwordRequired=false.');"
+              image_revision="$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}' gpt-image-playground-customer:ci)"
+              if [[ "$image_revision" != "$GITHUB_SHA" ]]; then
+                printf 'Image revision mismatch: expected %s, received %s\n' "$GITHUB_SHA" "$image_revision"
+                docker logs gpt-image-playground-customer-ci
+                exit 1
+              fi
               exit 0
             fi
-            printf 'Waiting for auth-status endpoint (attempt %s/30)\n' "$attempt"
-            sleep 1
+            printf 'Waiting for healthy production container and auth-status endpoint (attempt %s/120, health=%s)\n' "$attempt" "$health_status"
+            if (( attempt < 120 )); then
+              sleep 1
+            fi
           done
           docker logs gpt-image-playground-customer-ci
           exit 1

Dockerfile

@@ -18,19 +18,23 @@ RUN npm run build
 FROM node:26-alpine AS runner
 WORKDIR /app
 ARG NEXT_PUBLIC_IMAGE_STORAGE_MODE=fs
+ARG VCS_REF=unknown
 ENV NODE_ENV=production
 ENV NEXT_TELEMETRY_DISABLED=1
 ENV NEXT_PUBLIC_IMAGE_STORAGE_MODE=${NEXT_PUBLIC_IMAGE_STORAGE_MODE}
 ENV PORT=4783
 ENV HOSTNAME=0.0.0.0
+LABEL org.opencontainers.image.revision=$VCS_REF
 
 COPY --from=builder --chown=node:node /app/.next/standalone ./
 COPY --from=builder --chown=node:node /app/.next/static ./.next/static
 COPY --from=builder --chown=node:node /app/public ./public
 COPY --from=builder --chown=node:node /app/node_modules/next/dist/compiled/next-server ./node_modules/next/dist/compiled/next-server
+COPY --from=builder --chown=node:node /app/scripts/docker-entrypoint.mjs ./scripts/docker-entrypoint.mjs
 
 RUN mkdir -p /app/generated-images && chown node:node /app/generated-images
 USER node
 
 EXPOSE 4783
-CMD ["node", "server.js"]
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["node", "-e", "const port = process.env.PORT || '4783'; fetch(`http://127.0.0.1:${port}/api/auth-status`, { signal: AbortSignal.timeout(4000) }).then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1));"]
+CMD ["node", "scripts/docker-entrypoint.mjs"]

README.md

@@ -12,7 +12,7 @@ app_port: 4783
 本地 AI 图片创作工作台，面向中文内容运营、设计草图和自动化生图流程。支持 `gpt-image-2`、OpenAI 兼容图片接口、文生图、图生图、遮罩编辑、批量任务、历史复用、费用追踪和 Agent API。
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/MisonL/gpt-image-playground-customer/128efae485d0eb35670a525cf19069b5da3f4ace/readme-images/interface.jpg?v=20260608-07b596b" alt="GPT Image Playground 界面" width="900"/>
+  <img src="https://raw.githubusercontent.com/MisonL/gpt-image-playground-customer/6590d91c9e6e0a3314fa16bd8e5667b2d9e855cd/readme-images/interface.jpg?v=20260608-07b596b" alt="GPT Image Playground 界面" width="900"/>
 </p>
 
 ## 快速开始
@@ -30,10 +30,10 @@ npm run first-run -- --base-url https://your-space.hf.space
 npm run first-run -- --json --base-url https://your-space.hf.space
 ```
 
-本地服务推荐用 Docker：
+本地服务推荐使用带健康检查和镜像 revision 核验的部署脚本：
 
 ```bash
-docker compose up -d --build --remove-orphans
+npm run deploy:local
 ```
 
 打开：
@@ -83,13 +83,13 @@ start-windows.bat
 遮罩编辑示例：
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/MisonL/gpt-image-playground-customer/128efae485d0eb35670a525cf19069b5da3f4ace/readme-images/mask-creation.jpg?v=20260608-07b596b" alt="遮罩创建" width="900"/>
+  <img src="https://raw.githubusercontent.com/MisonL/gpt-image-playground-customer/6590d91c9e6e0a3314fa16bd8e5667b2d9e855cd/readme-images/mask-creation.jpg?v=20260608-07b596b" alt="遮罩创建" width="900"/>
 </p>
 
 历史与费用示例：
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/MisonL/gpt-image-playground-customer/128efae485d0eb35670a525cf19069b5da3f4ace/readme-images/history.jpg?v=20260608-07b596b" alt="历史面板" width="900"/>
+  <img src="https://raw.githubusercontent.com/MisonL/gpt-image-playground-customer/6590d91c9e6e0a3314fa16bd8e5667b2d9e855cd/readme-images/history.jpg?v=20260608-07b596b" alt="历史面板" width="900"/>
 </p>
 
 ## 配置
@@ -98,6 +98,7 @@ start-windows.bat
 
 | 场景               | 变量                                                                                                | 说明                                                                                                                                                                                                                                                                                                                                                                                                               |
 | ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Docker 监听地址    | `GIP_BIND_HOST`、`GIP_PORT`                                                                         | Compose 默认仅发布到 `127.0.0.1:4783`。需要局域网或公网访问时显式设置非回环 `GIP_BIND_HOST`，并同时设置 `APP_PASSWORD`；容器会拒绝未设置访问码的非回环发布。                                                                                                                                                                                                                                                           |
 | 默认上游           | `OPENAI_API_KEY`、`OPENAI_API_BASE_URL`                                                             | 服务端默认 OpenAI 或兼容接口配置。页面 `API 设置` 优先级更高。                                                                                                                                                                                                                                                                                                                                                     |
 | 上游代理           | `OPENAI_UPSTREAM_PROXY_URL`、`OPENAI_CHANNEL_N_PROXY_URL`                                           | 可选。只用于服务端到图片上游的出站请求；渠道级地址优先于全局地址。仅接受无认证、无路径、无查询参数和无片段的 `http://` / `https://` 根代理地址，不支持 SOCKS。运行态和 Agent 诊断只公开是否启用及协议，不公开代理主机或端口。 |
 | 页面访问码         | `APP_PASSWORD`                                                                                      | 设置后访问页面和受保护图片需要访问码。公网部署建议开启。                                                                                                                                                                                                                                                                                                                                                           |
@@ -316,16 +317,16 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
 
 ## Docker 与部署
 
-默认 Compose 使用 SQLite 状态库和本地图片目录：
+默认 Compose 使用 SQLite 状态库和本地图片目录，并且只绑定本机回环地址：
 
 ```bash
-docker compose up -d --build --remove-orphans
+npm run deploy:local
 ```
 
-本地重建并探测真实端点：
+部署脚本会拒绝脏工作区、重建镜像、等待 Docker healthcheck、探测真实端点，并确认容器镜像的 revision 与当前 Git 提交一致。默认模式会断言 `sqlite/fs` 生效，`--memory` 会断言 `memory/indexeddb`，`--postgres` 会断言 `postgres/fs`。若确实需要局域网访问，先在 `.env.local` 设置 `APP_PASSWORD`，再显式指定绑定地址：
 
 ```bash
-npm run deploy:local
+GIP_BIND_HOST=0.0.0.0 npm run deploy:local
 ```
 
 本仓库的 Compose 服务只挂载 `generated-images/`。不要用 `docker run -v "$PWD:/workspace"` 启动本地图片上游 fixture；这会把 `.git/`、`node_modules/` 和 `.next/` 暴露给 Docker Desktop 文件共享层，可能触发文件事件风暴。本地 fixture gate 使用进程内服务：
@@ -342,11 +343,13 @@ npm run docker:cleanup-fixtures
 
 常见部署模式：
 
-| 模式       | 命令或配置                                           | 适用场景                              |
-| ---------- | ---------------------------------------------------- | ------------------------------------- |
-| SQLite     | `docker-compose.yml`                                 | 本地单实例和长期本地服务。            |
-| Memory     | `docker-compose.yml` + `docker-compose.memory.yml`   | Hugging Face Space 或临时演示。       |
-| PostgreSQL | `docker-compose.yml` + `docker-compose.postgres.yml` | 高并发、多实例或集中状态库。          |
+| 模式       | 命令                                      | 适用场景                              |
+| ---------- | ----------------------------------------- | ------------------------------------- |
+| SQLite     | `npm run deploy:local`                    | 本地单实例和长期本地服务。            |
+| Memory     | `npm run deploy:local -- --memory`        | Hugging Face Space 或临时演示。       |
+| PostgreSQL | `npm run deploy:local -- --postgres`      | 高并发、多实例或集中状态库。          |
+
+PostgreSQL 模式要求在运行 Compose 的 shell 或 Compose `.env` 中提供 `GPT_IMAGE_POSTGRES_PASSWORD`。不要把该 Secret 写入 `.env.local`；overlay 会显式清空直连密码变量，确保应用只读取 Docker secret 文件。
 
 图片默认保存在：
 

docker-compose.postgres.yml

@@ -20,36 +20,21 @@ services:
       - postgres-data:/var/lib/postgresql/data
 
   gpt-image-playground:
-    build:
-      context: .
-    image: gpt-image-playground-customer:postgres
-    container_name: gpt-image-playground-customer
-    restart: unless-stopped
-    env_file:
-      - path: .env.local
-        required: false
     environment:
-      NODE_ENV: production
-      NEXT_TELEMETRY_DISABLED: "1"
-      NEXT_PUBLIC_IMAGE_STORAGE_MODE: fs
       AGENT_STATE_BACKEND: postgres
-      # Force Docker secret fields below even if .env.local contains AGENT_DATABASE_URL.
+      # Force Docker secret fields below even if .env.local contains direct database credentials.
       AGENT_DATABASE_URL: ""
+      AGENT_DB_PASSWORD: ""
       AGENT_DB_HOST: postgres
       AGENT_DB_PORT: "5432"
       AGENT_DB_NAME: gpt_image_playground
       AGENT_DB_USER: gpt_image
       AGENT_DB_PASSWORD_FILE: /run/secrets/postgres_password
-      PORT: "4783"
     secrets:
       - postgres_password
     depends_on:
       postgres:
         condition: service_healthy
-    ports:
-      - "4783:4783"
-    volumes:
-      - ./generated-images:/app/generated-images
 
 volumes:
   postgres-data:

docker-compose.yml

@@ -4,7 +4,9 @@ services:
   gpt-image-playground:
     build:
       context: .
-    image: gpt-image-playground-customer:local
+      args:
+        VCS_REF: ${GIP_IMAGE_REVISION:-unknown}
+    image: gpt-image-playground-customer:${GIP_IMAGE_TAG:-local}
     container_name: gpt-image-playground-customer
     restart: unless-stopped
     env_file:
@@ -17,7 +19,11 @@ services:
       AGENT_STATE_BACKEND: sqlite
       NEXT_PUBLIC_IMAGE_STORAGE_MODE: fs
       PORT: "4783"
+      GIP_COMPOSE_DEPLOYMENT: "true"
+      GIP_BIND_HOST: "${GIP_BIND_HOST:-127.0.0.1}"
+    labels:
+      org.opencontainers.image.revision: "${GIP_IMAGE_REVISION:-unknown}"
     ports:
-      - "4783:4783"
+      - "${GIP_BIND_HOST:-127.0.0.1}:${GIP_PORT:-4783}:4783"
     volumes:
       - ./generated-images:/app/generated-images

docs/deployment/huggingface-space-free.md

@@ -85,7 +85,7 @@ npm run agent:doctor
 - `status`：只读输出 git、Node、固定 Space 目标、Agent capabilities 路径和 Skill 入口。
 - `doctor`：统一诊断入口，默认包含 HF Space 只读远端检查，并校验当前 npm 是否支持严格安装脚本策略、本地 `node_modules` 隐藏锁文件和直接依赖版本是否与根锁文件一致。
 - `verify`：提交前基线，先核对锁文件安装脚本与 `allowScripts` 白名单、当前 npm 严格安装策略能力和已安装直接依赖，再执行测试、lint、脚本语法、构建和 `git diff --check`；需要真实 PostgreSQL gate 时加 `--postgres`。
-- `deploy:local`：重建本地 Docker 服务并探测真实 HTTP 端点；加 `--memory` 会断言 memory/indexeddb overlay 生效。
+- `deploy:local`：拒绝脏工作区后重建本地 Docker 服务，等待 healthcheck、核验镜像 revision 并探测真实 HTTP 端点；加 `--memory` 会断言 memory/indexeddb overlay 生效，加 `--postgres` 会断言 postgres/fs overlay 生效且要求通过 shell 或 Compose `.env` 提供 `GPT_IMAGE_POSTGRES_PASSWORD`。默认 Compose 只绑定 `127.0.0.1:4783`；需要非回环发布时必须显式设置 `GIP_BIND_HOST` 和 `APP_PASSWORD`。
 - `deploy:space`：上传当前干净 git HEAD 到固定 HF Space，并做只读公网验证；已存在 Docker Space 根据远端元数据直接使用认证 Git 推送，其他类型才优先尝试 `hf upload`。
 - `agent:doctor`：通过仓库 Skill 脚本执行只读 Agent API 契约检查，不触发真实生图。
 

docs/reviews/CR-DEPLOYMENT-HARDENING-2026-07-27.md

@@ -0,0 +1,38 @@
+# 部署加固回归门禁
+
+日期: 2026-07-27
+
+范围: Docker 本地部署、Hugging Face Space memory smoke、PostgreSQL overlay、CI 运行时检查、部署脚本和部署文档。
+
+## 已审查变更
+
+- 默认 Compose 发布限制为 `127.0.0.1:4783`。
+- 非回环 Compose 发布必须设置非空 `APP_PASSWORD`。
+- Docker 镜像提供 OCI revision label 和 healthcheck。
+- 本地部署校验干净的 Git revision、镜像身份、发布端口和选定的状态/存储模式。
+- PostgreSQL overlay 在使用 Docker secret 文件前清空直连数据库凭证变量。
+- HF Space 和本地端点轮询不会在最后一次失败后继续等待。
+- CI 校验实际 Docker 入口点的回环分支、健康状态、端点响应和镜像 revision。
+
+## 自动化证据
+
+| 命令 | 退出码 | 结果 |
+| --- | --- | --- |
+| `npm run verify` | 0 | 版本、安装策略、依赖、测试、lint、脚本语法、生产构建和 diff 检查均通过。 |
+| `npm run test:postgres` | 0 | 101 个测试通过，包含真实 PostgreSQL 并发和 schema 契约。 |
+| `npm run smoke:hf-space-local` | 0 | 最新 Docker 镜像通过 memory/indexeddb 运行态和非计费 Agent 契约检查。 |
+| `docker build --check .` | 0 | 无 Dockerfile 警告。 |
+| `docker compose ... config --quiet` | 0 | SQLite、memory 和 PostgreSQL Compose 配置均成功渲染。 |
+| CI 固定 digest 的 actionlint 容器 | 0 | GitHub Actions 工作流语法和语义通过 actionlint。 |
+| 非回环 Docker 入口点检查 | 预期退出码 1 | 容器拒绝 `GIP_COMPOSE_DEPLOYMENT= TRUE `、`GIP_BIND_HOST=0.0.0.0` 且未设置 `APP_PASSWORD` 的启动。 |
+
+## 审查证据
+
+- CodeRabbit 审查全部已修改和未跟踪文件后未发现问题。
+- Claude Code 使用默认模型且未传 `--model`，报告未发现 P0-P3 问题。
+- OMP 仅识别出本地部署和 CI 的最后一次轮询延迟。两条路径均已改为仅在仍有下一次尝试时等待，并为本地探针补充回归覆盖。
+
+## 范围边界
+
+- 本门禁不执行计费的图片生成或编辑请求。
+- 真实本地 Docker 和 Hugging Face Space 发布检查属于独立部署验证步骤，因为它们需要干净的已提交 revision 和实时服务状态。

public/hf-space-deploy-marker.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "local_sha": "128efae485d0eb35670a525cf19069b5da3f4ace",
-  "created_at": "2026-07-26T03:42:06.320Z",
-  "deploy_id": "aaf32bf5-46f3-48cf-8f53-ca6c7a48ba6e"
+  "local_sha": "6590d91c9e6e0a3314fa16bd8e5667b2d9e855cd",
+  "created_at": "2026-07-27T03:45:51.712Z",
+  "deploy_id": "d1603a14-8385-441d-adac-e4c5b059dde4"
 }

scripts/command-center.test.mjs

@@ -7,7 +7,17 @@ import {
     summarizeDockerMounts
 } from './cleanup-docker-fixtures.mjs';
 import { fetchJsonWithTimeout, parseJsonPayload, pickFailureOutput, runCommand } from './command-center-utils.mjs';
-import { assertLocalProbeMatchesMode, buildDockerComposeArgs, buildDockerComposeEnv } from './deploy-local.mjs';
+import {
+    assertDeploymentImageIdentity,
+    assertLocalProbeMatchesMode,
+    buildDeploymentImageReference,
+    buildDeploymentImageTag,
+    buildDockerComposeArgs,
+    buildDockerComposeEnv,
+    buildLocalBaseUrl,
+    parsePublishedContainerPortBindings,
+    waitForLocalEndpoints
+} from './deploy-local.mjs';
 import { buildFirstRunReport, formatFirstRunText } from './first-run.mjs';
 import {
     buildAdminCommands,
@@ -449,7 +459,19 @@ describe('Command center scripts', () => {
     });
 
     it('builds deterministic local deploy compose arguments', () => {
-        assert.deepEqual(buildDockerComposeArgs(), ['compose', '-f', 'docker-compose.yml', 'up', '-d', '--build']);
+        assert.deepEqual(buildDockerComposeArgs(), [
+            'compose',
+            '-f',
+            'docker-compose.yml',
+            'up',
+            '-d',
+            '--build',
+            '--force-recreate',
+            '--remove-orphans',
+            '--wait',
+            '--wait-timeout',
+            '120'
+        ]);
         assert.deepEqual(buildDockerComposeArgs({ memory: true }), [
             'compose',
             '-f',
@@ -458,8 +480,29 @@ describe('Command center scripts', () => {
             'docker-compose.memory.yml',
             'up',
             '-d',
-            '--build'
+            '--build',
+            '--force-recreate',
+            '--remove-orphans',
+            '--wait',
+            '--wait-timeout',
+            '120'
         ]);
+        assert.deepEqual(buildDockerComposeArgs({ postgres: true }), [
+            'compose',
+            '-f',
+            'docker-compose.yml',
+            '-f',
+            'docker-compose.postgres.yml',
+            'up',
+            '-d',
+            '--build',
+            '--force-recreate',
+            '--remove-orphans',
+            '--wait',
+            '--wait-timeout',
+            '120'
+        ]);
+        assert.throws(() => buildDockerComposeArgs({ memory: true, postgres: true }), /不能同时使用/);
     });
 
     it('uses plain compose progress for diagnosable local deploy output', () => {
@@ -467,6 +510,109 @@ describe('Command center scripts', () => {
             PATH: '/bin',
             COMPOSE_PROGRESS: 'plain'
         });
+        assert.deepEqual(
+            buildDockerComposeEnv(
+                { PATH: '/bin' },
+                {
+                    revision: '0123456789abcdef0123456789abcdef01234567',
+                    imageTag: 'local-0123456789abcdef0123456789abcdef01234567'
+                }
+            ),
+            {
+                PATH: '/bin',
+                COMPOSE_PROGRESS: 'plain',
+                GIP_IMAGE_REVISION: '0123456789abcdef0123456789abcdef01234567',
+                GIP_IMAGE_TAG: 'local-0123456789abcdef0123456789abcdef01234567'
+            }
+        );
+    });
+
+    it('uses immutable full-revision Docker image tags for deploys', () => {
+        const revision = '0123456789abcdef0123456789abcdef01234567';
+        assert.equal(buildDeploymentImageTag(revision), `local-${revision}`);
+        assert.equal(buildDeploymentImageReference(revision), `gpt-image-playground-customer:local-${revision}`);
+        assert.throws(() => buildDeploymentImageTag('0123456'), /40/);
+        assert.throws(() => buildDeploymentImageTag('z'.repeat(40)), /40/);
+    });
+
+    it('builds local probe URLs from the published container port mapping', () => {
+        assert.equal(buildLocalBaseUrl('127.0.0.1', '4783'), 'http://127.0.0.1:4783');
+        assert.equal(buildLocalBaseUrl('0.0.0.0', '4784'), 'http://127.0.0.1:4784');
+        assert.equal(buildLocalBaseUrl('::1', '4783'), 'http://[::1]:4783');
+        assert.deepEqual(parsePublishedContainerPortBindings('[{"HostIp":"127.0.0.1","HostPort":"4783"}]'), {
+            bindHost: '127.0.0.1',
+            hostPort: '4783',
+            baseUrl: 'http://127.0.0.1:4783'
+        });
+        assert.deepEqual(
+            parsePublishedContainerPortBindings('[{"HostIp":"::","HostPort":"4784"},{"HostIp":"0.0.0.0","HostPort":"4784"}]'),
+            {
+                bindHost: '0.0.0.0',
+                hostPort: '4784',
+                baseUrl: 'http://127.0.0.1:4784'
+            }
+        );
+        assert.throws(() => buildLocalBaseUrl('127.0.0.1', '0'), /1 到 65535/);
+        assert.throws(() => parsePublishedContainerPortBindings('not-json'), /端口映射/);
+        assert.throws(() => parsePublishedContainerPortBindings('null'), /未发布/);
+    });
+
+    it('waits only between failed local endpoint probe attempts', async () => {
+        let requestCount = 0;
+        let sleepCount = 0;
+
+        await assert.rejects(
+            waitForLocalEndpoints('http://127.0.0.1:4783', {
+                attempts: 2,
+                intervalMs: 2000,
+                fetchJson: async () => {
+                    requestCount += 1;
+                    throw new Error('container not ready');
+                },
+                sleep: async () => {
+                    sleepCount += 1;
+                }
+            }),
+            /container not ready/
+        );
+
+        assert.equal(requestCount, 2);
+        assert.equal(sleepCount, 1);
+    });
+
+    it('requires the running Docker image and revision label to match the deployed revision', () => {
+        const deployment = {
+            revision: '0123456789abcdef0123456789abcdef01234567',
+            imageTag: 'local-0123456789abcdef0123456789abcdef01234567'
+        };
+        assert.doesNotThrow(() =>
+            assertDeploymentImageIdentity(
+                {
+                    image: 'gpt-image-playground-customer:local-0123456789abcdef0123456789abcdef01234567',
+                    revision: deployment.revision
+                },
+                deployment
+            )
+        );
+        assert.throws(
+            () =>
+                assertDeploymentImageIdentity(
+                    { image: 'gpt-image-playground-customer:local', revision: deployment.revision },
+                    deployment
+                ),
+            /镜像不匹配/
+        );
+        assert.throws(
+            () =>
+                assertDeploymentImageIdentity(
+                    {
+                        image: 'gpt-image-playground-customer:local-0123456789abcdef0123456789abcdef01234567',
+                        revision: 'different'
+                    },
+                    deployment
+                ),
+            /revision 不匹配/
+        );
     });
 
     it('detects only the legacy fixture whole-repository Docker mount', () => {
@@ -540,14 +686,33 @@ describe('Command center scripts', () => {
         assert.equal(buildSkippedReport('custom', container.Mounts).removed, false);
     });
 
-    it('fails local memory deploy probes when the overlay did not take effect', () => {
+    it('requires local deploy probes to match the selected state and storage backend', () => {
         assert.doesNotThrow(() => assertLocalProbeMatchesMode({ stateBackend: 'sqlite', imageStorageMode: 'fs' }));
+        assert.throws(
+            () => assertLocalProbeMatchesMode({ stateBackend: 'memory', imageStorageMode: 'indexeddb' }),
+            /SQLite deployment mode did not take effect/
+        );
         assert.doesNotThrow(() =>
             assertLocalProbeMatchesMode({ stateBackend: 'memory', imageStorageMode: 'indexeddb' }, { memory: true })
         );
         assert.throws(
             () => assertLocalProbeMatchesMode({ stateBackend: 'sqlite', imageStorageMode: 'fs' }, { memory: true }),
-            /Memory overlay did not take effect/
+            /Memory deployment mode did not take effect/
+        );
+        assert.doesNotThrow(() =>
+            assertLocalProbeMatchesMode({ stateBackend: 'postgres', imageStorageMode: 'fs' }, { postgres: true })
+        );
+        assert.throws(
+            () => assertLocalProbeMatchesMode({ stateBackend: 'sqlite', imageStorageMode: 'fs' }, { postgres: true }),
+            /PostgreSQL deployment mode did not take effect/
+        );
+        assert.throws(
+            () =>
+                assertLocalProbeMatchesMode(
+                    { stateBackend: 'memory', imageStorageMode: 'indexeddb' },
+                    { memory: true, postgres: true }
+                ),
+            /不能同时使用/
         );
     });
 

scripts/deploy-hf-space.mjs

@@ -353,7 +353,7 @@ export async function waitForRunning(spaceCommitSha, deployMarker, options = {})
             lastManagementError = error instanceof Error ? error.message : String(error);
             if (!isRetryableSpaceInfoReadError(error)) throw error;
             log(`attempt=${attempt} management_status=unavailable error=${lastManagementError}`);
-            await sleep(intervalMs);
+            if (attempt < attempts) await sleep(intervalMs);
             continue;
         }
         lastStage = info.runtime?.stage || 'unknown';
@@ -368,15 +368,16 @@ export async function waitForRunning(spaceCommitSha, deployMarker, options = {})
                 log(`attempt=${attempt} marker_status=not_ready error=${lastMarkerError}`);
             }
         }
-        await sleep(intervalMs);
+        if (attempt < attempts) await sleep(intervalMs);
     }
     const marker = await verifyMarker(deployMarker);
     return {
         stage: lastStage,
         sha: lastSha,
-        management_status: 'runtime_stage_not_running',
+        management_status: 'target_commit_not_confirmed',
+        verification_source: 'service_marker_after_management_timeout',
         service_marker_verified: true,
-        warning: `Space did not reach RUNNING with a matching service marker for ${spaceCommitSha}; last stage=${lastStage} sha=${lastSha} marker_error=${lastMarkerError} management_error=${lastManagementError}`,
+        warning: `Hugging Face management status did not confirm RUNNING for ${spaceCommitSha}, but the public service returned the exact one-time deploy marker; last stage=${lastStage} sha=${lastSha} marker_error=${lastMarkerError} management_error=${lastManagementError}`,
         marker
     };
 }

scripts/deploy-hf-space.test.mjs

@@ -344,6 +344,93 @@ describe('HF Space deploy script', () => {
         });
     });
 
+    it('does not sleep after the final transient management status error before verifying the marker', async () => {
+        const marker = buildDeployMarker(
+            '7777777777777777777777777777777777777777',
+            new Date('2026-06-20T14:00:00.000Z'),
+            'deploy-777'
+        );
+        let sleepCount = 0;
+
+        const runtime = await waitForRunning('cccccccccccccccccccccccccccccccccccccccc', marker, {
+            attempts: 1,
+            intervalMs: 10_000,
+            readInfo: () => {
+                throw new Error('httpx.ReadTimeout: timed out while reading Space status');
+            },
+            verifyMarker: async (expected) => assertDeployMarkerMatches(marker, expected),
+            sleep: async () => {
+                sleepCount += 1;
+            },
+            log: () => {}
+        });
+
+        assert.equal(sleepCount, 0);
+        assert.deepEqual(runtime, {
+            stage: 'unknown',
+            sha: 'unknown',
+            management_status: 'target_commit_not_confirmed',
+            verification_source: 'service_marker_after_management_timeout',
+            service_marker_verified: true,
+            warning:
+                'Hugging Face management status did not confirm RUNNING for cccccccccccccccccccccccccccccccccccccccc, but the public service returned the exact one-time deploy marker; last stage=unknown sha=unknown marker_error=unknown management_error=httpx.ReadTimeout: timed out while reading Space status',
+            marker
+        });
+    });
+
+    it('accepts an exact one-time service marker when management status remains stale', async () => {
+        const marker = buildDeployMarker(
+            '8888888888888888888888888888888888888888',
+            new Date('2026-06-20T15:00:00.000Z'),
+            'deploy-888'
+        );
+        let sleepCount = 0;
+
+        const runtime = await waitForRunning('dddddddddddddddddddddddddddddddddddddddd', marker, {
+            attempts: 1,
+            intervalMs: 0,
+            readInfo: () => ({ runtime: { stage: 'RUNNING' }, sha: 'stale-space-sha' }),
+            verifyMarker: async (expected) => assertDeployMarkerMatches(marker, expected),
+            sleep: async () => {
+                sleepCount += 1;
+            },
+            log: () => {}
+        });
+
+        assert.equal(sleepCount, 0);
+        assert.deepEqual(runtime, {
+            stage: 'RUNNING',
+            sha: 'stale-space-sha',
+            management_status: 'target_commit_not_confirmed',
+            verification_source: 'service_marker_after_management_timeout',
+            service_marker_verified: true,
+            warning:
+                'Hugging Face management status did not confirm RUNNING for dddddddddddddddddddddddddddddddddddddddd, but the public service returned the exact one-time deploy marker; last stage=RUNNING sha=stale-space-sha marker_error=unknown management_error=none',
+            marker
+        });
+    });
+
+    it('rejects a stale service marker after management status times out', async () => {
+        const marker = buildDeployMarker(
+            '9999999999999999999999999999999999999999',
+            new Date('2026-06-20T16:00:00.000Z'),
+            'deploy-999'
+        );
+        const staleMarker = { ...marker, deploy_id: 'deploy-stale' };
+
+        await assert.rejects(
+            waitForRunning('eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', marker, {
+                attempts: 1,
+                intervalMs: 0,
+                readInfo: () => ({ runtime: { stage: 'RUNNING' }, sha: 'stale-space-sha' }),
+                verifyMarker: async (expected) => assertDeployMarkerMatches(staleMarker, expected),
+                sleep: async () => {},
+                log: () => {}
+            }),
+            /deploy_id mismatch/
+        );
+    });
+
     it('only classifies transient Hugging Face management transport errors as retryable', () => {
         assert.equal(
             isRetryableSpaceInfoReadError(

scripts/deploy-local.mjs

@@ -4,57 +4,165 @@ import { setTimeout as delay } from 'node:timers/promises';
 
 import { fetchJsonWithTimeout, isMainModule, pickFailureOutput, printJson, runCommand } from './command-center-utils.mjs';
 
-const LOCAL_BASE_URL = 'http://localhost:4783';
+const CONTAINER_NAME = 'gpt-image-playground-customer';
+const IMAGE_REPOSITORY = 'gpt-image-playground-customer';
+const DEFAULT_BIND_HOST = '127.0.0.1';
+const DEFAULT_HOST_PORT = '4783';
 const PROBE_PATHS = ['/api/auth-status', '/api/runtime-capabilities', '/api/agent/capabilities'];
 const PROBE_ATTEMPTS = 30;
 const PROBE_INTERVAL_MS = 2000;
 const PROBE_TIMEOUT_MS = 5000;
 const DOCKER_COMPOSE_TIMEOUT_MS = 10 * 60 * 1000;
+const DOCKER_COMPOSE_WAIT_TIMEOUT_SECONDS = 120;
+const GIT_REVISION_PATTERN = /^[0-9a-f]{40}$/i;
 
 export function buildDockerComposeArgs(options = {}) {
+    assertSingleDeploymentMode(options);
     const files = ['-f', 'docker-compose.yml'];
     if (options.memory) files.push('-f', 'docker-compose.memory.yml');
-    return ['compose', ...files, 'up', '-d', '--build'];
+    if (options.postgres) files.push('-f', 'docker-compose.postgres.yml');
+    return [
+        'compose',
+        ...files,
+        'up',
+        '-d',
+        '--build',
+        '--force-recreate',
+        '--remove-orphans',
+        '--wait',
+        '--wait-timeout',
+        String(DOCKER_COMPOSE_WAIT_TIMEOUT_SECONDS)
+    ];
 }
 
-export function buildDockerComposeEnv(env = process.env) {
-    return { ...env, COMPOSE_PROGRESS: 'plain' };
+function assertSingleDeploymentMode(options = {}) {
+    if (options.memory && options.postgres) {
+        throw new Error('--memory 和 --postgres 不能同时使用。');
+    }
+}
+
+export function buildDockerComposeEnv(env = process.env, deployment) {
+    return {
+        ...env,
+        COMPOSE_PROGRESS: 'plain',
+        ...(deployment
+            ? {
+                  GIP_IMAGE_REVISION: deployment.revision,
+                  GIP_IMAGE_TAG: deployment.imageTag
+              }
+            : {})
+    };
+}
+
+export function buildDeploymentImageTag(revision) {
+    const normalized = revision?.trim().toLowerCase();
+    if (!GIT_REVISION_PATTERN.test(normalized || '')) throw new Error('Git revision 必须是完整的 40 位 SHA。');
+    return `local-${normalized}`;
+}
+
+export function buildDeploymentImageReference(revision) {
+    return `${IMAGE_REPOSITORY}:${buildDeploymentImageTag(revision)}`;
+}
+
+export function buildLocalBaseUrl(bindHost = DEFAULT_BIND_HOST, hostPort = DEFAULT_HOST_PORT) {
+    const host = bindHost.trim();
+    const port = hostPort.trim();
+    if (!host) throw new Error('GIP_BIND_HOST 不能为空。');
+    if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+        throw new Error(`GIP_PORT 必须是 1 到 65535 的整数，收到：${hostPort}`);
+    }
+
+    const probeHost = host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '[::1]' : host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+    return `http://${probeHost}:${port}`;
+}
+
+export function parsePublishedContainerPortBindings(output) {
+    let bindings;
+    try {
+        bindings = JSON.parse(output);
+    } catch {
+        throw new Error('无法解析 Docker 容器端口映射。');
+    }
+    if (!Array.isArray(bindings) || bindings.length === 0) {
+        throw new Error('Docker 容器未发布 4783/tcp 端口。');
+    }
+
+    const binding = bindings.find((entry) => typeof entry?.HostIp === 'string' && !entry.HostIp.includes(':')) || bindings[0];
+    const bindHost = typeof binding?.HostIp === 'string' && binding.HostIp.trim() ? binding.HostIp.trim() : '0.0.0.0';
+    const hostPort = typeof binding?.HostPort === 'string' ? binding.HostPort.trim() : '';
+    return { bindHost, hostPort, baseUrl: buildLocalBaseUrl(bindHost, hostPort) };
+}
+
+export function assertDeploymentImageIdentity(identity, deployment) {
+    const expectedImage = buildDeploymentImageReference(deployment.revision);
+    if (identity.image !== expectedImage) {
+        throw new Error(`运行容器镜像不匹配：expected ${expectedImage}, received ${identity.image || '<missing>'}。`);
+    }
+    if (identity.revision !== deployment.revision) {
+        throw new Error(
+            `运行镜像 revision 不匹配：expected ${deployment.revision}, received ${identity.revision || '<missing>'}。`
+        );
+    }
 }
 
 function parseArgs(argv) {
-    const unknown = argv.find((arg) => !['--help', '-h', '--memory', '--skip-probe'].includes(arg));
+    const unknown = argv.find((arg) => !['--help', '-h', '--memory', '--postgres', '--skip-probe'].includes(arg));
     if (unknown) throw new Error(`Unknown option: ${unknown}`);
-    return {
+    const options = {
         help: argv.includes('--help') || argv.includes('-h'),
         memory: argv.includes('--memory'),
+        postgres: argv.includes('--postgres'),
         skipProbe: argv.includes('--skip-probe')
     };
+    assertSingleDeploymentMode(options);
+    return options;
 }
 
 function printHelp() {
     console.log(`Usage:
   npm run deploy:local
   npm run deploy:local -- --memory
+  npm run deploy:local -- --postgres
 
 Options:
   --memory       Use docker-compose.memory.yml overlay for HF Space-like memory mode.
+  --postgres     Use docker-compose.postgres.yml and require GPT_IMAGE_POSTGRES_PASSWORD.
   --skip-probe   Rebuild and start the container without HTTP endpoint probes.
   --help         Show this help.`);
 }
 
-async function fetchJson(path) {
-    return fetchJsonWithTimeout(new URL(path, LOCAL_BASE_URL), { timeoutMs: PROBE_TIMEOUT_MS });
+function readCleanGitRevision() {
+    const revisionResult = runCommand('git', ['rev-parse', '--verify', 'HEAD']);
+    if (!revisionResult.ok) throw new Error(`无法读取当前 Git revision：${pickFailureOutput(revisionResult)}`);
+
+    const revision = revisionResult.stdout.trim().toLowerCase();
+    const imageTag = buildDeploymentImageTag(revision);
+    const statusResult = runCommand('git', ['status', '--porcelain=v1', '--untracked-files=all']);
+    if (!statusResult.ok) throw new Error(`无法检查 Git 工作区状态：${pickFailureOutput(statusResult)}`);
+    if (statusResult.stdout) {
+        throw new Error('拒绝部署脏工作区。请先提交或清理当前改动，再运行 npm run deploy:local。');
+    }
+
+    return { revision, imageTag };
 }
 
-async function waitForLocalEndpoints() {
+async function fetchJson(path, baseUrl) {
+    return fetchJsonWithTimeout(new URL(path, baseUrl), { timeoutMs: PROBE_TIMEOUT_MS });
+}
+
+export async function waitForLocalEndpoints(baseUrl, options = {}) {
+    const attempts = options.attempts ?? PROBE_ATTEMPTS;
+    const intervalMs = options.intervalMs ?? PROBE_INTERVAL_MS;
+    const requestJson = options.fetchJson || fetchJson;
+    const sleep = options.sleep || delay;
     let lastError = '';
-    for (let attempt = 1; attempt <= PROBE_ATTEMPTS; attempt += 1) {
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
         try {
             const responses = {};
-            for (const path of PROBE_PATHS) responses[path] = await fetchJson(path);
+            for (const path of PROBE_PATHS) responses[path] = await requestJson(path, baseUrl);
             return {
                 attempts: attempt,
-                baseUrl: LOCAL_BASE_URL,
+                baseUrl,
                 authRequired: responses['/api/auth-status'].passwordRequired,
                 stateBackend: responses['/api/agent/capabilities'].defaults?.state_backend,
                 imageStorageMode: responses['/api/agent/capabilities'].storage?.image_storage_mode,
@@ -62,20 +170,57 @@ async function waitForLocalEndpoints() {
             };
         } catch (error) {
             lastError = error instanceof Error ? error.message : String(error);
-            await delay(PROBE_INTERVAL_MS);
+            if (attempt < attempts) await sleep(intervalMs);
         }
     }
     throw new Error(`Local container did not pass HTTP probes: ${lastError}`);
 }
 
 export function assertLocalProbeMatchesMode(probe, options = {}) {
-    if (!options.memory) return;
+    assertSingleDeploymentMode(options);
+    const expected = options.memory
+        ? { label: 'Memory', stateBackend: 'memory', imageStorageMode: 'indexeddb' }
+        : options.postgres
+          ? { label: 'PostgreSQL', stateBackend: 'postgres', imageStorageMode: 'fs' }
+          : { label: 'SQLite', stateBackend: 'sqlite', imageStorageMode: 'fs' };
     const mismatches = [];
-    if (probe.stateBackend !== 'memory') mismatches.push(`stateBackend=${probe.stateBackend ?? '<missing>'} expected memory`);
-    if (probe.imageStorageMode !== 'indexeddb') {
-        mismatches.push(`imageStorageMode=${probe.imageStorageMode ?? '<missing>'} expected indexeddb`);
+    if (probe.stateBackend !== expected.stateBackend) {
+        mismatches.push(`stateBackend=${probe.stateBackend ?? '<missing>'} expected ${expected.stateBackend}`);
+    }
+    if (probe.imageStorageMode !== expected.imageStorageMode) {
+        mismatches.push(`imageStorageMode=${probe.imageStorageMode ?? '<missing>'} expected ${expected.imageStorageMode}`);
     }
-    if (mismatches.length) throw new Error(`Memory overlay did not take effect: ${mismatches.join(', ')}.`);
+    if (mismatches.length) throw new Error(`${expected.label} deployment mode did not take effect: ${mismatches.join(', ')}.`);
+}
+
+function inspectDeploymentImage(deployment) {
+    const expectedImage = buildDeploymentImageReference(deployment.revision);
+    const containerImage = runCommand('docker', ['inspect', '--format', '{{.Config.Image}}', CONTAINER_NAME]);
+    if (!containerImage.ok) throw new Error(`无法读取部署容器镜像：${pickFailureOutput(containerImage)}`);
+
+    const imageRevision = runCommand('docker', [
+        'image',
+        'inspect',
+        '--format',
+        '{{ index .Config.Labels "org.opencontainers.image.revision" }}',
+        expectedImage
+    ]);
+    if (!imageRevision.ok) throw new Error(`无法读取部署镜像 revision：${pickFailureOutput(imageRevision)}`);
+
+    const identity = { image: containerImage.stdout.trim(), revision: imageRevision.stdout.trim().toLowerCase() };
+    assertDeploymentImageIdentity(identity, deployment);
+    return identity;
+}
+
+function inspectPublishedContainerPort() {
+    const result = runCommand('docker', [
+        'inspect',
+        '--format',
+        '{{json (index .NetworkSettings.Ports "4783/tcp")}}',
+        CONTAINER_NAME
+    ]);
+    if (!result.ok) throw new Error(`无法读取部署容器端口映射：${pickFailureOutput(result)}`);
+    return parsePublishedContainerPortBindings(result.stdout.trim());
 }
 
 async function main() {
@@ -85,8 +230,9 @@ async function main() {
         return;
     }
 
+    const deployment = readCleanGitRevision();
     const docker = runCommand('docker', buildDockerComposeArgs(options), {
-        env: buildDockerComposeEnv(),
+        env: buildDockerComposeEnv(process.env, deployment),
         timeoutMs: DOCKER_COMPOSE_TIMEOUT_MS
     });
     if (!docker.ok) {
@@ -94,14 +240,16 @@ async function main() {
         process.exit(1);
     }
 
+    const image = inspectDeploymentImage(deployment);
+    const localConfig = inspectPublishedContainerPort();
     if (options.skipProbe) {
-        printJson({ ok: true, phase: 'docker-compose', probe: 'skipped' });
+        printJson({ ok: true, phase: 'docker-compose', image, probe: 'skipped' });
         return;
     }
 
-    const probe = await waitForLocalEndpoints();
+    const probe = await waitForLocalEndpoints(localConfig.baseUrl);
     assertLocalProbeMatchesMode(probe, options);
-    printJson({ ok: true, phase: 'ready', probe });
+    printJson({ ok: true, phase: 'ready', deployment: { ...deployment, ...localConfig }, image, probe });
 }
 
 if (isMainModule(import.meta.url, process.argv[1])) {

scripts/docker-build-context.test.mjs

@@ -4,12 +4,16 @@ import { describe, it } from 'node:test';
 
 describe('Docker build context', () => {
     it('keeps the tracked real-upstream smoke template available to containerized tests', async () => {
-        const [dockerignore, dockerfile, gitignore, realSmokeTemplate] = await Promise.all([
-            readFile(new URL('../.dockerignore', import.meta.url), 'utf8'),
-            readFile(new URL('../Dockerfile', import.meta.url), 'utf8'),
-            readFile(new URL('../.gitignore', import.meta.url), 'utf8'),
-            readFile(new URL('../.env.real-smoke.example', import.meta.url), 'utf8')
-        ]);
+        const [dockerignore, dockerfile, gitignore, realSmokeTemplate, compose, postgresCompose, ciWorkflow] =
+            await Promise.all([
+                readFile(new URL('../.dockerignore', import.meta.url), 'utf8'),
+                readFile(new URL('../Dockerfile', import.meta.url), 'utf8'),
+                readFile(new URL('../.gitignore', import.meta.url), 'utf8'),
+                readFile(new URL('../.env.real-smoke.example', import.meta.url), 'utf8'),
+                readFile(new URL('../docker-compose.yml', import.meta.url), 'utf8'),
+                readFile(new URL('../docker-compose.postgres.yml', import.meta.url), 'utf8'),
+                readFile(new URL('../.github/workflows/ci.yml', import.meta.url), 'utf8')
+            ]);
 
         assert.match(dockerignore, /^\.gitignore$/m);
         assert.match(dockerignore, /^!\.gitignore$/m);
@@ -17,7 +21,24 @@ describe('Docker build context', () => {
         assert.match(dockerignore, /^!\.env\.real-smoke\.example$/m);
         assert.match(dockerfile, /^COPY \. \.$/m);
         assert.match(dockerfile, /^COPY vendor\/brace-expansion-compat \.\/vendor\/brace-expansion-compat$/m);
+        assert.match(
+            dockerfile,
+            /^COPY --from=builder --chown=node:node \/app\/scripts\/docker-entrypoint\.mjs \.\/scripts\/docker-entrypoint\.mjs$/m
+        );
+        assert.match(dockerfile, /^HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD /m);
+        assert.match(dockerfile, /^LABEL org\.opencontainers\.image\.revision=\$VCS_REF$/m);
         assert.match(gitignore, /^!\.env\.real-smoke\.example$/m);
         assert.match(realSmokeTemplate, /^IMAGE_REAL_SMOKE_TIMEOUT_MS=240000$/m);
+        assert.match(compose, /^      - "\$\{GIP_BIND_HOST:-127\.0\.0\.1\}:\$\{GIP_PORT:-4783\}:4783"$/m);
+        assert.doesNotMatch(compose, /^      - "4783:4783"$/m);
+        assert.match(postgresCompose, /^      AGENT_DATABASE_URL: ""$/m);
+        assert.match(postgresCompose, /^      AGENT_DB_PASSWORD: ""$/m);
+        assert.match(postgresCompose, /^      AGENT_DB_PASSWORD_FILE: \/run\/secrets\/postgres_password$/m);
+        assert.doesNotMatch(postgresCompose, /gpt-image-playground-customer:postgres/);
+        assert.doesNotMatch(postgresCompose, /^    ports:/m);
+        assert.match(ciWorkflow, /--env GIP_COMPOSE_DEPLOYMENT=true --env GIP_BIND_HOST=127\.0\.0\.1/);
+        assert.match(ciWorkflow, /for attempt in \{1\.\.120\}; do/);
+        assert.match(ciWorkflow, /attempt %s\/120/);
+        assert.match(ciWorkflow, /if \(\( attempt < 120 \)\); then\n\s+sleep 1/);
     });
 });

scripts/docker-entrypoint.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const IPV4_LOOPBACK_PATTERN = /^127(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+const LOOPBACK_HOSTS = new Set(['localhost', '::1', '[::1]']);
+
+export function isLoopbackBindHost(value) {
+    const host = value?.trim().toLowerCase();
+    return Boolean(host) && (LOOPBACK_HOSTS.has(host) || IPV4_LOOPBACK_PATTERN.test(host));
+}
+
+export function assertDockerComposeAccessPolicy(env = process.env) {
+    if (env.GIP_COMPOSE_DEPLOYMENT?.trim().toLowerCase() !== 'true') return;
+    if (isLoopbackBindHost(env.GIP_BIND_HOST)) return;
+    if (env.APP_PASSWORD?.trim()) return;
+
+    throw new Error(
+        '拒绝以非回环地址发布 Docker 服务：请先在 .env.local 设置 APP_PASSWORD，或将 GIP_BIND_HOST 保持为 127.0.0.1。'
+    );
+}
+
+async function main() {
+    assertDockerComposeAccessPolicy();
+    await import('../server.js');
+}
+
+if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(`[ERROR] ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
+}

scripts/docker-entrypoint.test.mjs

@@ -0,0 +1,39 @@
+import { assertDockerComposeAccessPolicy, isLoopbackBindHost } from './docker-entrypoint.mjs';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+describe('Docker Compose access policy', () => {
+    it('recognizes only loopback bind hosts as local-only', () => {
+        for (const host of ['127.0.0.1', '127.0.12.34', 'localhost', '::1', '[::1]']) {
+            assert.equal(isLoopbackBindHost(host), true, host);
+        }
+        for (const host of ['0.0.0.0', '10.0.90.200', '::', 'localhost.example.test']) {
+            assert.equal(isLoopbackBindHost(host), false, host);
+        }
+    });
+
+    it('allows standalone images and loopback Compose deployments without a page password', () => {
+        assert.doesNotThrow(() => assertDockerComposeAccessPolicy({}));
+        assert.doesNotThrow(() =>
+            assertDockerComposeAccessPolicy({ GIP_COMPOSE_DEPLOYMENT: 'true', GIP_BIND_HOST: '127.0.0.1' })
+        );
+    });
+
+    it('rejects unauthenticated non-loopback Compose deployments', () => {
+        assert.throws(
+            () => assertDockerComposeAccessPolicy({ GIP_COMPOSE_DEPLOYMENT: 'true', GIP_BIND_HOST: '0.0.0.0' }),
+            /APP_PASSWORD/
+        );
+        assert.throws(
+            () => assertDockerComposeAccessPolicy({ GIP_COMPOSE_DEPLOYMENT: ' TRUE ', GIP_BIND_HOST: '0.0.0.0' }),
+            /APP_PASSWORD/
+        );
+        assert.doesNotThrow(() =>
+            assertDockerComposeAccessPolicy({
+                GIP_COMPOSE_DEPLOYMENT: 'true',
+                GIP_BIND_HOST: '10.0.90.200',
+                APP_PASSWORD: 'access-code'
+            })
+        );
+    });
+});

scripts/smoke-hf-space-memory.mjs

@@ -5,7 +5,11 @@ import { readPositiveIntegerEnv } from './env-utils.mjs';
 
 const imageName = process.env.HF_SPACE_SMOKE_IMAGE || 'gpt-image-playground:hf-space-memory-smoke';
 const containerName = process.env.HF_SPACE_SMOKE_CONTAINER || 'gpt-image-playground-hf-space-smoke';
-const hostPort = process.env.HF_SPACE_SMOKE_PORT || '4785';
+const parsedHostPort = readPositiveIntegerEnv('HF_SPACE_SMOKE_PORT', 4785);
+if (parsedHostPort > 65_535) {
+  throw new Error('HF_SPACE_SMOKE_PORT must be less than or equal to 65535');
+}
+const hostPort = String(parsedHostPort);
 const token = process.env.HF_SPACE_SMOKE_AGENT_TOKEN || 'hf-space-smoke-token';
 const baseUrl = `http://127.0.0.1:${hostPort}`;
 const readyTimeoutMs = readPositiveIntegerEnv('HF_SPACE_SMOKE_READY_TIMEOUT_MS', 45_000);
@@ -16,6 +20,9 @@ function run(command, args, options = {}) {
     encoding: 'utf8',
     env: { ...process.env, ...(options.env || {}) }
   });
+  if (result.error) {
+    throw new Error(`${command} ${args.join(' ')} failed to start: ${result.error.message}`);
+  }
   if (result.status !== 0) {
     const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
     throw new Error(`${command} ${args.join(' ')} failed${output ? `\n${output}` : ''}`);
@@ -93,7 +100,7 @@ try {
     '--name',
     containerName,
     '-p',
-    `${hostPort}:4783`,
+    `127.0.0.1:${hostPort}:4783`,
     '-e',
     'AGENT_STATE_BACKEND=memory',
     '-e',

scripts/smoke-hf-space-memory.test.mjs

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, it } from 'node:test';
@@ -8,6 +9,13 @@ const repoRoot = fileURLToPath(new URL('..', import.meta.url));
 const scriptPath = join(repoRoot, 'scripts/smoke-hf-space-memory.mjs');
 
 describe('HF Space memory smoke script validation', () => {
+  it('publishes the temporary container only on the IPv4 loopback interface', () => {
+    const source = readFileSync(scriptPath, 'utf8');
+
+    assert.match(source, /`127\.0\.0\.1:\$\{hostPort\}:4783`/);
+    assert.doesNotMatch(source, /^\s*`\$\{hostPort\}:4783`,?$/m);
+  });
+
   it('rejects invalid ready timeout values before Docker access', () => {
     const result = spawnSync(process.execPath, [scriptPath], {
       cwd: repoRoot,
@@ -20,4 +28,30 @@ describe('HF Space memory smoke script validation', () => {
     assert.match(result.stderr, /positive integer/);
     assert.equal(result.stdout.trim(), '');
   });
+
+  it('rejects out-of-range host ports before Docker access', () => {
+    const result = spawnSync(process.execPath, [scriptPath], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      env: { ...process.env, HF_SPACE_SMOKE_PORT: '65536' }
+    });
+
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /HF_SPACE_SMOKE_PORT/);
+    assert.match(result.stderr, /65535/);
+    assert.equal(result.stdout.trim(), '');
+  });
+
+  it('reports the underlying spawn error when Docker is unavailable', () => {
+    const result = spawnSync(process.execPath, [scriptPath], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      env: { ...process.env, PATH: '' }
+    });
+
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /docker build/);
+    assert.match(result.stderr, /failed to start/);
+    assert.match(result.stderr, /ENOENT/);
+  });
 });

skills/gpt-image-playground-agent/SKILL.md

@@ -141,7 +141,7 @@ Authorization: Bearer <token>
 - `npm run status`：只读查看 git、Space 目标、Agent API、Skill 入口和独立真实图片上游 smoke 配置摘要；会自动读取 `.env.real-smoke.local`，不输出 URL 或 API Key。
 - `npm run doctor`：统一诊断本机与 HF Space 配置，不写 Secret。
 - `npm run verify`：运行提交前基线；需要真实 PostgreSQL gate 时加 `-- --postgres`。
-- `npm run deploy:local`：重建本地 Docker 服务并探测真实 HTTP 端点；加 `-- --memory` 会断言 memory/indexeddb overlay 生效。
+- `npm run deploy:local`：重建本地 Docker 服务并探测真实 HTTP 端点；加 `-- --memory` 会断言 memory/indexeddb overlay 生效，加 `-- --postgres` 会断言 postgres/fs overlay 生效。PostgreSQL 模式要求在运行环境或 Compose `.env` 中提供 `GPT_IMAGE_POSTGRES_PASSWORD`。
 - `npm run deploy:space`：部署干净 git HEAD 到固定 Space，并做只读公网验证。
 - `npm run agent:doctor`：执行非计费分层诊断，覆盖 capabilities、Agent contract、runtime backend、state backend 和 Responses/GPT2Image readiness；支持 `-- --base-url <url>`；真实 1K/2K smoke 必须显式加 `-- --allow-billable`。
 

src/app/api/deploy-marker/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
-const deployMarker = {"schema_version":1,"local_sha":"128efae485d0eb35670a525cf19069b5da3f4ace","created_at":"2026-07-26T03:42:06.320Z","deploy_id":"aaf32bf5-46f3-48cf-8f53-ca6c7a48ba6e"} as const;
+const deployMarker = {"schema_version":1,"local_sha":"6590d91c9e6e0a3314fa16bd8e5667b2d9e855cd","created_at":"2026-07-27T03:45:51.712Z","deploy_id":"d1603a14-8385-441d-adac-e4c5b059dde4"} as const;
 
 export const dynamic = 'force-dynamic';