QQSafeChat：基于 NapCat + DeepSeek 的 Ubuntu QQ 智能回复机器人

Myth2265742472
3 阅读6分钟

项目简介

QQSafeChat 是一个运行在 Ubuntu 系统上的 QQ 自动回复机器人，基于 NapCat 框架接入 QQ 消息收发，通过 DeepSeek 大模型生成智能回复。支持私聊自动回复、群聊 @ 回复、多人群切换、消息上下文记忆、回声消除等功能，并提供一键安装脚本和 systemd 服务管理，部署简单，开箱即用。

功能特性

  • 私聊自动回复：智能应答好友私聊消息，支持白名单过滤
  • 群聊 @ 回复：在群聊中被 @ 时自动回复，支持群白名单
  • 大模型驱动：接入 DeepSeek API，也可切换 OpenAI、硅基流动等兼容接口
  • 消息上下文记忆：每个会话独立存储历史记录，支持连续对话
  • 多人群切换：预设多种聊天人格（话痨、粘人、温柔等），支持自定义
  • 回声消除：自动过滤自己发出的消息，避免死循环
  • 多消息分割：支持同时发送多条消息，模拟真人发条回复
  • 随机回复延迟：1-3 秒随机延迟，回复行为更自然
  • 管理命令：!ping、!status、!help 等命令在线管理
  • WebUI 管理：NapCat 自带 Web 管理界面，可查看状态、管理配置
  • 一键安装脚本：全自动部署，无需手动操作
  • systemd 服务：支持开机自启、自动重启

系统架构

QQSafeChat 的整体架构由四个核心模块组成：手机 QQ 扫码登录、NapCat 桥接层（OneBot 协议）、QQSafeChat 机器人主程序（bot_main）以及 DeepSeek LLM API。数据流为：QQ 消息 → NapCat WebSocket → bot_main → LLM API → 回复发送。

所需环境

硬件要求

组件要求
操作系统Ubuntu 22.04 / 24.04（64 位）
内存≥ 4GB
网络能访问 GitHub 和 DeepSeek API
架构x86_64

软件依赖

  • 运行环境：Python 3.8+，Node.js 18+
  • 系统包：zip、unzip、jq、curl、xvfb、screen、g++、libnss3、libgbm1、libasound2
  • Python 包：requests、websocket-client
  • 核心组件：Linux QQ 3.2.23、NapCat 最新版

安装部署

方法一：一键安装（推荐）

# 解压安装包
unzip QQSafeChat-Ubuntu.zip
cd QQSafeChat-Ubuntu
赋予执行权限并运行一键安装脚本
chmod +x install.sh
sudo bash install.sh

安装脚本会自动完成以下操作：

  1. 安装系统依赖包
  2. 安装 Linux QQ 3.2.23 兼容版本
  3. 下载并编译 NapCat（含 napcat-linux-launcher）
  4. 安装 QQSafeChat 及其 Python 依赖
  5. 创建 systemd 服务（napcat.service + qqsafechat.service）

方法二：手动安装

1. 安装系统依赖

sudo apt update && sudo apt install -y zip unzip jq curl xvfb screen g++ python3 python3-pip libnss3 libgbm1 libasound2

2. 安装 Linux QQ

# 下载兼容版本 (3.2.23)
wget https://dldir1.qq.com/qqfile/qq/QQNT/9a841627/linuxqq_3.2.23-44343_amd64.deb
sudo dpkg -i linuxqq_3.2.23-44343_amd64.deb
sudo apt install -f -y

3. 安装 NapCat

sudo mkdir -p /opt/napcat && cd /opt/napcat
sudo wget https://github.com/NapNeko/NapCatQQ/releases/latest/download/NapCat.Shell.zip
sudo unzip -o -d napcat NapCat.Shell.zip
sudo wget https://raw.githubusercontent.com/NapNeko/napcat-linux-launcher/refs/heads/main/launcher.cpp
sudo g++ -shared -fPIC launcher.cpp -o libnapcat_launcher.so -ldl

4. 安装 QQSafeChat

