📖 简介

Koishi 是一个功能强大、可扩展的跨平台机器人框架。本指南将引导你如何在 Ubuntu 服务器上，通过 Docker 快速部署 Koishi，并使用 NapCat 作为 QQ 适配器，最终搭建一个稳定、高效的 QQ 机器人。

⚠️ 准备工作

在开始之前，请确保你已准备好以下环境：

1. 一台拥有公网 IP 的 Ubuntu 服务器。
2. 一个用于登录的 QQ 小号。
3. 确保服务器防火墙或云服务商安全组已开放以下端口：

步骤一：安装 Docker 环境

本部分参考自博客 蓝羽天空，并已适配国内网络环境。

1. 检查旧版本

验证当前环境是否已安装旧版本 Docker。如果已安装，建议先卸载。

docker -v

2. 更新软件包索引并安装依赖

sudo apt update
sudo apt install -y ca-certificates curl

3. 添加 Docker 的 GPG 密钥

GPG 密钥用于验证软件包的完整性，确保其来源可信。

# 创建用于存储 GPG 密钥的目录
sudo install -m 0755 -d /etc/apt/keyrings

# 下载 GPG 密钥（使用阿里云镜像）
sudo curl -fsSL http://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

# 更改密钥文件的权限，确保 apt 可以读取
sudo chmod a+r /etc/apt/keyrings/docker.asc

4. 添加 Docker 软件源

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] http://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. 安装 Docker

# 更新软件包索引
sudo apt update

# 安装 Docker 最新版本
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

6. 配置国内镜像源

为了提升拉取 Docker 镜像的速度，建议配置国内镜像源。

sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "http://hub-mirror.c.163.com",
    "https://docker.nju.edu.cn"
  ]
}
EOF

7. 重启并验证 Docker

# 重启 Docker 服务使配置生效
sudo systemctl restart docker

# 设置 Docker 开机自启
sudo systemctl enable docker

# 验证 Docker 是否安装成功并可以正常运行
sudo docker run hello-world

如果能看到 "Hello from Docker!" 字样，说明 Docker 已成功安装。

步骤二：使用 Docker 安装 Koishi

运行以下命令来启动 Koishi 容器。

docker run -d \
  --name koishi \
  --restart always \
  -p 5140:5140 \
  -v /root/koishi_data:/koishi \
  -e TZ=Asia/Shanghai \
  koishijs/koishi

参数说明:

• -d: 后台运行容器。
• --name koishi: 将容器命名为 koishi，方便管理。
• --restart always: 容器退出时总是自动重启。
• -p 5140:5140: 将宿主机的 5140 端口映射到容器的 5140 端口。
• -v /root/koishi_data:/koishi: 将 Koishi 的数据（配置、插件等）持久化到宿主机的 /root/koishi_data 目录。
• -e TZ=Asia/Shanghai: 设置时区为东八区，确保日志时间正确。

容器运行后，稍等片刻即可通过浏览器访问 http://<你的服务器IP>:5140 进入 Koishi 控制台。

步骤三：安装并运行 NapCat

1. 一键安装 NapCat

使用官方提供的一键安装脚本，以 TUI (终端图形界面) 模式进行安装。

curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh && sudo bash napcat.sh --tui

根据提示完成安装即可。

2. 后台运行 NapCat

为了让 NapCat 能在关闭 SSH 连接后依然保持运行，我们使用 screen 工具。

# 启动一个名为 napcat 的后台会话，并运行 NapCat
screen -dmS napcat bash -c "xvfb-run -a /root/Napcat/opt/QQ/qq --no-sandbox"

# 如果需要附加到会话查看日志或扫码
screen -r napcat

提示：在 screen 会话中，按 Ctrl+A 然后按 D 可以分离会话（使其在后台继续运行）。

3. 登录 QQ

访问 http://<你的服务器IP>:6099/webui，进入 NapCat 的 WebUI，使用手机 QQ 扫描二维码登录。

步骤四：连接 Koishi 与 NapCat

1. NapCat 中开启 WebSocket 服务

进入 NapCat WebUI (http://<你的服务器IP>:6099/webui) 后：

1. 点击左侧的「网络配置」。
2. 点击左上角的「添加配置」。
3. 新建一个「正向 Websocket 服务器」，格式如下图所示，然后保存。

   

2. Koishi 中安装 OneBot 适配器

NapCat 兼容 OneBot v11 协议，因此我们需要在 Koishi 中安装相应的适配器。

1. 进入 Koishi 控制台 (http://<你的服务器IP>:5140)。
2. 在左侧菜单中点击「插件市场」。
3. 搜索 adapter-onebot 并安装它。

3. 配置 OneBot 适配器

安装完成后，Koishi 会自动跳转到配置页面（或在「插件配置」中找到 adapter-onebot）。

1. 点击「添加机器人」。
2. 在弹出的表单中，关键配置如下：
   • protocol: 选择 ws (正向 WebSocket)。
   • endpoint: 填写 NapCat 的 WebSocket 地址，即 ws://127.0.0.1:3000。 > 注意：因为 Koishi 和 NapCat 运行在同一台服务器的 Docker 网络中，此处建议使用 ws://host.docker.internal:3000 或宿主机内网IP，127.0.0.1 可能无法访问。最稳妥的方式是直接使用服务器的公网IP，例如 ws://<你的服务器IP>:3000。
3. 保存配置并启用该插件。

如果一切顺利，你应该能在 Koishi 控制台的「连接」页面看到状态为「ONLINE」的机器人。

✅ 完成

至此，Koishi 和 NapCat 的配置已全部完成。你的 QQ 机器人已经可以接收和发送消息了。接下来，你可以在 Koishi 的插件市场中探索和安装各种有趣的功能插件，打造属于你自己的强大机器人！

附录：常用 Docker 命令

# 查看所有正在运行的容器
docker ps

# 查看所有容器（包括已停止的）
docker ps -a

# 启动一个已停止的容器
docker start <容器ID或名称>

# 停止一个正在运行的容器
docker stop <容器ID或名称>

# 重启一个容器
docker restart <容器ID或名称>

# 进入一个正在运行的容器的命令行
docker exec -it <容器ID或名称> /bin/sh