refactor: migrate browser gateway to native xvfb
This commit is contained in:
@@ -1,28 +1,35 @@
|
||||
# CreatorHub
|
||||
|
||||
面向团队的新媒体多账号运营管理平台，统一管理浏览器环境、代理资源、账号池、负责人和自动化运营任务。
|
||||
面向团队的新媒体多账号运营管理平台，统一管理浏览器环境、代理资源、账号池、负责人和运营任务。
|
||||
|
||||
## 当前阶段
|
||||
|
||||
业务范围与验收以 [docs/plan01.md](docs/plan01.md) 为准；规划范围不代表已经实现，离线检查不能替代真实平台验收。
|
||||
业务范围与验收以 [docs/plan01.md](docs/plan01.md) 为准；离线检查不能替代真实平台验收。
|
||||
|
||||
浏览器环境目标改为 **各机器 gateway 管理原生浏览器 + Xvfb**，并在采集结束后清理任务临时资源、保留登录状态和正式结果。本轮仅完成方案文档，当前代码及下方运行命令仍使用 Docker：
|
||||
浏览器环境由每台机器上的 **native browser gateway + Xvfb** 管理。gateway 不访问 Docker socket，不创建容器、镜像、卷或网络；登录 Profile 和正式素材持久保留，任务临时资源按执行归属清理。
|
||||
|
||||
- [变更评审](docs/native-browser-change-review.md)：现状、风险、资源保留与清理边界。
|
||||
- [实施计划](docs/native-browser-implementation-plan.md)：改动范围、阶段顺序与批准条件。
|
||||
- [验证文档](docs/native-browser-verification.md)：多机、异常清理、磁盘与性能的手工验收。
|
||||
- [变更评审](docs/native-browser-change-review.md)
|
||||
- [实施计划](docs/native-browser-implementation-plan.md)
|
||||
- [验证文档](docs/native-browser-verification.md)
|
||||
|
||||
当前目标是单机单节点闭环；多节点调度、A/B 环境和跨机恢复另立目标。
|
||||
|
||||
## 本地运行
|
||||
|
||||
以下是完整 Compose 启动方式，适合人工部署验证。命令应在仓库根目录、同一个 shell 中执行；不要把 `compose.dev.yaml` 混入本次标准 gateway 验证。
|
||||
native gateway 必须先在宿主机以非 root 用户运行。准备已安装的 fingerprint Chromium、Xvfb、systemd user session 和 gateway 配置：
|
||||
|
||||
首次部署可生成一组新的本地凭据：
|
||||
```bash
|
||||
mkdir -p ~/.config/creatorhub
|
||||
cp deploy/browser-gateway.env.example ~/.config/creatorhub/browser-gateway.env
|
||||
$EDITOR ~/.config/creatorhub/browser-gateway.env
|
||||
scripts/install-native-browser-gateway.sh
|
||||
curl --fail --silent --show-error http://127.0.0.1:8081/healthz
|
||||
```
|
||||
|
||||
首次部署可生成控制面凭据：
|
||||
|
||||
```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)"
|
||||
@@ -31,65 +38,63 @@ docker compose config --quiet
|
||||
docker compose up --detach --build
|
||||
```
|
||||
|
||||
已有数据的部署重启必须复用原来的 `GATEWAY_TOKEN`、控制面账号密码和 `CREATORHUB_CREDENTIAL_MASTER_KEY`，不要重新生成主密钥。三个控制面凭据变量均为必填，主密钥变化会导致已有账号凭据无法解密。
|
||||
|
||||
启动后检查服务：
|
||||
Compose 只运行 control-plane 和 PostgreSQL，浏览器 gateway 仍是宿主机 systemd user service。启动后检查：
|
||||
|
||||
```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
|
||||
curl --fail --silent --show-error "http://127.0.0.1:${CREATORHUB_PORT:-8080}/healthz"
|
||||
curl --fail --silent --show-error "http://127.0.0.1:${CREATORHUB_PORT:-8080}/readyz"
|
||||
docker compose logs --tail=200 creator-hub postgres
|
||||
```
|
||||
|
||||
打开 `http://127.0.0.1:${CREATORHUB_PORT}`（默认端口为 8080），使用控制面账号登录。首次配置和人工抖音验证：
|
||||
打开 `http://127.0.0.1:${CREATORHUB_PORT:-8080}` 登录。首次配置：
|
||||
|
||||
1. 在「网关管理」注册 `http://docker-gateway:8081`，令牌填写当前 shell 中的 `GATEWAY_TOKEN`。
|
||||
2. 在「镜像版本」添加已登记的 immutable 浏览器镜像引用。
|
||||
3. 创建抖音账号和运行环境，恢复账号后显式启动运行环境。
|
||||
4. 在账号页点击「显示登录二维码」；完成扫码或验证码后，点击「核验浏览器身份」。
|
||||
5. 所有真实平台操作必须由 CreatorHub 发起，不要直接操作抖音页面；二维码或验证码画面不能作为身份核验成功的证明。
|
||||
1. 在「网关管理」注册 gateway。control-plane 在 Compose 中运行时使用 `http://host.docker.internal:8081`；裸机运行 control-plane 时使用 `http://127.0.0.1:8081`。令牌必须与 gateway 配置一致。
|
||||
2. 在「浏览器版本」登记宿主机上实际存在的浏览器版本和绝对路径。
|
||||
3. 创建抖音账号和运行环境，显式启动环境。
|
||||
4. 在账号页显示登录二维码，完成登录后核验浏览器身份。
|
||||
5. 按验证文档手工完成抖音采集、结果保存、停止、再启动和资源释放检查。
|
||||
|
||||
停止服务但保留数据库、账号凭据和素材：
|
||||
已有数据的重启必须复用原控制面主密钥、gateway 令牌、Profile 根目录和素材目录。不要使用 `docker compose down -v`，也不要删除 gateway 的 Profile 根目录。
|
||||
|
||||
停止控制面和数据库：
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
systemctl --user stop creatorhub-browser-gateway.service
|
||||
```
|
||||
|
||||
不要使用 `docker compose down -v`。架构、API 契约、失败语义和 `docker.sock` 风险边界见
|
||||
[《浏览器容器控制面》](docs/architecture/container-control.md)。
|
||||
|
||||
## 本地开发（热加载）
|
||||
|
||||
日常开发不再整仓重建镜像，改用源码热加载：
|
||||
|
||||
```bash
|
||||
npm --prefix web ci
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
- `pnpm dev`：同时起后端（air 热重载）与前端（vite HMR）；
|
||||
- `pnpm dev:backend` / `pnpm dev:frontend`：单独启动其中一端；
|
||||
- `pnpm dev:deps`：仅启动 postgres 与 docker-gateway 两个容器（`compose.dev.yaml` 会把 5432/8081 映射到宿主机）。
|
||||
- `pnpm dev`：同时运行 Go control-plane 和 Vite HMR；
|
||||
- `pnpm dev:backend`：启动 PostgreSQL 依赖，检查宿主机 native gateway 后运行 control-plane；
|
||||
- `pnpm dev:frontend`：单独运行前端。
|
||||
|
||||
服务地址：
|
||||
|
||||
| 端 | 地址 | 说明 |
|
||||
| --- | --- |
|
||||
| 前端 | <http://127.0.0.1:5173> | `/api` 由 vite 代理到本地 control-plane |
|
||||
| 后端 control-plane | <http://127.0.0.1:8082> | Go 源码改动即自动重启 |
|
||||
| docker-gateway | <http://127.0.0.1:8081> | 容器内常驻，重启不频繁 |
|
||||
| postgres | `127.0.0.1:5432` | 容器内常驻，数据库重建直接销毁 volume |
|
||||
| --- | --- | --- |
|
||||
| 前端 | <http://127.0.0.1:5173> | `/api` 代理到本地 control-plane |
|
||||
| control-plane | <http://127.0.0.1:8082> | Go 热加载 |
|
||||
| native browser gateway | <http://127.0.0.1:8081> | 宿主机 Xvfb/浏览器生命周期 |
|
||||
| PostgreSQL | `127.0.0.1:5432` | 仅数据库依赖使用容器 |
|
||||
|
||||
开发默认值（`.env` 缺失或留空时）：登录 `admin` / `admin123`；控制面监听 `:8082`；凭据主密钥使用本地开发专用密钥；本地网关注册地址用 `http://127.0.0.1:8081`（容器名 `docker-gateway` 仅存在于 Compose 网络内）。
|
||||
开发默认登录信息和目录可在 `.env.example`、`deploy/browser-gateway.env.example` 中查看。不要把真实密码、Cookie、验证码或令牌写入仓库。
|
||||
|
||||
注意：本地开发后端占用 `:8082`，与整仓 `docker compose up` 的容器端口互斥，两者二选一运行。
|
||||
|
||||
最小验证：
|
||||
最小检查：
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go vet ./...
|
||||
go build ./cmd/control-plane
|
||||
go test -race ./...
|
||||
npm --prefix web ci
|
||||
npm --prefix web test -- --run
|
||||
npm --prefix web run build
|
||||
docker compose config --quiet
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user