抖音多账号自动回复管理系统

基于 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）

---

系统架构

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. 克隆项目

git clone <你的仓库地址>
cd kefu

2. 安装依赖

方式 A：一键安装（推荐）

.\install.bat

方式 B：手动安装 — 见 INSTALL.md

3. 启动服务

生产 / Web 访问（单端口，推荐）

# Windows
.\start_web.bat
# 浏览器打开 http://localhost:8000

# Linux / 宝塔
chmod +x install.sh start_web.sh
./start_web.sh
# 浏览器打开 http://服务器IP:8000

开发模式（前后端分离，热更新）

# 终端 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。

---

Linux / 宝塔部署

详细表单填写见 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 手动安装（非宝塔或备用）

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：

# .env 或环境变量；支持 http/https/socks5，可带账号密码
KEFU_DOUYIN_PROXY=http://user:pass@your-residential-proxy:port

2. 无图形界面的 Linux 起不来有头浏览器 → 装 Xvfb

扫码登录与 7911 后的凭证刷新都需要有头 Chromium（无头易被抖音安全 SDK 判定）。无 GUI 的服务器装好 Xvfb 后，程序会自动拉起虚拟显示：

# 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。

pip 报 SSL module is not available

说明服务器上的 Python 没有编译进 OpenSSL，pip 无法访问 HTTPS 源（阿里云镜像也一样）。

先验证：

python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
# 若报错 No module named '_ssl'，就是这个问题

推荐修复（宝塔）：

1. 面板 → 软件商店 → 安装 Python 项目管理器
2. 在项目管理器里安装 Python 3.10 或 3.11
3. 删除旧 venv，用宝塔 Python 重建：

cd /www/wwwroot/douyin
rm -rf backend/.venv
AUTO_BUILD_PYTHON=1 ./install.sh

或安装系统依赖后重装 Python：

# 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 — 依赖清单、分步安装、更新依赖
• FastAPI 交互文档 — 后端启动后访问 http://localhost:8000/docs

---

License

本项目未指定开源协议，默认保留所有权利。如需开源请自行添加 LICENSE 文件。