个人实践 · 容器部署 · 消息机器人

如何搭建
鸣潮 Bot

从接收到第一条消息，到把服务稳定地维护下去。

整理于 · 阅读约 15 分钟

搭建 Bot 最容易让人迷糊的地方，是把 QQ 连接、指令处理、游戏查询和网页登录当成了同一个程序。实际上，它们常常运行在不同进程里。一条消息能否得到回复，取决于这些进程之间的连接是否完整。

这篇手记介绍我使用的一种组合：QQ 客户端与 LLBot 接入消息，AstrBot 组织插件，GSUID Core 承载游戏查询，XutheringWavesUID 提供鸣潮相关功能。它是一条可选路线，各项目安装界面和配置字段会随版本变化。下面重点说明连接方法、检查顺序与数据边界，具体安装包请以文末项目原始文档为准。

本文是个人学习记录，与鸣潮官方无关联。所有命令中的目录和服务名都是示例；请在自己的测试环境中替换后执行。本文不包含真实服务器凭证、玩家登录信息或聊天记录。

01 / FOUNDATION

准备环境时，先想清楚数据放在哪里

我倾向于用 Linux 与 Docker Compose 管理多服务项目。第一步先完成 SSH 登录与 Docker 安装，再看磁盘、内存和时间是否正常。图片渲染、插件数量与活跃用户都会影响资源消耗，所以不要仅按“容器启动成功”判断机器够用；小范围试运行后再观察内存峰值和响应时间。

# 在自己的 Linux 测试机上检查基础环境
docker --version
docker compose version
free -h
df -h
timedatectl status

把工作目录分成四类会更容易维护：Compose 配置、程序代码、持久数据和备份。代码可以重新下载，登录状态和用户绑定数据却不能随意重建。尤其要确认 QQ 客户端登录目录、插件数据库与业务配置挂载到了持久目录或命名卷。

# 示例目录结构，不是安装命令
bot-lab/
├── compose/       # 服务编排
├── apps/          # 程序与插件
├── data/          # 持久数据
└── backups/       # 按日期保存的回退副本

第一次运行前先检查 Compose 的卷映射和端口映射。管理面板尽量只绑定 127.0.0.1，远程管理通过 SSH 隧道完成。同一个 Docker 网络里的服务通常用服务名互相访问；容器内的 127.0.0.1 指向这个容器自身，不是宿主机，也不是另一个容器。

这一阶段的完成标志：能通过 SSH 管理机器；Docker 正常工作；知道每一份登录数据和数据库保存在哪里。

02 / MESSAGE TRANSPORT

先让 QQ 消息可靠地进来和出去

在这套组合中，QQ 客户端维持账号会话，LLBot 将平台事件转换为 OneBot 消息，AstrBot 接收事件并发送回复。先完成这一段，再接游戏插件，排错范围会小很多。平台适配方式会变化，使用前应阅读平台规则与适配项目说明。

  1. 按所选适配项目的文档启动客户端和适配层，完成本人账号登录，确认在线状态。
  2. 在 AstrBot 配置对应的 OneBot 适配器，并配置接收事件的监听地址、端口和路径。
  3. 把适配层的反向 WebSocket 地址指向 AstrBot；两端的访问令牌保持一致，并留在私有配置中。
  4. 在自己控制的测试会话发送一条简单指令，观察入站事件、指令处理与发送结果。

反向 WebSocket 的“反向”是说适配层主动连接 Bot 服务。如果把目标填写成适配层自己的地址，两个容器即使都显示运行中，也不会形成消息链路。这里要同时核对服务名、端口、路径和协议，不能只比较一个端口数字。

用同一条测试消息对齐日志

记下发送时间，分别查看适配层和 AstrBot 同一时间窗口的日志。适配层看到消息、AstrBot 没看到时，优先检查连接；AstrBot 已执行命令但 QQ 没收到时，继续检查出站 API 的返回结果。只读与该问题相关的小段日志，分享截图前遮住群号、令牌和消息内容。

这一阶段的完成标志：同一条测试消息能从 QQ 进入 AstrBot，并把回复送回原会话。

03 / SERVICE CONNECTION

让 AstrBot 与 GSUID Core 各司其职

AstrBot 是消息处理和插件运行的一层，GSUID Core 是另一套承载游戏插件的核心。本实践通过适配插件把两者连接起来。安装时需要区分：AstrBot 的插件放在 AstrBot 管理的目录，Core 的插件放在 Core 管理的目录，不能因为都叫“插件”就放在同一个地方。

先依照 GSUID Core 项目的安装说明启动核心，确认它能初始化配置和数据库。随后在 AstrBot 安装兼容当前版本的 GSUID 适配插件，将 WebSocket 目标设为 Core 在容器网络中的地址，并对齐适配器要求的 Bot 标识。确认两端日志都记录连接成功，再继续安装游戏功能。

部署前为已验证的版本留下记录：容器镜像标签或摘要、插件版本或提交号、所用适配器版本。不要把所有组件同时升级到未知组合；出现故障时，版本记录能帮助判断是连接配置出错，还是更新带来了接口变化。

把“启动”和“就绪”分开看

Compose 可以组织启动顺序，但依赖容器启动并不总等于应用完成初始化。首次启动可能要下载资源或建立数据库，应观察应用的就绪日志与连接状态。若反复断开，先核对两边的时间、地址、认证和重复连接，不急着循环重启全部服务。

