鸣潮机器人安装指南

鸣潮机器人（GsCore + XutheringWavesUID）极简安装指南

本文为 Windows/Linux 通用简化版安装指南，步骤简洁无冗余，适配常见报错（含 node not found），可直接对照操作，快速完成鸣潮机器人部署。

一、必备环境安装（必做，奠定基础）

1. Windows 系统

2. Linux 系统（Ubuntu/Debian 适配）

复制以下命令，一键安装所有必备依赖：

sudo apt update
sudo apt install -y python3 python3-pip python3-tk git curl unzip

二、核心组件安装（按顺序执行）

1. 安装 GsCore 早柚核心

# 克隆早柚核心仓库（简化克隆，提升速度）
git clone https://github.com/Genshin-bots/gsuid_core.git --depth=1
# 进入核心目录
cd gsuid_core
# 安装 uv 工具（依赖管理工具）
pip install uv
# 初始化核心依赖
uv sync
# 首次运行，生成必要目录和配置文件
uv run core

2. 安装鸣潮插件（XutheringWavesUID）

# 进入插件目录（核心目录下）
cd gsuid_core/plugins
# 克隆鸣潮插件
git clone https://github.com/Loping151/XutheringWavesUID.git
# 回到核心根目录（后续操作需在此目录）
cd ../..

3. 安装鸣潮签到插件（可选，按需安装）

# 进入插件目录
cd gsuid_core/plugins
# 克隆签到插件
git clone https://github.com/Loping151/RoverSign.git
# 回到核心根目录
cd ../..

4. 连接 QQ（安装 NapCat 协议端）

# 下载并运行 NapCat 一键安装脚本
curl -o napcat.sh https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh && bash napcat.sh
# 启动 NapCat（安装完成后执行）
sudo bash ./launcher.sh

三、机器人启动与控制台访问

1. 启动核心机器人（普通启动，关闭窗口即停止）

# 确保在 gsuid_core 根目录下，执行启动命令
uv run core

2. screen 安装与后台运行（推荐，关闭窗口不停止）

screen 可实现后台运行机器人，避免关闭终端后进程终止，步骤如下：

# 1. 安装 screen（Linux 系统）
sudo apt install screen

# 2. 配置 screen（解决部分系统无法保存会话的问题）
mkdir ~/.screen && chmod 700 ~/.screen
export SCREENDIR=$HOME/.screen
source ~/.bashrc

# 3. 新建 screen 会话（命名为 wwbot，便于后续识别）
screen -S wwbot

# 4. 进入 gsuid_core 根目录，启动机器人
cd gsuid_core
uv run core

# 5. 后台脱离会话（不终止机器人进程）
# 按 Ctrl + a 键，松开后再按 d 键，即可退出会话，机器人后台运行

# 6. 常用 screen 命令（速查）
# 重新连接会话（wwbot 为会话名）
screen -r wwbot
# 查看所有 screen 会话
screen -ls
# 强制终止会话（wwbot 为会话名，谨慎使用）
screen -X -S wwbot quit

3. 访问 Web 控制台

启动成功后，浏览器访问以下地址，进行后续配置（如注册、修改密码）：

本地访问：localhost:8765/app

提示：首次进入控制台需注册，注册码在 bot/gsuid_core/data/config.json 末尾（"REGISTER_CODE" 对应的值）。

四、常见报错修复（针对性解决）

1. 报错：node not found（最常见）

# Windows：重新安装 Node.js，勾选 Add to PATH，重启机器人运行窗口
# Linux 一键安装修复
sudo apt install -y nodejs npm
# 验证安装成功（显示版本号即为正常）
node -v

2. 缺少 tk 依赖报错

sudo apt install -y python3-tk

3. 端口冲突（如 8765 端口被占用）

# 查看 8765 端口占用情况
ss -tulpn | grep 8765
# 结束占用进程（替换 [进程ID] 为查询到的ID）
kill [进程ID]

4. screen 相关报错（如会话无法创建）

# 重新执行配置命令
mkdir ~/.screen && chmod 700 ~/.screen
export SCREENDIR=$HOME/.screen
source ~/.bashrc
# 再次尝试创建会话
screen -S wwbot

五、常用基础命令速查（随时调用）

六、补充说明

1. 若克隆仓库时网络卡顿，可尝试使用国内镜像（如将 github.com 替换为 cnb.cool 镜像地址），或选择网络较稳定的时间段重新执行克隆命令；若中途拉取失败，建议先删除未完成的目录后再重新克隆，避免残缺文件影响后续安装。

2. 所有命令需在对应目录下执行，若提示「目录不存在」或命令执行结果与教程不一致，请优先检查当前路径是否正确；不确定时，可先使用 pwd、cd、ls 等命令确认自己当前所在位置，再继续下一步。

3. 使用 screen 后台运行后，即使关闭终端，机器人也会持续运行；但服务器重启、系统更新重启、或 screen 会话被手动关闭后，仍需重新进入会话并再次启动机器人，这属于正常情况。

4. 如果你是首次部署，建议每完成一个大步骤就先做一次最小验证，例如安装完 Python / Node 后先查看版本号，安装完核心依赖后先确认 uv sync 没有报错，再继续执行插件安装；这样比全部做完后一次性排错更省时间。

5. Windows 用户如果已经安装过多个 Python 或 Node 版本，出现命令可执行但版本不对、插件运行异常、或提示找不到模块时，通常是环境变量指向混乱导致；可先关闭终端重新打开，再分别检查 python --version、pip --version、node -v 是否符合预期。

6. Linux 用户若使用普通账户部署，遇到权限不足、目录无法写入、或某些脚本无法执行时，不要直接跳过报错，建议先确认当前用户是否具备目标目录权限；需要时可在明确风险的前提下使用 sudo 执行安装命令，但机器人运行目录本身尽量保持权限一致，避免后续读写混乱。

7. 插件更新、核心更新、协议端更新不一定总是完全同步，若昨天还能运行、今天更新后突然报错，先不要立刻怀疑所有步骤都错了；更常见的情况是某个依赖版本、插件接口或配置项发生变化，此时优先查看项目仓库的最新说明、更新日志或 issue 区域。

8. Web 控制台首次注册、修改密码、绑定配置后，若页面没有立刻生效，可尝试刷新浏览器、重新登录，或确认后台进程是否仍在正常运行；如果控制台能打开但机器人没有响应消息，通常需要回头检查协议端连接状态和核心日志，而不是只盯着网页本身。

9. 若后续准备长期使用，建议把核心目录、插件目录、关键配置文件位置、控制台地址、注册信息保存方式、以及常用的重启命令单独记一份，后面维护、迁移、换机器或排错时会省很多时间。

10. 实际部署过程中，最重要的不是一次性把所有命令背下来，而是始终保持“当前在哪个目录、当前这一步是否成功、下一步依赖什么条件”这三个信息清楚；只要这三点不乱，大部分报错都能较快定位并修复。

七、相关资源链接（备用）