116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# ncatbot-webhook-plugin
|
||
|
||
NcatBot 插件，对外暴露 HTTP 接口，接收外部消息转发至 QQ。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装依赖
|
||
uv sync
|
||
|
||
# 复制环境变量并填写
|
||
cp .env.example .env
|
||
# 编辑 .env，至少设置 WEBHOOK_API_KEY
|
||
|
||
# 启动
|
||
uv run python -m ncatbot
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 必填 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `WEBHOOK_API_KEY` | 否 | 自动生成 | API 鉴权密钥，未设置时自动生成 UUIDv4 并打印到启动日志 |
|
||
| `WEBHOOK_HOST` | 否 | `0.0.0.0` | 监听地址 |
|
||
| `WEBHOOK_PORT` | 否 | `8081` | 监听端口 |
|
||
| `UPLOAD_DIR` | 否 | `./uploads` | 上传文件保存目录 |
|
||
| `MAX_UPLOAD_SIZE` | 否 | `20971520` | 单文件最大字节数（默认 20 MB） |
|
||
| `ALLOWED_EXTENSIONS` | 否 | 空（不限） | 允许的扩展名，逗号分隔，如 `jpg,png,pdf` |
|
||
| `QQ_API_TIMEOUT` | 否 | `10` | QQ API 超时秒数 |
|
||
| `QQ_API_MAX_RETRIES` | 否 | `2` | QQ API 失败重试次数 |
|
||
|
||
## 接口说明
|
||
|
||
所有接口均需通过 `Authorization: Bearer <KEY>` 或 `X-API-Key: <KEY>` 鉴权。
|
||
|
||
### GET /healthz
|
||
|
||
健康检查，无需鉴权。
|
||
|
||
```json
|
||
{"status": "ok", "health": "ok"}
|
||
```
|
||
|
||
### POST /webhook
|
||
|
||
发送 QQ 消息。
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"type": "text",
|
||
"group_id": "123456",
|
||
"msg": "Hello!"
|
||
}
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `type` | 否 | 消息类型：`text`（默认）、`image`、`file`、`video` |
|
||
| `group_id` | 二选一 | 群号 |
|
||
| `user_id` | 二选一 | QQ 号（私聊） |
|
||
| `msg` | text 时必填 | 文本内容 |
|
||
| `url` | image/file/video 时必填 | 资源链接 |
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{"status": "ok"}
|
||
```
|
||
|
||
**错误响应：**
|
||
|
||
```json
|
||
{"status": "error", "error": "invalid json", "code": 400}
|
||
```
|
||
|
||
### POST /upload
|
||
|
||
上传文件到服务器，供后续消息引用。
|
||
|
||
**请求：** `multipart/form-data`，字段名不限，每个文件部分需带 `filename`。
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"files": ["photo.jpg"],
|
||
"path": "photo.jpg"
|
||
}
|
||
```
|
||
|
||
`files` 为相对路径（文件 ID），`path` 为单文件时的快捷字段。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── main.py # 入口，组装并启动服务
|
||
├── config.py # 配置（环境变量）
|
||
├── middleware.py # 鉴权 & 请求 ID 中间件
|
||
├── response.py # 统一响应格式
|
||
├── handlers/
|
||
│ ├── health.py # /healthz
|
||
│ ├── message.py # /webhook 消息发送
|
||
│ └── upload.py # /upload 文件上传
|
||
├── .env.example # 环境变量模板
|
||
└── pyproject.toml # 依赖声明
|
||
```
|
||
|
||
## 内网部署建议
|
||
|
||
- 放在 Nginx/Caddy 后面，启用 HTTPS 和限流
|
||
- 用 systemd 管理进程，配置 `EnvironmentFile=.env`
|
||
- 日志默认输出到 stdout，可由 systemd/journald 收集
|