QQ Bot Push

一个轻量 QQ 机器人推送服务。它通过 QQ 机器人官方 API 获取 Access Token，连接 WebSocket Gateway，并支持多机器人、定时发送、QQ 单聊（C2C）和群聊消息推送。Cron 解析仅使用 robfig/cron 这一项运行依赖。

启动

$env:APP_ID = "你的 AppID"
$env:APP_SECRET = "你的 AppSecret"
go run .

程序会自动读取当前目录的 config.json。也可以通过 -c config.json、--config config.json 或 CONFIG_FILE 指定配置文件。打开 http://127.0.0.1:5606/ 使用管理页面。机器人、账户、目标和定时任务数据默认分别保存在 data/bots.json、data/account.json、data/targets.json、data/schedules.json。

机器人内部 ID 从 1 开始单调递增。旧版随机 ID 会在首次启动新版程序时自动迁移，并同步更新已有推送目标的 bot_id。通过管理页面或 POST /api/bots 添加机器人时，服务会先调用 QQ 官方 AccessToken 接口校验 app_id 和 app_secret，校验成功后才保存。

首次启动若没有 data/account.json，默认登录账号为 admin，密码为 admin；登录后请立即在“账户设置”修改密码。也可以通过 admin_username / admin_password 或环境变量 ADMIN_USERNAME / ADMIN_PASSWORD 预置初始账号。旧版本仍未修改过的默认账户 a12345 / a123456789 会自动迁移为 admin / admin。

默认只监听本机回环地址。若要开放到局域网或公网，请配合反向代理启用 HTTPS，并立即修改默认登录密码。

HTTP API

网页登录后的管理接口只使用 HttpOnly 会话 Cookie，不再兼容旧版 admin_token。业务推送接口和 OneBot v11 接口使用账户设置中创建的 API Key。

# 添加机器人
Invoke-RestMethod http://localhost:5606/api/bots -Method Post -ContentType 'application/json' -Body '{"name":"通知机器人","app_id":"你的AppID","app_secret":"你的AppSecret"}'

# 添加目标；bot_id 为机器人管理页中的机器人 ID，qq_number 只是显示/调用映射，openid 才是 QQ 官方 API 的真实目标
Invoke-RestMethod http://localhost:5606/api/targets -Method Post -ContentType 'application/json' -Body '{"bot_id":"机器人ID","name":"管理员","kind":"c2c","qq_number":"123456789","openid":"用户OpenID"}'

# 推送文本
# 业务系统请使用账户设置中生成的 API Key（推荐使用下面的 OpenAPI 路径）
Invoke-RestMethod http://localhost:5606/api/openapi/v1/push/private -Method Post -Headers @{'X-Notice-OpenAPI-Key'='qbp_你的APIKey'} -ContentType 'application/json' -Body '{"bot_id":"机器人ID","target":"123456789","content":"服务已恢复"}'

管理页面模块

• 概览：已接入机器人数量、运行中的机器人数量、目标数量和 Gateway 状态。
• 机器人 Bot：添加、启用、停用、删除机器人，并可独立启动或关闭每个机器人的 Gateway。
• 消息推送：选择 API Key、机器人和绑定 QQ 号的目标；页面同时提供 OpenAPI 请求示例。
• 定时发送：创建标准五字段 Cron 周期任务，或指定一个未来时间执行一次；可编辑、启停和删除任务，并查看下次执行及最后结果。Cron 使用 Asia/Shanghai（UTC+8）时区。
• 账户设置：修改网页登录密码、创建和撤销 API Key。

API Key 只在创建时完整显示一次，服务端只保存哈希。推送接口支持 X-Notice-OpenAPI-Key、X-API-Key，也支持 Authorization: Bearer <API_KEY>。

Gateway 仅用于接收 QQ 事件和自动发现目标。启用时，用户给机器人发送私聊消息后，服务会保存该用户的 OpenID，并使用事件 msg_id 被动回复 OpenID。关闭 Gateway 后不会保持 WebSocket 连接，但机器人仍可向已经保存的 OpenID 执行 HTTP、OpenAPI 和 OneBot 推送。添加机器人时可以选择是否立即启动 Gateway，也可以在机器人管理页随时切换。

