rogee/creator-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: continue CreatorHub plan01 implementation

Browse Source
This commit is contained in:
rogee
2026-09-12 20:17:29 +08:00
parent 1fbf126b21
commit 860ecaf7ea
52 changed files with 9441 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment.md
+13 -11
View File
@@ -1,6 +1,8 @@
# CreatorHub 部署
本文档适用于当前阶段 A：在一台 Linux 主机上通过 Docker Compose 部署。控制面使用单用户 HTTP Basic Auth；当前不提供 RBAC 或多租户隔离。
本文档按 `main@1fbf126` 当前可运行代码说明单台 Linux 主机 Docker Compose 部署及旧阶段 A Mock 检查，不证明新产品功能已实现。[plan01](plan01.md) 是业务范围与验收依据，旧阶段 A 离线结果不等于 G0/G1，也不能替代抖音/小红书最终真机验收。
当前控制面仍使用单用户 HTTP Basic Auth（除 `/healthz` 外，包括静态页面），不提供 RBAC 或多租户隔离。开发目标不新增认证/访问限制，但本轮未删除现有代码或配置；以下变量仍须填写，不新增认证 profile。
## 部署内容
@@ -60,7 +62,8 @@ docker compose up --detach --build
1. 「网关管理」页注册网关：名称如 `gw-main`，Endpoint `http://docker-gateway:8081`，令牌填 `GATEWAY_TOKEN` 的值（即 `openssl rand -hex 24` 生成的值）。
2. 「镜像版本」页添加可用镜像，如版本 `148.0.7778.215`、引用 `git.ipao.vip/rogee/fingerprint-chromium:148.0.7778.215`（或 `@sha256:` 摘要引用）。
3. 「运行环境」页创建环境：中文名 + 小写别名 + 指纹参数，容器名 `creatorhub-browser-<别名>`，Profile 卷 `creatorhub-profile-<别名>`。
3. 「社媒账号」页先创建账号（默认暂停），再在「运行环境」选该账号、网关、镜像，填写中文名、小写别名及指纹参数。代理可选；指定代理须先手动检测为健康，留空是明确直连，不是失败回退。
4. 创建得到停止态容器；在账号页恢复账号后回环境页显式启动。容器名 `creatorhub-browser-<别名>`，Profile 卷 `creatorhub-profile-<别名>`。回收只删除容器、保留环境/binding/Profile；完整契约见[架构说明](architecture/container-control.md)。当前直连 create/start 不代表 upgrade/rebind 已支持空出口。
## 部署验证
@@ -84,8 +87,7 @@ docker compose ps
健康检查应成功，浏览器列表接口应返回 JSON，迁移查询当前应输出 `1`，三个 Compose 服务应为运行状态。`CREATORHUB_CREDENTIAL_MASTER_KEY` 必须由部署侧 Secret Manager/OS Keyring 持久保存并在每次启动时注入同一值；账号凭据以 AES-GCM 密文写入独立 `creatorhub_credentials` 卷，轮换主密钥前必须先迁移已有凭据。然后访问 <http://127.0.0.1:8080>；修改过 `CREATORHUB_PORT` 时使用对应端口。
若任何持久环境曾运行 PR 中间版本 `a37732c`，发布前先执行
`SELECT to_regclass(current_schema() || '.account_credential_reconciliation');`。结果非空表示遗留了当前代码不再使用的非秘密对账表；不要手工改写 `schema_migration` 或直接删表。应在确认不再回滚到该中间版本并完成数据库备份后，以单独的前向迁移 v15 删除该表并先在备份副本演练；该清理不影响当前账号创建链路，但属于正式发布前检查项。
旧实验版本的数据库异常应先记录版本、备份并核实，不把历史文档中的建议迁移当成本期开发要求；本期不新增兼容迁移、回填或双写。下文更新/恢复命令仅描述现有部署的数据操作，不改变 plan01 验收范围。
排障时读取结构化服务日志：
@@ -95,11 +97,11 @@ docker compose logs --tail=200 creator-hub docker-gateway postgres
## 手工业务验证（阶段 A Mock）
当前阶段 A 是单用户、虚拟平台 mock 的离线闭环，不连接真实社交平台。最小业务路径是：账号 → 草稿 → 显式确认 → 任务入队 → Mock 执行 → 审计回溯。
本节的旧阶段 A 业务执行器是 Mock，不向真实社交平台发送；容器、数据库、网关和可选代理则是实际运行资源。最小业务路径是：账号 → 草稿 → 显式确认 → 任务入队 → Mock 执行 → 审计回溯。
页面路径如下：
1. 登录后在「网关管理」注册 <http://docker-gateway:8081，令牌必须等于> GATEWAY_TOKEN。
1. 登录后在「网关管理」注册 <http://docker-gateway:8081>，令牌必须等于 GATEWAY_TOKEN。
2. 在「镜像版本」添加并启用一个可拉取的 fingerprint-chromium 镜像。
3. 可选：在「网络出口」创建出口并点击「检测」，健康状态必须为「健康」；这里只填写凭据引用 ID，不填写密码、Cookie 或 token。留空则使用网关所在机器的网络出口直连。
4. 在「社媒账号」创建平台为抖音的账号；创建后默认暂停，后续仍可使用 Mock 执行器验证离线闭环。
@@ -213,7 +215,7 @@ printf 'PASS account=%s environment=%s task=%s state=succeeded audit=task_queued
通过标准：/healthz 返回 204；受保护的 /api/browsers 返回 JSON；网关、控制面、PostgreSQL 均为运行状态；运行环境有 runtime_id 和 runtime_instance_id；任务最终为 succeeded，且执行尝试的脱敏证据为 mock_outcome=succeeded；审计至少包含 task_queued、task_claimed、task_finished。重复提交同一确认时应返回同一任务 ID，不应产生第二条任务。
验证完成后的安全清理（不删除 PostgreSQL 或 Profile 卷）：
验证完成后的容器回收（保留账号、环境/binding、PostgreSQL 数据与 Profile 卷，不是永久删除环境）：
~~~bash
api() {
@@ -234,11 +236,11 @@ docker compose stop
| 手工验证脚本在 `:?` 处退出 | CREATORHUB_PORT、GATEWAY_TOKEN、CONTROL_PLANE_USERNAME、CONTROL_PLANE_PASSWORD、CREATORHUB_CREDENTIAL_MASTER_KEY 是否都已 export | 在启动 Compose 的同一个 shell 中 export 完整变量集；不要只依赖 `.env` 或 Compose 默认值 |
| creator-hub 未启动 | docker compose ps、docker compose logs --tail=200 postgres docker-gateway creator-hub | 先确认 PostgreSQL 与网关 health 为 healthy；网关需能访问 /var/run/docker.sock，DOCKER_GID 使用 stat -c '%g' /var/run/docker.sock 的实际值 |
| API 返回 401 | curl 是否带 --user CONTROL_PLANE_USERNAME:CONTROL_PLANE_PASSWORD | /healthz 不需要认证，其余 /api/* 需要控制面 Basic Auth |
| /api/browsers 返回 503 或网关不可用 | 网关注册的 Endpoint、令牌与 Compose 的 GATEWAY_TOKEN | Endpoint 在 Compose 网络内应为 <http://docker-gateway:8081；重新注册时令牌必须完全一致> |
| 生命周期动作报网关不可用 | 网关注册的 Endpoint、令牌与 Compose 的 GATEWAY_TOKEN | Endpoint 应为 <http://docker-gateway:8081>；令牌必须完全一致。列表/详情只读持久记录，其成功不能证明网关在线 |
| 出口一直是 unchecked/unhealthy | 出口协议、主机、端口；控制面容器到代理的连通性；last_check_reason | 先用无认证代理完成最小验证；有认证时只提供已配置的凭据引用，不把认证值放到请求、日志或文档 |
| 创建环境时报 image_unavailable 或拉取超时 | image_ref 格式、镜像架构、Docker daemon 的 registry 登录和网络 | 版本表中的镜像必须可被 Docker daemon 拉取；缺失镜像会由网关按引用拉取，最长约 10 分钟 |
| 创建环境时报 image_unavailable 或拉取超时 | image_ref 格式、镜像架构、Docker daemon 的 registry 登录和网络 | 版本表中的镜像必须可被 Docker daemon 拉取，最长约 10 分钟；已保存环境/binding 不会因网关失败自动删掉，核对记录后按原配置恢复 |
| 恢复/入队返回 503 | readiness、GET /api/browsers/<alias>、GET /api/network-exits/<id> | binding_missing、network_exit_unhealthy、runtime_missing 表示固定资源未就绪；先修复出口并启动原环境，不要换出口重试 |
| Mock 执行没有领取任务 | GET /api/phase-a/tasks/<id> 的 state、hold_reason | POST /api/phase-a/mock/execute 只领取满足账号、确认、健康出口、活动 runtime 和租约条件的 queued 任务；policy_hold/needs_confirmation 不会自动重试 |
| Mock 执行没有领取任务 | GET /api/phase-a/tasks/<id> 的 state、hold_reason | POST /api/phase-a/mock/execute 只领取满足账号、确认、已绑定出口健康（显式直连无此项）、活动 runtime 和租约条件的 queued 任务；policy_hold/needs_confirmation 不会自动重试 |
| 停止 Compose 后浏览器仍在运行 | docker ps --filter 'name=^creatorhub-browser-' | 动态浏览器不由 Compose 管理；先通过「运行环境」停止/回收，再 docker compose stop，不要误删 Profile 卷 |
不要执行 docker compose down --volumes 作为普通排障手段；它会删除 PostgreSQL 数据卷。不要把控制面密码、网关令牌、代理密码、Cookie 或 token 写入仓库、截图、日志或审计查询。
@@ -314,7 +316,7 @@ docker compose config --quiet
docker compose up --detach --build
```
镜像版本升级在页面「运行环境 → 升级」完成：平台会停止并删除旧容器（保留 Profile 卷），用新镜像引用与原指纹参数重建后启动；失败时直接重试即可，无需回滚。
镜像版本升级在页面「运行环境 → 升级」完成：删除旧容器并保留 Profile，用新镜像与原指纹/binding 重建，账号可运行才启动，否则保持停止态；无自动回滚。失败先查看记录，人工重试由现有流程调和，不承诺所有失败都可直接重试消除。当前 upgrade 无条件要求有效代理出口，直连环境会失败；rebind 也不支持空出口切回直连。此为现状限制，不是新产品范围裁决。
数据库迁移只支持安全前进，不提供自动破坏性回滚。需要同时恢复旧代码和更新前数据库时，修改下面两个变量后**整块执行一次**；不要逐行或拆块执行。预检、恢复演练、动态容器停止、停服、主库恢复、提交切换和启动都位于同一个 fail-fast subshell 中。