这一阶段的完成标志：Core 初始化结束；AstrBot 与 Core 已连接；一条由 Core 处理的测试指令能返回。

04 / WAVES PLUGIN

安装鸣潮功能，先跑通最小用例

这套实践使用 XutheringWavesUID。它依赖 GSUID Core，不是独立运行的网页。其项目说明提供了安装指令，安装完成后按说明重启 Core；也可以按 Core 的插件管理方式安装。相似名称的项目可能是不同分支，应先确认选用的项目再操作。

# 以下为聊天指令，由有权限的管理员发送
core安装插件XutheringWavesUID

# 安装与重启完成后，先查看插件自己的帮助
ww帮助

安装成功还需要检查资源和依赖。缺少图片、字体或渲染环境时，文本帮助可能正常而图片命令失败。先用帮助指令确认插件加载，再用一个小范围查询检查图片渲染，最后验证需要账号授权的功能。不要一开始就安排全量定时任务。

如果需要签到、提醒等扩展，应分别阅读对应插件的说明，了解它们保存哪些数据、需要哪些权限。每次只增加一个功能，验证通过再继续。对用户的授权材料按敏感数据处理，避免在群聊里粘贴 Cookie、登录令牌或完整回调链接。

把结果写进简短记录：测试了什么指令、预期是什么、回复是否送达、遇到的错误是什么。这样以后升级时可以重复同一组检查，而不是只凭“似乎没报错”判断成功。

这一阶段的完成标志：帮助可见、基础查询可返回，所需图片资源能加载，新增扩展经过逐项验证。

05 / WEB ENTRY

理解域名、端口与网页登录的关系

域名解析负责把名字指向服务器，端口决定访问哪个网络服务，反向代理再按域名或路径分发请求。普通 A 记录只填写 IP 地址，不能把 :11292 写进记录值。是否需要在网址后写端口，由实际监听方式决定。

面向用户的登录页应使用可信 HTTPS。下面是一个 Caddy 路由结构示例：技术文章由静态目录提供，游戏登录相关请求交给内部服务。它不是可覆盖所有插件版本的一键配置；部署前还要根据实际插件确认回调、接口和静态资源路径。

# 示例域名、目录和服务名均需替换
example.com {
    @management path /app /app/* /ws /ws/*
    respond @management "Not Found" 404
    handle /waves/* {
        reverse_proxy core:8765
    }
    handle {
        root * /srv/notes
        file_server
    }
}

反代上线后分层验证：DNS 是否指向目标机器；连接能否到达服务器；TLS 证书是否有效；登录页与资源是否正常；最后用本人账号走一次完整回调。浏览器显示页面并不代表最后的账号绑定成功，测试必须覆盖回调结果。

如果 HTTP 返回云服务商的拦截页面，而服务器内部访问正常，应保留状态码、响应头和测试时间，交给接入服务商核实域名状态。换端口并不能代替域名接入和备案要求。静态文章可以在证书准备期间通过 HTTP 验证，敏感登录过程仍应使用 HTTPS。

这一阶段的完成标志：公开页面和资源可访问，登录证书可信，管理路径不可公开访问，真实回调结果通过检查。

06 / OPERATIONS

出问题时，沿着消息链路排查

我的维护习惯是先记录症状，再定位边界：哪条命令、何时发送、预期回复是什么、实际停在哪里。把故障分成“没收到”“没处理”“没发出”和“网页打不开”，通常比一开始搜索所有错误日志有效。

现象先检查下一步
所有命令无回复QQ 在线状态与适配层入站日志确认到 AstrBot 的连接，再核对权限和指令触发条件
普通回复正常，游戏指令无回复AstrBot 到 Core 的连接核对插件加载、指令处理和下行发送结果
文字正常，图片失败渲染依赖、资源文件与磁盘用单个图片请求定位资源下载或渲染错误
内网能开，域名打不开DNS、响应来源与证书区分云端拦截、网络不通、反代错误和应用错误

下面的命令只展示排查方式。进入自己实际使用的 Compose 项目目录，替换服务名；若项目依赖多个叠加配置文件，应带上相同的 -f 参数。

docker compose config --quiet
docker compose ps
docker compose logs --since 10m --tail 100 astrbot
docker compose logs --since 10m --tail 100 core

升级前，先确认能退回去

备份需要包含配置、持久数据和版本清单。运行中的 SQLite 数据库适合使用数据库提供的一致性备份方式；直接复制正在写入的数据库文件可能得到不完整副本。QQ 登录目录和数据库不要与可再生的下载缓存一起清理。

修改时按服务缩小范围：静态页面更新检查代理即可；游戏插件故障优先处理 Core；QQ 连接正常时不主动重建客户端。完成后复查原来的失败操作、连接日志和数据数量，并记录回退文件的位置。一次成功恢复解决的是眼前故障，只有定位原因并验证修复后，才能判断是否消除了重复发生的条件。

这一阶段的完成标志：有可用备份、能说清每次改动、能复现最小测试，也知道如何恢复到上一版。

READ THE ORIGINALS

继续阅读：项目原始文档

本文的服务组织与检查清单为个人整理。安装方式、功能指令与版本要求应以项目维护者的文档为准，阅读日期为 2026 年 9 月 20 日。

← 返回个人技术分享首页