【NapCat】搭建自己的QQ消息推送服务器
·
目录
3.1 WebUI 侧边栏 → 网络配置 → 新增 HTTP服务
4、接口调用示例（对标飞书 Webhook，POST 发消息）
4.1 示例 1：Python 发送 QQ 群消息（运维告警）
5、docker-compose 持久化部署（推荐长期使用）
1、Docker 一键启动 NapCat
docker run -d \
-e NAPCAT_GID=$(id -g) \
-e NAPCAT_UID=$(id -u) \
-p 3300:3000 \
-p 3301:3001 \
-p 6099:6099 \
--name napcat \
--restart=always \
mlikiowa/napcat-docker:latest端口说明：
6099：WebUI 管理后台（登录扫码、开启 HTTP 接口）
3000/3001：OneBot HTTP/WS 接口端口
注意：云服务器需要放行端口：安全组 / 防火墙放行：3000、3001、6099，否则外网无法访问后台和调用接口
2、登录QQ帐号
浏览器访问：http://服务器IP:6099/webui
默认密码：napcat 登录后台
docker logs --tail 100 napcat
选择二维码登录，用闲置小号 QQ 扫码（不建议常用主号），确认 Linux 设备登录
这个是不需要后台去看登录账户密码，你直接设置好,注意下面的密码不是我的
docker rm -f napcat
docker run -d \
-e NAPCAT_GID=$(id -g) \
-e NAPCAT_UID=$(id -u) \
-e WEBUI_TOKEN="MyNapCat123456" \
-e TZ=Asia/Shanghai \
-v /etc/localtime:/etc/localtime:ro \
-v /opt/napcat_data:/app/.config/QQ \
-v /opt/napcat_config:/app/napcat/config \
-p 3100:3000 \
-p 3101:3001 \
-p 6099:6099 \
--name napcat \
--restart=always \
mlikiowa/napcat-docker:latest3、开启 HTTP API（实现 Webhook 调用）
3.1 WebUI 侧边栏 → 网络配置 → 新增 HTTP服务
配置参数：
- HTTP Server：启用
- 名称：随便取名字
- Host：0.0.0.0
- Port：3000 容器内部的，部署映射出去的3300
- 启用CORS：开启
- 消息格式：Array
- Token：使用默认生成的 后续调用接口鉴权用，例如
abc123456）
3.2 重启服务生效
docker restart napcat4、接口调用示例（对标飞书 Webhook，POST 发消息）
宿主机端口映射：3100:3000
接口基准地址：
http://服务器IP:3100# 请求头必须携带鉴权：Authorization: Bearer 你设置的AccessToken
Authorization: Bearer Rjw.kBmuLKNCJXS64.1 示例 1：Python 发送 QQ 群消息（运维告警）
import requests
base_url = "http://你的服务器IP:3100"
token = "abc123456" # 刚才自定义的AccessToken
group_id = 123456789 # 目标QQ群号
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
# 发送文本告警
data = {
"group_id": group_id,
"message": "【服务告警】订单接口异常，请立即排查！"
}
resp = requests.post(f"{base_url}/send_group_msg", json=data, headers=headers)
print(resp.json())4.2 示例 2：curl 命令直接调用（脚本内使用）
curl -X POST http://IP:3100/send_group_msg \
-H "Authorization: Bearer abc123456" \
-H "Content-Type:application/json" \
-d '{
"group_id": 123456789,
"message": "定时任务执行失败！"
}'4.3 示例 3：发送私聊消息
接口路径 /send_private_msg，参数替换 user_id 为对方 QQ 号即可。
5、docker-compose 持久化部署（推荐长期使用）
新建 docker-compose.yml
version: "3"
services:
napcat:
image: mlikiowa/napcat-docker:latest
container_name: napcat
restart: always
environment:
NAPCAT_UID: ${UID}
NAPCAT_GID: ${GID}
ports:
- "3100:3000"
- "3101:3001"
- "6099:6099"
volumes:
- ./qq_data:/app/.config/QQ # 持久化QQ登录信息，不用重复扫码启动命令：
UID=$(id -u) GID=$(id -g) docker compose up -d优势：重启容器不会丢失登录状态，不用反复扫码。
6、常见问题 & 避坑指南
- 调用接口返回 401 AccessToken 写错，或请求头
Bearer后有多余空格，核对 WebUI 里的密钥。 - 消息发不出去、无报错
- 机器人 QQ 号在目标群内，且没有被禁言
- 新登录 QQ 有风控冷却，等待 5-10 分钟再发消息
- 主号挂机风险极高 务必注册小号专用挂机，一旦触发腾讯风控会限制账号登录。
- 和飞书机器人迁移成本 只需要修改请求 URL、请求头、JSON 字段，业务告警脚本几乎不用重构。
7、优缺点总结
私有部署，无第三方平台暂停服务、额度限制
标准 HTTP 接口，CI/CD、监控脚本、定时任务均可对接
免费永久自用，一次部署长期运行
❌ 缺点：
需要一台常驻服务器运行容器（低配置轻量机器即可）
需要自备闲置 QQ 小号挂机，有轻微账号风控风险
8、完整封装代码
import requests
from typing import Optional, Dict
class AlertNotifier:
def __init__(
self,
# 飞书配置
feishu_webhook: str = "",
# NapCat QQ配置
napcat_api: str = "http://127.0.0.1:3100",
napcat_token: str = "",
target_group_id: int = 0
):
self.feishu_webhook = feishu_webhook
self.napcat_api = napcat_api
self.napcat_token = napcat_token
self.group_id = target_group_id
def send_feishu(self, title: str, content: str) -> Dict:
"""发送飞书卡片消息，兼容原有告警格式"""
payload = {
"msg_type": "text",
"content": {
"text": f"【告警】{title}\n{content}"
}
}
resp = requests.post(self.feishu_webhook, json=payload, timeout=10)
return resp.json()
def send_qq_group(self, title: str, content: str) -> Dict:
"""NapCat 发送QQ群消息，替代飞书"""
headers = {
"Authorization": f"Bearer {self.napcat_token}",
"Content-Type": "application/json"
}
url = f"{self.napcat_api}/send_group_msg"
payload = {
"group_id": self.group_id,
"message": f"【告警】{title}\n{content}"
}
resp = requests.post(url, json=payload, headers=headers, timeout=10)
return resp.json()
def send_alert(self, title: str, content: str, use_qq: bool = False) -> Dict:
"""统一入口：一行调用，自由切换渠道"""
if use_qq:
return self.send_qq_group(title, content)
else:
return self.send_feishu(title, content)
# ==================== 使用示例 ====================
if __name__ == "__main__":
notifier = AlertNotifier(
# 填入你的飞书webhook
feishu_webhook="https://open.feishu.cn/open-apis/bot/v2/hook/xxx",
# NapCat 配置
napcat_api="http://你的服务器IP:3100",
napcat_token="你在NapCat后台设置的AccessToken",
target_group_id=12345678 # QQ群号，纯数字
)
# 1. 原有逻辑：发飞书（无需改动原有业务调用代码）
notifier.send_alert(
title="数据库连接异常",
content="订单库查询超时，耗时>5s，请运维检查"
)
# 2. 切到QQ推送，只多加一个参数 use_qq=True
notifier.send_alert(
title="数据库连接异常",
content="订单库查询超时，耗时>5s，请运维检查",
use_qq=True
)9、cmd测试
curl -X POST http://199.28.10.135:3100/send_group_msg ^
-H "Authorization: Bearer akn7aHghuGyde1n1" ^
-H "Content-Type: application/json" ^
-d "{\"group_id\":797549442,\"message\":\"CMD测试QQ消息推送正常\"}"10、替代方案但是镜像下载不了
docker run -d \
--name lagrange-onebot \
--restart=always \
-e TZ=Asia/Shanghai \
-v /etc/localtime:/etc/localtime:ro \
-v /etc/timezone:/etc/timezone:ro \
-p 3100:8080 \
-v /opt/lag_data:/app/data \
lagrangedev/lagrange.onebot:latest
openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构
更多推荐
9
0- 0
已为社区贡献2条内容
所有评论(0)