Eridanus

Appearance

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

遇到终端刷红报错或者更新卡住千万不要慌张！
文档早就把大家平时最容易踩到的小水坑总结成排障清单啦，按照下面的步骤一步步检查，99% 的问题都能迎刃而解哦~

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

更新代码时最担心的就是新版本的配置文件把我们自己辛苦填好的 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' 或找不到某个第三方库。
  • 排障方法： 通常是因为未在虚拟环境中运行，或者更新后项目引入了新依赖。进入终端执行：
    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 端口。