From af8f13859bf69a992b7f1b03a6ce446211644475 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Wed, 16 Sep 2026 16:15:59 +0800
Subject: [PATCH] docs: add Compose startup and manual validation steps

---
 README.md | 39 +++++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 4956896..d6b3afe 100644
--- a/README.md
+++ b/README.md
@@ -11,18 +11,49 @@
 
 ## 本地运行
 
-需要 Docker Compose：
+以下是完整 Compose 启动方式，适合人工部署验证。命令应在仓库根目录、同一个 shell 中执行；不要把 `compose.dev.yaml` 混入本次标准 gateway 验证。
+
+首次部署可生成一组新的本地凭据：
 
 ```bash
+git pull --ff-only
+export DOCKER_GID="$(stat -c '%g' /var/run/docker.sock)"
+export CREATORHUB_PORT=8080
+export GATEWAY_TOKEN="$(openssl rand -hex 24)"
 export CONTROL_PLANE_USERNAME=creatorhub
 export CONTROL_PLANE_PASSWORD="$(openssl rand -hex 24)"
 export CREATORHUB_CREDENTIAL_MASTER_KEY="$(openssl rand -base64 32)"
-DOCKER_GID=$(stat -c %g /var/run/docker.sock) docker compose up --build
+
+docker compose config --quiet
+docker compose up --detach --build
 ```
 
-三个控制面凭据变量均为必填；Compose 不提供默认凭据。`CREATORHUB_CREDENTIAL_MASTER_KEY` 必须在重启后保持不变。开发环境可复制 `.env.example` 后显式填写本地值。
+已有数据的部署重启必须复用原来的 `GATEWAY_TOKEN`、控制面账号密码和 `CREATORHUB_CREDENTIAL_MASTER_KEY`，不要重新生成主密钥。三个控制面凭据变量均为必填，主密钥变化会导致已有账号凭据无法解密。
 
-打开 <http://127.0.0.1:8080>，使用 `CONTROL_PLANE_USERNAME` / `CONTROL_PLANE_PASSWORD` 登录；局域网内用宿主机 IP 访问同一端口。首次使用：在「网关管理」用 Compose 里的 `GATEWAY_TOKEN` 注册 `http://docker-gateway:8081`，在「镜像版本」添加可用的指纹浏览器镜像引用，即可创建环境；网关会在镜像缺失时自动拉取。架构、API 契约、失败语义和 `docker.sock` 风险边界见
+启动后检查服务：
+
+```bash
+docker compose ps
+curl --fail --silent --show-error "http://127.0.0.1:${CREATORHUB_PORT}/healthz"
+curl --fail --silent --show-error "http://127.0.0.1:${CREATORHUB_PORT}/readyz"
+docker compose logs --tail=200 creator-hub docker-gateway postgres
+```
+
+打开 `http://127.0.0.1:${CREATORHUB_PORT}`（默认端口为 8080），使用控制面账号登录。首次配置和人工抖音验证：
+
+1. 在「网关管理」注册 `http://docker-gateway:8081`，令牌填写当前 shell 中的 `GATEWAY_TOKEN`。
+2. 在「镜像版本」添加已登记的 immutable 浏览器镜像引用。
+3. 创建抖音账号和运行环境，恢复账号后显式启动运行环境。
+4. 在账号页点击「显示登录二维码」；完成扫码或验证码后，点击「核验浏览器身份」。
+5. 所有真实平台操作必须由 CreatorHub 发起，不要直接操作抖音页面；二维码或验证码画面不能作为身份核验成功的证明。
+
+停止服务但保留数据库、账号凭据和素材：
+
+```bash
+docker compose down
+```
+
+不要使用 `docker compose down -v`。架构、API 契约、失败语义和 `docker.sock` 风险边界见
 [《浏览器容器控制面》](docs/architecture/container-control.md)。
 
 ## 本地开发（热加载）