使用koishi搭建一个高可连接本地数据库的QQ机器人

搭建一个QQ机器人需要准备一下内容：

  • 一台可长时间运行的电脑（不需要公网ip）
  • 一个等级不太低的小号
  • 可稳定拉取docker的环境
  • python环境

其中，python环境用于后端处理数据，非必要。如果你有scratch拼图能力的话，或许可以不需要外挂后端。

整个过程分为：

  • 选择你的机器
  • 搭建NapCat容器
  • k搭建koishi容器
  • 连接koshi和NapCat
  • 下载并编写blockly插件
  • （可选）使用自己的后端处理数据

选择你的机器

NapCat需求

机器的选择没有特定操作系统，NapCat和koishi都有对应的windows版本，官方文档：Shell | NapCatQQ
不论是windows还是linux或者macos，都有对应的安装指导：

  • windows

NapCat.Win.一键版本

特殊说明: 一键版仅适用 Windows.AMD64 无需安装 QQ 和 NapCat 已内置
1.前往 NapCatQQ 的 Releases 页面 下载 NapCat.Shell.Windows.OneKey.zip 无头绿色版本解压
2.点击 NapCatInstaller.exe 等待自动化配置
3.进去 NapCat.XXXX.Shell 目录
4.启动 napcat.bat
对应的 NapCat.Shell.Windows.OneKey.zip 启动后 自动化部署一键包(此包仅适用 Windows)

  • linux推荐使用docker安装

NapCat.Docker - Linux容器化部署

仓库地址: NapCat.Docker
除了常规的 docker run 样式的安装方法,此方法支持 compose 一键模板部署 astrbot, koishi, nonebot 详细参考 Readme 处 一键模板化配置 部分

  • macos

NapCat.MacOs - MacOs安装工具

前往下载
需要 MacOS 12.0 或以上系统，支持下载和更新 NapCatQQ
由于权限问题，补丁过程需要手动替换 package.json，请注意备份原文件～

koishi需求

对于koishi，官方直接提供了直装版windows应用，官方文档：为 Windows 安装 | Koishi

总结

该工作流对设备操作系统没有过多限制，三大主流操作系统均可运行：

  • windows
  • macos
  • linux
    但是笔者推荐使用linux进行服务搭建。后续安装我只讲解linux部分，由于macos和windows均有gui，请自行安装。

搭建NapCat容器

首先保证你能正常连接dockerhub，否则无法进行后续操作！NapCat-Docker官网也有同样的安装指导：
GitHub - NapNeko/NapCat-Docker: NapCat-Docker
首先创建一个 docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# docker-compose.yml  
version: "3"  
services:  
napcat:  
environment:  
- NAPCAT_UID=${NAPCAT_UID}  
- NAPCAT_GID=${NAPCAT_GID}  
ports:  
- 3000:3000  
- 3001:3001  
- 6099:6099  
container_name: napcat  
network_mode: bridge  
restart: always  
image: mlikiowa/napcat-docker:latest

然后运行

1
sudo docker-compose up -d

如果成功了，查看日志获取登录链接：

1
sudo docker logs napcat | less

登录成功后，打开webui，可以看到这样的界面：

打开左侧的网络配置，添加一个websocket服务：

设置地址为广播（0.0.0.0），端口为：3001，上报自身消息为自选项。保存这里生成的token，备用。

搭建koishi容器

koishi也使用docker搭建，但是注意要和NapCat在不同的目录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# docker-compose.yml  
services:  
koishi:  
image: koishijs/koishi:latest  
container_name: koishi  
ports:  
- "5140:5140"  
volumes:  
- /opt/koishi:/koishi  
environment:  
- TZ=Asia/Shanghai  
restart: always  
network_mode: bridge  
extra_hosts:  
- host.docker.internal:host-gateway  
1
sudo docker-compose up -d

使用 http://<主机ip>:5140 打开koishi控制面板。

进入依赖管理，点击小火箭更新所有依赖包：

然后到插件市场，安装adapter-onebot：

点击安装后页面会重载，重新回到插件市场，点击adapter-onebot右上角的修改，点击配置：

这里需要用到NapCat配置的时候生成的token，将它填入这里的token，协议选择ws，下面填入NapCat的地址和3001端口：

然后点击右上角的启动插件，等到左侧显示变绿说明成功了。

测试连接

直接对机器人发送help，如果有回复说明成功。
配置参考：

ref(APA): 天穹何以高.天远日记.https://www.tqhyg.net. Retrieved 2025/10/1.

原文链接：

基于NapCat和Koishi搭建QQ聊天机器人

下载blockly插件

前往koishi插件市场搜索blockly，然后安装blockly-null，注意补药安装blockly，原版插件已经不再维护且无法在最新版koishi上使用。

安装好后，启动插件。
然后你的侧边会多出来一个选项：

点击打开它，接下来我们介绍一些简单的的插件知识。

如何编写blockly插件