sudo mkdir -p /opt/QQSafeChat && cd /opt/QQSafeChat
sudo cp -r /path/to/QQSafeChat/* .
sudo pip3 install -r requirements.txt
sudo mkdir -p history personas

启动服务

首次登录

NapCat 启动后会产生二维码图片，使用手机 QQ 扫码登录：

# 启动 NapCat（后台运行）
cd /opt/napcat
nohup ./launcher.sh > /dev/null 2>&1 &
查看二维码
ls /opt/napcat/napcat/cache/qrcode.png
或通过 WebUI 扫码
浏览器访问 http://服务器IP:6099/webui?token=YOUR_TOKEN

启动 QQSafeChat

# 确保 NapCat 已经启动并登录成功
# 然后启动机器人
cd /opt/QQSafeChat
nohup python3 bot_main.py > /dev/null 2>&1 &

使用 systemd 服务管理

# 启动
sudo systemctl start napcat
sudo systemctl start qqsafechat
开机自启
sudo systemctl enable napcat
sudo systemctl enable qqsafechat
查看状态
sudo systemctl status napcat
sudo systemctl status qqsafechat
查看日志
journalctl -u napcat -f
journalctl -u qqsafechat -f

配置说明

修改方法

所有配置通过编辑 JSON 文件完成，修改后重启服务生效。

DeepSeek API 配置

编辑 /opt/QQSafeChat/settings/openai.json：

{
  "provider": "deepseek",
  "api_key": "your_deepseek_api_key_here",
  "base_url": "https://api.deepseek.com",
  "model": "deepseek-v4-flash",
  "temperature": 0.6
}

参数说明：

参数说明默认值
providerLLM 供应商（deepseek/openai/siliconflow/mock）deepseek
api_keyAPI 密钥必填
base_urlAPI 地址api.deepseek.com
model模型名称deepseek-v4-flash
temperature回复随机性（0-1）0.6

机器人配置

编辑 /opt/QQSafeChat/config.json：

{
  "napcat_ws_url": "ws://127.0.0.1:3001",
  "napcat_http_url": "http://127.0.0.1:3000",
  "napcat_access_token": "",
  "auto_reply": true,
  "private_whitelist": [],
  "group_whitelist": [],
  "group_only_at_me": true,
  "blacklist": [],
  "reply_delay_min": 1.0,
  "reply_delay_max": 3.0,
  "split_delimiter": "<<<NEXT>>>",
  "split_min_pause": 0.5,
  "split_max_pause": 3.0,
  "history_max_messages": 400,
  "persona_file": "",
  "command_prefix": "!"
}

核心参数详解：

参数说明默认值
napcat_ws_urlNapCat WebSocket 地址ws://127.0.0.1:3001
napcat_http_urlNapCat HTTP API 地址http://127.0.0.1:3000
auto_reply自动回复总开关true
private_whitelist私聊白名单（QQ 号列表），空表表示回复所有人[]
group_whitelist群白名单（群号列表），空表表示回复所有群[]
group_only_at_me群里只回复 @ 机器人的消息true
blacklist黑名单（QQ 号或群号列表）[]
reply_delay_min回复最小延迟（秒）1.0
reply_delay_max回复最大延迟（秒）3.0
persona_file人格文件（personas/ 目录下的文件名）""

NapCat 配置

NapCat 的配置文件位于 /opt/napcat/napcat/config/：

  • webui.json：WebUI 端口和 token 配置
  • onebot11_1550421257.json：OneBot11 适配器配置（WebSocket/HTTP 端口）
  • napcat_1550421257.json：NapCat 核心配置

管理命令

在 QQ 中发送以下命令管理机器人：

命令功能
!ping测试机器人是否在线（返回 pong ✅）
!status查看运行状态（LLM 供应商、当前人格等）
!help显示帮助信息

多人群系统

预设人格

personas/ 目录下包含多种预设人格文件：

人格文件特点
真实朋友-基础普通朋友式聊天
真实朋友-开心小狗活泼热情风格
真实朋友-懒懒感慵懒随意风格
真实朋友-话痨话多爱聊风格
真实朋友-更粘人粘人风格
真实朋友-话痨+高粘人话痨加粘人组合
真实朋友-没有🚨省略
真实男友-基础男友风格
真实男友-可爱可爱男友风格
真实男友-更粘人粘人男友风格
默认人格普通助手风格

启用人格

在 config.json 中设置 persona_file 字段：

{
  "persona_file": "真实朋友-话痨.txt"
}

重启服务后生效。留空则不启用人格。

项目文件说明

QQSafeChat-Ubuntu/
├── install.sh                    # 一键安装脚本
├── README.md                     # 详细部署文档
└── QQSafeChat/                   # 项目代码
    ├── core/                     # 核心模块
    │   ├── llm_client.py         # LLM 客户端（支持 DeepSeek/OpenAI/SiliconFlow）
    │   ├── napcat_bridge.py      # NapCat OneBot 11 桥接层
    │   ├── models.py             # 数据模型定义
    │   └── __init__.py
    ├── personas/                 # 人格文件目录（多种预设）
    ├── settings/                 # 配置文件目录
    │   └── openai.json           # LLM 配置
    ├── storage/                  # 数据存储模块
    │   ├── history_store.py      # 对话历史管理
    │   ├── persona_store.py      # 人格文件管理
    │   └── settings_store.py     # 配置管理
    ├── bot_main.py               # 主程序入口
    ├── config.json               # 机器人配置
    ├── requirements.txt          # Python 依赖
    └── run.sh                    # 运行脚本

关键技术解析

消息处理流程

接收消息 → 消息过滤 → 回声消除 → 保存历史 → LLM 生成 → 发送回复
  1. NapCat 桥接层通过 WebSocket 接收 QQ 消息事件，解析消息段中的纯文本
  2. 消息过滤判断是否该回复（白名单、黑名单、@ 检测）
  3. 回声消除检查消息是否为自己刚刚发出的，防止死循环
  4. 历史记录按会话维度存储对话记录，格式化后作为 LLM 的上下文
  5. LLM 生成组装 system prompt + 人格设定 + 历史记录，调用 DeepSeek API
  6. 发送回复支持多条消息分割、随机延迟，模拟真人回复

回声消除机制

机器人发送消息后，NapCat 会通过 WebSocket 回传同样的消息。如果不加处理，机器人会以为自己收到了新消息，再次回复，形成无限循环。

个人网站

欢迎访问我的个人网站：mythlj2.lovestoblog.com/，了解更多项目与分享。

avatar
文章
阅读
粉丝