362 lines
12 KiB
Markdown
362 lines
12 KiB
Markdown
# 抖音多账号自动回复管理系统
|
||
|
||
基于 **FastAPI + Playwright + 抖音 IM 直连** 与 **Vue3** 的抖音私信自动客服后台。支持多账号托管、规则化自动回复、实时消息监听、凭证持久化与多用户权限管理。
|
||
|
||
> 仅供学习与研究使用。请遵守抖音平台相关协议与法律法规，勿用于 spam、骚扰等违规场景。
|
||
|
||
---
|
||
|
||
## 功能特性
|
||
|
||
### 账号与 IM 托管
|
||
- **多账号并行托管**：每个抖音账号独立 Worker，互不影响
|
||
- **浏览器登录**：Playwright 打开抖音网页，扫码登录并采集 Cookie / IM 签名凭证
|
||
- **IM 直连模式**：凭证就绪后可免浏览器启动，通过 WebSocket + HTTP API 实时收消息、发私信
|
||
- **凭证持久化**：登录后自动保存 Cookie、`web_protect`、`keys` 等，下次启动优先直连
|
||
- **凭证检测**：启动前自动校验 sessionid / IM 签名是否可用，并提示是否需要重新登录
|
||
|
||
### 自动回复
|
||
- **规则匹配**：精确匹配、包含匹配、正则匹配
|
||
- **全局兜底**：无规则命中时使用默认话术
|
||
- **多种回复类型**：文本、网址（超链接）、卡片
|
||
- **按账号 / 全局规则**：可为单个账号或全部账号配置策略
|
||
- **回复延迟**：支持设置秒级延迟，降低触发频控风险
|
||
- **智能跳过**：自动忽略 `[赞]`、表情互动等非文本消息，避免无效回复
|
||
|
||
### 消息与日志
|
||
- **聊天式日志面板**：按会话查看收发记录，支持手动发消息
|
||
- **系统诊断日志**：记录 IM 发送失败、凭证刷新、风控错误码等，便于排查
|
||
- **仪表盘统计**：在线账号数、回复情况等概览
|
||
|
||
### 权限与安全
|
||
- **用户登录**：JWT 鉴权
|
||
- **角色分级**：`admin` / `operator` / `viewer`
|
||
- **数据隔离**：非管理员只能看到、操作自己名下的账号与规则
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 后端 API | Python 3.10+、FastAPI、Uvicorn、SQLAlchemy、aiosqlite |
|
||
| 自动化 / IM | Playwright、httpx、WebSocket、Protobuf |
|
||
| IM 签名 | PyExecJS + Node.js（`a_bogus`、`bd-ticket-guard`） |
|
||
| 前端 | Vue 3、Vite、Ant Design Vue、Pinia、Axios |
|
||
| 数据库 | SQLite（`backend/kefu.db`） |
|
||
|
||
---
|
||
|
||
## 系统架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Frontend["前端 Vue3"]
|
||
UI[管理控制台]
|
||
end
|
||
|
||
subgraph Backend["后端 FastAPI"]
|
||
API[REST API]
|
||
WM[Worker 管理器]
|
||
AUTH[JWT 鉴权]
|
||
end
|
||
|
||
subgraph Worker["单账号 Worker"]
|
||
PW[Playwright 浏览器]
|
||
IM[IM 直连服务]
|
||
WS[Frontier WebSocket]
|
||
HTTP[imapi HTTP]
|
||
end
|
||
|
||
UI --> API
|
||
API --> AUTH
|
||
API --> WM
|
||
WM --> Worker
|
||
PW -->|采集 Cookie/签名| IM
|
||
IM --> WS
|
||
IM --> HTTP
|
||
WS -->|收消息| IM
|
||
HTTP -->|发私信| Douyin[(抖音 IM)]
|
||
```
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
kefu/
|
||
├── backend/ # Python 后端
|
||
│ ├── main.py # API 入口、Worker 调度
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ ├── auth/ # 登录、JWT、角色权限
|
||
│ ├── models/ # 数据表（账号、规则、日志、用户）
|
||
│ ├── rpa_engine/
|
||
│ │ ├── playwright_worker.py # 浏览器登录与托管
|
||
│ │ └── douyin_im/ # IM 直连（HTTP/WS/签名/Proto）
|
||
│ └── utils/ # Cookie 存储、系统日志
|
||
├── frontend/ # Vue3 前端
|
||
│ └── src/views/ # 仪表盘、账号、规则、日志等页面
|
||
├── install.bat / install.sh # 一键安装（含前端构建）
|
||
├── start_web.bat / start_web.sh # 单端口 Web 访问（推荐生产）
|
||
├── start_backend.bat / .sh # 仅启动 API
|
||
├── start_frontend.bat # 开发模式前端热更新
|
||
├── deploy/ # Nginx / systemd 示例
|
||
├── .env.example # 生产环境变量模板
|
||
├── INSTALL.md # 详细安装与排错说明
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
- **Python 3.10+**
|
||
- **Node.js 18+**（IM 签名运行时，必需）
|
||
- **npm**
|
||
- **Windows 10/11** 或 **Linux**（宝塔、Ubuntu、CentOS 等）
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone <你的仓库地址>
|
||
cd kefu
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
**方式 A：一键安装（推荐）**
|
||
|
||
```powershell
|
||
.\install.bat
|
||
```
|
||
|
||
**方式 B：手动安装** — 见 [INSTALL.md](./INSTALL.md)
|
||
|
||
### 3. 启动服务
|
||
|
||
**生产 / Web 访问（单端口，推荐）**
|
||
|
||
```powershell
|
||
# Windows
|
||
.\start_web.bat
|
||
# 浏览器打开 http://localhost:8000
|
||
```
|
||
|
||
```bash
|
||
# Linux / 宝塔
|
||
chmod +x install.sh start_web.sh
|
||
./start_web.sh
|
||
# 浏览器打开 http://服务器IP:8000
|
||
```
|
||
|
||
**开发模式（前后端分离，热更新）**
|
||
|
||
```powershell
|
||
# 终端 1：后端 API
|
||
.\start_backend.bat
|
||
|
||
# 终端 2：前端开发服务器（Vite 代理 /api）
|
||
.\start_frontend.bat
|
||
# 打开 http://localhost:5173
|
||
```
|
||
|
||
### 4. 登录后台
|
||
|
||
浏览器打开 **http://localhost:8000**（生产）或 **http://localhost:5173**（开发），使用默认管理员账号（**首次启动自动创建**）：
|
||
|
||
| 字段 | 默认值 |
|
||
|------|--------|
|
||
| 用户名 | `admin` |
|
||
| 密码 | `admin123` |
|
||
|
||
> 部署到公网前，请务必修改密码并设置 `KEFU_SECRET_KEY`、`KEFU_ADMIN_PASSWORD` 环境变量。
|
||
|
||
---
|
||
|
||
## 使用流程
|
||
|
||
1. **添加账号**：账号管理 → 添加抖音账号
|
||
2. **启动托管**：点击「启动托管」
|
||
- 凭证有效 → 自动 **IM 直连**，无需开浏览器
|
||
- 凭证缺失 → 弹出浏览器扫码登录，登录后自动保存凭证
|
||
3. **配置规则**：自动回复规则 → 新建规则（关键字 + 回复内容，支持文本/网址/卡片）
|
||
4. **查看效果**：回复日志 / 消息中心查看收发记录；系统日志查看 IM 诊断信息
|
||
|
||
---
|
||
|
||
## 环境变量（可选）
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `KEFU_SECRET_KEY` | JWT 签名密钥 | 内置默认值（不安全） |
|
||
| `KEFU_ADMIN_PASSWORD` | 首次创建 admin 的密码 | `admin123` |
|
||
| `KEFU_HOST` / `KEFU_PORT` | 监听地址与端口 | `0.0.0.0` / `8000` |
|
||
| `KEFU_SERVE_WEB` | 后端是否托管前端静态文件 | `true` |
|
||
| `PLAYWRIGHT_BROWSERS_PATH` | Chromium 安装目录 | 系统默认 |
|
||
|
||
完整模板见 [`.env.example`](./.env.example)。
|
||
|
||
---
|
||
|
||
## Linux / 宝塔部署
|
||
|
||
详细表单填写见 **[deploy/baota.md](./deploy/baota.md)**（对照宝塔「添加 Python 项目」截图）。
|
||
|
||
### 宝塔面板（推荐）
|
||
|
||
| 字段 | 填写 |
|
||
|------|------|
|
||
| 项目路径 | `/www/wwwroot/douyin/backend` |
|
||
| 启动方式 | **命令行启动** |
|
||
| 启动命令 | `bash /www/wwwroot/douyin/backend/baota_start.sh` |
|
||
| 依赖包 | `/www/wwwroot/douyin/backend/requirements.txt` |
|
||
| 初始化命令 | `bash /www/wwwroot/douyin/backend/baota_init.sh` |
|
||
| 环境变量 | 从文件加载 `/www/wwwroot/douyin/.env` |
|
||
|
||
### SSH 手动安装（非宝塔或备用）
|
||
|
||
```bash
|
||
cd /www/wwwroot/douyin
|
||
|
||
chmod +x install.sh start_web.sh
|
||
|
||
# 先诊断本机 Python（宝塔/原生均适用）
|
||
./install.sh --diagnose
|
||
|
||
# 自动安装（会扫描宝塔 pyporject_evn、当前 shell、系统 Python）
|
||
./install.sh
|
||
|
||
# 若宝塔 Python 缺 SSL，自动编译一个可用的 3.11
|
||
AUTO_BUILD_PYTHON=1 ./install.sh
|
||
|
||
./start_web.sh
|
||
```
|
||
|
||
宝塔 **Python 项目** 配置：
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| 项目路径 | `/www/wwwroot/douyin/backend` |
|
||
| 启动命令 | `/www/wwwroot/douyin/backend/.venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8000` |
|
||
| 运行用户 | `www` |
|
||
|
||
> 不要用宝塔自带的坏 Python 直接跑项目。`install.sh` 会在 `backend/.venv` 创建独立环境。
|
||
|
||
健康检查：`GET /api/health`
|
||
可选：使用 `deploy/nginx.conf.example` 配置域名与 HTTPS。
|
||
|
||
### 云服务器发私信报 7911（机房 IP 风控）
|
||
|
||
本地正常、一上云服务器发消息就 `status_code=7911`，几乎都是两件事，已内置支持：
|
||
|
||
**1. 机房 IP 被风控 → 走住宅代理**
|
||
|
||
云服务器是 IDC 机房 IP，抖音对私信接口的安全校验会判定为高风险。配置代理后，IM 的 HTTP 请求与浏览器登录会走同一出口 IP：
|
||
|
||
```bash
|
||
# .env 或环境变量；支持 http/https/socks5，可带账号密码
|
||
KEFU_DOUYIN_PROXY=http://user:pass@your-residential-proxy:port
|
||
```
|
||
|
||
**2. 无图形界面的 Linux 起不来有头浏览器 → 装 Xvfb**
|
||
|
||
扫码登录与 7911 后的凭证刷新都需要**有头** Chromium（无头易被抖音安全 SDK 判定）。无 GUI 的服务器装好 Xvfb 后，程序会自动拉起虚拟显示：
|
||
|
||
```bash
|
||
# Debian/Ubuntu
|
||
apt install -y xvfb
|
||
# CentOS/Rocky
|
||
yum install -y xorg-x11-server-Xvfb
|
||
# Python 依赖（requirements.txt 已含）
|
||
pip install pyvirtualdisplay
|
||
```
|
||
|
||
> 也可改用 `xvfb-run -a ./start_web.sh` 启动。`KEFU_BROWSER_HEADLESS=1` 可强制无头，但更易触发风控，不推荐。
|
||
|
||
配置好后，**在服务器上重新浏览器登录一次**（不要拷本地的 `kefu.db` / `sessions`），让凭证在服务器环境与代理 IP 下重新生成。
|
||
|
||
---
|
||
|
||
## 权限说明
|
||
|
||
| 角色 | 能力 |
|
||
|------|------|
|
||
| **admin** | 全部功能，含用户管理、全局规则 |
|
||
| **operator** | 管理自己的账号、规则，启动/停止托管 |
|
||
| **viewer** | 只读查看日志与统计 |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
| 现象 | 处理 |
|
||
|------|------|
|
||
| 启动报找不到 uvicorn | 运行 `install.bat` 或 `install.sh` |
|
||
| 宝塔报权限不够 | 删除 Windows 拷来的 `.venv`，在 Linux 上运行 `./install.sh` |
|
||
| pip 报 fastapi 版本找不到 | 系统 Python 是 3.6，需安装 Python 3.10+ |
|
||
| IM 显示「未就绪」 | 用浏览器模式登录一次并打开私信页，采集 `web_protect` / `keys` |
|
||
| 发送失败 7911 | 抖音安全校验未过（多为机房 IP 风控）。①确认 Node.js 已装；②在服务器本机重新浏览器登录刷新凭证；③云服务器配置 `KEFU_DOUYIN_PROXY` 走住宅代理；④无 GUI 的 Linux 装 `xvfb`（详见下方「云服务器部署」） |
|
||
| 发送失败 8xxx（如 8101） | 多为陌生人私信条数/隐私限制，用真实用户先发起会话再测试 |
|
||
| 每次都要开浏览器 | 确认 IM 凭证已保存；重启后端使最新校验逻辑生效 |
|
||
|
||
更多排错步骤见 **[INSTALL.md](./INSTALL.md)**。
|
||
|
||
### pip 报 `SSL module is not available`
|
||
|
||
说明服务器上的 **Python 没有编译进 OpenSSL**，pip 无法访问 HTTPS 源（阿里云镜像也一样）。
|
||
|
||
**先验证：**
|
||
|
||
```bash
|
||
python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
|
||
# 若报错 No module named '_ssl'，就是这个问题
|
||
```
|
||
|
||
**推荐修复（宝塔）：**
|
||
|
||
1. 面板 → **软件商店** → 安装 **Python 项目管理器**
|
||
2. 在项目管理器里安装 **Python 3.10 或 3.11**
|
||
3. 删除旧 venv，用宝塔 Python 重建：
|
||
|
||
```bash
|
||
cd /www/wwwroot/douyin
|
||
rm -rf backend/.venv
|
||
AUTO_BUILD_PYTHON=1 ./install.sh
|
||
```
|
||
|
||
**或安装系统依赖后重装 Python：**
|
||
|
||
```bash
|
||
# CentOS / Rocky
|
||
yum install -y openssl openssl-devel libffi-devel zlib-devel
|
||
|
||
# Ubuntu / Debian
|
||
apt install -y libssl-dev libffi-dev zlib1g-dev python3-venv
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
- **不要提交敏感数据**：`kefu.db`、`backend/sessions/`、`.env` 等已在 `.gitignore` 中忽略
|
||
- **合规使用**：请控制自动回复频率，避免对平台或用户造成骚扰
|
||
- **凭证时效**：`ts_sign` 等 IM 签名会过期，异常时需重新浏览器登录刷新
|
||
- **测试建议**：不要用两个互不关注的小号互发测试，易触发抖音业务层限制（8xxx）
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [INSTALL.md](./INSTALL.md) — 依赖清单、分步安装、更新依赖
|
||
- FastAPI 交互文档 — 后端启动后访问 `http://localhost:8000/docs`
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
本项目未指定开源协议，默认保留所有权利。如需开源请自行添加 `LICENSE` 文件。
|