Linuxで鳴潮Bot「XutheringWavesUID」をインストールする

クイックナビゲーション

• 0 チュートリアルを始める前に：コンポーネントの理解、ルートの選択、環境の準備
• 1 GsCoreのインストール：コア、鳴潮プラグイン、バックグラウンド実行のインストール
• 2 NapCatQQのインストール：個人QQプロトコルエンド
• 3 NoneBot2のインストール：個人QQまたはQQ公式Botルート
• 4 AstrBotのインストール：個人QQとLLMルート
• 5 発展チュートリアル
• 6 XutheringWavesUID FAQ

0 チュートリアルを始める前に

小維がなぜ花房を作ったのか聞いてきた。彼女のためだと言った。それは本当だ。でも、それだけじゃない——花房は自分のためでもあった。花房を作る前、私も隅っこに落ちているクッキーのようなものだった。

——小維151

0-1 はじめに

この強力で複雑なBotアーキテクチャの設定を始める前に、各コンポーネントの役割と、これから選択できるデプロイルートを整理しておきましょう。実際にターミナルでコマンドを叩き始める前に、このドキュメントを最初から最後まで一度読んでおくことを強くお勧めします。全体の流れを把握してから操作を始めれば、ほとんどの設定の落とし穴を避けられます。

デプロイ中に問題が発生した場合は、このドキュメントをAIに読み込ませてみるのも手です。

および：

0-1-1 コンポーネント概要

このシステムを構築するにあたり、以下の主要なオープンソースプロジェクトを使用します：

• GsCore（GenshinUID Core）：高度にモジュール化され、マルチプラットフォームに対応したゲームデータクエリ・対話フレームワーク。Webコンソールと複数のゲームプラグインを内蔵し、ゲームデータ（鳴潮、原神など）の取得、パネルレンダリング、デイリーログインなどのコアビジネスロジックを処理します。
• NapCatQQ：NTQQベースのQQプロトコルエンド。Shell Mode（ヘッドレスサーバー向け）またはFramework Mode（QQクライアントに注入）で動作可能。主な役割はあなたのQQアカウントにログインし、プロトコルエンドとしてメッセージの送受信を安定して処理し、標準プロトコル（OneBot V11など）を介して上位のBotフレームワークに公開することです。
• NoneBot2：モダンでクロスプラットフォーム、非同期のPythonチャットボットフレームワーク。エコシステムが非常に豊富で、多数のプラグインをサポートしており、プロトコルエンド（NapCatやQQ公式APIなど）とビジネスロジックエンド（GsCoreなど）を接続するミドルウェアとして最適です。
• AstrBot：ビジュアル設定に対応し、すぐに使えるマルチプラットフォーム大規模言語モデル（LLM）チャットボットフレームワーク。LLMとの連携が優れているだけでなく、特定のアダプタープラグイン（astrbot_plugin_gscore_adapterなど）を使用することで、GsCoreのゲームデータ機能を比較的スマートに統合できるため、軽量デプロイに適しています。

0-1-2 デプロイルートガイド

あなたのユースケースと使用するQQの種類に応じて、主に3つの手動デプロイの組み合わせを提供します。実際のニーズに合わせて、該当する章を読んでインストールを進めてください。

ルート1：個人QQ（"野良"）クイックルート

自分のQQサブアカウントでBotを運用し、管理画面が直感的でデプロイロジックがシンプルなものをお求めなら、このルートをお勧めします。

• アーキテクチャフロー：GsCore ↔ AstrBot ↔ NapCatQQ ↔ QQクライアント
• 実装ロジック：NapCatQQが個人QQにログインし、メッセージをネットワークプロトコルに変換。AstrBotが中央制御としてメッセージを受信し、アダプターを介してゲームクエリに関する命令をGsCoreに転送して処理。GsCoreが画像を生成し、元の経路でユーザーに返します。

ルート2：QQ公式Bot / NoneBot上級ルート

QQオープンプラットフォームで申請した公式Botを使用する場合、またはNoneBot2の広大なプラグインエコシステムに強く依存する場合、このルートをお勧めします。

• アーキテクチャフロー：GsCore ↔ NoneBot2 ↔ QQ公式API（またはNapCat） ↔ QQクライアント
• 実装ロジック：NoneBot2がブリッジとして機能し、一方でNoneBot-Adapter-QQを介して公式インターフェースに接続（またはOneBotプロトコルを介してNapCatに接続）、もう一方でnonebot-plugin-genshinuidを介してGsCoreとWebSocket通信を確立し、機能を連携させます。

0-1-3 よく使うポート一覧

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

1 GsCoreのインストール

この章はすべてのルートに共通する基礎です。GsCoreと鳴潮プラグインのインストールが完了したら、ルートに応じて第2、3、または4章に進んでください。

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

# ターミナルを開き直すか、以下のコマンドを実行して現在のシェルに即座に反映
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

GsCoreは現在Python >=3.11,<4.0 を要求しています。ここではPython 3.13を互換範囲内の推奨例として使用しています。

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 pypinyin rapidfuzz && uv run playwright install chromium
# Windows
.venv\Scripts\activate; uv pip install playwright opencv-python fonttools pypinyin rapidfuzz; uv run playwright install chromium

1-6 バックグラウンド実行と永続化

1-6-1 systemd

/etc/systemd/system/gscore.service を作成し、以下の基本内容を記述します：

[Unit]
Description=GsCore
Wants=network-online.target
After=network-online.target

