first commit

2026-07-23 17:55:23 +08:00
commit a05dae8412
1 changed files with 361 additions and 0 deletions
@@ -0,0 +1,361 @@
+# 抖音多账号自动回复管理系统
+
+基于 **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` 文件。