ncatbot-webhook-plugin
NcatBot 插件，对外暴露 HTTP 接口，接收外部消息转发至 QQ。
快速开始
# 安装依赖
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
健康检查，无需鉴权。
{"status": "ok", "health": "ok"}
POST /webhook
发送 QQ 消息。
请求体：
{
"type": "text",
"group_id": "123456",
"msg": "Hello!"
}
| 字段 | 必填 | 说明 |
|---|---|---|
type |
否 | 消息类型：text（默认）、image、file、video |
group_id |
二选一 | 群号 |
user_id |
二选一 | QQ 号（私聊） |
msg |
text 时必填 | 文本内容 |
url |
image/file/video 时必填 | 资源链接 |
成功响应：
{"status": "ok"}
错误响应：
{"status": "error", "error": "invalid json", "code": 400}
POST /upload
上传文件到服务器，供后续消息引用。
请求： multipart/form-data，字段名不限，每个文件部分需带 filename。
成功响应：
{
"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 收集