在 Debian12 服务器上部署 Astrbot 与 Overflow (NapCat 双后端)

15 Sept , 2025

本指南旨在提供一个清晰、高效的流程，在 Debian 12 服务器上部署一套 QQ 机器人架构，其中 Napcat 作为核心协议端，同时为 Astrbot 和 Overflow 两个独立的应用后端提供支持，此外，我们还将为需要访问外部资源（如 Google API）的 Astrbot 配置代理能力

前置准备

一台 Debian 12 服务器（位于国内）
一个 QQ 账号
一个有效的代理服务订阅链接 (可选)

第一步：配置代理环境 (v2rayA/可选)

此步骤为可选操作，主要为 Astrbot 访问外部服务提供网络支持，如果您不需要访问如 Google API 等服务，可以跳过此步

安装 v2rayA

# 添加 GPG 公钥与软件源
wget -qO - https://apt.v2raya.org/key/public-key.asc | sudo tee /etc/apt/keyrings/v2raya.asc
echo "deb [signed-by=/etc/apt/keyrings/v2raya.asc] https://apt.v2raya.org/ v2raya main" | sudo tee /etc/apt/sources.list.d/v2raya.list

# 安装
sudo apt update && sudo apt install v2raya xray -y

启动并配置
```
sudo systemctl start v2raya
sudo systemctl enable v2raya
```
- 访问 http://<服务器IP>:2017，创建管理员
- 导入您的订阅链接，选择一个节点并启动
- 在 设置 -> 地址与端口 中，确认 SOCKS5 端口为 20170

第二步：部署 Napcat

Napcat 是连接 QQ 网络的协议端，它将作为事件中心，将消息和事件分发给后端的 Astrbot 和 Overflow

创建工作目录与 compose.yml

mkdir -p ~/napcat && cd ~/napcat
nano compose.yml

粘贴以下 Docker Compose 配置

version: "3.8"
services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    network_mode: "host"
    volumes:
      - ./napcat-data:/app/data

启动并扫码登录
- 前台启动获取二维码
```
sudo docker compose up
```
- 扫描日志中的二维码或链接，使用手机 QQ 确认登录
- 复制终端中 Napcat WebUI 链接到浏览器打开，进行后续配置
- 点击左侧 其它配置 -> 登录配置 -> 填入快速登录 QQ 账号
- 登录成功后，按 Ctrl+C 停止容器
- 后台启动服务
```
sudo docker compose up -d
```
请务必记下终端输出中 WebUI 的访问地址和 Token，后续配置连接时需要用到

第三步：部署应用后端 1 (Astrbot)

Astrbot 是我们的第一个应用后端，使用 Docker Compose 进行部署

创建工作目录与克隆 Astrbot 仓库

mkdir -p ~/astrbot && cd ~/astrbot
git clone https://github.com/AstrBotDevs/AstrBot.git .
# 克隆到当前目录

编辑 compose.yml 文件

根据是否在第一步中配置了代理，对 Astrbot 的 compose.yml 文件进行相应修改

version: "3.8"
services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    # [核心修改1] 添加 network_mode: "host" 以共享主机网络
    # 这样容器就能直接访问 v2rayA 的代理端口，并且方便与 Napcat 通信
    network_mode: "host"

    environment:
      - TZ=Asia/Shanghai
      # [核心修改2 - 可选] 如果配置了 v2rayA，请添加以下代理环境变量
      - HTTP_PROXY=socks5://127.0.0.1:20170
      - HTTPS_PROXY=socks5://127.0.0.1:20170

    volumes:
      - ./data:/AstrBot/data
      - /etc/localtime:/etc/localtime:ro

启动 Astrbot
```
sudo docker compose up -d
```
Astrbot WebUI 现已运行在 http://<服务器IP>:6185 上

第四步：部署应用后端 2 (Overflow)

Overflow 是我们的第二个应用后端，基于 Mirai 生态，我们使用 Systemd 来管理其服务

准备环境 使用 SFTP 等工具上传 overflow.zip 到服务器的 ~/overflow 目录并解压

mkdir -p ~/overflow && cd ~/overflow
sudo apt install unzip openjdk-17-jre -y
unzip overflow.zip

