docs/docker.md

Docker 部署

快速开始

git clone https://github.com/cnitlrt/AutoTeam.git
cd AutoTeam

mkdir -p data
cp .env.example data/.env

# 编辑 data/.env
docker compose up -d

常用命令：

docker compose logs -f
docker compose restart
docker compose down

当前 docker-compose.yml 默认启用以下运行时加固：

• init: true：容器内启用 init/reaper，帮助回收 Chromium / Playwright 子进程。
• shm_size: "1gb"：提高 /dev/shm，降低 Chromium 在 Docker 默认 64MB shm 下崩溃的概率。
• mem_limit: "2g" / pids_limit: 768：给浏览器和后台任务设置硬边界，避免异常增长拖垮宿主机。
• healthcheck：通过 http://127.0.0.1:8787/api/version 检查真实 API 可用性。
• AUTOTEAM_MEMORY_WARN_RATIO / AUTOTEAM_ZOMBIE_WARN_THRESHOLD：控制运行时资源告警阈值。

运行时默认启用与 autoteam-1 对齐的轻量 Team API transport：

• 默认 CHATGPT_API_TRANSPORT=auto，Team backend API 读取会先尝试 HTTP transport；如果返回 Cloudflare/HTML/challenge 或鉴权异常，会回退 Playwright。
• 显式设置 CHATGPT_API_TRANSPORT=playwright 时，可强制恢复旧的浏览器上下文 fetch 行为。
• 该选项只影响管理员 Team API 读写；free 帐号注册、Personal OAuth、验证码、workspace UI 选择必须继续强制真实浏览器上下文。

数据持久化

所有运行数据都存储在 data/ 目录，通过 volume 挂载到容器：

文件 / 目录	说明
data/.env	配置文件
data/accounts.json	账号池状态
data/state.json	管理员登录态
data/auths/	Codex 认证文件
data/screenshots/	调试截图

重建容器不会丢失这些数据。

如果你使用了 pull-cpa，从 CPA 导入的认证文件也会落在 data/auths/ 中。

手动构建

docker build -t autoteam .
docker run -d -p 8787:8787 -v $(pwd)/data:/app/data autoteam

快速增量镜像

首次完整构建后，本仓库提供 Dockerfile.fast 用于本地快速迭代。它复用 autoteam:latest 中已经安装好的系统依赖、uv 和 Playwright Chromium，只覆盖 Python 依赖与源码。

# 先确保有稳定基础镜像
GIT_SHA=$(git rev-parse --short HEAD) \
BUILD_TIME=$(date -u +%FT%TZ) \
docker build -t autoteam:latest .

# 后续本地快速迭代
GIT_SHA=$(git rev-parse --short HEAD) \
BUILD_TIME=$(date -u +%FT%TZ) \
docker build -f Dockerfile.fast -t autoteam:fast .

Dockerfile.fast 仅用于开发迭代，不替代首次完整构建；如果系统依赖、Playwright 版本、基础镜像或 uv.lock 出现难以解释的问题，回到标准 Dockerfile 做 --no-cache 构建。

配置方式

方式一：预先编辑 .env

启动前编辑 data/.env，容器启动后即可直接使用。

方式二：Web 页面配置

不预先配置直接启动，打开：

http://host:8787

浏览器中会显示配置向导页面，填写后自动验证连通性。

容器中的文件权限

容器以 root 运行，docker-entrypoint.sh 会把 /app/data 下的文件设为可写。

如果你在宿主机上看到部分认证文件类似：

• nobody:nogroup
• 600

通常不影响容器内运行；如需宿主机直接查看，可手动调整权限。

常见问题

容器一直重启

查看日志：

docker compose logs

通常是：

• 配置缺失
• CloudMail / CPA 连通性验证失败
• entrypoint self-check 发现镜像代码与契约符号不一致
• /api/version healthcheck 持续失败

查看健康状态：

docker compose ps
docker inspect --format '{{json .State.Health}}' autoteam-autoteam-1 | python -m json.tool

查看资源占用和 PID 数：

docker stats
docker compose top

如果日志出现 [资源] ... browser zombie processes=...，优先确认 compose 中 init: true 仍然存在；如果出现 memory usage warning，先减少并发注册/轮转，再考虑调大 mem_limit。

data 目录没有写权限

容器入口会自动 chmod -R 777 /app/data。如果宿主机仍无法访问：

sudo chmod -R 777 data/

重建后配置丢失

确保 docker-compose.yml 中有 volume 挂载：

volumes:
  - ./data:/app/data

反向同步后 data/auths 里出现重复文件名风格

新版本会在同步时自动做去重，并统一为本地命名规范。若你怀疑历史版本留下了旧文件，执行一次：

uv run autoteam pull-cpa

即可重新整理。

---

代码更新后的 rebuild SOP(SPEC-3 §8)

关键认知:本项目 Dockerfile 用 COPY src/(非 volume mount), git pull 后必须 rebuild 镜像,代码改动才会进入容器。

标准更新流程(4 步)

# 1. 拉取新代码
cd /path/to/AutoTeam && git pull

# 2. 停掉旧容器
docker compose down

# 3. 重建镜像(--no-cache 防意外缓存命中,GIT_SHA 注入版本指纹)
GIT_SHA=$(git rev-parse --short HEAD) \
BUILD_TIME=$(date -u +%FT%TZ) \
docker compose build --no-cache

# 4. 启动
docker compose up -d

验证镜像版本(三选一,结果应一致)

# 方式 A:HTTP 端点(免鉴权)
curl http://localhost:8787/api/version
# 期望:{"git_sha":"cf2f7d3","build_time":"2026-04-26T..."}

# 方式 B:进容器查环境变量
docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA

# 方式 C:看镜像 OCI label(无需启动容器)
docker image inspect autoteam-autoteam --format '{{json .Config.Labels}}'

启动期 self-check

容器每次启动都会执行 [self-check] 段,白名单 import 任一失败立即 exit 1 → docker 进入 crash-loop。

docker compose logs autoteam | head -20
# 期望看到:
# [self-check] verifying critical imports...
# [self-check] OK: 15 critical symbols imported.
# [self-check] passed.

故障排查:为什么修了代码 bug 还在?

99% 是镜像没 rebuild。先跑这条快速诊断:

# 对比 image 内 sha 与 repo HEAD
echo "image:" && curl -s http://localhost:8787/api/version | python -m json.tool
echo "repo HEAD:" && git rev-parse --short HEAD

如果 image.git_sha 与 repo HEAD 不一致 → 重做上面 4 步 SOP。

如果 self-check 报 FATAL: critical import failed:

• 说明镜像里的源码与最新代码的契约符号对不上(典型 typo 引入未定义名)
• 解决:回退最近 commit 或修复 typo,再 rebuild

lint 守卫(开发期)

pyproject.toml 已配置 ruff(F401/F811/F821 三条规则),.pre-commit-config.yaml 也接入了同样的检查。

首次启用:

uv sync                           # 装 dev 依赖(pre-commit、ruff 已声明)
uv run pre-commit install         # 注入 .git/hooks/pre-commit
uv run pre-commit run --all-files # 一次性扫全仓,确认基线干净

之后每次 git commit 会自动跑 ruff;手动检查可:

uv run ruff check src/