0 写在教程之前

0-1 前言

在开始配置这套强大且复杂的机器人架构之前，我们先来理清一下各个组件的作用，以及接下来可供选择的部署路线。强烈建议在正式动手敲击终端命令前，将本文档从头到尾完整阅读一遍，对整体流程有概念后再进行操作，能帮你避开绝大多数的配置坑。

0-1-1 组件简介

构建这套体系，我们会用到以下几个核心开源项目：

• GsCore (GenshinUID Core)：一个高度模块化、多平台支持的游戏数据查询与交互框架。它自带强大的网页控制台以及多个游戏插件，负责处理游戏数据（如鸣潮、原神等）的获取、面板渲染和签到等硬核业务逻辑。
• NapCatQQ：基于现代 NTQQ 架构的无头（Headless）QQ 机器人服务端。它的主要工作就是登录你的 QQ 账号，作为底层协议端，稳定地处理消息的收发，并将其通过标准协议（如 OneBot V11）暴露给上层的机器人框架。
• NoneBot2：一个现代、跨平台、异步的 Python 聊天机器人框架。生态极其繁荣，支持海量插件，非常适合作为中间件来连接底层协议端（如 NapCat 或 QQ 官方 API）和业务逻辑端（如 GsCore）。
• AstrBot：一款支持可视化配置、开箱即用的多平台大模型聊天机器人框架。它不仅对接 LLM 体验优秀，通过特定的适配器插件（例如 astrbot_plugin_gscore_adapter），也能极其优雅地将 GsCore 的游戏数据能力集成进来，是轻量化部署的绝佳选择。

0-1-2 部署路线指北

根据你的应用场景和使用的 QQ 类型，这里提供了两条主要的技术路线。你可以根据自己的实际需求，在下文选择对应的章节进行安装：

路线一：个人 QQ（“野鸡”）极速路线

如果你打算使用自己的 QQ 小号来运行机器人，且希望管理面板直观、部署逻辑简洁，推荐这条路线。

• 架构流向：GsCore $\leftrightarrow$ AstrBot $\leftrightarrow$ NapCatQQ $\leftrightarrow$ QQ 客户端
• 实现逻辑：NapCatQQ 负责登录个人 QQ 并将消息转化为网络协议；AstrBot 作为中控大脑接收消息，并通过适配器将涉及游戏查询的指令转发给 GsCore 处理；GsCore 生成精美图片后，原路返回给用户。

路线二：官方 QQ 机器人（“官机”）/ NoneBot 进阶路线

如果你使用的是 QQ 开放平台申请的官方机器人，或者你极其依赖 NoneBot2 庞大的插件生态，推荐这条路线。

• 架构流向：GsCore $\leftrightarrow$ NoneBot2 $\leftrightarrow$ QQ 官方 API (或 NapCat) $\leftrightarrow$ QQ 客户端
• 实现逻辑：NoneBot2 作为桥梁，一方面通过 NoneBot-Adapter-QQ 连接官方接口（或通过 OneBot 协议连接 NapCat），另一方面通过 nonebot-plugin-genshinuid 插件与 GsCore 建立 WebSocket 通信，实现功能的全面打通。

Warning

注意事项

1. 切勿盲目复制：文中的路径（如 /root/bot）和端口（如 8765, 8080, 6199）为示例配置。如果你有自己的网站（例如挂在 Nginx 上的博客），请注意端口防冲突。
2. 网络环境：拉取 GitHub 仓库或安装依赖时可能会遇到网络波动，请灵活使用文中提供的国内镜像源（如 pip 换源、uv 代理或镜像仓库）。
3. 账号安全：各个控制台（GsCore、AstrBot、NapCat WebUI）启动后，务必第一时间修改默认密码和 Token。

0-2 准备工作

1 安装 GsCore

1-1 安装 uv

1-1-1 使用 pip 安装

1-1-2 使用 pipx 安装

1-1-3 使用官方脚本安装

1‑2 克隆核心

1‑3 安装依赖

1‑4 运行

Important

网页控制台：首次启动即生成，默认地址 localhost:8765/genshinuid，账号密码 root/root。务必登录后修改密码。

WS_TOKEN：建议填写，填写后应在对应的适配器内设置该 token，若不填写则只有TRUSTED_IPS配置项中的 IP 可与 GsCore 连接。

若要外网访问，把 bot/gsuid_core/data/config.json 里的 HOST 改成 0.0.0.0 后重启，或直接反向代理localhost:8765即可。

可在反向代理中添加以下配置来实现example.com指向控制台而不是example.com/genshinuid:

CodeBlock Loading...

Tip

除此之外你也可以使用 Docker 快速部署

1‑5 安装鸣潮插件 XutheringWavesUID

1-6 持久化

1-6-1 systemd

在 /etc/systemd/system/目录下创建一个以 .service为后缀的文件并写入如下基本内容：

1-6-2 tmux

1-6-3 screen

2 安装 NapCatQQ 协议端

2‑1 下载并运行一键脚本

也可以安装tui版本：

2‑2 启动

