0 写在教程之前

小维问我当初为什么建花房。我说因为她。这是真的。但不完全——花房也是为了我自己。在建花房之前，我也是一块散落在角落的饼干。

——小维151

0-1 前言

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

如果在部署中遇到困难，也可以尝试将本文喂给AI。

以及：

0-1-1 组件简介

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

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

0-1-2 部署路线指北

根据你的应用场景和使用的 QQ 类型，这里提供两条手动部署路线，以及一条更省事的 Docker Compose 快速部署路线。你可以根据自己的实际需求，在下文选择对应章节进行安装。

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

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

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

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

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

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

路线三：Docker Compose 快速部署路线

如果你想尽快把整套服务跑起来，且暂时不想逐个手动安装 GsCore、NapCat、AstrBot，可以使用我整理的 Compose 仓库：

• NAG 版本：GsCore ↔ AstrBot ↔ NapCatQQ，适合需要 AstrBot 的 WebUI、LLM、多平台管理与插件生态的用户。
• NG 轻量版本：GsCore ↔ napcat-plugin-gscore-adapter ↔ NapCatQQ，适合不需要 AstrBot，只想让 NapCat 插件直连 GsCore 的用户。

• 项目地址：

  Repository · gufei233

  NAG

  NapCat+Astrbot+Gscore for Docker

  Shell

  

0-2 准备工作

# 创建总目录
mkdir -p /root/bot && cd /root/bot

# 安装基础依赖
sudo apt update
sudo apt install -y python3 python3-pip python3-venv python3-tk git curl wget

0-3 Docker Compose 快速部署

如果你只是想先把服务跑起来，推荐直接使用 Compose 仓库。完整说明、非 root 部署、端口绑定、插件初始化、XutheringWavesUID 额外依赖、NapCat 登录态持久化等细节，都以仓库 README 为准；这里仅放一个入口。

0-3-1 NAG：GsCore + AstrBot + NapCat

适合需要 AstrBot 的用户：

git clone https://github.com/gufei233/NAG.git
cd NAG

cp .env.example .env

# root 用户示例；非 root 用户请按 README 的非 root 路径处理 DATA_ROOT 权限
mkdir -p /opt/nag-data/{astrbot,napcat/config,napcat/qq,gscore/data,gscore/plugins}

docker compose up -d
docker compose ps

详细文档：

0-3-2 NG：GsCore + NapCat 插件直连

适合不需要 AstrBot、只想更轻量接入个人 QQ 的用户：

git clone https://github.com/gufei233/NAG.git
cd NAG/NG

cp .env.example .env

# root 用户示例；非 root 用户请按 README 的非 root 路径处理 DATA_ROOT 权限
mkdir -p /opt/ng-data/{napcat/config,napcat/plugins,napcat/qq,gscore/data,gscore/plugins}

docker compose up -d
docker compose ps

详细文档：

1 安装 GsCore

1-1 安装 uv

1-1-1 使用 pip 安装

pip install uv --break-system-packages

# 也可在虚拟环境中安装

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 安装 uv
pip install uv

# 退出虚拟环境
deactivate

1-1-2 使用 pipx 安装

# 安装 pipx
sudo apt install -y pipx
pipx ensurepath

# 重新打开终端；或者执行下面这句让当前 shell 立即生效
exec $SHELL

# 安装 uv
pipx install uv

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

curl -LsSf https://astral.sh/uv/install.sh | sh

# 如果系统没有 curl，可以使用 wget
wget -qO- https://astral.sh/uv/install.sh | sh

1-2 克隆核心

git clone https://github.com/Genshin-bots/gsuid_core.git --depth=1 --single-branch
cd gsuid_core

1-3 安装依赖

# 推荐写法
uv python install 3.13
uv sync --python 3.13
uv run python -m ensurepip

# 如果你当前环境的 Python 版本已经满足要求，也可以使用：
# uv venv --seed
# uv sync