创建 Systemd 服务

执行

sudo nano /etc/systemd/system/overflow.service

并粘贴以下内容：

[Unit]
Description=Overflow QQ Bot Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/overflow
ExecStart=/bin/bash /root/overflow/start.sh
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target

启动服务

sudo systemctl daemon-reload
sudo systemctl start overflow
sudo systemctl enable overflow

第五步：建立连接 (Napcat -> Astrbot & Overflow)

我们采用两种不同的 WebSocket 模式来连接两个后端：

Astrbot (反向 WS)：Astrbot 作为服务端，Napcat 作为客户端连接它
Overflow (正向 WS)：Napcat 作为服务端，Overflow 作为客户端连接它

5.1 连接 Astrbot (反向模式)

配置 Astrbot (服务端)
- 访问 Astrbot WebUI (http://<服务器IP>:6185)
- 进入 消息平台 -> + 新增适配器 -> 选择 aiocqhttp(OneBotv11)
- 配置项：
  - ID(id)：astrbot-reverse-server (或自定义)
  - 启用(enable): 勾选
  - 反向 WebSocket 主机地址：0.0.0.0
  - 反向 WebSocket 端口：6199 (确保此端口未被占用)
- 点击 保存
- 进入 配置 -> 其他配置，在 管理员 ID 中填写你的 QQ 号，保存
配置 Napcat (客户端)
- 进入 Napcat WebUI
- 点击 网络配置 -> 新建 -> Websockets客户端
- 配置项：
  - 勾选 启用
  - URL: ws://127.0.0.1:6199/ws
  - 点击 保存

5.2 连接 Overflow (正向模式)

配置 Napcat (服务端)
- 进入 Napcat WebUI
- 点击 网络配置 -> 新建 -> Websocket服务器
- 配置项：
  - 勾选 启用
  - 主机: 127.0.0.1
  - 端口: 3001 (确保此端口未被占用)
  - 点击 保存
  输入一个足够复杂的 Token，如 mirai_overflow108
Overflow 强制要求 Token 足够复杂以保证安全，否则无法启动

配置 Overflow (客户端)

确保 Overflow 已启动过一次且成功生成了配置文件 overflow.json
进入 Overflow 的配置文件 (通常在 Overflow 根目录下)，找到 ws_host 的相关设置
修改/新增一个正向 WebSocket 客户端配置，指向 Napcat 监听的地址：

"ws_host": "ws://127.0.0.1:3001",

填写之前在 Napcat 配置的 Token，配置完成后的 overflow.json 文件大致如下所示：

{
  no_log___DO_NOT_REPORT_IF_YOU_SWITCH_THIS_ON___开启此选项时不接受漏洞反馈: false,
  ws_host: "ws://127.0.0.1:3001",
  reversed_ws_port: -1,
  token: "mirai_overflow108",
  no_platform: false,
  use_cq_code: false,
  retry_times: 5,
  retry_wait_mills: 5000,
  retry_rest_mills: 60000,
  heartbeat_check_seconds: 60,
  use_group_upload_event_for_file_message: false,
  resource_cache: {
    enabled: false,
    keep_duration_hours: 168,
  },
  drop_events_before_connected: true,
}

保存配置并重启 Overflow 服务 ( sudo systemctl restart overflow )

5.3 验证连接

在 Astrbot WebUI 的 控制台，应出现 aiocqhttp(OneBot v11) 适配器已连接 的日志
通过 sudo journalctl -u overflow -f 查看 Overflow 日志，应能看到成功连接到 ws://127.0.0.1:3001 的日志

至此，您已成功搭建了 Napcat 同时为 Astrbot 和 Overflow 两个后端服务的 QQ 机器人

附录：Mirai 权限问题处理

当使用 Overflow/Mirai 时，如果终端提示权限不足，这是 Mirai 的安全机制所致

错误示例: 权限不足. /bili 需要权限 top.colter.bili-dynamic-mirai-plugin:command.bili
解决方法: 在 Overflow 的控制台中，使用 /perm 指令进行授权，语法为 被授权对象 在前

# 示例：允许所有用户执行任意 Console 内置指令
/perm permit u* console:*

#astrbot #bot #mirai #napcat #overflow #tech