Tip

若为tui版本可输入sudo napcat并在可视化界面中进行配置、启动。

2-3 通过 WebUI 配置 OneBot 服务

在/root/bot/napcat/napcat/config/webui.json或tui中可配置 WebUI 相关信息。

详情参考 NapCatのWebUI配置指南

2-4 持久化

同上。

3 安装 NoneBot2 框架

3-1 安装 pipx

3‑2 安装脚手架

3-3 生成项目

也可以直接使用以下指令安装并生成项目

选择bootstrap模板后按下回车。

输入项目名称后按下回车。

↑ ↓移动，空格选择，个人QQ选择OneBot V11，官方QQ选择QQ（QQ 官方机器人），最后按下回车。

同上，选择HTTPX与websockets驱动器后按下回车。

保持默认按下回车。

安装依赖与虚拟环境。

可选echo插件。

若无需要回车跳过即可。

3‑4 连接到 GsCore

安装适配器

若你在 GsCore 中设置了WS_TOKEN，则需要在.env中添加：

3‑5 运行

3-6 连接到 NapCat

3-6-1 个人 QQ

前提是你安装了上述提到的OneBot V11。

参考 接入框架

在 NapCat 配置添加反向 WS 地址，地址为ws://127.0.0.1:8080/onebot/v11/ws, 这里的8080是 NoneBot 输出的端口号，/onebot/v11/ws是 NoneBot onebot 适配器默认的路径并设置Token

修改项目中 NoneBot 配置文件.env，添加ONEBOT_ACCESS_TOKEN=你在 NapCat 中配置的 token。

3-6-2 官方 QQ 机器人

前提是你安装了上述提到的QQ（QQ 官方机器人）。

参考 NoneBot-Adapter-QQ

编辑.env文件。将下面这段代码追加到文件后，将id、token、secret更改为开发设置中自己机器人的信息。

3-7 持久化

同上。

4 安装 AstrBot 框架

除了 NoneBot2 外，你可以选择使用 AsrtBot，两者只需要安装一个。需要注意的是，AstrBot 对官方机器人的支持不佳，目前无法正常通过 GsCore 发送消息，所以若你需要搭建官方机器人，请选择 NoneBot2。

4-1 通过宝塔面板安装

进入Docker的应用商店，搜索AstrBot并安装。

安装成功后，点击Docker栏容器，找到AstrBot容器，点击管理，点击编辑容器，添加6199端口（QQ 个人号(aiocqhttp) 消息平台默认端口）。

最后点击宝塔左侧安全，放行对应的AstrBot端口（默认是6185端口）与6199端口。

4-2 使用一键脚本安装

Important

网页控制台：首次启动即生成，默认地址 http://127.0.0.1:6185，账号密码 astrbot/astrbot。务必登录后修改密码。
具体配置参考 接入到NapCat

4-3 连接到 GsCore

在 AstrBot 的插件商店安装astrbot_plugin_gscore_adapter并配置。

• 链接至GsCore的IP地址：默认填写localhost
• 链接至GsCore的端口：默认填写8765
• 向GsCore注册自身的Bot：默认应为AstrBot
• 连接Core的WsToken：即在 GsCore 中设置的值。

4-4 增加 GsCore 适配器对引用图片的转发

目前适配器已支持将引用图片传递给 GsCore。

6 更多的教程

7 XutheringWavesUID FAQ

Q1：申请总排行 token / 评分 OCR token ？

A：

总排行 token：进 QQ 群653696746387393347，使用 入群 QQ 注册，star XutheringWavesUID，在 群内 艾特群主，等待审核。审核通过后在注册的网站内即可看到 token，若要申请别名，重复上述操作。

评分 token：star ScoreEcho，在 群内 艾特群主，等待审核。

Warning

请勿私聊。

Q2：总排行 token / 评分 OCR token 填在哪里？

A：

总排行 token：

评分 OCR token：

安装 GsCore 插件 ScoreEcho 后填入：

Q3：渲染失败？

A：在 gsuid_core 目录下执行：

Q4：git clone 网络问题？

A：使用镜像：GitCode CNB

Q5：如何自定义添加体力背景图

A：

1./root/bot/gsuid_core/data/XutheringWavesUID/alias/下面的id2name.json添加对应 id，记得要足够复杂和鸣潮的 id 避开

2.同目录下的char_alias.json中，加上他的alias

3.使用ww上传xx背景图上传。

Q6：tmux 与 screen 滚动与查看历史输出

A：

tmux：按下Ctrl+B后按[键，使用方向键或PageUp/PageDown滚动，按q键退出。

screen：按下Ctrl+A后按[键，使用方向键或PageUp/PageDown滚动，按q键退出。

Q7：签到插件

A：

Q8：群聊内发送导入抽卡链接无反应

A：默认配置中仅允许私聊导入，你也可以通过在 GsCore 网页控制台内修改对应指令的功能服务配置。

参考 & 致谢

wwuid

 GsCore

AstrBot

NapCat

NoneBot

https://github.com/Loping151

https://github.com/tyql688