《从零给 QQ 挂一个 AI 机器人》系列 · 第 1 篇共 2 篇作者AVA环境国内云服务器Ubuntu Docker Compose AstrBot 4.28.2 NapCat⚠️看之前先注意两件事本文里所有 IP / QQ 号 / token 都替换成了占位符你照着做时换成自己的。另外第 6 节那个坑会直接把机器人搞掉线建议先扫一眼再动手。这套东西到底由几个部分组成第一次搭 QQ 机器人最容易懵的就是「AstrBot 和 NapCat 是什么关系为什么要装两个容器」一句话说清分工NapCat 协议端。手机 QQ 能聊天靠的是腾讯的私有协议NapCat 的作用就是把这套协议翻译成标准的 HTTP / WebSocket 接口。它本身不含任何 AI 能力也完全不懂你说的话是什么意思。AstrBot 大脑。它接收消息、调大模型、决定回什么再把要发的内容交回给协议端。两者之间用OneBot v11这个事实标准通信——这也是为什么 NapCat 不止能配 AstrBot换别的框架同样能用。连接方式为什么选「反向 WebSocket」OneBot v11 有两种连法方向正好相反方式谁主动连谁适用场景正向 WS框架 → NapCat框架和协议端在同一台机器、网络简单反向 WSNapCat → 框架推荐。协议端主动连框架只需开个端口等着我们选反向配置上更省事AstrBot 当服务端监听6199NapCat 当客户端主动连过来。⚠️ 这里有个关键细节连的地址要写容器名而不是 IP——ws://astrbot:6199/ws因为两个容器在同一个 Docker 网络里Docker 内置的 DNS 能把容器名解析成 IP。写死 IP 的话容器重建换 IP 就断。部署核心是一份docker-compose.ymlservices:astrbot:image:soulter/astrbot:latestcontainer_name:astrbotrestart:unless-stoppedports:-127.0.0.1:6185:6185# WebUI只绑本机volumes:-./astrbot/data:/AstrBot/datanapcat:image:mlikiowa/napcat-docker:latestcontainer_name:napcatrestart:unless-stoppedenvironment:-TZAsia/Shanghai-WEBUI_TOKEN你自己的-token-ACCOUNT机器人的QQ号# ← 别省见第 6 节-QQ_APP_ARGS--no-sandboxports:-127.0.0.1:6099:6099# NapCat WebUI只绑本机volumes:-./napcat/QQ:/app/.config/QQ# 登录态 设备指纹删了就重新扫码-./napcat/config:/app/napcat/config-./napcat/logs:/app/napcat/logs两个restart: unless-stopped是必须的——服务器重启后要能自己拉起来不能依赖任何人的电脑开着。打开管理界面SSH 隧道注意上面两个端口都写的是127.0.0.1:xxxx不是0.0.0.0。这是故意的管理界面公网碰不到只能走隧道进去。ssh-L6185:127.0.0.1:6185-L6099:127.0.0.1:6099 root你的服务器IP然后本地浏览器开http://localhost:6185。⚠️隧道只影响「你能否打开管理界面」跟机器人本身无关——关掉隧道机器人照样 24 小时在线。踩坑合辑这几个都是实测撞过的按顺序排① 国内服务器装 Docker 会失败curl: (35) Recv failure: Connection reset by peerget.docker.com在国内基本连不上。换清华源mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu如果正好是腾讯云机器https://mirror.ccs.tencentyun.com这个内网加速器更快但只在腾讯云内网可用。② AstrBot 没有默认密码了老教程里写的astrbot / astrbot早就没了新版启动时会生成一个随机强密码只在启动日志里打印一次。第一次部署记得先看一眼日志再关窗口dockercompose logs astrbot|head-60忘了也不至于重装——去data/cmd_config.json里删掉dashboard下面那六个凭据字段重启会重新生成。③ 用 FinalShell 粘贴长命令会吃掉结尾docker-compose-plugin粘上去变成docker-compose-plugi然后 apt 报Unable to locate package。报「找不到包」时先怀疑这个别去折腾源。长命令拆成两条敲。④ Windows 上写.bat启动脚本窗口一闪就关罪魁祸首是和在 cmd 里是重定向符。echo里想输出尖括号必须写成^^否则脚本静默死掉——不报错、不暂停、直接消失。另外.bat里有中文要用 GBK 存CMD 默认 936 代码页但用 VS Code 这种 UTF-8 编辑器打开会显示乱码看着像没写完。最省事的做法是脚本里干脆别用中文。⑤ WebSocket 死活连不上先确认 AstrBot 侧监听地址是0.0.0.0而不是127.0.0.1容器里的127.0.0.1是它自己别的容器连不进来再确认端口号两边一致。 第 6 节重建 NapCat 容器 QQ 掉线 腾讯风控这是全文最值钱的一段也是踩得最惨的一段。改完docker-compose.yml执行docker compose up -d容器被重建不是重启。启动日志变成了这样正在快速登录 机器人QQ号 快速登录错误 你的用户身份已失效为保证账号安全请你重新登录。快速登录不行就转扫码。扫码之后[Core] [Login] 二维码已被扫描等待确认... [Core] [Login] Login Error , ErrInfo: [1,{account:...,serverErrorCode:168, message:你的账号近期存在安全风险部分功能使用受限 请登录最新手机QQ并根据提示恢复账号使用。}]机器人彻底离线。为什么会这样腾讯把「容器重建」识别成了一次新设备 / 新环境登录直接触发账号级风控。错误码 168 是账号被限制不是你的配置写错了。所以在服务器上怎么改配置都绕不过去。别去翻 NapCat 和 AstrBot 的文档浪费一晚上。唯一的解法机主亲自在最新版手机 QQ 上登录这个机器人账号按提示走完安全验证短信 / 人脸之类然后回来重新扫一次码。⚠️ 注意这里有个坑缓存的登录票据已经作废了所以快速的「免扫码登录」那条路回不来必须重新扫码。第一遍扫大概率还是 168那是风控没解除不是操作错了。两个经验能不重建容器就不重建。真要改 NapCat 的配置先想清楚会不会触发重建并且跟能立刻做手机验证的人约好时间——不然机器人就挂在那儿了。ACCOUNT环境变量一定要配。不配的话容器重启时 NapCat 不知道要登哪个号会退化成无参启动白白多一步。配上之后日志里会显示「正在快速登录 QQ号」省心很多。最后一句实话云服务器的 IP 上登录 QQ被风控是常态不是你做错了什么。真要做长期稳定的机器人用一个养过一段时间、有正常使用记录的老号比什么配置优化都管用。怎么算部署成功看到这一行就通了[Core] [INFO] [aiocqhttp.aiocqhttp_platform_adapter:107]: aiocqhttp(OneBot v11) 适配器已连接。然后拿另一个QQ 号私聊机器人能正常回复整条链路就闭环了。补充 ①自己起个小标题留给你写两三句话就行——比如你为什么要搭这个机器人、原本打算让它干什么。写不出来就把这一整节删掉不影响阅读。补充 ②自己起个小标题留给你写这个坑里你当时的反应或者你机器上遇到的不一样的地方。本系列共 2 篇下一篇02 给它装一双手 —— 让机器人自己下载文件、还能发回给你代码与环境基于 AstrBot 4.28.2 实测有问题欢迎评论区交流。