Spaces:
Paused
Paused
| # 从零开始部署 AutoTeam | |
| 本文档带你从一台全新的 VPS 或本地机器开始，完成 AutoTeam 的安装、配置、管理员登录、首次补号与日常使用。 | |
| ## 前置条件 | |
| 在开始之前，你需要准备好以下服务： | |
| | 服务 | 说明 | 获取方式 | | |
| |------|------|---------| | |
| | **ChatGPT Team 订阅** | 管理员主号，需要有 Team 订阅 | [chatgpt.com](https://chatgpt.com) | | |
| | **临时邮箱** | 自动注册与收验证码,二选一 | ① **`cf_temp_email`(默认)** = 自建 [dreamhunter2333/cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email)<br>② **`maillab`** = 自建 [maillab/cloud-mail](https://github.com/maillab/cloud-mail) | | |
| | **CLIProxyAPI** | Codex 代理与认证文件同步目标 | 自建 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) | | |
| | **VPS / 本地机器** | 推荐 Ubuntu 22.04+；也支持 Windows / macOS | 任意云服务商 / 本地电脑 | | |
| | **域名** | 用于 CloudMail 临时邮箱与 Verified Domains | 任意域名注册商 | | |
| > 建议使用住宅 IP 或干净的 VPS IP，避免被 OpenAI / Cloudflare 标记。 | |
| ## 准备工作 | |
| ### 1. 搭建临时邮箱后端（二选一） | |
| > **【重要】先决定后端,再决定填哪一组配置。** 两个后端 API 完全不兼容:`CLOUDMAIL_*` 字段对应 `dreamhunter2333/cloudflare_temp_email`,**不是** `maillab/cloud-mail`(社区里另一个同名项目)。**必须** 在 `.env` 里显式声明 `MAIL_PROVIDER=cf_temp_email` 或 `MAIL_PROVIDER=maillab`,否则可能撞 [issue#1](configuration.md#-协议错配排查issue-1) 错配。 | |
| #### 选项 A:`maillab`(**推荐**,中文社区活跃) | |
| 适配 [maillab/cloud-mail](https://github.com/maillab/cloud-mail)(参考 [官方文档](https://doc.skymail.ink/guide/dashboard))。一键 Docker / Cloudflare Workers,内置管理后台。 | |
| 部署完成后,在 `.env` 中显式设置: | |
| ```dotenv | |
| MAIL_PROVIDER=maillab | |
| MAILLAB_API_URL=https://your-maillab.example.com | |
| MAILLAB_USERNAME=admin@example.com | |
| MAILLAB_PASSWORD=your_password | |
| MAILLAB_DOMAIN=@your-domain.com | |
| ``` | |
| #### 选项 B:`cf_temp_email`(经典选项) | |
| 适配 [dreamhunter2333/cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email),基于 Cloudflare Workers,搭建简单。 | |
| 按官方文档完成部署后你会得到: | |
| - API 地址(如 `https://your-domain.com/api`)→ `CLOUDMAIL_BASE_URL` | |
| - 管理员密码(`x-admin-auth`)→ `CLOUDMAIL_PASSWORD` | |
| - 邮箱域名(如 `@your-domain.com`)→ `CLOUDMAIL_DOMAIN` | |
| ```dotenv | |
| MAIL_PROVIDER=cf_temp_email | |
| CLOUDMAIL_BASE_URL=https://your-domain.com/api | |
| CLOUDMAIL_PASSWORD=your_password | |
| CLOUDMAIL_DOMAIN=@your-domain.com | |
| ``` | |
| > 切换后业务调用方零改动,工厂会按 `MAIL_PROVIDER` 自动 dispatch。详见 [配置说明](configuration.md#mail-provider-切换)。 | |
| ### 2. 设置 OpenAI Verified Domains | |
| 由于重复邀请有概率触发 `"unable to invite user due to an error."` 错误（[参考](https://community.openai.com/t/email-invite-error-in-chatgpt-business/1378252)），需要设置域名验证让账号自动加入 Team： | |
| 1. 打开 ChatGPT → Settings → Account | |
| 2. 找到 **Verified Domains**，点击 **Verify new domain** | |
| 3. 输入你的域名（如 `your-domain.com`） | |
| 4. 在 Cloudflare（或你的 DNS 服务商）添加 OpenAI 要求的 DNS 记录 | |
| 5. 回到 ChatGPT 点击 **Check**，验证通过后状态变为 verified | |
| 6. 进入 Workspace → Identity & Access，打开 **Automatic account creation** | |
| 这样使用该域名邮箱注册的 ChatGPT 账号会自动加入 Team workspace，不需要手动邀请。 | |
| > 域名验证只针对 ChatGPT 侧,与你选哪个临时邮箱后端无关 — `cf_temp_email` 和 `maillab` 都需要。 | |
| ### 3. 搭建 CLIProxyAPI | |
| 参考 CPA 项目文档完成搭建：https://github.com/router-for-me/CLIProxyAPI | |
| 搭建完成后你会得到： | |
| - CPA 地址（如 `http://127.0.0.1:8317`） | |
| - 管理密钥（`secret-key`） | |
| ## 第一步：安装 | |
| ### 方式一：直接部署 | |
| ```bash | |
| # 克隆项目 | |
| git clone https://github.com/cnitlrt/AutoTeam.git | |
| cd AutoTeam | |
| # Linux 一键安装（uv、依赖、Playwright、pre-commit） | |
| bash setup.sh | |
| ``` | |
| Windows / macOS 可直接执行： | |
| ```bash | |
| uv sync | |
| uv run playwright install chromium | |
| ``` | |
| > Windows / macOS 不需要 xvfb。Linux 无图形环境时项目会自动处理虚拟显示。 | |
| ### 方式二：Docker 部署 | |
| ```bash | |
| git clone https://github.com/cnitlrt/AutoTeam.git | |
| cd AutoTeam | |
| mkdir -p data | |
| docker compose up -d | |
| ``` | |
| ## 第二步：配置 | |
| ### 直接部署 | |
| 启动任何命令时会自动进入配置向导： | |
| ```bash | |
| uv run autoteam api | |
| ``` | |
| **推荐使用 Web 面板配置**(SetupPage 已支持 provider 选择 + 一站式校验,见下文 §2.5);CLI 向导仍可用,以默认的 `cf_temp_email` 后端为例: | |
| ```text | |
| === AutoTeam 首次配置 === | |
| Mail Provider [cf_temp_email]: ← 回车用默认,或填 maillab | |
| CloudMail API 地址: https://your-cloudmail.com/api | |
| CloudMail 管理员密码: your_password | |
| 邮箱域名（如 @example.com）: @your-domain.com | |
| CPA 管理密钥: your_cpa_key | |
| API 鉴权密钥 [回车自动生成]: | |
| ``` | |
| 选 `maillab` 时,SetupPage 会按 provider 动态切换需要填的字段(`MAILLAB_API_URL` / `MAILLAB_USERNAME` / `MAILLAB_PASSWORD` / `MAILLAB_DOMAIN`),CLI 向导也会按 `MAIL_PROVIDER` 跳过无关字段。 | |
| 配置会自动验证临时邮箱后端和 CPA 的连通性，失败会提示具体原因。 | |
| ### 2.5 邮箱后端归属验证 | |
| Web 面板的 SetupPage 把邮箱后端配置拆成 4 步状态机,每一步必须前一步通过才能解锁: | |
| 1. **后端类型** — 在「cf_temp_email」/「maillab」中选一个;切换会重置后续状态。 | |
| 2. **服务器连接** — 填入 `*_BASE_URL` / `MAILLAB_USERNAME`(maillab 才需要)/ `*_PASSWORD`,点击「测试连接」会同时跑指纹嗅探(防止 issue#1 错配)+ 凭据校验。 | |
| 3. **域名归属** — 后端探到 `domain_list` 时显示下拉,否则手动输入。点击「验证归属」会创建 `probe-{ts}{uuid}` 探测邮箱并立即删除,确认管理员持有该域名。 | |
| 4. **保存配置** — 域名验证通过后才能保存,Settings 页面同样支持后续切换并提示「重启服务后生效」。 | |
| 错误码与修复方向见 [配置说明 → 错误码对照表](configuration.md#错误码对照表apimail-providerprobe)。 | |
| ### Docker 部署 | |
| 方式一：编辑配置文件 | |
| ```bash | |
| cp .env.example data/.env | |
| nano data/.env # 填入实际配置 | |
| docker compose restart | |
| ``` | |
| 方式二：Web 页面配置 | |
| 直接打开 `http://your-server:8787`，会显示配置向导页面，在浏览器中填写。 | |
| 如果你需要让浏览器流量走宿主机 SOCKS5 代理，请先确认容器内可以解析并访问宿主机代理地址（例如 `host.docker.internal`，或你自己提供的宿主机网关别名）。 | |
| 然后在 `data/.env` 中加入： | |
| ```dotenv | |
| PLAYWRIGHT_PROXY_URL=socks5://host.docker.internal:1080 | |
| PLAYWRIGHT_PROXY_BYPASS=localhost,127.0.0.1 | |
| ``` | |
| 如果代理需要认证，可以写成： | |
| ```dotenv | |
| PLAYWRIGHT_PROXY_URL=socks5://username:password@host.docker.internal:1080 | |
| ``` | |
| ## 第三步：管理员登录 | |
| 配置完成后，需要先用 ChatGPT Team 管理员账号登录。 | |
| ### 通过 Web 面板 | |
| 1. 打开 `http://your-server:8787` | |
| 2. 输入 API Key 进入面板 | |
| 3. 进入「设置」页 | |
| 4. 输入管理员邮箱，点击「开始登录」 | |
| 5. 按提示输入密码或邮箱验证码 | |
| 6. 选择 Team workspace（如 `Idapro`） | |
| 7. 登录成功后会自动保存到 `state.json` | |
| ### 通过命令行 | |
| ```bash | |
| uv run autoteam admin-login --email your-admin@example.com | |
| ``` | |
| ## 第四步：首次轮转 | |
| ```bash | |
| uv run autoteam rotate 3 | |
| ``` | |
| 或在 Web 面板「账号池操作」页点击「智能轮转」。 | |
| 首次运行会： | |
| 1. 同步 Team 实际成员到本地 | |
| 2. 检查所有 active 账号额度 | |
| 3. 移出额度低于阈值的账号 | |
| 4. 优先复用 standby 中额度已恢复的旧号 | |
| 5. 不够时自动创建新账号 | |
| 6. 同步 active 认证文件到 CPA | |
| > **注意：** | |
| > `rotate 3` / `fill 3` 中的 `3` 指的是 **Team 总人数目标**，不是“本地管理账号数量”。当前运行契约最多为 `1 owner + 2 managed children`。 | |
| > 如果 Team 中已经有 owner / 外部成员，它们也会计入总数。 | |
| ## 第五步：日常使用 | |
| ### 方式一：API 模式（推荐） | |
| ```bash | |
| uv run autoteam api | |
| ``` | |
| API 模式下： | |
| - Web 面板集中管理日常操作 | |
| - 后台自动巡检（默认每 5 分钟） | |
| - 可在「同步中心」中做对账与双向同步 | |
| - 可在「OAuth 登录」页手动导入账号 | |
| ### 方式二：手动执行 | |
| ```bash | |
| uv run autoteam status # 查看状态 | |
| uv run autoteam check # 检查额度 | |
| uv run autoteam rotate 3 # 智能轮转 | |
| uv run autoteam sync # 同步到 CPA | |
| uv run autoteam pull-cpa # 从 CPA 拉回本地 | |
| ``` | |
| ## 常见流程 | |
| ### 添加更多账号 | |
| ```bash | |
| uv run autoteam rotate 3 # 补满到 3 个总席位 | |
| # 或 | |
| uv run autoteam add # 自动注册并添加一个 | |
| # 或 | |
| uv run autoteam manual-add # 手动 OAuth 导入一个账号 | |
| ``` | |
| ### 清理多余账号 | |
| ```bash | |
| uv run autoteam cleanup 3 # 保留 3 个总席位 | |
| ``` | |
| ### 从 CPA 恢复认证文件到本地 | |
| ```bash | |
| uv run autoteam pull-cpa | |
| ``` | |
| 或在 Web 面板「同步中心」页点击「拉取 CPA」。 | |
| 该操作会： | |
| - 从 CPA 下载 `codex-*.json` | |
| - 清理同账号重复文件 | |
| - 按本地命名规范重写到 `auths/` | |
| - 将新导入账号补进 `accounts.json`（默认标记为 `standby`） | |
| ## 下一步 | |
| - [配置详解](configuration.md) | |
| - [工作原理](architecture.md) | |
| - [API 文档](api.md) | |
| - [常见问题](troubleshooting.md) | |