docs/troubleshooting.md

# 常见问题

## 安装相关

### Playwright 安装失败

```bash
uv run playwright install chromium
uv run playwright install-deps chromium
```

### macOS 上 Playwright Sync API 报错

```text
playwright._impl._errors.Error: It looks like you are using Playwright Sync API inside the asyncio loop.
```

设置环境变量：

```bash
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
uv run autoteam rotate
```

### Windows 启动时出现编码报错

如果历史 `.env` 文件含有 GBK / ANSI 编码或旧版内联注释格式，建议：

1. 将 `.env` 保存为 UTF-8
2. 确认配置值格式为：

```env
AUTO_CHECK_INTERVAL=300  # 5 分钟
```

新版本已兼容 UTF-8 与尾部注释。

## 登录相关

### Codex OAuth 登录失败：未获取到 authorization code

常见原因：
1. **IP 被标记** — VPS 的 IP 被 OpenAI/Cloudflare 拦截，建议换住宅代理
2. **Cloudflare 验证** — 浏览器环境被检测，需更新 Chromium 或切换网络
3. **workspace 选择失败** — 页面结构变化，查看 `screenshots/codex_04_*.png`
4. **自动回调不可达** — 如果浏览器和 AutoTeam 不在同一台机器，`localhost:1455` 回调可能不会到达 AutoTeam，此时请改用手动粘贴回调 URL
5. **本地回调被代理拦截** — 如果启用了 `PLAYWRIGHT_PROXY_URL`，建议同时设置 `PLAYWRIGHT_PROXY_BYPASS=localhost,127.0.0.1`

### 登录后 plan 显示 free 而不是 team

通常是 `state.json` 中的 `workspace_name` 或 `account_id` 不正确。

检查：

```bash
cat state.json | python -m json.tool
```

确认：
- `account_id` 是有效 UUID
- `workspace_name` 是 Team 名称

### 验证码一直获取失败

- 检查 CloudMail 是否正常
- 检查邮箱域名 `CLOUDMAIL_DOMAIN`
- 系统会按 **邮件 ID** 跳过已经尝试过的验证码邮件，而不是按 6 位数字去重
- 如果浏览器长时间停在 `email-verification`，通常说明新的验证码邮件没有到达，或拿到的是旧邮件

## 轮转相关

### rotate 没有补号

先看 `get_team_member_count` 是否失败。若返回 `-1`，说明 Team API 调用异常：

- 确认管理员已登录（`state.json` 有 session token）
- 确认 `account_id` 是有效 UUID

### rotate 的目标人数为什么算不准

`rotate 3` / `fill 3` 中的 `3` 指的是 **Team 总人数目标**。

也就是说：
- owner
- 外部成员
- 本地管理成员

都会一起计入这 3 个席位。当前自动轮转契约最多保留 `1 owner + 2 managed children`。

### 旧号一直被复用但额度不够

旧号复用前会先验证额度。

如果验证返回 `auth_error`（token 失效），系统会参考：
- `last_quota`
- `quota_resets_at`

判断是否值得继续复用。5h 重置时间过后，旧数据会视为过期。

### Team 超员但没有清理

`rotate` 会自动清理超员成员。如果没生效，可手动执行：

```bash
uv run autoteam cleanup 3
```

## CPA 同步相关

### 反向同步后本地 token 似乎“变旧了”

新版本会比较本地与 CPA 两侧文件的：

- `last_refresh`
- `expired`

只有 CPA 文件更“新”时，才会覆盖本地文件。

如果你怀疑历史版本已经把旧 token 写回本地，可以先重新登录目标账号，再执行：

```bash
uv run autoteam pull-cpa
```

查看日志里的：
- `local_kept_newer`
- `cpa_duplicates_deleted`
- `local_duplicates_deleted`

### 同账号在 CPA / 本地出现多个文件名不同的认证文件

新版本会在同步时按同账号去重：

- CPA 侧只保留一份
- 本地也只保留一份
- 并统一重写为本地命名规范

如果你怀疑之前版本遗留了重复文件，执行一次：

```bash
uv run autoteam pull-cpa
```

## Docker 相关

### 容器一直重启

```bash
docker compose logs
```

通常是配置缺失或连通性验证失败。

### `data` 目录没有写权限

入口脚本会自动 `chmod -R 777 /app/data`。若仍有问题：

```bash
sudo chmod -R 777 data/
```

### 重建容器后配置丢失

确认 `docker-compose.yml` 中有：

```yaml
volumes:
  - ./data:/app/data
```

### 容器里访问不到宿主机 SOCKS5 代理

如果代理在宿主机上，比如 `host.docker.internal:1080`，请先确认容器内可以解析并访问宿主机代理地址；不同 Docker / Podman 环境的宿主机别名配置方式可能不同。

然后在 `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
```

## Web 面板相关

### 页面显示 `JSON parse error`

说明后端返回了非 JSON 响应（通常是 500 错误）。查看后端日志定位具体异常。

### 操作按钮全部禁用

轮转 / 补满 / 清理等账号池操作需要先在「设置」页完成管理员登录。

### Team 成员页的 owner 为什么没有“移出”按钮

`account-owner` 角色不会显示“移出”按钮，因为这类账号通常无法通过普通成员删除接口移出。

### 刷新后数据没更新

点击侧边栏底部的「刷新数据」按钮手动刷新。

### 配置保存后 401 创建邮箱失败

issue#1 错配的典型表现:配置时填的是 maillab 的 `*_BASE_URL`,但 `MAIL_PROVIDER` 还是默认的 `cf_temp_email` → 启动校验在 `/admin/address` catch-all 路由上误回 200,但创建邮箱阶段被 maillab 拒回 `code:401`。

修复路径见 [配置说明 → ⚠️ 协议错配排查](configuration.md#-协议错配排查issue-1) 与 [SetupPage 4 步状态机](getting-started.md#25-邮箱后端归属验证)。

## 邮箱后端

### 5 个常见错配场景与对应 `error_code`

| 场景 | 触发条件 | 报错 `error_code` | 修复 |
|---|---|---|---|
| issue#1 错配 | 选 `cf_temp_email` 但 base_url 是 maillab(或反向) | `PROVIDER_MISMATCH` | SetupPage 切换 provider 后重试 |
| 域名后台为空 | maillab `/setting/websiteConfig.domainList` 为空 | `EMPTY_DOMAIN_LIST` | 在 maillab 后台先添加可用域名 |
| 凭据错误 | 管理员密码或 username/password 错 | `UNAUTHORIZED` | 重置密码或确认主账号 |
| 启用了登录验证码 | maillab 后台 captcha = ON | `CAPTCHA_REQUIRED`(warning) | 关闭 captcha 或改用 admin 直登 |
| 域名未授权 | maillab 设置了 `addVerify=1` 拒绝创建非白名单域名 | `DOMAIN_REJECTED` | 在管理后台添加域名白名单 |

### 紧急逃生口

如果嗅探阻断了你已确认无误的配置,可以临时:

```bash
export AUTOTEAM_SKIP_PROVIDER_SNIFF=1
uv run autoteam api
```

仅在确诊误报时使用,生产环境不建议长期开启。

### maillab 401 自愈

`MaillabClient` 业务方法被装饰器包裹,任何一次响应 `code:401` 会自动触发 re-login 并重试。如果重试仍 401,会抛 `MaillabAuthFailed`(日志关键字 `[maillab] token 已自愈` 表示自愈成功)。详细策略见 [mail-provider-design.md §8](mail-provider-design.md#8-401-自愈策略)。