From a05dae8412642ef24f4d77780d9ad1670604306b Mon Sep 17 00:00:00 2001 From: Your Name Date: Thu, 23 Jul 2026 17:55:23 +0800 Subject: [PATCH] first commit --- README.md | 361 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..cfc5cd5 --- /dev/null +++ b/README.md @@ -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` 文件。