Terminus Olares One 外置 GPU 指南：在 Olares OS 上连接与配置 NVIDIA eGPU（含 Gen1 临时方案）-育师

云原生
后端
运维

【免费下载链接】Terminus

Open-Source Personal Cloud OS for Always-On Agents

项目地址：https://gitcode.com/gh_mirrors/terminus2/Terminus

Olares One 可以通过雷电 5（Thunderbolt 5 / USB-C）接口连接 NVIDIA 外置显卡（eGPU），为本地 Agent、AI 推理与渲染任务补充 GPU 算力。本文以 Olares OS（Olares One 预装系统）为操作环境，完整讲解 eGPU 的冷启动连接、连接状态核验，以及在开机卡住或显卡无法识别时安装 Gen1 PCIe 临时方案的原理与步骤，读完即可独立完成 eGPU 的接入、验证、排障与卸载。

适用前提与安全须知

在开始操作前，需要理解 Olares OS 对外置显卡的两个关键约束：

不支持热插拔。Olares OS 运行期间连接或断开 eGPU 可能导致系统不稳定或驱动异常。连接、断开、重连 eGPU 前，必须先完全关闭 Olares One。
兼容性因硬件而异。实际能否正常工作取决于 eGPU 设备（dock / enclosure）、桌面版显卡型号、供电、线材、操作系统与 NVIDIA 驱动等多重因素。Olares 官方在将 eGPU 连接到 Olares One 中维护了已知硬件组合的兼容状态表，可作参考，但该表不代表产品推荐，也不涵盖所有组合。

注意：本文针对Olares OS（Olares One 的预装 Linux 系统）。若你使用的是 Windows 11 双系统，请参阅在 Windows 11 上设置 eGPU。

连接 eGPU

按以下顺序执行，任何变更连接的操作都必须先关机：

打开Settings>My hardware>Shutdown。
使用 LarePass 扫描屏幕上显示的二维码，再点击Confirm批准关机。
等待 Olares One 完全关机（电源指示灯熄灭）。
准备 eGPU：
- 如果设备已经安装 GPU（例如自带显卡的雷电外置显卡坞），请连接它的电源适配器。
- 如果使用 eGPU dock 或 eGPU enclosure，请装入桌面版 NVIDIA 显卡，并接好显卡所需的全部供电线（供电不足是后续"识别不到"和"运行掉卡"的最常见原因）。
给 eGPU 通电（先于连接线材）。
断开其他高带宽雷电设备（如雷电 SSD、雷电扩展坞），使用认证的雷电 5 线材（优先使用外置显卡设备附带的线材），将 eGPU 直接连接到 Olares One 的雷电 5（USB-C）接口。
按下 Olares One 的电源键启动。

检查连接状态

通过 Dashboard 检查

登录 Olares，打开Dashboard。
选择GPU卡片。
检查内置显卡和eGPU是否都已显示。

通过终端检查

也可以在 Olares 终端中直接查看 NVIDIA 驱动视角下的显卡列表：

nvidia-smi

判断结果：

Dashboard 和nvidia-smi中都能看到 eGPU：连接成功，无需安装临时方案，可直接开始使用。
开机卡住，或 Dashboard 与nvidia-smi中都看不到 eGPU：先关闭 Olares One，断开 eGPU，再重新开机。重新连接 eGPU 前，先安装下一节的 Gen1 临时方案。

Gen1 临时方案：原理与适用场景

为什么需要 Gen1 临时方案

部分雷电外设（尤其是某些 dock / enclosure 组合）在 NVIDIA 驱动初始化（GSP 初始化阶段）时，雷电隧道（Thunderbolt tunnel）上的 Gen4 PCIe 链路质量不足以支撑稳定的高速传输，导致系统开机卡在 logo或eGPU 无法被驱动枚举。这是 Olares 官方提供的临时解决方案，并非 NVIDIA 官方修复，其作用对象仅限于通过雷电连接的外置 NVIDIA 显卡，不会修改内置显卡。

后续 Olares 版本会在系统中内置该方案，届时无需手动配置。当前阶段请只安装本页提供的文件，不要混用来源不明的脚本。