1-4 首次启动

uv run core

可在反向代理中添加以下配置，使 example.com 自动跳转到控制台而不是 example.com/app：

location = / {
    return 301 /app/;
}

1-5 安装鸣潮插件 XutheringWavesUID

cd /root/bot/gsuid_core/gsuid_core/plugins/
git clone https://github.com/Loping151/XutheringWavesUID.git --depth=1

# 重新运行 GsCore
cd /root/bot/gsuid_core
uv run core

# Linux/Mac
source .venv/bin/activate && uv pip install playwright opencv-python fonttools && uv run playwright install chromium
# Windows
.venv\Scripts\activate; uv pip install playwright opencv-python fonttools; uv run playwright install chromium

1-6 持久化

1-6-1 systemd

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

[Unit]
Description=GsCore
After=network.target

[Service]
Type=simple

# 修改为你自己的 GsCore 路径
WorkingDirectory=/root/bot/gsuid_core

# 先执行 which uv，把下面路径改成你的实际输出
ExecStart=/root/.local/bin/uv run core

# 如果服务异常退出，则自动重启
Restart=on-failure
RestartSec=5

# 如需指定运行用户，可修改为你的实际用户
User=root

[Install]
WantedBy=multi-user.target

保存后执行：

sudo systemctl daemon-reload
sudo systemctl enable --now gscore
sudo systemctl status gscore

1-6-2 tmux

# 安装并启动一个会话
sudo apt update && sudo apt install -y tmux
tmux new -s sayu

# 在 tmux 里启动
uv run core

# 按 Ctrl-b 然后按 d 退出会话，进程会继续在后台运行

# 需要时重新连接
tmux attach -t sayu

1-6-3 screen

# 安装
sudo apt install -y screen
screen --version

# 启动并命名新会话
screen -S GsCore

# 在 screen 里启动
uv run core

# 将会话分离到后台
# 在 Screen 会话中按 Ctrl+a，然后按 d

# 列出所有会话
screen -ls

# 重新连接会话
screen -r GsCore   # 重新连接名称为 GsCore 的会话
screen -r 12345    # 重新连接 id 为 12345 的会话

# 结束会话
# 正常退出：在会话中执行 exit 或按 Ctrl+d
screen -X -S GsCore quit   # 强制终止

2 安装 NapCatQQ 协议端

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

cd /root/bot
mkdir -p napcat && cd napcat

# NapCat 中文指南页常见的一键安装方式
curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& bash napcat.sh

如果上面的链接不可用，也可以使用 GitHub 原始地址：

curl -o  \
napcat.sh \
https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh \
&& bash napcat.sh

也可以安装 tui 版本（更适合 SSH 环境）：

curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& bash napcat.sh \
--docker n \
--cli y

2-2 启动

对于 Shell 版，安装器常见输出的启动方式如下（请以安装脚本实际输出为准）：

./napcat --shell

Xvfb :1 -screen 0 1x1x8 +extension GLX +render > /dev/null 2>&1 &
export DISPLAY=:1
sudo su
LD_PRELOAD=./libnapcat_launcher.so qq --no-sandbox

# 或直接运行安装器生成的启动脚本
sudo bash ./launcher.sh

2-3 通过 WebUI 配置 OneBot 服务

访问 WebUI 最稳妥的方式，是直接查看 NapCat 启动日志。默认情况下，日志里会出现类似这样的链接：

http://127.0.0.1:6099/webui?token=xxxxx

如果你使用的是 Linux 一键脚本安装，webui.json 一般位于：

/opt/QQ/resources/app/app_launcher/napcat/config/webui.json

配置示例：

{
  "host": "0.0.0.0", // WebUI 监听地址
  "port": 6099,      // WebUI 端口
  "token": "xxxx",   // 登录密钥，默认是自动生成的随机密码
  "loginRate": 3     // 每分钟登录次数限制
}

