文档

闲鱼自动回复 开发文档

这个项目是什么

xianyu-auto-reply 是面向闲鱼（Goofish）个人卖家的自动回复系统：通过 WebSocket 长连接接入闲鱼消息通道，实时接收买家的商品咨询与议价消息，按关键词回复 / AI 回复 / 默认话术自动作答，并附带一个本地 Web 管理控制台（商品列表、回复记录、用户管理、日志管理）。

和浏览器脚本类方案不同，它的核心是「协议接口 + 长连接」：用 wss-goofish.dingtalk.com 的消息网关 + mtop 接口配合签名/解密工具函数收发消息，Cookie 保活与 token 刷新都自动化，7×24 小时跑在自己服务器上。部署形态有源码直跑、Docker（docker-compose.yml / Dockerfile-cn 国内源版）+ Nginx。

技术栈与仓库结构

领域 技术
语言与框架 Python 3.11+、FastAPI、uvicorn、pydantic
消息通道 websockets（闲鱼消息网关长连接 + 心跳）、aiohttp / httpx / requests
AI 回复 openai SDK（OpenAI 兼容接口）
浏览器自动化 Playwright（扫码登录、页面操作辅助）
协议工具 PyExecJS、blackboxprotobuf、utils/xianyu_utils.py（签名、解密、设备指纹）
认证与安全 PyJWT、passlib(bcrypt)、cryptography（控制台用户体系）
数据与日志 SQLite（db_manager.py）、pandas/openpyxl 导出、loguru 轮转日志
部署 Docker / Dockerfile-cn、docker-compose(-cn)、Nginx、entrypoint.sh 
xianyu-auto-reply/
├── Start.py                # 启动入口：CookieManager + 后台线程跑 FastAPI，主协程保持运行
├── XianyuAutoAsync.py      # 核心：WebSocket 长连接、心跳、token 刷新、cookie 保活、自动回复
├── reply_server.py         # FastAPI 管理服务（静态控制台 + 接口，HTTPBearer 鉴权、邮箱验证码注册/登录）
├── ai_reply_engine.py      # AI 回复引擎（openai 兼容接口）
├── cookie_manager.py       # Cookie 初始化与保活
├── db_manager.py           # SQLite 数据层
├── file_log_collector.py   # 文件日志收集
├── config.py / global_config.yml   # 配置加载与全局配置
├── utils/                  # xianyu_utils（签名/解密/设备ID 等）等工具
├── secure_*.py             # 授权/完整性校验相关脚本（加密与解密版）
├── static/                 # Web 控制台：login/register/index/item_search/user_management/log_management…
├── Dockerfile / Dockerfile-cn / docker-compose.yml / docker-compose-cn.yml / docker-deploy.{bat,sh}
├── entrypoint.sh / nginx/
└── requirements.txt / CHANGELOG.md / README.md

快速开始

git clone <本仓库地址>
cd xianyu-auto-reply
pip install -r requirements.txt
playwright install chromium
playwright install-deps chromium   # Linux 需要
python Start.py

Start.py 按 config.py 的 COOKIES_LIST 初始化账号任务，在后台线程启动 FastAPI：默认绑定 0.0.0.0:8080（API_HOST / API_PORT 环境变量可覆盖，global_config.yml 的 AUTO_REPLY.api 配置优先）。浏览器打开 http://localhost:8080/login.html（首次先 register.html 注册），控制台页面在 static/。

配置项说明（global_config.yml 摘要）

配置 默认 说明
API_ENDPOINTS passport / h5api mtop 接口 登录态检查、消息 headinfo、token 获取
APP_CONFIG api_version / app_key / platform web mtop 请求参数
AUTO_REPLY.enabled true 自动回复总开关
AUTO_REPLY.default_message 含 {send_user_name} 的问候话术 无命中关键词时的兜底回复
AUTO_REPLY.api enabled false、host 0.0.0.0、port 8080、timeout 10 本地 Web 服务；回复走 AI 或关键词而非 API 回复
ITEM_DETAIL.auto_fetch enabled true、外部 API selfapi.zhinianboke.com/api/getItemDetail、并发 3、timeout 30 商品详情自动获取（可关）
COOKIES / DEFAULT_HEADERS 闲鱼 Cookie 与浏览器 UA/Referer 头 登录态来源
HEARTBEAT_INTERVAL / HEARTBEAT_TIMEOUT 15 / 5（秒） WebSocket 心跳
TOKEN_REFRESH_INTERVAL / TOKEN_RETRY_INTERVAL 36000 / 1800（秒） token 定时刷新与失败重试
COOKIE_KEEPALIVE_INTERVAL 7200（秒，每 2 小时） 保活请求延长 Cookie 有效期
MESSAGE_EXPIRE_TIME 300000（毫秒） 消息过期时间
MANUAL_MODE enabled false、timeout 3600、toggle_keywords [] 手动模式：关键词切换，进入人工接管
LOG_CONFIG INFO、每天轮转、保留 7 天、zip 压缩 loguru 日志配置

工作原理

  1. Start.py 读取配置与 Cookie，初始化 CookieManager、db_manager，后台线程启动 reply_server（FastAPI 提供控制台与管理接口）。
  2. XianyuAutoAsync.py 主协程建立到闲鱼消息网关的 WebSocket 长连接，按 HEARTBEAT_INTERVAL 发心跳；utils/xianyu_utils.py 负责签名（generate_sign）、解密（decrypt）、设备指纹（generate_device_id / generate_mid / generate_uuid）与 Cookie 转换（trans_cookies）。
  3. 收到消息后按优先级匹配：手动模式开关词 → 关键词回复 → AI 回复（ai_reply_engine，openai 兼容接口）→ default_message 兜底；结果入库并写日志。
  4. 定时任务负责 token 刷新（TOKEN_REFRESH_INTERVAL，失败 30 分钟重试）与 Cookie 保活（每 2 小时）。
  5. 控制台（static/index.html 等）通过 reply_server.py 的接口管理商品、回复记录、用户与日志，接口走 HTTPBearer 鉴权、注册/登录带邮箱验证码。

二次开发要点

更新记录（摘自 CHANGELOG.md）

相关链接