这是什么？

守护神机器人是一款帮 DNF 游戏群管理员管理 QQ 群的工具。把机器人 QQ 加入你的群后，玩家可以通过发送指令完成签到、查排行、领福利等操作，同时还能自动过滤广告、踢除刷屏用户，让群聊更干净。

你（运营者）通过网页后台管理所有设置，不需要懂技术。

能做什么？

系统架构

部署在客户的 Linux 服务器上，两个组件自动配合工作：

运营者用浏览器访问后台地址即可管理，不需要额外软件。

联系方式

⚙ 功能说明

后台共有 20+ 个功能，分为四大类。

游戏功能

群管功能

安全功能

统计功能

🚀 30分钟快速部署

以下步骤由厂商协助完成。如有问题直接联系厂商技术人员。

第一步：服务器准备

1.1 安装宝塔面板

宝塔是一个服务器管理工具，让不懂技术的也能管服务器。去 bt.cn 下载安装，免费使用。

1.2 安装 Docker

宝塔面板里：软件商店 → 搜索 Docker → 安装 Docker 管理器。

第二步：上传文件

把厂商提供的文件上传到服务器任意目录（如 /www/wwwroot/dnf-bot/），只需两个文件：

第三步：启动服务

在宝塔「终端」里执行：

cd /www/wwwroot/dnf-bot
docker compose up -d

首次启动会自动下载两个组件（镜像约 300MB），可能需要几分钟，完成后两个容器都显示 Up 即成功。

第四步：登录机器人 QQ

1. 1

   查看登录密码（在宝塔终端执行）：

   docker logs dnf-napcat

   在服务器终端执行命令查看 Token：

   docker logs dnf-napcat 2>&1 | grep -i token

   在输出中找到 Token 或 token，复制后面的那串字符。

2. 2

   打开机器人管理页面：

   http://服务器IP:6099/webui

   输入上一步找到的 Token，登录。

3. 3

   用做机器人的 QQ 号扫码登录。登录后状态显示"在线"即可。

   登录态会自动保存，重启服务器不需要重新扫码。

第五步：配置双向通信

需要在 NapCat 管理页面配两个通道，缺一不可：

5.1 HTTP 服务端（让机器人能发消息）

1. 1

   左侧菜单点「网络配置」→「新建」

2. 2

   类型选「HTTP 服务端」，标题随便填（如"消息服务"）

3. 3

   Host 填 0.0.0.0（不能用 127.0.0.1，否则 agent 容器连不进来），端口填 3000

4. 4

   Token 不能留空，填一串字符（比如 abc123），保存。

   ⚠️ Host 填 0.0.0.0 时 NapCat 要求必须填 Token 才能保存。

5. 5

   开关打开，保存后等 NapCat 重启，日志显示「HTTP服务已启动」即可。

5.2 HTTP 客户端（让收到的消息发给后台处理）

1. 1

   再点「网络配置」→「新建」

2. 2

   类型选「HTTP 客户端」，标题随便填（如"消息回调"）

3. 3

   URL 填写：

   http://dnf-agent:8081/napcat/callback

   开关打开，保存。

第六步：初始化后台

打开后台管理页面：

http://服务器IP:8081

按顺序做以下几步（只需做一次）：

1. 1

   注册账号 → 填用户名和密码（记住它们，以后登录用）

2. 2

   激活授权 → 找厂商要卡密，输入后激活

3. 3

   添加机器人 → 填写机器人名称和 QQ 号，NapCat 地址填 http://napcat:3000，Token 填机器人管理页面左上角显示的 Token

4. 4

   添加群组 → 填写你的 QQ 群号，选中上一步添加的机器人

完成后把机器人 QQ 加进你的群，机器人就能正常收发消息了。

常用命令

在宝塔「终端」里执行：

🏗 系统架构说明

了解整体结构有助于排查问题。

两个组件各做什么？

两个组件自动配合：NapCat 收到群消息 → 转发给 Agent → Agent 处理后通过 NapCat 回复。

对外端口

📖 后台配置指南