[Service]
# 国内ミラーソース
# Environment="UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple"
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

専用の一般ユーザーでデプロイする場合は、User=root、WorkingDirectory、ExecStart をそのユーザーと対応する絶対パスに置き換えてください。

保存後、以下を実行：

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 プロトコルエンドのインストール

この章は個人QQのみを対象としています。QQ公式Botを使用する場合はこの章をスキップし、NoneBot2のQQ公式Bot設定に直接進んでください。

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

Shellインストール時にTUI-CLIを有効にすることもできます（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版の場合、インストーラーが生成したサービスまたは起動スクリプトを優先的に使用し、インストール完了時の実際の出力に従ってください：

# 例：インストーラーが生成した起動スクリプトを実行
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     // 1分間あたりのログイン試行回数制限
}

初回WebUIアクセス時は、通常パスワードの変更を求められます。ログイン成功後、ネットワーク設定に入り、新しいOneBotサービスを作成して有効にします。

詳細は：NapCatのWebUI設定ガイド を参照

2-4 永続化

インストーラーが生成したサービスやTUI-CLIを使用する場合、通常はバックグラウンド実行機能がすでに備わっています。そうでない場合は、1-6 バックグラウンド実行と永続化 の考え方を参考に設定してください。

2-5 補足説明

NoneBot2 または AstrBot を選択してNapCatとGsCoreを接続する（後述）か、NapCatのプラグインを使用してGsCoreに直接接続することもできます：

Repository · xiowo

28

napcat-plugin-gscore-adapter

一个适用于NapCat的GScore适配器

TypeScript

3 NoneBot2 フレームワークのインストール

NoneBot2ルートを選択した場合にこの章を読んでください。個人QQルートですでにAstrBotを使用することが決まっている場合は、第4章に進んでください。

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 テンプレートを選択したら、Enterキーを押します。

プロジェクト名を入力したら、Enterキーを押します。

アダプターを選択する際：

• 個人QQの場合は OneBot V11 を選択
• 公式QQの場合は QQ（QQ公式Bot） を選択

最後にEnterキーを押します。

ドライバーは HTTPX、FastAPI、websockets を選択することをお勧めします。この組み合わせで、このチュートリアルで想定される一般的な接続シナリオのほとんどをカバーできます。

ローカルストレージ戦略はデフォルトのままで問題ありません。

その後、プロンプトに従って依存関係と仮想環境をインストールします。

内蔵プラグイン echo はオプションで、テスト用です。

不要であれば、Enterキーを押してスキップします。

3-4 GsCoreへの接続

アダプターのインストール：

cd /root/bot/<あなたのプロジェクト名>
nb plugin install nonebot-plugin-genshinuid

GsCoreで WS_TOKEN を設定した場合は、.env に以下を追加します：

gsuid_core_ws_token=あなたのトークン

必要に応じて他のパラメータを明示的に指定することもできます（通常は記入しなくても正常に動作します）：

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

3-5 実行

nb run

3-6 メッセージプラットフォームへの接続

3-6-1 個人QQ：NapCatへの接続

前提として、上記で説明した OneBot V11 アダプターがインストールされていること。

参照：フレームワークへの接続

NapCatのネットワーク設定に リバースWebSocket アドレスを追加します：

# 両方が同じDocker Composeネットワーク内にある場合、ws://nonebot:8080/onebot/v11/ws と記入。NapCatのみがDocker内にある場合、ホストOSの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で設定したトークン

3-6-2 公式QQBot：QQオープンプラットフォームへの接続

前提として、上記で説明した QQ（QQ公式Bot） アダプターがインストールされていること。

参照：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 永続化

1-6 バックグラウンド実行と永続化 を参照してsystemdを設定するか、次のセクションのDockerデプロイ方法を使用してください。

3-8 Dockerデプロイ（オプション）

このドキュメントでは引き続き手動デプロイを中心に説明します。すでに作成したNoneBotプロジェクトをコンテナ化したい場合は、プロジェクトディレクトリでNoneBot公式のDockerプラグインを使用します：

nb self install nb-cli-plugin-docker
nb docker generate
nb docker up
nb docker logs

# 停止
nb docker down

nb docker generate は基本的な Dockerfile と docker-compose.yml を生成します。NapCat、NoneBot、GsCoreが同じComposeネットワーク内にある場合、Composeのサービス名を使用して相互にアクセスします。例：NapCatは ws://nonebot:8080/onebot/v11/ws に接続し、NoneBotがGsCoreに接続する際は gsuid_core_host=gscore と記入し、localhost は使用しないでください。

4 AstrBot フレームワークのインストール

この章は「個人QQ + NapCat + AstrBot + GsCore」ルートに適しています。すでにNoneBot2を選択したユーザーは、通常AstrBotをインストールする必要はありません。

NoneBot2の代わりにAstrBotを使用することもできます。通常はどちらか一方をインストールすれば十分です。

注意点：AstrBot本体はすでにQQ公式Botへの接続をサポートしていますが、astrbot_plugin_gscore_adapter とQQ公式アダプターの間には現在も既知の互換性問題があります。 そのため、目標が 「QQ公式Bot + GsCore」 の場合は、現時点では NoneBot2 ルートをお勧めします。目標が 「個人QQ + NapCat + GsCore」 の場合、AstrBotは依然として非常に手間のかからない選択肢です。

AstrBot公式はDockerとソースコード / uv デプロイ方法を優先的にメンテナンスしています。以下の宝塔やAntliaスクリプトは操作を簡略化したいユーザー