【NapCat】搭建自己的QQ消息推送服务器

目录

1、Docker 一键启动 NapCat

2、登录QQ帐号

3、开启 HTTP API（实现 Webhook 调用）

3.1 WebUI 侧边栏 → 网络配置 → 新增 HTTP服务

3.2 重启服务生效

4、接口调用示例（对标飞书 Webhook，POST 发消息）

4.1 示例 1：Python 发送 QQ 群消息（运维告警）

4.2 示例 2：curl 命令直接调用（脚本内使用）

4.3 示例 3：发送私聊消息

5、docker-compose 持久化部署（推荐长期使用）

6、常见问题 & 避坑指南

7、优缺点总结

8、完整封装代码

9、cmd测试

10、替代方案但是镜像下载不了

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:latest

3、开启 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 napcat

4、接口调用示例（对标飞书 Webhook，POST 发消息）

宿主机端口映射：3100:3000 接口基准地址：

http://服务器IP:3100

# 请求头必须携带鉴权：Authorization: Bearer 你设置的AccessToken

Authorization: Bearer Rjw.kBmuLKNCJXS6

4.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、常见问题 & 避坑指南

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