把大模型接进 QQ 群，新手最常见的失败方式是把所有东西塞进一个进程里：协议、逻辑、模型全糊在一起，坏了都不知道从哪查。AstrBot 加 NapCat 的组合正好相反——职责切干净，每层单独验证。NapCat 负责 QQ 协议侧的收发，把消息通过 OneBot v11 接口交出去；AstrBot 负责逻辑侧，管模型、人设、插件和 MCP。两层各自有 Web 管理页，本文按端口 6185（AstrBot）与 6099（NapCat）展开。
分层的意义：排障按层走
职责分开后，故障定位变成固定的排查链：群里没反应，先看 NapCat 是否在线掉线；NapCat 在线但 AstrBot 收不到消息，查 OneBot 链路配置；消息到了但 AI 不回，查模型提供商的 Key 与配额；回复内容不对，才轮到人设与插件配置。四层各查各的，互不干扰。很多人在这一步就输在架构上——不是技术不会，是出了问题没有排查路径。
Docker 一次拉起两套服务
Windows 11 上用 PowerShell 执行一键脚本，脚本自动完成 Docker 检查、目录创建、拉取编排文件并启动容器；Linux 侧就是建目录、下载 compose 文件、docker compose -f astrbot.yml up -d 三步。容器起来后先别配任何东西，验证两个 Web 页面都能打开——6185 和 6099 各自可访问，才说明部署层正常。
NapCat 首次进入要 Token，部署控制台会打印；手快清了日志就用容器日志捞：
docker logs napcat | Select-String "Token"
然后 NapCat 登录 QQ 账号完成授权，在 OneBot 配置里把上报地址指向 AstrBot 的 ws 端口。验证标志很简单：AstrBot 的会话列表里出现群消息，链路即通。这一步的常见坑是反向 WS 地址写错协议头——ws:// 开头而非 http://，以及容器网络下要用容器名而非 localhost 互访。
接模型、人设与插件
模型侧以 DeepSeek 为例：在 AstrBot 的提供商配置里填 API Key、选模型、保存后用自带的测试对话验证。人设决定了机器人在群里的说话风格，写清角色边界和回复长度能显著减少无效输出。插件市场按需装，MCP 支持让机器人获得外部工具能力——比如挂一个火车票查询的 MCP 服务，群里直接问车次就能返回结构化结果。
每加一层能力都单独验证：模型通了再配人设，人设对了再上插件，插件稳了再挂 MCP。一口气全配上再排障，等于自己把分层优势拆掉。
公网维护与安全边界
人在外网时要维护管理页，走内网穿透把 6185 暴露出去。这里必须划一条安全线：AstrBot 管理页能改模型 Key、能装插件、能看全部群消息，属于高权限入口。穿透隧道必须叠认证，NapCat 的 6099 则尽量不暴露——协议层被攻击者拿到，等于 QQ 会话被劫持。条件允许的话用带身份验证的反向代理或零信任组网方案，比裸端口映射稳得多。
最后一层验证回到群里发一条真实消息，观察回复延迟与内容质量。整条链 QQ 协议、消息转发、模型调用、工具扩展各安其位，后续加任何新能力，都只是往某一层里添东西，而不是推倒重来。
评论0