败草寒风

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

14 min

本指南旨在提供一个清晰、高效的流程，在 Debian 12 服务器上部署一套 QQ 机器人架构，其中 Napcat 作为核心协议端，同时为 Astrbot 和 Overflow 两个独立的应用后端提供支持

前置准备

  1. 一台 Debian 12 服务器（位于国内）
  2. 一个 QQ 账号

第一步：部署 Napcat

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

NapNekoNapCatQQ

Loading repository data...

-- -- --

  1. 创建工作目录与 compose.yml

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

  2. 粘贴以下 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

  3. 启动并扫码登录

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

    请务必记下终端输出中 WebUI 的访问地址和 Token，后续配置连接时需要用到

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

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

AstrBotDevsAstrBot

Loading repository data...

-- -- --

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

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

  2. 编辑 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

  3. 启动 Astrbot

    sudo docker compose up -d

    Astrbot WebUI 现已运行在 http://<服务器IP>:6185 上

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

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

MrXiaoMOverflow

Loading repository data...

-- -- --

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

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

  2. 创建 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

  3. 启动服务

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

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

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

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

4.1 连接 Astrbot (反向模式)

  1. 配置 Astrbot (服务端)

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

  2. 配置 Napcat (客户端)

    • 进入 Napcat WebUI
    • 点击 网络配置 -> 新建 -> Websockets客户端
    • 配置项：
      • 勾选 启用
      • URL: ws://127.0.0.1:6199/ws
      • 点击 保存

4.2 连接 Overflow (正向模式)

  1. 配置 Napcat (服务端)

    • 进入 Napcat WebUI

    • 点击 网络配置 -> 新建 -> Websocket服务器

    • 配置项：

      • 勾选 启用
      • 主机: 127.0.0.1
      • 端口: 3001 (确保此端口未被占用)
      • 点击 保存

      输入一个足够复杂的 Token，如 mirai_overflow108

    Overflow 强制要求 Token 足够复杂以保证安全，否则无法启动

  2. 配置 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 )

4.3 验证连接

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

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

附录

  1. Mirai 权限问题处理

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

  • 错误示例: 权限不足. /bili 需要权限 top.colter.bili-dynamic-mirai-plugin:command.bili

  • 解决方法: 在 Overflow 的控制台中，使用 /perm 指令进行授权，语法为 被授权对象 在前

    # 示例：允许所有用户执行任意 Console 内置指令
/perm permit u* console:*
  1. 配置代理环境 (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

tech server bot