112 lines
3.3 KiB
Markdown
112 lines
3.3 KiB
Markdown
# python-wechat-kf
|
||
|
||
微信客服 API 网页测试工具：监听用户消息、主动/被动发消息，消息存储到 PostgreSQL。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 创建 PostgreSQL 数据库
|
||
|
||
```bash
|
||
createdb wechat_kf
|
||
```
|
||
|
||
### 2. 配置 .env
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 填入真实配置：
|
||
|
||
```env
|
||
# --- 企业微信基础信息（必填）---
|
||
# 企业 ID，在企业微信管理后台 - 我的企业 页面底部查看
|
||
CORPID=ww9f866d5bf5175e77
|
||
|
||
# 应用 Secret，在企业微信管理后台 - 微信客服 - 开发配置 中获取
|
||
SECRET=your_secret_here
|
||
|
||
# 客服账号 ID，在企业微信管理后台 - 微信客服 - 客服账号 详情页查看
|
||
OPEN_KFID=wkxxxxxxxxxxxxx
|
||
|
||
# --- 回调配置（可选，仅接收实时消息时需要）---
|
||
# 自定义 3-32 位字符串，与后台配置的回调 Token 一致
|
||
CALLBACK_TOKEN=my_token_123
|
||
|
||
# 企业微信后台随机生成的 43 位 EncodingAESKey
|
||
CALLBACK_AES_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||
|
||
# --- 数据库配置 ---
|
||
# 格式: postgresql+asyncpg://用户名:密码@主机:端口/数据库名
|
||
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/wechat_kf
|
||
```
|
||
|
||
**数据库连接字符串** 格式：
|
||
```
|
||
postgresql+asyncpg://用户名:密码@主机地址:端口/数据库名
|
||
```
|
||
如果需要修改用户名、密码、主机或数据库名，直接改这个连接字符串即可。
|
||
|
||
### 3. 安装依赖并启动
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
python run.py
|
||
```
|
||
|
||
访问 http://localhost:8000 即可看到聊天界面。
|
||
|
||
---
|
||
|
||
## CALLBACK_TOKEN 和 CALLBACK_AES_KEY 的使用
|
||
|
||
这两个参数用于 **微信回调消息的加解密**，只在需要接收实时消息推送时才需要配置。
|
||
|
||
### 配置流程
|
||
|
||
1. 登录 [企业微信管理后台](https://work.weixin.qq.com)
|
||
2. 进入 **微信客服** → 选中客服账号 → **开发配置**
|
||
3. 在回调配置中：
|
||
- **Token**：自定义填一个 3-32 位字符串（如 `my_token_123`），同时写入 `.env` 的 `CALLBACK_TOKEN`
|
||
- **EncodingAESKey**：点击"随机生成"，得到一个 **43 位字符串**，填入 `.env` 的 `CALLBACK_AES_KEY`
|
||
- **回调 URL**：填写 `https://你的域名/webhook`（见下方本地测试方案）
|
||
4. 保存后微信会立刻发送 GET 请求到回调 URL 进行验证
|
||
|
||
### 如果不配回调
|
||
|
||
不配回调不影响以下功能：
|
||
- 点击页面的 **"同步拉取"** 按钮主动轮询获取消息
|
||
- 在页面中 **发送消息** 给客户
|
||
|
||
---
|
||
|
||
## 本地测试方案
|
||
|
||
回调模式要求 URL 必须是 **公网 HTTPS**。本地开发可以用以下工具：
|
||
|
||
### ngrok（推荐）
|
||
|
||
```bash
|
||
# 安装 ngrok 并启动
|
||
ngrok http 8000
|
||
|
||
# 会得到一个公网 URL，例如 https://abc123.ngrok.io
|
||
# 在微信管理后台填入 https://abc123.ngrok.io/webhook 即可
|
||
```
|
||
|
||
### 其他方案
|
||
|
||
| 方案 | 说明 |
|
||
|------|------|
|
||
| **ngrok** | 免费，一行命令，推荐 |
|
||
| **frp** | 需要一台有公网 IP 的服务器 |
|
||
| **localhost.run** | `ssh -R 80:localhost:8000 localhost.run` |
|
||
| **部署到公网服务器** | 直接部署到有 HTTPS 的服务器 |
|
||
|
||
### 不配回调也能测试
|
||
|
||
即使没有公网地址，也可以：
|
||
1. 启动应用 → 打开页面 → 点击 **"同步拉取"** 获取历史消息
|
||
2. 在输入框输入内容 → 点击 **"发送"** 主动给客户发消息
|
||
3. 这是**轮询模式**，不需要公网、不需要回调配置
|