{"id":278,"date":"2026-10-29T16:52:13","date_gmt":"2026-10-29T08:52:13","guid":{"rendered":"https:\/\/dfwce.cn\/?p=278"},"modified":"2026-11-01T21:31:30","modified_gmt":"2026-11-01T13:31:30","slug":"%e7%94%a8-astrbot-napcat-%e6%8a%8a%e5%a4%a7%e6%a8%a1%e5%9e%8b%e6%8e%a5%e5%85%a5-qq","status":"publish","type":"post","link":"https:\/\/dfwce.cn\/?p=278","title":{"rendered":"\u7528 AstrBot + NapCat \u628a\u5927\u6a21\u578b\u63a5\u5165 QQ"},"content":{"rendered":"
\n
注意：下面这套东西不要用自己的主号跑，有被封的风险。用小号。<\/strong><\/div>\n
\n

1. 项目介绍<\/h2>\n

现在大模型的 API 很便宜，搭一个能上 QQ 的机器人成本不高，就想着自己做一个试试。<\/p>\n

整体是三层：<\/p>\n

\n
QQ 客户端（手机）\n    ↓ 扫码登录\n协议端（NapCat \/ SnowLuma）   ← 登录 QQ，把协议翻译成 OneBot 标准接口\n    ↓ WebSocket（OneBot v11）\nAstrBot                       ← 接消息、调模型、管人格\n    ↓ HTTP\n大模型 API<\/code><\/pre>\n<\/div>\n
说人话<\/strong>：<\/p>\n
    \n
  • 协议端<\/strong>：让一个程序能以 QQ 号的身份登录，收发消息。没有它，AstrBot 拿不到 QQ 的消息。<\/strong><\/li>\n
  • AstrBot<\/strong>：拿到消息之后干什么——调模型、发回复。<\/li>\n
  • QQ 客户端<\/strong>：用来跟机器人聊天、扫码登录。<\/li>\n<\/ul>\n
    协议端有两个选择，NapCat<\/strong> 和 SnowLuma<\/strong>，功能一样，选一个就行。<\/p>\n
    \n
    2. AstrBot<\/h2>\n
    AstrBot 是一个支持插件、多平台的大模型机器人框架。<\/p>\n
      \n
    • GitHub：https:\/\/github.com\/AstrBotDevs\/AstrBot<\/li>\n
    • 文档：https:\/\/astrbot.app\/<\/li>\n<\/ul>\n
      2.1 基础安装<\/h3>\n
      Docker 一条命令：<\/p>\n
      \n
      docker run -d --name astrbot \\\n  --network host \\\n  -v \/www\/wwwroot\/astrbot\/data:\/AstrBot\/data \\\n  soulter\/astrbot:latest<\/code><\/pre>\n<\/div>\n
      --network host<\/code> 是为了省掉端口映射的麻烦，后面协议端连它的时候直接用 127.0.0.1<\/code>。<\/p>\n
      起来之后浏览器打开 http:\/\/服务器IP:6185<\/code>。<\/p>\n\n
      2026-10-31 修正：<\/strong>上面这句只在你把 6185 放行到公网的条件下才成立。后来我把这个做法改了——6185 和 6099 都不要对公网开<\/strong>，走 SSH 隧道进来：ssh -N -L 16185:127.0.0.1:6185 用户名@服务器IP<\/code>，然后开 127.0.0.1:16185<\/code>。理由在《把大肥鱼搬上腾讯云》第三节。<\/div>\n
      默认账号密码<\/strong>在容器日志里：<\/p>\n
      \n
      docker logs astrbot 2>&1 | grep -i password<\/code><\/pre>\n<\/div>\n
      登进去第一件事：改密码<\/strong>。<\/p>\n
      2.2 配置模型<\/h3>\n
      AstrBot 里叫「服务提供商」。进「配置 → 服务提供商 → 新增」：<\/p>\n
      \n
      类型      OpenAI 兼容\nAPI Base  https:\/\/api.deepseek.com\/v1\nAPI Key   你的 key\n模型      deepseek-chat<\/code><\/pre>\n<\/div>\n
      保存之后在「默认模型」里选中它。<\/p>\n
      2.3 配置 QQ 平台<\/h3>\n
      「配置 → 平台 → 新增」：<\/p>\n
      \n
      类型            aiocqhttp\n名称            napcat\n反向 WS 主机     0.0.0.0\n反向 WS 端口     6199\nToken           （留空，或者跟协议端填一致）<\/code><\/pre>\n<\/div>\n
      这里有个坑<\/strong>：6199<\/code> 是 AstrBot 的 OneBot 反向 WS 端口<\/strong>，不是 6185<\/code>。<\/p>\n
      6185<\/code> 是给人看的 WebUI，6199<\/code> 才是给协议端连的。<\/p>\n
      保存之后重启：<\/p>\n
      \n
      docker restart astrbot<\/code><\/pre>\n<\/div>\n
      \n
      3. NapCatQQ<\/h2>\n
      NapCat 是基于 TypeScript 的 QQ 协议端，把 QQ 协议转成 OneBot 标准接口。<\/p>\n
        \n
      • GitHub：https:\/\/github.com\/NapNeko\/NapCatQQ<\/li>\n
      • 文档：https:\/\/napneko.github.io\/<\/li>\n<\/ul>\n
        3.1 安装<\/h3>\n
        \n
        docker run -d --name napcat \\\n  --network host \\\n  -e NAPCAT_GID=0 \\\n  -v \/www\/wwwroot\/napcat\/config:\/app\/napcat\/config \\\n  -v \/www\/wwwroot\/napcat\/qq:\/app\/.config\/QQ \\\n  mlikiowa\/napcat-docker:latest<\/code><\/pre>\n<\/div>\n
        -e NAPCAT_GID=0<\/code> 那句的意思是让容器里跑出来的文件属主跟着 root 走。但宿主机那两个挂载目录的属主也得对得上，否则 NapCat 读不到登录态，表现是「每次重启都让你重新扫码」——十个里有九个会当成风控，其实是权限。<\/p>\n\n
        两个挂载点很关键<\/strong>：<\/p>\n
        \n
        config  协议配置（OneBot 连接信息）\nqq      登录态（不挂的话容器重启就要重新扫码）<\/code><\/pre>\n<\/div>\n
        3.2 扫码登录<\/h3>\n
        \n
        docker logs napcat 2>&1 | tail -40<\/code><\/pre>\n<\/div>\n
        日志里会打印一个字符画的二维码，或者告诉你二维码图片存在哪：<\/p>\n
        \n
        二维码已保存到 \/app\/napcat\/cache\/qrcode.png<\/code><\/pre>\n<\/div>\n
        拷出来：<\/p>\n
        \n
        docker cp napcat:\/app\/napcat\/cache\/qrcode.png .\/qrcode.png<\/code><\/pre>\n<\/div>\n
        用手机 QQ 扫，然后手机上点「确认登录」。<\/strong><\/p>\n
        第一次登录可能触发设备验证（短信或者好友辅助），这个是正常的。<\/p>\n
        3.3 连接 AstrBot<\/h3>\n
        NapCat 的 WebUI 在 http:\/\/服务器IP:6099<\/code>。<\/p>\n
        网络配置 → 新建 → WebSocket 客户端<\/strong>：<\/p>\n
        \n
        名称        astrbot\nURL         ws:\/\/127.0.0.1:6199\/ws\n重连间隔     30000\n启用心跳     是<\/code><\/pre>\n<\/div>\n
        保存之后看 AstrBot 的日志：<\/p>\n
        \n
        docker logs -f astrbot<\/code><\/pre>\n<\/div>\n
        连上会打印类似这样：<\/p>\n
        \n
        [aiocqhttp] 1234567890\/你的昵称: 你好<\/code><\/pre>\n<\/div>\n
        前面是 QQ 号，后面是昵称。能刷出这行就是通了。<\/strong><\/p>\n
        \n
        4. SnowLuma<\/h2>\n\n
        SnowLuma 是另一个 QQ 协议端。功能和 NapCat 一样——把 QQ 变成 OneBot v11，AstrBot 那头一行都不用改。<\/p>\n\n
        但后来我把它换成了默认。<\/strong>换的理由不是功能，是它走的路子不一样；而那个路子，恰好更抗踢。<\/p>\n\n
        4.1 它和 NapCat 差在哪<\/h3>\n\n
        先把一个常见的误传说掉：两个都在跑真的 QQ。<\/strong>不是「一个用协议、一个用客户端」，两个都是 NTQQ 的客户端，一个不少。<\/p>\n\n
        NapCat 跑的是一个拆掉了显示层的 QQ。<\/strong>Shell 模式自己把 NTQQ 引擎拉起来（loadQQWrapper<\/code>，启动时带 --no-sandbox<\/code>），只是不渲染窗口。它拿消息走两条路：调 QQ 内部的 Node 模块，以及 Hook 原生包——登录时抓数据库密码用的就是后面这条。官网那句「天生无头、不依赖 Electron、内存 50~100MB」是真的，省掉的正是渲染和显示那一层。<\/p>\n\n
        SnowLuma 跑的是一个原样的 QQ。<\/strong>镜像里装了 Linux QQ，容器起来先把 QQ 拉起来，配 Xvfb 开出虚拟显示，再往 QQ 进程里注入 hook，读它已经解析好的内部数据包，翻成 OneBot v11。它不省任何一层。<\/p>\n\n
        区别就在这一句：NapCat 拆掉显示层去跑 QQ，SnowLuma 原样跑 QQ。<\/strong><\/p>\n\n
        那为什么拆掉显示层会更容易掉线？我的理解是：风控判断的不是「你发了什么」，是「这个设备像不像一个正常人在用」。SnowLuma 那边，登录是在真 QQ 的界面里扫的，会话由原装客户端自己维持，渲染进程、显示层、心跳全是 QQ 自己的——它和一个坐在电脑前的人没有区别。NapCat 把这些拆了，只留引擎和消息通道。<\/p>\n\n
        我不敢说这就是它更稳的全部原因。账号本身的质量、常用地、发消息的节奏，影响可能都比协议端大得多。但在我这台机器上，换过去之后确实没再出现过那种「日志显示在线、消息发不出去」的状态。<\/p>\n\n
        吃内存这件事也能对上。SnowLuma 是真的在跑一个完整的 QQ：渲染进程、Xvfb、VNC 一个不少，单账号 300MB 起，多开能到 1.2G。NapCat 那 50~100MB 省掉的，省的就是这些。<\/p>\n\n
        还有一个顺带的差别，是扫码。NapCat 把二维码打进日志<\/strong>，你得 docker logs<\/code> 里捞、或者 docker cp<\/code> 出来再扫。SnowLuma 是 noVNC 网页远程桌面<\/strong>：你看到的是真的 QQ 登录窗口，鼠标点上去扫。<\/p>\n\n
        4.2 安装<\/h3>\n\n
        \n
        docker run -d --name snowluma \\\n  --network host \\\n  --restart unless-stopped \\\n  -e TZ=Asia\/Shanghai \\\n  -v \/www\/wwwroot\/snowluma\/data:\/app\/data \\\n  <镜像名><\/code><\/pre>\n<\/div>\n\n
        镜像名以它 Releases 页面上写的为准。它的发行包分 full 和 lite：full 自带 Node 运行时，lite 要你机器上本来就有 Node 22 以上。Docker 镜像走的是 full 那一套，这点不用你操心。<\/p>\n\n
        别用 latest<\/code><\/strong>——协议端发版快，某次拉到坏版本，表现就是「某天开始老掉线」，而且你根本不会想到是镜像的问题。<\/p>\n\n
        它有四个端口，一个都别混：<\/p>\n\n