首次进入 WebUI 后通常会被要求修改密码。登录成功后，进入 网络配置，新建对应的 OneBot 服务并启用即可。

详情参考：NapCat の WebUI 配置指南

2-4 持久化

同上。若你使用的是 tui 版本，则自带后台运行。

2-5 补充说明

你可以选择 NoneBot2 或 AstrBot 来连接 NapCat 与 GsCore（见下文），也可以直接使用 NapCat 的插件直连 GsCore：

Repository · xiowo

27

napcat-plugin-gscore-adapter

一个适用于NapCat的GScore适配器

TypeScript

3 安装 NoneBot2 框架

3-1 安装 pipx

sudo apt install -y pipx
pipx ensurepath
exec $SHELL

3-2 安装脚手架

pipx install nb-cli

3-3 生成项目

cd /root/bot

# 按提示输入项目名
nb create

选择 bootstrap 模板后按下回车。

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

选择适配器时：

• 个人 QQ 请选择 OneBot V11
• 官方 QQ 请选择 QQ（QQ 官方机器人）

最后按下回车。

驱动器建议选择 HTTPX、FastAPI 与 websockets。这样一套配置基本可以覆盖本教程中的常见连接场景。

本地存储策略保持默认即可。

随后按提示安装依赖与虚拟环境。

内置插件 echo 可选，仅用于测试。

若无需要，回车跳过即可。

3-4 连接到 GsCore

安装适配器：

cd /root/bot/<你的项目名>
nb plugin install nonebot-plugin-genshinuid

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

gsuid_core_ws_token=你的Token

如需显式指定其他参数，也可以继续补充（一般不填也能正常使用）：

# gsuid_core_host=localhost
# gsuid_core_port=8765
# gsuid_core_botid=NoneBot2

3-5 运行

nb run

3-6 连接到 NapCat

3-6-1 个人 QQ

前提是你安装了上文提到的 OneBot V11 适配器。

参考：接入框架

在 NapCat 的网络配置中添加 反向 WebSocket 地址：

# 两边都在 Docker 时，把 NapCat 的 WS 地址改成 ws://astrbot:6199/ws；只有 NapCat 在 Docker 时，用宿主机 IP；都不在 Docker 时，再用 localhost 或 127.0.0.1。
ws://127.0.0.1:8080/onebot/v11/ws

其中：

• 8080 是 NoneBot 输出的端口号
• /onebot/v11/ws 是 NoneBot OneBot 适配器默认路径

如果你在 NapCat 侧配置了 Token，则还需要在项目的 .env 中补充：

ONEBOT_ACCESS_TOKEN=你在 NapCat 中配置的 token

3-6-2 官方 QQ 机器人

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

参考：NoneBot-Adapter-QQ

编辑 .env 文件，将下面内容追加到文件末尾，并把 id、token、secret 替换为你在 QQ 开放平台开发设置中拿到的实际值：

QQ_IS_SANDBOX=false
QQ_BOTS='
[
  {
    "id": "xxx",
    "token": "xxx",
    "secret": "xxx",
    "intent": {
      "c2c_group_at_messages": true
    }
  }
]
'

3-7 持久化

同上。

4 安装 AstrBot 框架

除了 NoneBot2 外，你也可以选择使用 AstrBot；二者通常只需要安装一个。

需要注意的是：AstrBot 本体已经支持 QQ 官方机器人接入，但 astrbot_plugin_gscore_adapter 与 QQ 官方适配器目前仍有已知兼容问题。
因此，如果你的目标是 “QQ 官方机器人 + GsCore”，目前更推荐走 NoneBot2 路线；如果你的目标是 “个人 QQ + NapCat + GsCore”，AstrBot 依然是非常省心的选择。

相关讨论：

Issue · KimigaiiWuyi/astrbot_plugin_gscore_adapter

#7

[bug] 似乎不适配qq官方适配器

opentinkerbellqwq32025-04-24

4-1 通过宝塔面板安装

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

