1483 字
7 分钟
AstrBot 接入 QQ:SnowLuma(OneBot v11)

SnowLuma 通过 OneBot v11 接入 AstrBot。AstrBot 侧和 NapCat 共用同一个适配器;这篇从创建适配器开始写,单独看也能跑通。

1. 在 AstrBot 中创建 OneBot v11 适配器#

如果已经按 NapCat 那篇创建过适配器,直接跳到第 2 节。否则打开 AstrBot WebUI,进入「机器人 → 创建机器人」:

创建适配器

  1. 创建机器人

    消息平台类别选 OneBot v11,机器人名称填 qq。

  2. 填写反向 WebSocket

    反向 WebSocket 主机填 0.0.0.0,端口填 6199,Token 留空。

    AstrBot 创建 OneBot v11 机器人
    消息平台类别 OneBot v11,反向 WebSocket 主机 0.0.0.0,端口 6199
  3. 保存并启用

    保存后回到机器人列表,确认 qq 处于运行中。SnowLuma 后面连的就是这个 6199。

    AstrBot 机器人列表
    qq 使用 aiocqhttp,反向 WebSocket 端口 6199

2. 部署 SnowLuma#

以 SnowLuma 为例,1Panel 防火墙放行 6185、5099、6081 即可:

1Panel 防火墙放行 AstrBot、SnowLuma 和 noVNC 端口
放行 6185、6081、5099,协议 TCP,来源全部 IPv4 地址

2.1 单独部署 SnowLuma#

AstrBot 已经部署好时,只新增 SnowLuma。它使用自己的 snowluma-network,通过 host.docker.internal 访问宿主机上的 AstrBot,并共享 astrbot-data。

单独部署 SnowLuma

  1. 保存配置

    SnowLuma 需要先设置 VNC_PASSWD,例如 VNC_PASSWD=passwd123。

    services:
    snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: "0:0"
    shm_size: 1gb
    cap_add:
    - SYS_PTRACE
    security_opt:
    - seccomp=unconfined
    extra_hosts:
    - "host.docker.internal:host-gateway"
    environment:
    VNC_PASSWD: ${VNC_PASSWD:-vncpasswd}
    SNOWLUMA_UID: ${SNOWLUMA_UID:-1000}
    SNOWLUMA_GID: ${SNOWLUMA_GID:-1000}
    SNOWLUMA_WEBUI_PORT: ${SNOWLUMA_WEBUI_PORT:-5099}
    SNOWLUMA_LOG_LEVEL: ${SNOWLUMA_LOG_LEVEL:-info}
    SNOWLUMA_SCREEN: ${SNOWLUMA_SCREEN:-1920x1080x16}
    SNOWLUMA_HOOK_AUTOLOAD: ${SNOWLUMA_HOOK_AUTOLOAD:-1}
    SNOWLUMA_EXTRA_QQ_HOMES: "${SNOWLUMA_EXTRA_QQ_HOMES:-}"
    SNOWLUMA_QQ_FLAGS: "${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}"
    ports:
    - "${VNC_PORT:-5900}:5900"
    - "${NOVNC_PORT:-6081}:6081"
    - "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"
    - "${ONEBOT_HTTP_PORT:-3000}:3000"
    - "${ONEBOT_WS_PORT:-3001}:3001"
    volumes:
    - snowluma-data:/app/snowluma-data
    - snowluma-qq-config:/app/.config
    - snowluma-qq-data:/app/.local/share
    - astrbot-data:/AstrBot/data
    networks:
    - snowluma-network
    networks:
    snowluma-network:
    name: snowluma-network
    driver: bridge
    volumes:
    snowluma-data:
    snowluma-qq-config:
    snowluma-qq-data:
    astrbot-data:
    external: true

    保存为 /opt/astrbot/compose.snowluma.yml。

  2. 启动

    Terminal window
    cd /opt/astrbot
    docker compose -f compose.snowluma.yml up -d

2.2 AstrBot + SnowLuma 一起部署#

如果还没有单独部署 AstrBot,可以用一份 Compose 把两者一起拉起。两个容器都在 astrbot-network,共享 astrbot-data,6199 不映射到宿主机。

