默认使用 GHCR 单文件部署，并补齐 Compose 启动依赖

.github/workflows/ci.yml

@@ -166,3 +166,4 @@ jobs:
           docker compose config --quiet
           docker compose -f deploy/compose/docker-compose.yml config --quiet
           docker compose --profile replicas config --quiet
+          docker compose -f docker-compose.yml -f docker-compose.build.yml config --quiet

README.en.md

@@ -52,21 +52,40 @@ The tree brings four concerns together:
 
 ## Quick start: run a gateway locally
 
-The default Docker Compose stack includes the app, PostgreSQL, and S3-compatible object storage. Docker with Compose is required; credentials are generated by the installer.
+The default Docker Compose stack uses a prebuilt app image from GHCR and includes PostgreSQL and S3-compatible object storage. Install Docker with Compose and download a single Compose file; no source checkout or local build is required. Credentials are generated by the installer.
 
 ### 1. Start and pair the instance
 
 ```sh
-git clone https://github.com/TokenRollAI/tool-bridge.git
+mkdir -p tool-bridge
 cd tool-bridge
-docker compose up -d --build
+curl -fsSL https://raw.githubusercontent.com/TokenRollAI/tool-bridge/main/docker-compose.yml -o docker-compose.yml
+docker compose up -d
 docker compose exec -T app node /app/dist/admin.js pair
 ```
 
 Open [http://127.0.0.1:8787/ui/setup](http://127.0.0.1:8787/ui/setup), enter the one-time pairing credential, and complete installation using the built-in database and object storage. Save the Admin SK shown after installation in a password manager; use it to log in below. PostgreSQL, object storage, and bootstrap identity/keys each persist in Docker volumes.
 
 Prefer a hosted deployment? Follow the [Railway quick start](#railway).
 
+To build from source, clone this repository and run the following from its root:
+
+```sh
+docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+```
+
+Both the root Compose file and [`deploy/compose/docker-compose.yml`](deploy/compose/docker-compose.yml) default to a pinned GHCR image. Source builds require the explicit [`docker-compose.build.yml`](docker-compose.build.yml) override.
+
+To restart the full stack, use the following sequence so the app waits for a healthy PostgreSQL service and completed bucket initialization. Restarting all services simultaneously can put the app into recovery mode while the database is still starting:
+
+```sh
+docker compose stop app
+docker compose stop postgres objects
+docker compose up -d
+```
+
+To restart only the app, use `docker compose restart app`. If the app entered recovery mode during dependency startup, restart it after the dependencies are ready to reconnect to the existing instance.
+
 ### 2. Log in, discover, and invoke with the CLI
 
 ```sh

README.md

@@ -52,21 +52,40 @@ Agent / CLI / Dashboard / MCP client
 
 ## 快速开始：本地运行一个网关
 
-默认 Docker Compose 栈包含应用、PostgreSQL 和 S3 兼容对象存储。需要安装 Docker（含 Compose）；安装器会自动生成基础设施凭证。
+默认 Docker Compose 栈使用 GHCR 预构建应用镜像，包含 PostgreSQL 和 S3 兼容对象存储。只需安装 Docker（含 Compose）并下载一份 Compose 文件，无需克隆源码或本地构建；安装器会自动生成基础设施凭证。
 
 ### 1. 启动并配对实例
 
 ```sh
-git clone https://github.com/TokenRollAI/tool-bridge.git
+mkdir -p tool-bridge
 cd tool-bridge
-docker compose up -d --build
+curl -fsSL https://raw.githubusercontent.com/TokenRollAI/tool-bridge/main/docker-compose.yml -o docker-compose.yml
+docker compose up -d
 docker compose exec -T app node /app/dist/admin.js pair
 ```
 
 打开 [http://127.0.0.1:8787/ui/setup](http://127.0.0.1:8787/ui/setup)，输入一次性配对凭证，使用内置数据库和对象存储完成安装。将安装成功后显示的 Admin SK 保存到密码管理器，后续登录时使用。PostgreSQL、对象存储和 bootstrap 身份/密钥分别保存在 Docker 持久卷中。
 
 希望直接托管到云上？跳到 [Railway 快速部署](#railway)。
 
+需要从源码构建时，克隆本仓库并在仓库根目录运行：
+
+```sh
+docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+```
+
+根目录与 [`deploy/compose/docker-compose.yml`](deploy/compose/docker-compose.yml) 均默认使用固定版本的 GHCR 镜像；源码构建需要显式叠加 [`docker-compose.build.yml`](docker-compose.build.yml)。
+
+重启整套服务时，使用以下顺序，让应用在 PostgreSQL 健康、对象桶初始化完成后启动；直接同时 `restart` 全部服务可能使应用因数据库尚未就绪进入恢复态：
+
+```sh
+docker compose stop app
+docker compose stop postgres objects
+docker compose up -d
+```
+
+仅重启应用可用 `docker compose restart app`。如果依赖服务启动期间应用已进入恢复态，待依赖就绪后重启应用即可重新连接原实例。
+
 ### 2. 用 CLI 登录、发现和调用
 
 ```sh

deploy/compose/docker-compose.yml

@@ -1,7 +1,7 @@
 name: tool-bridge
 
 x-app-image: &app-image
-  image: ghcr.io/tokenrollai/tool-bridge:0.22.0
+  image: ghcr.io/tokenrollai/tool-bridge:0.24.0
 
 services:
   init:
@@ -63,6 +63,10 @@ services:
     depends_on:
       init:
         condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+      init-bucket:
+        condition: service_completed_successfully
     ports:
       - '127.0.0.1:8787:8787'
     volumes:

docker-compose.build.yml

@@ -0,0 +1,14 @@
+# 源码开发时显式叠加：docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+x-local-build: &local-build
+  image: tool-bridge:local
+  build:
+    context: .
+    dockerfile: Dockerfile
+
+services:
+  init:
+    <<: *local-build
+  init-bucket:
+    <<: *local-build
+  app:
+    <<: *local-build

docker-compose.yml

@@ -1,10 +1,7 @@
 name: tool-bridge
 
 x-app-image: &app-image
-  image: tool-bridge:local
-  build:
-    context: .
-    dockerfile: Dockerfile
+  image: ghcr.io/tokenrollai/tool-bridge:0.24.0
 
 services:
   init:
@@ -66,6 +63,10 @@ services:
     depends_on:
       init:
         condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+      init-bucket:
+        condition: service_completed_successfully
     ports:
       - '127.0.0.1:8787:8787'
     volumes:

llmdoc/hosts-deploy/node-docker-and-helm.mdx

@@ -1,5 +1,5 @@
 ---
-description: Node/Compose/Railway/Helm 自托管部署：零 env 安装、PG/S3 持久卷、探针与响应流排空、受限 deployment agent 与 Redis 多副本路由。
+description: Node/Compose/Railway/Helm 自托管部署：GHCR 单文件部署与显式源码构建、零 env 安装、PG/S3 持久卷、探针与响应流排空、受限 deployment agent 与 Redis 多副本路由。
 kind: guide
 relations:
   related:
@@ -32,6 +32,7 @@ code:
     - Dockerfile
     - Dockerfile.railway
     - docker-compose.yml
+    - docker-compose.build.yml
     - deploy/compose/docker-compose.yml
     - deploy/helm/tool-bridge/values.yaml
     - deploy/helm/tool-bridge/templates/deployment.yaml
@@ -48,10 +49,14 @@ code:
 
 ## Compose 与镜像
 
-根 `docker-compose.yml` 用于本地构建，`deploy/compose/docker-compose.yml` 使用已发布镜像。默认栈包含独立 init、PG、SeaweedFS、init-bucket 与 app；镜像版本/摘要以清单为准，不在知识里手抄。init 自动生成应用/管理员数据库凭证和 S3 installer/应用凭证，最小权限文件分别只挂到需要的服务。app 只拿 bootstrap 卷，不挂 Docker socket；对象字节只在对象服务的数据卷。
+根 `docker-compose.yml` 与 `deploy/compose/docker-compose.yml` 都默认使用 GHCR 已发布镜像，单独下载清单即可部署，不依赖源码或宿主构建产物。源码开发须显式叠加 `docker-compose.build.yml`，让 app、init 与 init-bucket 使用同一本地构建镜像，避免应用与安装器版本混用；默认启动命令不触发源码构建。
+
+默认栈包含独立 init、PG、SeaweedFS、init-bucket 与 app；镜像版本/摘要以清单为准，不在知识里手抄。init 自动生成应用/管理员数据库凭证和 S3 installer/应用凭证，最小权限文件分别只挂到需要的服务。app 只拿 bootstrap 卷，不挂 Docker socket；对象字节只在对象服务的数据卷。
 
 首次启动检查 init 完成、PG/S3 可用、受保护配对、setup ready 与业务授权调用。`/healthz` 在安装态仍能成功，这是为了让安装面存活；不能把 Docker HEALTHCHECK healthy 当作安装已经完成。首次安装、重新构建应用和重启 PG/S3 是不同验收，必须分别证明身份、配置和对象字节仍可恢复。`down` 与删卷重置不同，清空卷必须是明确的数据丢弃操作。
 
+正常 `docker compose up` 在 PostgreSQL 健康、init 与 init-bucket 成功完成后才启动 app。整组重启须先完整停止 app，使 runtime 登记和租约在 PG 可达时释放，再停止 PG/S3，最后通过 `up` 恢复依赖顺序。不能从这些启动闸门推导任意并发 `restart` 或 Docker daemon 重启都能自动恢复：应用启动失败会进入 recovery，不会自动重试 launch；依赖就绪后须重启 app，并重新核验原实例身份、权限、配置与对象字节。
+
 正式镜像同时携带应用、Dashboard 和官方 PG dump/restore 客户端，运行用户无 root 权限；installer 的初始化容器才执行所需 owner 设置。镜像构建不得依赖宿主已存在 dist，Node 二进制与运行基础镜像也必须匹配。runtime 基于 Node slim，安装官方 PGDG client 工具，不继承数据库 server 镜像及其隐式 VOLUME。
 
 ## 探针、反向代理与关停
@@ -105,4 +110,6 @@ Node DeviceHub 保有本副本活 socket，DeviceRouter 通过 Redis 路由到
 
 ## 部署验证
 
+预构建镜像部署须以 Registry 的实际产物核验所选标签存在且支持目标平台，通过检查 manifest 或实际拉取取得证据。Compose 配置解析、源码测试与发布 workflow 成功记录都不能替代产物核验；拉取成功仍须分别验收初始化、业务功能与持久性，不能据此宣称部署闭环完成。
+
 `pnpm verify` 与 `pnpm turbo run build` 是工程底线，不能替代生命周期验收：关停设置用真实子进程 SIGTERM 与未结束请求验证；维护从实际编码/别名 HTTP 入口进入，并与阻塞写入、并发 SIGTERM 组合验证写入完成和最终登记清空；真实慢响应验证 body 完成/取消/错误前的计数与背压；可选目录清空核对实际 Compose mount 与镜像内 UI。后端测试使用隔离本地 PG/S3/Redis，先完成 server.close 再删除 schema，不能为错误 teardown 顺序削弱生产租约 guard；缺 env 不静默跳过；部署还需验证持久性和失败回滚。真实平台验证遵守授权与每轮一次资源约束，证据留在验收记录，不把运行 URL、资源 ID 或测试次数写入知识。

llmdoc/meta.json

@@ -30,7 +30,7 @@
       "validatedRevision": "b7c8bc5f595b8e1c781a92f8a1d95bfda78a17dc"
     },
     "hosts-deploy/node-docker-and-helm.mdx": {
-      "validatedRevision": "fca74657f159c6a41b0a58abceb44243f025af5d"
+      "validatedRevision": "8ee80df623c5e8917dd1f0235fca4e026be72a1a"
     },
     "hosts-deploy/state-store-decision.mdx": {
       "validatedRevision": "fca74657f159c6a41b0a58abceb44243f025af5d"

package.json

@@ -19,7 +19,8 @@
     "test:integration": "pnpm --filter @tool-bridge/app --filter @tool-bridge/server --if-present test",
     "test": "turbo run test && pnpm test:package-release && pnpm test:dockerfile && pnpm test:deploy-ci && pnpm test:compose-snapshot",
     "verify": "pnpm typecheck && pnpm lint && pnpm test",
-    "compose:up": "docker compose up -d --build",
+    "compose:up": "docker compose up -d",
+    "compose:build": "docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build",
     "compose:smoke": "docker compose exec -T app node -e \"fetch('http://127.0.0.1:8787/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))\"",
     "compose:down": "docker compose down --remove-orphans",
     "compose:reset": "docker compose --profile replicas down -v --remove-orphans",