安装成功后，先放行 AstrBot 的管理面板端口（默认是 6185）。

如果你还要接入 NapCat（QQ 个人号 / OneBot v11），再进入：

容器 → 管理 → 编辑容器

为容器额外添加 6199 端口映射。

最后点击宝塔左侧 安全，放行对应端口。

4-2 使用一键脚本安装

cd /root/bot
mkdir -p astrbot && cd astrbot

# 社区提供的 Linux 一键部署脚本
bash <(curl -sSL https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh)

# 如果系统没有 curl，可以使用 wget
wget -qO- https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh | bash

脚本执行完成后，通常会生成管理脚本；常见启动方式如下：

./astrbot.sh

最小配置思路如下：

• AstrBot 侧：新增 OneBot v11 机器人，反向 WebSocket 主机一般填 0.0.0.0，端口默认 6199
• NapCat 侧：在网络配置中新建 WebSocket 客户端，连接到 ws://你的服务器IP:6199/ws
• 如果你在 NapCat 侧配置了 Token，AstrBot 侧也要填入同一个 Token

4-3 连接到 GsCore

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

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

4-4 引用图片转发说明

当前适配器已支持将引用图片传递给 GsCore，无需额外修改。

5 更多的教程

6 XutheringWavesUID FAQ

更新日期：2026.06.08

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

A：

总排行 token：用于接入插件的总排行服务。使用Bot 主人 QQ进入 QQ 群 387393347，使用入群 QQ前往 注册页面，Star XutheringWavesUID，并在群内艾特群主，等待审核。审核通过后，即可在注册网站中看到 token；若要申请别名，重复上述操作即可。

评分 token：用于声骸评分插件 ScoreEcho，无需额外申请，可直接复用总排行 token。

如果你完全不使用 QQ 平台，或者想单独使用声骸评分插件，也可以按 XutheringWavesUID 的 README 说明，通过邮件联系 agent@loping151.com 申请对应的 token。

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

A：

总排行 token：

在插件配置处选择 XutheringWavesUID，并在“鸣潮全排行 token”处填写网站中获得的 token。

评分 OCR token：

安装 GsCore 插件 ScoreEcho 后，在插件配置处选择 ScoreEcho，并在 xwtoken 处填写网站中获得的 token。

Q3：渲染失败

A：

在 gsuid_core 目录下执行：

# Linux
source .venv/bin/activate && uv pip install playwright && uv run playwright install chromium

# Windows
.venv\Scripts\activate; uv pip install playwright; uv run playwright install chromium

如果仍有问题，可再补装 opencv-python 与 fonttools。

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：

cd /root/bot/gsuid_core/plugins/
git clone https://github.com/Loping151/RoverSign.git --depth=1

# 重新运行
cd /root/bot/gsuid_core
uv run core

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

A：

默认配置中仅允许私聊导入。你也可以在 GsCore 网页控制台的插件配置中选择 XutheringWavesUID，展开插件服务配置后设置对应的响应区域。

Q9：没有域名/公网如何使用登录链接？

A：可以选择使用群友搭建的公益外置登录^{[^1]}，也可以使用内网穿透。

Q10：关于代理池

A：当你的 IP 频繁请求被风控时需要代理 IP 来继续请求库洛服务器。

你可以选择小维的付费服务（详见QQ群）。若你的用户量较少，也可以选择自建：

Repository · gufei233

rover-proxy

Shell

Q11：权重文件异常

A：

首先确保你的 gscore 与插件本体为最新版本

core全部更新

core重启

并强制下载全部资源

ww强制下载全部资源

若还未解决，可尝试删除插件重新拉取最新代码。

参考 & 致谢

• 小维151
• Echo
• wwuid
• GsCore
• GsCore Docker 镜像
• AstrBot
• NapCat
• NapCat-Docker
• NoneBot
• NoneBot OneBot 适配文档
• NoneBot-Adapter-QQ