登录后台 http://服务器IP:8081 后，按以下顺序完成配置。

配置顺序

注册账号 → 激活授权 → 服务器配置 → 添加机器人 → 添加群组 → 开启功能

1. 注册 & 激活

首次登录会跳到注册页面，填用户名密码完成注册，然后用厂商给的卡密激活授权。

2. 服务器配置

「服务器配置」→ 「添加服务器」，填写游戏服数据库信息：

填完后点「测试连接」，通了再启用。

3. 添加机器人

「机器人管理」→ 「添加机器人」：

4. 添加群组

「群组管理」→ 「添加群组」，填写群号，绑定对应的机器人和服务器。

5. 开启功能

「功能开关」→ 选择群组 → 打开需要的功能开关（默认全开）。安全相关参数（踢人阈值、禁言时长等）在页面下方设置。

多机器人

一个后台可以管多个 QQ 机器人，每加一个 QQ 需要单独运行一个 NapCat：

# 第二个 QQ
chmod +x start-napcat.sh
./start-napcat.sh 2

# 第三个 QQ
./start-napcat.sh 3

运行后在后台「机器人管理」里新增一条，填写对应端口的 NapCat 地址和 Token。

⌨ 群聊指令速查

以下指令玩家在群里发送即可。灰色标注的只有管理员能用。

所有玩家都能用

管理员指令（群主/管理员）

❓ 常见问题

机器人没反应，收不到消息

1. 检查 QQ 状态是否"在线"（打开 http://IP:6099/webui 看）
2. 检查网络配置里 URL 是否填了 http://dnf-agent:8081/napcat/callback
3. 查看后台日志：docker compose logs -f agent

后台打不开（8081端口）

检查容器是否正常运行：docker compose ps

需要重新扫码登录 QQ

执行 docker compose logs -f napcat 重新扫码。轻度重启不需要重新登录。

扫码登录了，但浏览器还提示要 Token

扫码只是让 QQ 号上线，浏览器要的是 NapCat HTTP API 的访问令牌，不是扫码登录。

1. 在服务器终端执行：docker logs dnf-napcat 2>&1 | grep -i token
2. 找到日志里类似 token: xxxxxx 或 accessToken: xxxxxx 的那串字符
3. 把这串 Token 填到 agent 后台「绑定机器人」页面的 NapCat Token 输入框里

如果日志里没有 token，可能是还没生成过，参考「第五步：配置双向通信」重新保存一次 NapCat 的网络配置。

发送消息超时（ECONNREFUSED 或 2ms 超时）

日志里出现「Connect to napcat:3000 failed」或「发送消息超时(2ms)」，通常是以下两个原因：

1. HTTP Server Host 填了 127.0.0.1：NapCat 容器内的 127.0.0.1 是回路地址，agent 容器无法连通。
   解决：NapCat WebUI → 网络配置 → HTTP Server → Host 改为 0.0.0.0，保存重启。
   ⚠️ 填 0.0.0.0 时 Token 不能留空，填一串字符后保存。
2. 两边 Token 不一致：NapCat HTTP Server 的 Token 和 agent 后台「机器人管理」里填的 NapCat Token 不匹配。
   解决：两边都填成同一个值（不能一边有一边空），保存后等 NapCat 重启。

升级后后台打不开

因为数据库密码变了，需要重置数据：

docker compose down -v
docker compose up -d

游戏功能不生效（签到/发奖励等）

1. 确认「群组管理」里群绑定了服务器
2. 确认「服务器配置」里数据库测试连接成功
3. 确认玩家发了"绑定"指令绑定了游戏角色

定时任务没发

1. 确认时间格式正确（发福利用 0910，发公告用 09:30）
2. 确认对应功能在「功能开关」里开了
3. 确认该条任务状态是"启用"

误踢了正常玩家

在「本地白名单」里加上该玩家的 QQ 号即可解除，并不会被再踢。

需要改后台密码

在后台点「修改密码」，输入旧密码和新密码即可。

其他问题

联系厂商技术人员，提供后台地址和出现问题的时间点，方便快速定位。