81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
# 本地调试说明
|
||
|
||
## 1. 启动开发环境
|
||
|
||
```bash
|
||
./run-dev.sh
|
||
```
|
||
|
||
- 前端：<http://localhost:3000>（管理页、登录等）
|
||
- 后端：<http://localhost:8000>（API）
|
||
- `.env` 会被自动加载，可配置 `WECHAT_UPSTREAM_BASE_URL`、`KEY` 等
|
||
|
||
## 2. 账号 key 与消息接收
|
||
|
||
- 登录页使用的 **key** 需要与后端「消息接收」使用同一 key，否则收不到该账号消息。
|
||
- 在 `.env` 中设置 **`KEY=你的key`**（或 `WECHAT_WS_KEY=你的key`、`WS_KEY=你的key`），与登录时填的 key 一致即可。
|
||
|
||
## 3. 消息接收：WS 与回调两种方式
|
||
|
||
### 不设 CALLBACK_BASE_URL（默认，适合本地）
|
||
|
||
- 不配置 `CALLBACK_BASE_URL` 时，后端用 **WebSocket** 连接 7006 的 GetSyncMsg 拉取消息。
|
||
- 7006 若拒绝 WS，日志会出现 `WS disconnected ... server rejected WebSocket`，消息可能收不到，但不影响登录、发消息、联系人等接口调试。
|
||
|
||
### 使用回调（7006 主动 POST 到本机）
|
||
|
||
- 7006 在公网，无法直接访问你本机的 `localhost`，需要先用 **ngrok** 把本机 8000 暴露到公网，再设回调。
|
||
|
||
**一键用 ngrok 调通（推荐）：**
|
||
|
||
1. **先配置 ngrok**（仅首次）：ngrok 需登录并配置 authtoken，否则会报 `ERR_NGROK_4018`。
|
||
- 打开 https://dashboard.ngrok.com/get-started/your-authtoken 复制 token
|
||
- 执行：`ngrok config add-authtoken <你的token>`
|
||
2. **终端 1**：执行
|
||
```bash
|
||
./run-ngrok.sh
|
||
```
|
||
脚本会启动 `ngrok http 8000`，并把得到的公网隧道地址自动写入 `.env` 的 `CALLBACK_BASE_URL`（不会把 signup/dashboard 等链接误写成回调地址）。
|
||
|
||
2. **终端 2**：启动服务
|
||
```bash
|
||
./run-dev.sh
|
||
```
|
||
后端启动时会读取 `CALLBACK_BASE_URL` 并向 7006 注册 SetCallback，新消息会由 7006 POST 到你的 ngrok 地址。
|
||
|
||
3. 打开 <http://localhost:3000> 登录，用同一 key 收发消息即可验证回调是否生效。
|
||
|
||
**手动步骤（不用脚本时）：**
|
||
|
||
1. 终端运行 `ngrok http 8000`，记下输出的 **https** 地址（如 `https://xxxx.ngrok-free.app`）。
|
||
2. 在 `.env` 中增加或修改：`CALLBACK_BASE_URL=https://xxxx.ngrok-free.app`。
|
||
3. 执行 `./run-dev.sh`（若已在运行则重启）。之后新消息由 7006 POST 到 `https://xxxx.ngrok-free.app/api/callback/wechat-message`，不再走 WS。
|
||
|
||
## 4. 手动模拟回调（不暴露公网也可测接口）
|
||
|
||
不跑隧道时，可直接用 curl 测回调接口是否正常：
|
||
|
||
```bash
|
||
# 替换成你的 key
|
||
curl -X POST 'http://localhost:8000/api/callback/wechat-message?key=HBpEnbtj9BJZ' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"MsgList":[{"FromUserName":"wxid_test","Content":"你好","MsgType":1}]}'
|
||
```
|
||
|
||
返回 `{"ok":true}` 且后端无报错即表示回调入口和 `_on_ws_message` 逻辑正常。
|
||
|
||
## 5. 查看日志
|
||
|
||
- 后端：`backend/data/logs/app.log`（或控制台）
|
||
- 搜索 `SetCallback`、`callback/wechat-message`、`WS disconnected` 等便于排查消息接收问题。
|
||
|
||
## 6. 只调试后端 API
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
cd "$(dirname "$0")"
|
||
uvicorn backend.main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
再用浏览器或 Postman 访问 <http://localhost:8000/docs> 调试接口。
|