# 直播账号运营后台

斗鱼 / 虎牙账号运营 Web 平台：批量登录拿 Cookie、按工作台跑活动任务、应用宝点券充值。版本见 `pyproject.toml`（当前 0.3.0）。

## 能做什么

- **斗鱼**：极验滑块自动过验、邮箱验证码、批量登录与 CK 检测/重登；精英宝典 / 电竞手册 / 和平小店三套工作台（绑定、开通、充值、兑换）；鱼翅可由微信二维码或供应商直充。
- **虎牙**：Cookie / 密码 / App / 短信登录、自动注册、设备绑定、精英宝典、浏览器人工兑换；网页运行 Cookie 与 App 原始凭据（`raw_cookie`）分离，可从原始凭据重建网页 Cookie。
- **应用宝**：和平精英点券扫码登录、选区服角色、支付二维码。Worker 合在 Web 容器内，只监听 `127.0.0.1:8810`。
- **权限**：超级管理员 / 运营 / 客服；可按权限点覆盖。客服只看分配给自己的账号，虎牙侧默认只开放浏览器兑换。
- **安全**：密码、邮箱、Cookie、代理密钥等敏感字段落盘加密；操作写审计日志。

## 项目结构

```
live-hub-py/
├── core/                       # 协议客户端（不经过 Web 也可单独调用）
│   ├── douyu/                 # 登录、活动、鱼翅直充、代理
│   ├── huya/                  # App/Web/短信登录、WSS、设备指纹、网页 Cookie 补齐
│   └── geetest/               # 极验 v3 滑块
├── web/
│   ├── backend/               # FastAPI + SQLAlchemy + Alembic
│   │   ├── routers/           # HTTP / WebSocket
│   │   ├── services/         # 批次 runner（进程内线程池）
│   │   └── migrations/        # 数据库迁移
│   ├── frontend/              # React + Ant Design + Vite
│   └── extension/             # 虎牙浏览器兑换助手
├── services/yyb-worker/        # 应用宝协议运行时（随主镜像部署）
├── tests/                      # pytest（默认 SQLite 内存库）
├── docs/                       # 协议与联调文档（结论以「虎牙 Cookie 路线状态」为准）
├── deploy.sh / dev.sh          # 生产部署 / 本机热更新
└── docker-compose.yml         # 应用容器 + MySQL 8.4
```

## 快速开始

```bash
# Docker 部署（推荐）
./deploy.sh
```

访问 `http://localhost:8800`（compose 默认把容器 8800 映到宿主机 `APP_PORT`，缺省 8000）。默认管理员 `admin / admin123`，生产环境务必改掉。

本机热更新用 `./dev.sh`（或 `./deploy.sh dev`）。它会拉起绑定 `127.0.0.1:8810` 的开发 Worker，后端自动连该地址；Worker 数据在 `data/yyb-worker-dev/`。`Ctrl+C` 会一并停掉。应用日志按日期写到 `logs/app-YYYY-MM-DD.log`，可用 `./dev.sh logs` 跟踪当天文件。

```bash
./deploy.sh          # 构建并部署
./deploy.sh logs     # 当天持久化应用日志
./deploy.sh logs container  # Docker 容器输出（含 Worker）
./deploy.sh stop
./deploy.sh restart
./deploy.sh reset    # 重置所有数据（需二次确认）
```

## 运行时与密钥

生产是 **单个应用容器 + 内网 MySQL 8.4**。数据库不映射公网；本机 `./dev.sh` 通过 `127.0.0.1:3307` 连 compose 里的 MySQL。

在项目 `.env` 里准备：

```dotenv
MYSQL_PASSWORD=...
MYSQL_ROOT_PASSWORD=...
JWT_SECRET_KEY=随机密钥
APP_ENCRYPTION_KEY=随机密钥          # 敏感字段加密，更换后历史密文无法解密
YYB_WORKER_KEY=随机密钥              # 本机回环访问 Worker
```

生成随机密钥：

```bash
python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
```

可选：

- `FISH_FIN_RECHARGE_*`：鱼翅供应商直充，只走环境变量，不入库、不回前端。
- `MAIL_ROUNDCUBE_URL`：邮件验证码服务；不填则用代码默认 Roundcube 地址。
- `CORS_ORIGINS`、`COOKIE_SECURE`：HTTPS 部署时按实际填写。

应用宝扫码图和支付二维码只经后台授权接口返回。服务器只需要本仓库，不必再部署 `js_reverse`。Worker 任务数据在 `data/yyb-worker-jobs/`。

## 角色权限

| 角色 | 权限 |
|---|---|
| 超级管理员 | 全部功能 + 用户管理 + 权限分配 + 审计日志 |
| 运营 | 账号管理、批量登录、代理、Cookie、双平台任务、应用宝 |
| 客服 | 仅查看分配给自己的账号；虎牙只保留浏览器兑换 |

## 登录与任务流

斗鱼登录：

```
获取极验参数 → 滑块识别 → 邮箱验证码 → 提交 → Cookie
```

斗鱼工作台按 `handbook_scope`（elite / esports / peace）隔离任务和支付二维码。虎牙精英宝典走活动 WSS；缺少网页设备字段时先 `wsLaunch` 补齐，再把补齐后的 Cookie 回写账号。

进程重启会把内存里丢失的 pending/running 任务标成中断，避免前端被假活跃批次锁死。

## 运行测试

```bash
uv run --group dev pytest        # 或 ./dev.sh test
uv run --group dev pytest tests/test_cookie_operations.py
./dev.sh format tests conftest.py
./dev.sh format-check tests conftest.py
./dev.sh type-check            # 渐进式 Pyright
docker compose --profile test run --rm test
```

测试各自建 SQLite 内存库；根目录 `conftest.py` 兜底 `DATABASE_URL` / `APP_ENCRYPTION_KEY`，防止误连开发/生产库。迁移链冒烟见 `tests/test_migrations.py`。兑换、下单、支付属于写操作，默认用 mock 做契约测试，不打真实支付。

启用推送前门禁（Ruff + pytest）：

```bash
./scripts/install-git-hooks.sh
```

需要把 Pyright 也纳入时：`TYPECHECK=1 git push`。紧急绕过：`git push --no-verify` 或 `SKIP_TESTS=1 git push`。

## 技术栈

- 后端：FastAPI + SQLAlchemy + MySQL 8.4（测试用 SQLite）+ JWT
- 前端：React + Ant Design + Vite
- 核心：Python 3.12 + OpenCV + ONNX + pycryptodome + curl-cffi
- 迁移：Alembic
- 部署：Docker Compose

## 代理

在「代理配置」页填写代理 API（JSON）和白名单。移动出口 IP 漂移时，系统会保留多个出口 IP。示例：

```json
{"code":0,"success":"true","msg":"","data":[{"IP":"1.2.3.4","Port":8080}]}
```

白名单错误时接口会带上当前出口 IP，系统按平台凭证自动同步。

## 文档

协议与联调笔记在 `docs/`。当前虎牙 Cookie 行为以 [虎牙 Cookie 路线状态](docs/HUYA_COOKIE路线状态.md) 为准。