私聊推送接口：POST /api/openapi/v1/push/private

群聊推送接口：POST /api/openapi/v1/push/group

通用推送接口：POST /api/openapi/v1/push（根据目标类型匹配）

请求字段：bot_id、target、content。target 可以填写目标 ID、绑定的 QQ 号、OneBot ID 或 QQ 官方 OpenID。

GET /healthz 不需要认证，适合健康检查。QQ 平台是否允许主动消息、频率限制以及 OpenID 获取方式以官方文档和机器人后台权限为准。

注意：QQ 机器人开放 API 使用 user_openid / group_openid，不是普通 QQ 号。需要先在 QQ 开放平台事件或管理端获取对应 OpenID。当前服务支持文本和 Markdown 两种消息类型。

OneBot v11 HTTP 兼容

服务可作为 OneBot v11 HTTP API 的兼容接收端，支持：

• GET/POST /send_private_msg
• GET/POST /send_group_msg
• GET/POST /send_msg
• application/json、application/x-www-form-urlencoded 和 URL 查询参数
• 字符串消息，以及仅含 text 类型的消息段数组

QQ 官方机器人 API 不认识普通 QQ 号，因此 OneBot 请求里的 user_id / group_id 必须映射到已经保存的 OpenID。添加目标时填写可选的 onebot_id；也可以直接把目标自身的 id 或 OpenID 放入 OneBot 请求的 ID 字段。

# OneBot v11 JSON 请求
Invoke-RestMethod http://localhost:5606/send_private_msg -Method Post -Headers @{'X-Notice-OpenAPI-Key'='qbp_你的APIKey'} -ContentType 'application/json' -Body '{"user_id":123456789,"message":"服务已恢复","auto_escape":false}'

认证使用 X-Notice-OpenAPI-Key: <API_KEY>，也可使用 X-API-Key 或 Authorization: Bearer <API_KEY>。不再使用登录密码或旧版 admin_token。返回采用 OneBot v11 的 status、retcode、data.message_id 格式。QQ 官方接口当前只转发文本，因此图片、语音、at 等非 text 消息段会返回不支持。

WebSocket 在线与自动发现用户

启动后服务会连接 QQ Gateway，并订阅 GROUP_AND_C2C_EVENT (1<<25)。管理页面应显示“Gateway 已连接”。用户给机器人发送单聊消息后，服务会从 C2C_MESSAGE_CREATE 事件中读取 user_openid，自动加入推送目标。

若显示 4014 intent 无权限，需要在 QQ 开放平台为机器人申请或启用群与单聊事件权限。程序必须持续运行，QQ 客户端才会显示机器人服务已连接。

Tag 发布

推送任意 Git tag 会触发 .github/workflows/release.yml，自动运行测试并发布：

• qbot-push-linux-amd64.tar.gz
• qbot-push-linux-arm64.tar.gz
• qbot-push-windows-amd64.zip
• SHA256SUMS
• ghcr.io/crossgg/qbot-push:<tag> 多架构 Docker 镜像
• ghcr.io/crossgg/qbot-push:latest

例如：

git tag 1.0.0
git push origin 1.0.0

容器默认监听 5606，并将账户、机器人、目标和定时任务数据保存在 /data：

docker run -d --name qbot-push --user 1026:100 -p 5606:5606 -v ${PWD}/data:/data ghcr.io/crossgg/qbot-push:latest

也可以使用仓库中的 docker-compose.yml。该文件默认使用群晖用户 1026:100；Ubuntu 可改用文件中已注释的 1001:1001 配置。

最终容器基于 scratch，只包含静态二进制、HTTPS 所需的 CA 根证书和可写的 /data。镜像默认使用非 root UID/GID 65532，Compose 配置会根据宿主机覆盖该用户。