Eridanus

Appearance

常见启动与更新问题排查 ​

(指尖戳戳屏幕) 遇到终端刷红报错或者更新卡住千万不要慌张嘛！
文档早就把大家平时最容易踩到的小水坑总结成排障清单啦。按照下面的步骤一个个排查，99% 的抓狂瞬间都能迎刃而解哦~

一、启动与极简环境底层报错（避坑高频区） ​

1. ImportError: DLL load failed while importing ... 找不到指定的模块 ​

  • 报错现象： 双击脚本或者运行 python main.py 时，瞬间弹窗或终端狂刷：
    text
    ImportError: DLL load failed while importing _sqlite3: 找不到指定的模块。
或 ImportError: DLL load failed while importing ... (如 torch, numpy, orjson)
或 提示缺少 MSVCP140.dll / VCRUNTIME140.dll
  • 成因与救命解法（云服务器 / 挂机宝 / 虚拟机高发！）： 几乎 100% 是因为你用的是挂机宝、Windows Server 云服务器、精简版系统或全新虚拟机！这些系统被深度精简过，缺少了 Windows 最基础的 Visual C++ 运行库。
    解决起来非常简单，不需要重装系统：
    1. 戳微软官方链接下载：👉 微软官方 VC_redist.x64.exe 极速下载
    2. 双击运行安装程序，一路点击“下一步”，几十秒装好；
    3. 重新打开一个终端窗口或重新双击启动脚本，即可瞬间丝滑启动！

2. 'node' 不是内部或外部命令，也不是可运行的程序 / SnowLuma 秒退 ​

  • 报错现象： 双击 SnowLuma 的 launcher.bat 时，黑框一闪而过就自动关闭了；在终端敲命令提示：
    text
    'node' 不是内部或外部命令，也不是可运行的程序或批处理文件。
  • 成因与解决： SnowLuma 协议端本身是用 Node.js 编写与驱动的。系统里还没装 Node.js，或者装好后没有将环境变量刷新。
    • 在 PowerShell 终端敲一行命令安装：
      powershell
      winget install OpenJS.NodeJS.LTS
      或者直接去 Node.js 官方网站 下载 LTS 长期支持版安装。
    • 装完后务必关闭并重新打开终端，敲 node -v，只要能打印出版本号，再跑 launcher.bat 就不会闪退啦！

3. FileNotFoundError: [WinError 2] 系统找不到指定的文件: 'ffmpeg' / 语音发送变哑巴 ​

  • 报错现象： 文字聊天正常，但是机器人使用语音合成、群内点歌或解析视频时，后台提示找不到 ffmpeg，或者发出的语音全是一条条空白：
    text
    FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'
或 ffmpeg: command not found
  • 成因与解决： 系统里缺少 FFmpeg 多媒体转码核心。
    • Windows：PowerShell 执行 winget install Gyan.FFmpeg， 手动下载并将 bin 目录加入系统环境变量 Path 中；
    • Linux：终端直接执行 sudo apt install -y ffmpeg；
    • 装好后在新终端输入 ffmpeg -version 确认有版本输出即可。

二、一键式无损更新与配置合并 ​

更新代码时最担心的就是新版本的配置文件把我们自己辛苦填好的 API Key、Bot 昵称和开关给冲掉对不对？
不用担心！Eridanus 原生支持配置智能合并工具 tool.py：

1. Windows 用户更新步骤 ​

  • 双击运行根目录下的 更新脚本.bat；
  • 该脚本会自动执行 git pull 拉取最新代码，然后自动调用 python tool.py；
  • tool.py 的工作机制是：
    1. 扫描你的所有 run/common_config/ 和各插件配置；
    2. 自动备份当前配置为 .bak 文件；
    3. 比对新版本配置模板，将新增加的键值安全地合并进来，而你原本已经改好的值会 100% 完好无损地保留！

2. Linux 用户更新步骤 ​

bash
cd /opt/Eridanus
source .venv/bin/activate
git pull
python tool.py
sudo systemctl restart eridanus

三、常见更新报错排查 ​

1. Git 网络连接超时 / SSL 握手失败 ​

  • 报错现象：
    text
    fatal: unable to access 'https://github.com/...': Failed to connect to github.com port 443: Timed out
或 OpenSSL SSL_read: Connection was reset
  • 排障方法： GitHub 在国内部分网络环境下可能偶发连不上。如果你本地开启了网络加速工具，可以给 Git 设置全局代理端口（将 7890 替换为你实际的本地代理端口）：
    bash
    git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
    如果加速工具已关闭或不需要代理了，记得及时清除：
    bash
    git config --global --unset http.proxy
git config --global --unset https.proxy
  • 切换 GitCode 镜像源： Eridanus 在 basic_config.yaml 中提供了更新源选项：
    yaml
    # 0为官方GitHub源，1为GitCode国内源
git_update_source: 1
    如果你连接 GitHub 困难，可以将该字段改为 1。

2. Git 提示存在未提交修改冲突 (Merge Conflict) ​

  • 报错现象：error: Your local changes to the following files would be overwritten by merge...
  • 成因与解决： 你可能不小心在 Eridanus 核心代码文件里敲了改动。
    • 如果只是改动了配置文件，配置文件通常都在 .gitignore 中，不会产生冲突；
    • 如果是源码改动，可以使用暂存命令：
      bash
      git stash
git pull
git stash pop
    • 或者直接放弃对核心源码的本地修改：
      bash
      git reset --hard HEAD
git pull

四、启动与协议连接报错排查 ​

1. ModuleNotFoundError 依赖缺失 ​

  • 报错现象：ModuleNotFoundError: No module named 'colorlog' 或找不到某个第三方 Python 库。
  • 排障方法： 通常是因为未在虚拟环境中运行，或者更新后项目引入了新依赖。进入终端执行：
    bash
    # Windows
.\.venv\Scripts\activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# Linux
source .venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

2. OneBot 协议端连不上 / 连接被拒绝 (Connection Refused) ​

  • 报错现象：终端不断提示无法连接到 ws://127.0.0.1:3001，或者 QQ 收发完全没有反应。
  • 逐项核对清白：
    1. 协议端是否已启动并成功登录？ 确认 SnowLuma / NapCat 控制台显示 QQ 账号在线。
    2. 协议类型是否正确？ Eridanus 是主动连接的客户端，因此协议端内必须添加 正向 WebSocket 服务 (WebSocket Server)，而不是反向！
    3. 端口是否一致？ 检查协议端填写的监听端口与 Eridanus 配置文件 run/common_config/basic_config.yaml 中的 ws_link 端口是否完全一致（默认皆为 3001）。
    4. Access Token 是否清空？ 如果协议端设置了访问 Token，而 Eridanus 没配置，握手会被直接拒绝。初次配置最省心的做法是将双方的 Token 均留空。
    5. 防火墙问题：如果协议端和 Eridanus 运行在不同的电脑/虚拟机/容器内，需将 127.0.0.1 改为内网实际 IP，并在宿主机防火墙放行该端口。

3. WebUI 无法访问 ​

  • 默认访问地址：http://127.0.0.1:5007
  • 如果提示连接超时，检查 run/common_config/basic_config.yaml 中的 webui.enable 是否为 true；
  • 如果是云服务器，需要登录云服务器厂商控制台（阿里云/腾讯云/华为云），在“安全组规则”中添加入方向规则，放行 TCP 5007 端口。