临时方案的运行机制（源码视角）

仓库中随文档一起分发的三个文件构成完整的"识别 → 降速 → 重新枚举"链路，位于 docs/public/downloads/one/egpu/：

99-egpu-gen1-fix.rules：udev 规则。当系统出现 NVIDIA 显示控制器（VGA 类0x030000或 3D 类0x030200）的add事件时，通过ENV{SYSTEMD_WANTS}+="egpu-gen1-fix.service"异步拉起 systemd 服务。冷启动的 coldplug 与热插拔都会产生add事件，因此两种场景均被覆盖；而服务脚本内部还会按removable=="removable"过滤，确保只处理雷电外置 GPU、跳过内置显卡。
egpu-gen1-fix.service：oneshot 系统服务，After=bolt.service、Before=nvidia-persistenced.service nvidia-powerd.service，在 NVIDIA 持久化守护进程接管前执行降速脚本；WantedBy=multi-user.target保证开机阶段运行。
fix-egpu-link.sh：核心脚本。从源码看，它的工作分为四步：
1. 判定目标：遍历/sys/bus/pci/devices/*/，仅匹配 vendor 为0x10de（NVIDIA）、PCI class 为显示类（0x0300*/0x0302*）且removable属性为removable（雷电可移除外设）的设备，天然排除内置显卡。
2. 强制 Gen1：用setpci以读-改-写方式把桥（upstream bridge）与 GPU 的 PCIe 能力寄存器CAP_EXP+0x30（LnkCtl2）目标链路速度字段改写为 Gen1（2.5 GT/s），再置位CAP_EXP+0x10（LnkCtl）的 bit5 触发链路重训练（Link Retrain）。
3. 等待并校验：重训练后读取current_link_speed，确认已降到2.5 GT/s PCIe，否则放弃重枚举。
4. 重新枚举：对目标设备的所有 function 执行 driver unbind、/sys/bus/pci/devices/.../remove，再向/sys/bus/pci/rescan写 1 触发重扫，使 NVIDIA 驱动在 Gen1 链路上干净地重新初始化显卡。
脚本通过/run/egpu-gen1-fix.lock上的flock串行化，避免 udev 多次触发与冷启动/热插拔重叠导致的竞争；执行日志写入/var/log/egpu-gen1-fix.log。

性能影响提示：强制 Gen1 会降低系统内存与显存之间的传输带宽，因此模型加载、CPU offload、游戏和实时渲染可能变慢；但显卡的计算资源本身不会改变。

安装步骤

在不连接 eGPU的情况下启动 Olares One，然后：

将以下三个文件下载到同一目录：
- fix-egpu-link.sh
- egpu-gen1-fix.service
- 99-egpu-gen1-fix.rules
在下载目录中打开终端，确认系统可以使用setpci（临时方案依赖该工具读写 PCI 配置空间）：
```
command -v setpci
```
命令应返回/usr/sbin/setpci等路径。如果没有任何输出，请停止操作并联系 Olares 技术支持。

安装三个文件并启用服务：

sudo install -m 0755 fix-egpu-link.sh /usr/local/sbin/fix-egpu-link.sh sudo install -m 0644 egpu-gen1-fix.service /etc/systemd/system/egpu-gen1-fix.service sudo install -m 0644 99-egpu-gen1-fix.rules /etc/udev/rules.d/99-egpu-gen1-fix.rules sudo systemctl daemon-reload sudo udevadm control --reload-rules sudo systemctl enable egpu-gen1-fix.service

各命令的作用：install分别按脚本（可执行）与配置（只读）权限落盘；daemon-reload让 systemd 识别新服务单元；udevadm control --reload-rules让 udev 立即加载新规则；systemctl enable使服务在下次启动时自启（这也是冷启动路径生效的关键）。

检查安装结果：

sudo systemctl is-enabled egpu-gen1-fix.service

命令应返回enabled。

安装完成后，再次按照上文连接 eGPU的步骤操作（先关机 → 给 eGPU 通电 → 连接线材 → 开机）。

检查临时方案是否生效

Olares One 启动后，先在 Dashboard 或nvidia-smi中确认 eGPU 是否显示，再查看临时方案的运行日志：