首先你可以尝试导入该插件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
插件名称: 访问网站
导出时间: 2025/10/1 10:34:31
-=-=-=-=--=-=-=-=- BEGIN KOISHI BLOCKLY BLOCK V1 -=-=--=-=-=--=-=--=-=-=-
H4sIAAAAAAAAA71X23KqShD9lpShKhdvoCAkZSkKZKvRJAZN4gvFZUQiFwND1Dz4
7btBjMaExLPP2acKdWac7l7d02u6ISoNgqJekR9YngujCzIL3zM7NC1X2VmGD5kv
5Tn4zcYCruH5QfwP3SBoIVrUPGMZr8Q6NdvTp8F2bquuGaomGm6VFrMf94GmeCte
zlBi1LEMw0Zz1UeJZctI/tGujWFb4et6nup7t/LANc/YZM8idqQUuxIjoipsLOvO
QrwDSVdtW1P16R7o7XQHiO652PfsQLHG+0haBC2amWyjKJ21YZh/6vXZi+vBYrNv
z2pLKh5i0PZMS1d0z5l94XxnXpc437gjmGIPJJ9uwG67jxiY55O9YwvZxo7Zm9tE
tifewTdREb4Cxx8EzQowBMI10OLmUzRqYzjHU5mg6GYGRlP4PEyZN6knwchJASf2
hERcavXv5XR8Q/56IB6EES0sOF/lVfUtVbORYiK8D/USQA5CyN4GC9jOwSQNK5x9
NBmBPvU6BeyQ7ycKTNvTVJugiqrhWG6whr1+srEviVs/YMWe4oaOhvx9gE8Djs8U
AJt9XL+OAvnQQWxoeymZ9araITrEYICCiINKGCBfia19MJufynKhOj++4o0oDhW5
kX8U6rve7T2RdOMQw46KJym+tuujsvyElrJevDy9aHSXFp6nHEBv0I0mxa+BCDcH
8esbQgf+UbmhXOFL7wjEusNCvd8hT/4inQeM1NRqfvW4bOqIfZlKo7H092mM0QKn
sZhcXV6w4ng4Aan8s4T8q2ui0uyS/xt/NynqwC9UjX183twQKaHTvBNZjcxeakDi
ofTwnqKf2RdMVMObp8ZhX/8ZbV9leitT+LUKJPD80T51wQaf4r8sPsqJ5ATj2ZdU
+S9IokU31k0ftMlUrQa3/TnPCtxpf9j6m1QJoNorPx1I6LKPzcz5dHm8LD0cGydn
wvu9sl92gXnIxYdYns3wpxg8v+QHGM4CvPeewZGRpkBAGo8BXcumWOzx3Z2k+4ep
QN87A1p/uzKfZpMWFDFR6dH3a8kfUoEoNSfYsYkSGC/CpPA+20nTdOejTPqqbFXF
4rAUvq38FT+mj8/tTpf+lQLGR8HMcwOk7KhNJ2fo238cJYY0X0byHZyLzLxyw9FI
aNfAzAFRitwMLgqFqWcFEyuvT1RcODBCP+SkavGD227Vzt3OMsVR7bVZd7ax/4Mn
+wnAugFQDKTbqq/idV/7saxB2RY6ouI0WwwzdqkX6hZWqgVit1UlqfdWlaToL3m8
yWDwaqfX+HctUtzG6T5SMVLmFp7sY7/lC62VLbQoP+dGZ1nJikfZTapBDvjqPQbZ
rXILI6cJN0HM7VJabRKEg26d1K5osZhVltDm0jxYGJBjpurVzLcjLYX8B3dF39y7
I7hsoApM+pMTXO+o1DmzGnYfKTslu5NbF8ooU+RoqlL5ObvoTbZvGtaPr0Su6nzH
Pu9hVRDIZUvoHIGIn3kQWlK1usmRfQ3Rwe9r4D2yzLRC/ammvdTIl3Z/3r5PuLJ+
u1u/E+YchNWtowYKdN+a4e1bYqIXGh1HdbcxWfuGt47Fa1uO76AjRJbgRaIhESJH
cJVoLFaIhkBwZDTgGwS3eQ0Nw3f8bFk3tNJ4nKM5NM6Vx4jJaSxXznEMTRuMWtJZ
tbz25zcQtts48w4AAA==
-=-=--=-=-=--=-=-=-=- END KOISHI BLOCKLY BLOCK V1 -=-=--=-=-=--=-=--=-=-=-

只需要复制他们，然后选择导入插件：

并选择作为新插件导入：

将这里的QQ号切换为你自己的：

点击编译、启动插件：

然后发送一段链接（比如：https://baidu.com）给机器人，如果它返回了一张图片给你说明该插件生效了。
你可以先阅读一下这个代码，然后我解释几个地方。

数据类型

文本

对于拼接文本块，你可以点击齿轮修改文本参数量，并且该拼接不换行：

对于寻找第一次出现的地方块，返回位置+1

如果需要返回换行，尝试使用模板字符串，双击AB字样打开编辑器，设置内容为\n，随意添加一个tag即可：

数字

只有数字可进行数学运算，提供了转化为数字的块，但是失败会返回NoneType。

列表

列表可供遍历查询，适合设置为权限组或需要广播的群组列表。

对象

对象特指json对象：

提供了三个块，都非常的有用，可以使用{}块直接创建一个json对象（该块返回json对象，而非字符串）。其中键为常量，值可选。

指令创建

使用事件分类中的闯将新的指令，就可以添加一条指令，指令名称为唤起指令的开头文本。

打开创建指令块的小齿轮，这里可以设置参数的类型，对参数进行类型检测。（该操作并不好用，我喜欢用后端对数据进行处理）

上下文获取

上下文主要是获取当前指令的信息，比如发送人qq号，群号，内容，参数等等。

渲染html

该功能可以配合后端使用，后端返回html由koishi渲染成图片再回复：

网络请求

一个完整的网路请求如下：

使用自己的后端处理数据

依照上面的完整网络请求，你可以编写出一些后端api来对接机器人前端，这使得机器人的可拓展性得到了很大的提升。（其实使用为我很不喜欢blockly编程）
示例代码可以参考：
GitHub - zhywyt/BeetleRunBackEnd: back end of beetle run checkin statistics
该代码使用python编写，外加systemd服务，响应速度块，性能好，更重要的是自由度高。

QQbot
#技术文档
使用koishi搭建一个高可连接本地数据库的QQ机器人
http://hexo.zhywzs.top/posts/36682/
作者
zhywzs
发布于
2025年10月1日
更新于
2025年10月1日
许可协议