简介：这份资源是一套基于服务器/虚拟主机实现的QQ云端免挂发信API方案，面向需要长期自动发送QQ消息、又不想保持本地挂机的开发者或站长。它通过将机器人逻辑部署在云端，配合简单配置即可实现24小时在线收发消息，适合自动回复、定时任务、消息推送等常驻场景。压缩包共11个文件，体积仅42KB，以6个PHP核心接口脚本为主，辅以使用教程、必看说明两份txt文档，另含菜单、CSS样式及指定回复配置，结构精简，便于直接上传部署并二次修改。目前已有205人学习下载，对于刚接触云服务API或想低成本搭建轻量机器人的用户来说，是一份能快速上手的参考实现，既包含基础接入指引，也展示了简单的消息回复处理流程。虽然当前功能偏向基础，但可作为进一步扩展关键词触发、多类型消息或接入其他服务的起点。
1. 云端免挂QQ机器人到底省了什么：先说清发信API的边界
做了三年QQ机器人，被问得最多的不是"怎么写一个机器人"，而是"能不能不挂着电脑、不掉线、不每天扫码"。QQ云端免挂智能机器人云端发信API，本质就是把原来跑在手机或者PC里的协议客户端整个挪到云服务器上，让QQ号在云端保持在线，然后对外开放一个HTTP接口，任何业务方只要拿Token调一下，就能替你往指定群或个人发消息。相比传统方案里"电脑开着QQ才能触发命令"的做法，这套架构最大的价值是把机器人和业务解耦了——机器人只是一个稳定的发信通道，你的业务逻辑可以放在任何地方。
适合谁来用？如果你在做客服通知、群管理辅助、定时消息、或者想把QQ消息对接进自己的监控系统，这套方案能省掉一台常开的电脑和无数次"家里停电就失联"的焦虑。但要先说清楚边界：它解决的是"发消息"和"保持在线"，不解决"账号违规被限制"这种协议层的根本风险。接下来我会按架构、部署、API实现、避坑、进阶的顺序，把这套东西从零到一讲透。
2. 云端免挂的架构拆解：为什么机器人服务与发信API要分开
2.1 免挂的本质：协议客户端上云，会话不落地
所谓"免挂"，不是绕过QQ校验，而是把原本在你手机里运行的QQ协议交互层，换成可以在Linux服务器上跑的协议端程序。这个程序用QQ的现有登录方式（扫码或密码）拿到会话凭证，在云端维持在线状态。它做的事和安卓QQ底层做的事几乎一样：接收消息、发送消息、上报状态。区别是它没有图形界面，只暴露WebSocket端口或HTTP接口给上层调用。
这里要理解一个关键点：会话凭证存在哪。传统挂机方式里，凭证存在手机本地，QQ号跟着SIM卡和设备走；云端方案把凭证存在服务器的数据目录里，于是QQ号不再依赖任何物理设备，这就是"免挂"的本质。代价是，一旦服务器把凭证误删、或者账号被风控判定为异地常用设备，就会要求重新扫码验证。后文会专门讲怎么降低这种风险。
2.2 发信API放哪一层：HTTP接口与事件回调的选型
很多人把"发信API"想成一个集成在协议端里的功能，实际做的时候不推荐这么干。主流协议端提供的是事件上报和调用接口，你可以直接调它的HTTP接口发消息，但这会让业务方和协议端耦合太深——协议端升级、改端口、限流策略变化，都会直接影响你的业务。更稳的做法是在协议端外面单独包一层发信服务，它对外提供统一风格的REST API，对内对接协议端的调用接口。
选型上，我一般会这么做：协议端只负责维持QQ在线和收发消息；发信服务负责Token鉴权、参数校验、限流、重试和日志。这样业务方看到的是一个干净的POST /api/send，永远不碰协议端细节。协议端一旦换实现，比如从A框架换成B框架，发信服务内部只需要改一个适配模块，对外API保持不变。这就是分层的意义。
2.3 最小可跑架构：一条消息从调用方到QQ群的完整路径
用一个具体场景穿起来：你的监控系统检测到服务异常，要通过QQ群报警。请求路径是这样的：
监控系统 -> POST https://你的域名/api/send (带Token和消息内容) -> 发信服务校验Token、查限流 -> 发信服务再调用协议端的私聊/群发接口 -> 协议端通过WebSocket长连接把消息交给QQ服务器 -> QQ服务器下发到群成员会话这里每一步都可能出问题：Token校验失败、协议端不在线、被限流、消息违法被吞。所以发信服务必须能拿到协议端的在线状态和返回值，并且把错误码翻译成调用方能看懂的结果。比如协议端返回"消息被风控"，发信API就应该明确告诉调用方"这条没发出去，原因是被限制"，而不是返回一个通用的500让调用方乱猜。
3. 先把机器人端跑起来：Docker部署协议端与登录保活
3.1 协议端选型：轻量级实现与官方客户端的差别
做云端机器人，最常见的框架选项是go-cqhttp、NapCat、Lagrange等这一类开源实现。它们不是腾讯官方产品，而是社区基于QQ协议逆向出来的兼容层。选的时候我的优先级是：维护活跃度 > 协议稳定性 > 资源占用 > 部署复杂度。目前我会优先看NapCat和Lagrange这类偏向轻量、支持Docker的方案，go-cqhttp虽然经典，但维护频率已经不如以前，新协议变更时反应较慢。
不要选那种"一键整合"的桌面版机器人，它们通常把协议端、脚本、控制面板揉在一起，看着省事，但在云端场景下升级一个组件就可能全部翻车。云端部署，我建议只保留纯协议端，业务逻辑全放在自己的发信API里。这样将来换协议端，只需要重新配置发信通道。
3.2 用Docker拉起协议端：一条命令与关键挂载参数
以目前常见的NapCat Docker镜像为例，最简洁的启动方式大概是这样（不同镜像的细节略有差异，但思路一致）：
docker run -d \ --name qq-bot-protocol \ -p 8080:8080 \ -p 6099:6099 \ -v /opt/qq-bot/config:/app/config \ -v /opt/qq-bot/data:/app/data \ -e MODE=ws \ -e WS_PORT=6099 \ --restart=always \ napcat/napcat:latest这段命令做了四件事：后台启动容器、把8080端口暴露给管理接口、把6099暴露给WebSocket事件上报、把配置和数据目录挂载到宿主机。--restart=always是必须的，否则服务器一重启，你的QQ机器人就再也不会自动上线。MODE=ws表示使用WebSocket模式向外推送事件，发信API也需要主动连这个WebSocket来获取在线状态和事件。
数据目录挂载是重中之重。协议端的登录凭证、设备信息都写在data目录里，如果不挂载到宿主机，容器一删你的QQ号就要重新扫码。很多人的机器人"每次重启都要扫码"，就是忽略了这一步。配置文件挂载则让你可以在宿主机上直接改端口、改心跳间隔，而不用进容器。
3.3 登录、扫码与心跳保活：掉线率最高的三个原因
首次启动后，协议端会生成一个登录二维码，通常在管理页面上能看到，或者在日志里输出二维码的转义内容。你需要在电脑上用QQ客户端扫码，确认登录。这一步完成之后，协议端会保存凭证。后面只要data目录不丢，就不需要频繁扫码。
但"不用扫码"不等于"永不掉线"。掉线的原因里，最常见的是心跳失败。很多协议端有内置心跳包，默认间隔可能偏长。建议把心跳间隔调低到30到60秒，同时开启心跳包回复检测。具体参数一般在配置文件里，例如：
{ "heartbeatInterval": 30, "heartbeatRetryTimes": 3 }另一个掉线原因是网络出口变化。云服务器的IP段经常被QQ风控盯得很紧，登录成功后尽量不要更换服务器地区。如果条件允许，选择一个IP池更干净的机房，可以显著降低"秒掉线"的概率。这不是玄学，是很多做云端机器人的人用真金白银换来的血泪经验。
4. 用Python写一个云端发信API：带鉴权与超时的最小实现
4.1 接口设计：发送消息的请求体、响应体与错误码
发信API的职责只有一个：接收业务方的请求，把消息发到指定QQ群或个人。所以接口要尽量简单。我常用的是这样：
POST /api/send Authorization: Bearer <token> Content-Type: application/json请求体长这样：
{ "target_type": "group", "target_id": "123456789", "message": "警报：服务异常，请及时处理" }target_type只有两个取值：group或private。target_id是要发到的群号或QQ号。message是文本内容，如果将来要发图片，可以先加一个type字段扩展，不要在一开始设计一堆复杂字段。
响应体要区分"调用成功"和"消息送达成功"两个概念。发信服务只能保证"协议端成功接收了请求"，不保证"对方真的看到了"。所以响应体我通常这样设计：
{ "code": 0, "message": "ok", "data": { "message_id": "abc123" } }当协议端返回风控错误时，发信服务应该把这个错误转换成业务能理解的code，比如code: 43001表示"消息被风控拦截"。
4.2 对接协议端的核心代码：从HTTP到WebSocket的桥接
协议端本身提供了HTTP调用接口（例如监听http://127.0.0.1:8080/send_msg），发信API只需要把业务请求转换成协议端需要的参数。这里给出一个最小Python实现，使用Flask和requests库：
import requests from flask import Flask, request, jsonify app = Flask(__name__) PROTOCOL_ENDPOINT = "http://127.0.0.1:8080/send_msg" @app.route("/api/send", methods=["POST"]) def send_message(): auth = request.headers.get("Authorization", "") if auth != "Bearer " + app.config["API_TOKEN"]: return jsonify({"code": 401, "message": "unauthorized"}), 401 payload = request.get_json() target_type = payload.get("target_type") target_id = payload.get("target_id") message = payload.get("message") if not target_id or not message: return jsonify({"code": 400, "message": "missing params"}), 400 # 构造协议端参数 proto_params = { "user_id": int(target_id), "message": message, } if target_type == "group": proto_params["group_id"] = int(target_id) proto_params.pop("user_id") try: resp = requests.post(PROTOCOL_ENDPOINT, json=proto_params, timeout=5) result = resp.json() except requests.exceptions.Timeout: return jsonify({"code": 504, "message": "protocol timeout"}), 504 if result.get("status") == "ok": return jsonify({"code": 0, "message": "ok", "data": result.get("data")}) else: return jsonify({"code": 500, "message": result.get("message")}), 502 app.run(host="0.0.0.0", port=5000)这里的核心逻辑是：先做Token鉴权，再校验参数，然后调用协议端接口。注意timeout=5必不可少，否则协议端假死时，你的API也会跟着卡死。Authorization头的比较用的是简单的恒定字符串，生产环境建议用签名机制，后面会讲。
这个API的边界很清楚：它不负责处理消息事件，也不维护会话状态，只负责"发出去"。你可以把它部署在协议端的同一台服务器上，也可以单独部署。只要网络能通，两者不一定要同机。实际部署中，我倾向于让发信API和协议端在同一台私有网络内，避免公网暴露协议端端口。
4.3 顺手加上消息队列：高并发下避免发信被限流
如果调用方会在短时间狂发几十条消息，直接同步调协议端接口会有两个问题：一是协议端处理不过来，接口会超时；二是触发QQ风控，消息秒被拦截。所以我通常在发信API和协议端之间加一个简单的内存队列，把发送请求异步化。不必引入消息中间件，用Python的queue.Queue就能解决大部分场景：
import queue import threading send_queue = queue.Queue(maxsize=200) def worker(): while True: proto_params = send_queue.get() try: requests.post(PROTOCOL_ENDPOINT, json=proto_params, timeout=5) except Exception: pass finally: send_queue.task_done() threading.Thread(target=worker, daemon=True).start()在API请求中，不再直接requests.post，而是把proto_params丢进队列：
send_queue.put(proto_params) return jsonify({"code": 0, "message": "accepted"})这样API调用方收到的是"已接受"，消息由后台线程慢慢投递。注意maxsize=200是个保护阀，队列满了就直接返回429，不要无限堆积。队列的设计省去了复杂的分发逻辑，也让接口响应时间稳定在几十毫秒。
5. 避坑手册：云端免挂QQ机器人的5个高发翻车点
5.1 现象：登录后秒掉线，提示账号异常
刚部署完，扫码登录成功还没过一分钟，协议端就显示下线，后台日志里出现login_validate或account_protected之类的错误。
原因：云服务器IP被QQ风控标记为高风险，尤其是新建的头几次登录，容易触发异地登录保护。另一个常见原因是同IP下有多个QQ号先后登录，触发批量注册/挂机检测。
解决：先把协议端的数据目录清理干净，换一个相对宽松的时段重新尝试登录；如果仍然秒掉，就换机房IP，或者换一台新服务器。不要在同一IP下同时跑超过2个机器人账号。这一步没有银弹，只能排查。经验是，成熟机房的IP段比小厂VPS稳定得多，这钱值得花。
5.2 现象：发信接口偶发超时，重启后恢复
API调用时好时坏，偶尔报504，重启发信服务后又能正常几分钟。
原因：协议端的HTTP接口本身性能有限，长时间运行后内存泄漏或者连接未释放。很多协议端的HTTP服务是单线程模型，前一个请求卡住，后面全部排队。
解决：在发信API里把调用协议端的并发数限制在1到2个，同时给每次请求设置更短的连接重试机制。更省心的做法是定期重启协议端容器，比如写个cron每天凌晨4点重启一次，把内存泄漏风险降到最低。我用了一年多，这条能挡住绝大多数"莫名失联"问题。
5.3 现象：API被刷，QQ号被临时封禁
发信API暴露到公网后，没做限流，被脚本喊话机器人疯狂调用，导致QQ号在短时间内发出大量消息，被平台临时限制。
原因：Token泄露或者Token校验太弱。还有不少人直接用了协议端自带的未鉴权端口，等于把发送能力裸奔。
解决：三层防护必须做。第一层，API必须强校验，不要用固定字符串，至少用HMAC签名；第二层，给每个target_id做独立限流，比如同一群每秒最多1条，超出直接429；第三层，在协议端前面再加一层IP白名单，只有发信API的IP能访问协议端端口，公网一律拒绝。另外，建议把协议端的管理接口和发送接口分开，管理接口不要绑到公网。
5.4 现象：服务器重启后机器人失联，需要重新扫码
明明设置了--restart=always，服务器重启后容器也起来了，但发消息提示"机器人未登录"。
原因：容器启动时，协议端没有正确加载data目录里的登录凭证，或者因为非正常退出导致凭证文件损坏。还有可能是容器启动顺序有问题，比如挂载的宿主机目录还没就绪。
解决：确认挂载的是绝对路径，且目录权限足够。容器启动后，立刻看日志里有没有加载凭证成功的记录。我给所有容器增加了--stop-timeout=15，避免强制杀容器时损坏凭证文件。如果确实损坏，只能重新扫码，这是最难防的坑。所以记得定期备份data目录中的关键凭证文件。
5.5 现象：多个QQ号共用API，消息串号
用同一个发信API服务管理两个QQ号，A业务方发送的消息，莫名其名跑到了B号的名下。
原因：发信API里没有区分协议端的实例。当你有多个协议端容器时，你的PROTOCOL_ENDPOINT如果写死成一个，消息当然只往那一个容器发。协议端之间不互通，消息就发错号了。
解决：在发信API的配置里加入"目标账号"概念，请求体增加一个可选的bot_id字段，发信服务根据bot_id路由到对应协议端的API地址。或者更简单：每个QQ号部署一套独立的发信服务，端口隔离，互不干扰。对小规模使用，后者更省心。
6. 进阶：把发信API做成带状态的服务与验证技巧
6.1 用Redis保存会话状态与消息频率
基础版发信API是无状态的，重启后所有计数器清零。这会导致限流失效——比如同一个群每秒限1条，API重启后计数器归零，调用方就能钻空子刷一波。我一般在发信服务里挂一个Redis，把每个target_id的限流计数和上一次发送时间存进去。示例伪代码：
import redis r = redis.Redis(host='localhost', port=6379, db=0) def rate_limit(target_id): key = f"rate:{target_id}" current = r.get(key) if current and int(current) > 5: return False r.incr(key) r.expire(key, 60) return True这里的5次/60秒只是个示例，实际值要看你的场景。群通知类消息一天没几条，没必要给那么高；营销类才需要高一点，但QQ风控也不会容忍太高。建议从低频开始调，稳定后再逐步放宽。
6.2 验证接口是否真的"云端免挂"：三个检查点
做完以上所有步骤，不要急着接到业务里。先用三个检查点验证这套系统确实是"云端免挂"且"发信可用"。
第一，断点验证。把你的电脑彻底关机，只用手机流量访问服务器上的发信API，调用一条群消息，确认能收到。这一步验证了机器人不依赖任何本地设备。
第二，重启验证。docker restart qq-bot-protocol，等待30秒后再调一次发信API。如果不需要重新扫码，说明凭证持久化成功；如果失联，就要回去查data目录挂载。
第三，限流验证。用脚本连续调用10次同样参数的消息，确认后5次都返回429或504，而不是崩溃或无限接收。这一步能直观看出限流是否生效。
6.3 一个长期运行的技巧：时刻关注协议端升级
开源协议端的生命周期往往取决于社区维护，而QQ协议变化会频繁导致旧版本失效。我见过太多人部署完就丢在那儿，几个月后突然不能用了，一查是协议端版本太旧，QQ服务器已经不再兼容。所以我的习惯是：每两周去看一下所用协议端的发布动态，看到协议更新，先在测试容器里拉新镜像跑通，再切生产。如果不方便频繁升级，至少订阅它的发布通知，别等到翻车才后悔。
这套"云端免挂+发信API"的架构，我从单账号监控通知一路做到多账号业务消息分发，最大的教训就是：别让业务逻辑住在协议端里，也别让一个API裸奔在公网上。按上面的架构，协议端只做连接，发信API只做转发，限流鉴权当第一道防线，运行半年下来，除了几次账号主动认怂被风控之外，还真的没出过什么需要半夜爬起来修的故障。希望帮到你。
本文还有配套的精品资源，点击获取