sudo tail -n 20 /var/log/egpu-gen1-fix.log

在日志中查找类似内容：

after rescan: 0000:0a:00.0 speed=2.5 GT/s PCIe driver=nvidia

2.5 GT/s PCIe表示外置显卡链路正在以Gen1运行，说明降速与重新枚举成功、驱动已接管。不同系统显示的 PCI 地址（如0000:0a:00.0）可能不同，只需关注2.5 GT/s PCIe与driver=nvidia部分即可。

如果仍然看不到 eGPU，或运行不稳定，请参考排查 eGPU 问题按章节定位问题。

断开 eGPU

与连接对称，断开也必须全程断电：

打开Settings>My hardware>Shutdown。
在 LarePass 中批准关机，并等待 Olares One 完全关闭。
关闭 eGPU 电源。
从 Olares One 断开雷电线。
重新启动 Olares One。

卸载临时方案

卸载临时方案前，先关闭 Olares One 并断开 eGPU。

在不连接 eGPU 的情况下启动 Olares One。

卸载临时方案（与服务安装一一对应的逆操作）：

sudo systemctl disable egpu-gen1-fix.service sudo rm /usr/local/sbin/fix-egpu-link.sh sudo rm /etc/systemd/system/egpu-gen1-fix.service sudo rm /etc/udev/rules.d/99-egpu-gen1-fix.rules sudo systemctl daemon-reload sudo udevadm control --reload-rules

重启 Olares One 使改动完全生效：
```
sudo reboot
```

硬件兼容参考与排障思路

已知硬件组合兼容状态

在连接硬件之前，建议先对照将 eGPU 连接到 Olares One 中的兼容表。截至该文档维护时的已知状态：

外置显卡硬件	Olares OS	Windows 11
AOOSTAR EG02 eGPU dock + RTX 4060 Ti	设置后可用（需安装 Gen1 临时方案）	设置后可用（连接 eGPU 后重装 NVIDIA 驱动）
Razer Core X V2 eGPU enclosure + RTX 4090	验证中（未装临时方案时开机不稳定）	仅在多 eGPU 实测配置中验证
Razer Core X eGPU enclosure + RTX 4060	尚未验证	仅在多 eGPU 实测配置中验证
eGPU dock / enclosure + 桌面版 RTX 5090	暂不支持（NVIDIA 驱动无法初始化，暂无方案）	尚未验证

其中"可用"和"已验证"表示显卡完成过实际负载测试；仅在 Dashboard、设备管理器或nvidia-smi中识别到显卡，不视为兼容性验证通过。另外，Olares OS 目前每次只支持连接一台eGPU；如需多 eGPU，建议使用 Windows 11（官方已实测一种通过 Razer Thunderbolt 5 Dock 连接三台 eGPU 的配置，且该配置中内置 RTX 5090M 功耗约为 95 W 而非 175 W）。

常见问题快速定位

如果 Olares OS 出现以下现象，可参照排查 eGPU 问题处理：

开机卡在 logo：关机、断开 eGPU 后重启，确认sudo systemctl is-enabled egpu-gen1-fix.service返回enabled，否则重装临时方案。
可以启动但看不到 eGPU：按顺序检查供电、线材、直连接口、冷启动顺序，然后用lspci -nn | grep -i nvidia和nvidia-smi双命令确认；若lspci能看到而nvidia-smi看不到，先收集诊断信息再寻求帮助。
运行任务时掉卡：检查外置设备与显卡的供电功率和供电线，断开其他高带宽雷电设备后重试，掉卡后立即收集诊断信息。

向 Olares 论坛求助时，可下载并运行 collect-egpu-info.sh 生成诊断报告：该脚本只读取系统状态并在当前目录写入egpu-report-<hostname>-<timestamp>.txt（不会修改设置、联网或上传数据），报告包含External GPU detected摘要、PCIe 链路速度链、雷电拓扑、NVIDIA 驱动信息、当前与上一次启动的内核错误日志等章节，能显著加速问题定位。分享前请检查并删除报告中的主机名、内核命令行等个人敏感信息。