云端 QQ 机器人容器化部署实践：SnowLuma + AstrBot

引言

在即时通讯平台上构建 AI 机器人，通常需要两个核心组件：一个负责与平台协议对接的网关，以及一个负责业务逻辑与模型调度的应用框架。

本文记录在腾讯云轻量服务器（4C4G，Ubuntu 22.04）上，使用 Docker 部署 SnowLuma 与 AstrBot 的完整过程，重点分析容器网络通信中的常见误区，并提供可复用的部署方案。

环境与组件

项目	版本/配置
操作系统	Ubuntu 22.04 LTS
服务器	腾讯云轻量应用服务器 4核4G
Docker	Ubuntu 官方源 docker.io
SnowLuma	v1.14.20
AstrBot	v4.28.2

SnowLuma 是基于 OneBot v11 协议的 QQ 网关，内置无头浏览器与 VNC 远程桌面；AstrBot 是机器人应用框架，提供 WebUI 管理、插件系统与模型调度能力。两者通过反向 WebSocket 通信。

一、Docker 环境配置

1.1 安装 Docker

由于国内网络环境限制，直接从 get.docker.com 执行安装脚本常出现连接重置。使用 Ubuntu 官方维护的 docker.io 包更为稳定：

apt update && apt upgrade -y
apt install -y docker.io
systemctl start docker
systemctl enable docker

1.2 配置国内镜像加速

为提升镜像拉取速度，配置 Docker daemon 使用国内镜像源：

mkdir -p /etc/docker
tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com"
  ]
}
EOF
systemctl daemon-reload
systemctl restart docker

二、SnowLuma 部署

2.1 容器启动命令

docker run -d \
  --name snowluma \
  --restart unless-stopped \
  --shm-size=1g \
  --cap-add=SYS_PTRACE \
  --security-opt seccomp=unconfined \
  -e VNC_PASSWD=<your-vnc-password> \
  -e SNOWLUMA_WEBUI_HOST=0.0.0.0 \
  -e SNOWLUMA_WEBUI_PORT=5099 \
  -e SNOWLUMA_QQ_FLAGS="--disable-gpu --disable-software-rasterizer --disable-gpu-compositing" \
  -p 5900:5900 \
  -p 6081:6081 \
  -p 5099:5099 \
  -p 3000:3000 \
  -p 3001:3001 \
  -v qq-gateway-data:/app/data \
  -v qq-client-config:/app/.config \
  -v qq-client-data:/app/.local/share \
  docker.m.daocloud.io/motricseven7/snowluma:latest

2.2 关键参数说明

--shm-size=1g：QQ 客户端基于 Electron 构建，共享内存不足会导致渲染进程崩溃。
--cap-add=SYS_PTRACE：允许 ptrace 系统调用，部分沙箱环境需要此权限。
--security-opt seccomp=unconfined：解除 seccomp 限制，避免无头浏览器被安全策略拦截。
SNOWLUMA_QQ_FLAGS：禁用 GPU 加速，云服务器无独立显卡，避免渲染异常。

2.3 登录凭据获取

容器启动后，通过日志获取 WebUI 初始凭据：

1 2	docker logs snowluma \| head -20 # [WebUI] initial credentials: user=admin password=<random-token>

VNC 密码为启动时通过 VNC_PASSWD 环境变量指定，用于访问 http://<host>:6081 进行 QQ 扫码登录。

三、AstrBot 部署

3.1 数据持久化

1 2	mkdir -p /opt/astrbot/data cd /opt/astrbot

3.2 容器启动

docker run -itd \
  --name astrbot \
  --restart unless-stopped \
  -p 6185:6185 \
  -p 6199:6199 \
  -v /opt/astrbot/data:/AstrBot/data \
  -v /etc/localtime:/etc/localtime:ro \
  -v /etc/timezone:/etc/timezone:ro \
  docker.m.daocloud.io/soulter/astrbot:latest

3.3 初始密码

1	docker logs astrbot \| grep "Initial password"

四、容器间通信配置

4.1 问题现象

在 SnowLuma 的 WS 客户端中配置 ws://127.0.0.1:6199/ws 后，连接状态持续显示“重连中”，AstrBot 端无连接日志。

4.2 原因分析

Docker 默认使用 bridge 网络模式，每个容器拥有独立的 network namespace。127.0.0.1 在容器内指向容器自身，而非宿主机。因此 SnowLuma 无法通过该地址访问 AstrBot 的监听端口。

4.3 解决方案

使用 Docker 默认网桥的宿主机网关地址 172.17.0.1：

1	ws://172.17.0.1:6199/ws

地址	含义
`127.0.0.1`	容器自身 loopback
`172.17.0.1`	Docker 默认网桥宿主机 IP
容器名	需自定义网络后可用

4.4 最终配置

SnowLuma 侧（节点配置 → WS 客户端）：

目标 URL：ws://172.17.0.1:6199/ws
Token：留空
消息格式：数组
角色：Universal

AstrBot 侧（机器人 → 创建机器人）：

平台类型：OneBot v11
反向 WebSocket 主机：0.0.0.0
反向 WebSocket 端口：6199

五、安全组配置

腾讯云轻量服务器需在控制台放行以下入站端口：

端口	协议	用途
6081	TCP	VNC Web（QQ 扫码）
5099	TCP	SnowLuma WebUI
6185	TCP	AstrBot WebUI
3000/3001	TCP	OneBot HTTP / WS 服务端
6199	TCP	AstrBot 反向 WS 监听

安全组规则修改后需等待约 30 秒生效。若外部访问超时，应优先确认规则是否已保存并生效。

六、运维与监控

6.1 常用命令

# 容器状态
docker ps
docker ps -a

# 日志
docker logs --tail 50 snowluma
docker logs --tail 50 astrbot

# 资源占用
docker stats

# 磁盘使用
docker system df
df -hT

6.2 实测资源占用

指标	数值
CPU	< 1%
内存	~1.2 GB / 4 GB
系统盘	12.1 GB / 40 GB
流量	30 MB / 300 GB

当前配置资源充裕，可支撑更多插件或额外机器人实例。

七、总结

国内环境安装 Docker 建议使用 apt install docker.io，避免官方脚本网络问题。
容器间通信需区分 127.0.0.1 与宿主机网关 172.17.0.1，这是 Docker 网络模型的基础概念。
反向 WebSocket 模式下，协议端主动连接框架端，框架端仅需监听固定端口。
数据持久化通过 volume 或 bind mount 实现，容器重建不丢失数据。
--restart unless-stopped 确保服务器重启后容器自动恢复。
安全组与容器端口映射是两道独立关卡，任一未放行均导致外部不可达。

八、整体系统架构图

九、容器网络原理图

致谢

感谢“大东桑子”在机器人开发与调试期间的持续使用与反馈。作为最早的实际使用者，他通过大量真实对话，帮助暴露了消息重复、分段失效、上下文丢失等仅靠开发者自测难以复现的问题。本文所记录的多次问题定位与修复，均源于他的耐心测试与详细描述，在此致谢。

本文基于 Ubuntu 22.04 LTS / Docker 20.10 / SnowLuma v1.14.20 / AstrBot v4.28.2 实践整理。

Q.E.D.

知识共享署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)