清风微凉 Notes

Search

SearchSearch

01-overview

May 26, 2026, 6 min read

01. 概念与整体架构

目标

在自己的服务器上部署一个个人 QQ 聊天助手。

它不是公开运营机器人，定位是个人/小群使用：

  • 私聊可以直接对话。
  • 群聊默认只在 @机器人 时回复。
  • 底层模型先用 DeepSeek，复杂任务可以切到 ChatGPT/CPA。
  • 后台端口只对自己的公网 IP 开放。

实际架构

[ QQ 私聊 / 群聊 ]
        |
        v
[ NapCatQQ ]
  - 登录个人 QQ
  - 收发 QQ 消息
  - 通过 WebSocket Client 把消息发给 LangBot
        |
        | ws://qqbot-langbot:2280/ws
        v
[ LangBot ]
  - 管理机器人
  - 管理流水线
  - 管理触发条件
  - 调用 OpenAI 兼容模型
        |
        | http://172.17.0.1:3000/v1
        v
[ New API ]
  - 统一模型网关
  - token、日志、分组、渠道
        |
        +--> DeepSeek 渠道：deepseek-chat
        |
        +--> CPA / ChatGPT 渠道：gpt-5.4 / gpt-5.5 等

组件职责

组件职责
NapCatQQQQ 协议端，负责扫码登录个人 QQ、接收和发送消息
LangBot聊天机器人平台，负责机器人、流水线、触发规则、上下文、模型调用
New API模型网关，统一 DeepSeek、CPA、ChatGPT 等渠道
DeepSeek日常聊天底层模型，优先使用 deepseek-chat
CPA可作为 ChatGPT/Claude/Gemini 等上游渠道，适合高级分析或备用

NapCatQQ 是什么

NapCatQQ 可以理解为“QQ 侧的接线员”。

它负责把一个真实 QQ 账号登录到服务器上，然后把 QQ 里的事件转换成程序能处理的消息：

群里有人发：@神盾局特工26号 你好
        |
        v
NapCat 收到 QQ 群消息
        |
        v
转换成 OneBot 消息事件
        |
        v
通过 WebSocket 发给 LangBot

它也负责把 LangBot 生成的回复发回 QQ：

LangBot 生成回复：频道已接入。26 号在线。
        |
        v
NapCat 调用 QQ 发送消息
        |
        v
群里看到机器人回复

所以 NapCat 不负责“思考”，也不负责调用大模型。它更像 QQ 到机器人系统之间的网关。

典型例子：

  • 登录 QQ 小号。
  • 接收私聊消息。
  • 接收群消息和 @。
  • 接收图片、表情、文件等消息事件。
  • 把机器人回复发回 QQ。
  • 给 LangBot 提供 OneBot v11 连接。

LangBot 是什么

LangBot 可以理解为“机器人中枢”。

它不直接登录 QQ，而是接收 NapCat 转过来的消息，然后决定：

  • 这条消息要不要回复。
  • 用哪条流水线处理。
  • 用哪个模型。
  • 带不带上下文。
  • 套用什么人设提示词。
  • 最终把什么文本发回去。

流程大概是：

NapCat 发来消息事件
        |
        v
LangBot 判断触发条件
        |
        v
匹配到 qq bot 流水线
        |
        v
调用 New API 的 deepseek-chat
        |
        v
拿到回复后发回 NapCat

典型例子：

  • 设置“群聊只有 @ 才回复”。
  • 设置“普通消息走 DeepSeek”。
  • 设置“/gpt 前缀走 ChatGPT/CPA”。
  • 设置“神盾局特工 26 号”的人设提示词。
  • 查看对话日志。
  • 管理插件、知识库、长期记忆等扩展能力。

简单说：

NapCat 负责 QQ 连接。
LangBot 负责机器人逻辑。
New API 负责模型网关。
DeepSeek / CPA 负责真正生成回答。

为什么不让 LangBot 直接接 DeepSeek

可以直接接 DeepSeek，但本次更推荐接 New API：

LangBot -> New API -> DeepSeek

好处：

  • New API 可以统一看调用日志。
  • 可以给 QQ Bot 单独创建 token。
  • 可以限制额度。
  • 可以随时切换 DeepSeek / ChatGPT / CPA。
  • 后续做多模型路由更方便。

端口规划

端口服务是否需要公网开放
6099NapCat WebUI需要，但只对白名单 IP
5300LangBot WebUI需要，但只对白名单 IP
2280-2285LangBot OneBot 适配端口不需要公网开放，同机 Docker 内部访问
5400/5401LangBot plugin runtime不需要公网开放
3000New API视使用场景，至少服务器内可访问
8317CPA视使用场景，New API 可访问即可

风险边界

个人 QQ 机器人有风控风险。

建议：

  • 不要使用主力 QQ。
  • 不要群发、刷屏、主动私聊陌生人。
  • 群聊只在 @机器人 时回复。
  • 后台端口只允许自己的公网 IP。
  • 不公开保存 NapCat 的 QQ 登录态。

Graph View

Backlinks