一起部署

  1. 保存配置

    SnowLuma 需要先设置 VNC_PASSWD,例如 VNC_PASSWD=passwd123。

    services:
    astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
    - no-new-privileges:true
    ports:
    - "6185:6185" # AstrBot WebUI
    environment:
    - TZ=Asia/Shanghai
    volumes:
    - astrbot-data:/AstrBot/data
    - /etc/localtime:/etc/localtime:ro
    networks:
    - astrbot-network
    snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: "0:0"
    shm_size: 1gb
    cap_add:
    - SYS_PTRACE
    security_opt:
    - seccomp=unconfined
    environment:
    - VNC_PASSWD=${VNC_PASSWD:-vncpasswd}
    - SNOWLUMA_UID=${SNOWLUMA_UID:-1000}
    - SNOWLUMA_GID=${SNOWLUMA_GID:-1000}
    - SNOWLUMA_WEBUI_PORT=${SNOWLUMA_WEBUI_PORT:-5099}
    - SNOWLUMA_LOG_LEVEL=${SNOWLUMA_LOG_LEVEL:-info}
    - SNOWLUMA_SCREEN=${SNOWLUMA_SCREEN:-1920x1080x16}
    - SNOWLUMA_HOOK_AUTOLOAD=${SNOWLUMA_HOOK_AUTOLOAD:-1}
    ports:
    - "${VNC_PORT:-5900}:5900"
    - "${NOVNC_PORT:-6081}:6081"
    - "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"
    - "${ONEBOT_HTTP_PORT:-3000}:3000"
    - "${ONEBOT_WS_PORT:-3001}:3001"
    volumes:
    - snowluma-data:/app/snowluma-data
    - snowluma-qq-config:/app/.config
    - snowluma-qq-data:/app/.local/share
    - astrbot-data:/AstrBot/data
    networks:
    - astrbot-network
    networks:
    astrbot-network:
    driver: bridge
    volumes:
    snowluma-data:
    snowluma-qq-config:
    snowluma-qq-data:
    astrbot-data:
    name: astrbot-data

    保存为 /opt/astrbot/compose.snowluma.yml。

  2. 启动

    Terminal window
    cd /opt/astrbot
    docker compose -f compose.snowluma.yml up -d

3. 配置 SnowLuma WebSocket#

打开 SnowLuma WebUI。

配置 SnowLuma WebSocket

  1. 打开 WebSocket 反向客户端

    进入「节点配置 → OneBot 协议端点 → WebSocket 反向客户端」。

  2. 填写名称

    名称填 astrbot。

  3. 填写 URL

    URL 填 ws://astrbot:6199/ws,Token 留空。

  4. 保存并启用

    保存后确认客户端处于启用状态。

一起部署的填写示例:ws://astrbot/ws
名称 astrbot,URL ws://astrbot:6199/ws

4. 登录 SnowLuma#

登录 SnowLuma

  1. 获取访问令牌

    浏览器打开 http://<服务器IP>:5099。首次登录需要访问令牌,令牌在容器日志里:

    Terminal window
    docker logs snowluma 2>&1 | grep -i -E "webui|token|凭证|访问令牌"

    日志里会打印 WebUI 的访问令牌,不同镜像版本的字段名可能不一样。把它填到登录页:

    SnowLuma WebUI 登录页
    在「输入访问令牌」处填入日志里的 Token
  2. 同意用户协议

    首次进入会显示 EULA,勾选「我已阅读并同意」后点「同意并继续」。

    SnowLuma 首次使用协议
    勾选同意 EULA 后继续
  3. 设置访问密码

    按提示设置新的访问密码并确认。

    SnowLuma 设置访问密码
    设置并确认新的访问密码
  4. 进入控制台并加载 QQ

    设置完成后进入「概览」页;如果 QQ 还没启动,在「进程注入」里加载它,确认状态为「等待登录」。

    SnowLuma 控制台概览
    在概览页确认服务状态
    SnowLuma 进程注入等待登录
    进程注入里显示 qq 等待登录
  5. 登录 noVNC

    浏览器打开 http://<服务器IP>:6081,输入 VNC 密码后就能看到 SnowLuma 的桌面,容器会自动启动 QQ。

    VNC 密码来自 compose 里的 VNC_PASSWD;没有改过时默认是 vncpasswd。

    noVNC 登录凭证输入框
    输入 VNC_PASSWD,点击发送凭证
  6. 扫码登录 QQ

    在桌面里用手机 QQ 扫码登录:

    SnowLuma noVNC 中扫码登录 QQ
    用手机 QQ 扫描 noVNC 桌面里的二维码

    登录成功后,回到控制台的「进程注入」,可以看到 QQ 已在线:

    SnowLuma 进程注入显示 QQ 在线
    进程注入里显示 QQ 已在线

5. 验证连接#

验证连接

  1. 看 SnowLuma 概览

    「OneBot 连接」里出现 astrbot 的 WS 客户端「已连接」。

    SnowLuma 概览页显示 astrbot 已连接
    在线账号 1,astrbot WS 客户端已连接
  2. 看 AstrBot 日志

    日志里出现 aiocqhttp(OneBot v11) 适配器已连接。

    AstrBot 日志显示 SnowLuma 适配器已连接
    aiocqhttp(OneBot v11) 适配器已连接

常见问题#

SnowLuma 的 WS 客户端一直显示未连接

2.2 一起部署:确认两个容器在同一个 Docker 网络,URL 里的 astrbot 能解析到 AstrBot 容器。

单独部署或跨网络:见 不同网络下的 OneBot WebSocket 通信。

AstrBot 和 SnowLuma 一起部署时出现 Network 错误

检查 compose 里的网络名是否和 AstrBot 实际使用的网络一致;同一份 compose 里的两个服务必须加入同一个网络。

AstrBot 提示 Token 不匹配

AstrBot 的反向 WebSocket Token 和 SnowLuma 的 Token 必须一致;不想校验就两边都留空。

SnowLuma 的 VNC 密码在哪里设置

在 2.1 单独部署 / 2.2 AstrBot + SnowLuma 一起部署 的 Compose 环境变量里设置 VNC_PASSWD。

第 2 篇,共 3 篇本文属于系列

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取