Olares One 已知问题排查指南:初始设置 9% 失败与 Thunderbolt 5 端口显示异常

原创2026-10-14 13:17:171,644 阅读
文章标签:云原生后端运维

Olares One 已知问题排查指南:初始设置 9% 失败与 Thunderbolt 5 端口显示异常

本文基于 Olares One 官方已知问题清单(docs/one/known-issues.md),系统讲解两类已收录问题的症状、根因与完整变通方案:初始设置卡在 9% 的激活失败问题,以及 Windows 11 双启动下 Thunderbolt 5 端口显示为 USB4 的正常现象。读完本文,你将掌握通过 SSH 或本地终端卸载不完整安装、重新激活设备的完整流程,并能判断 Thunderbolt 5 带宽是否真正协商到 80 Gbps,避免误判硬件故障。

页面定位:官方已知问题清单的用法

known-issues 是 Olares One 文档体系中面向"Reference(参考)"类目的官方问题登记页(见 docs/one/index.md),与 Technical spec、FAQs 并列。该页面记录两类内容:

  • 真实故障:如初始设置失败,给出可操作的排查与修复步骤;
  • 误报性现象:如 Thunderbolt 5 显示为 USB4,属于设计行为,用于避免用户误判为硬件缺陷。

官方会定期更新此列表,补充临时变通方法(workaround)与永久修复(permanent fix)。当你在设备上遇到异常时,应优先对照本清单定位,再执行对应的处置步骤。

问题一:Olares One 初始设置停在 9% 并激活失败

症状与影响范围

设备在首次上电的初始设置(initial setup)过程中失败,安装进度停在约 9% 处,界面提示你卸载(uninstall)或重新安装(reinstall)。该问题在设备出厂时区仍为默认的 UTC+8、且尚未经过完整时间校准的情况下尤为常见。

根因:异步 NTP 时间同步与证书时间戳的竞态

根据官方文档的说明,设备在启动阶段执行安全证书签发流程之前,会先进行异步 NTP 时间同步。正常情况下该同步瞬间完成,但偶尔的网络延迟会导致同步未生效时证书已被签发,从而产生"未来时间戳"(future timestamp)的证书,最终触发激活校验失败。

这一流程在源码中可以得到印证。CLI 的引导阶段包含一个 ConfigSystem 模块(cli/pkg/bootstrap/os/module.go),它依次注册两个远程任务:

  1. UpdateNtpDate:执行 ntpdate -b -u pool.ntp.org(若系统中没有 ntpdate,则回退为 timedatectl set-ntp 1 启用 NTP 自动同步,见 cli/pkg/bootstrap/os/tasks.go);
  2. TimeSync:同步系统时间后,将 hwclock -w 写入 RTC 硬件时钟,并把时间同步脚本固化到 /etc/cron.daily/ntpdate,保证后续每次启动都能校准时间(见 cli/pkg/bootstrap/os/tasks.go)。

从源码结构看,这两个任务在模块内按顺序、非并行执行,属于开机初始化序列的一部分;若该序列与后续证书签发之间存在异步竞争窗口,就可能导致文档描述的"证书带未来时间戳"问题。理解这一点对后续排查很有帮助:问题的本质是系统时间偏差,而非网络或硬件故障。

修复策略:卸载不完整安装后重新激活

官方给出的变通方案是:卸载未完成的安装,将设备恢复到未激活状态,再重新走一遍发现与激活流程。整个过程分四步执行。

步骤 1:优先尝试 SSH 连接

如果你手头没有显示器和键盘,可通过网络远程进入设备:

  1. 打开手机上的 LarePass 应用,进入 Activate Olares 页面,获取 Olares One 的本地 IP 地址(见下图):

Activate Olares 页面显示的本地 IP 地址

  1. 在电脑上打开终端,执行 SSH 连接命令(将 <local_ip_address> 替换为上面获取的 IP):
ssh olares@<local_ip_address>
  1. 出现密码提示后,输入默认 SSH 密码 olares 并回车;
  2. 连接成功后,直接跳到下文"步骤 3:运行卸载命令"。

步骤 2:SSH 不可用时的本地登录

当 SSH 访问不可用(例如网络未配置或 SSH 未就绪)时,改用物理方式登录:

  1. 将显示器和键盘连接到 Olares One,屏幕上会自动出现基于文本的登录提示:
olares login:
  1. 输入用户名 olares 并回车;
  2. 按提示输入默认密码 olares 并回车。

步骤 3:运行卸载命令

登录终端后执行:

sudo olares-cli uninstall

该命令会删除所有已安装组件与数据,将设备恢复为未激活状态。从仓库源码看,olares-cli uninstall 对应 os 命令组的 NewCmdUninstallOs(cli/cmd/ctl/os/uninstall.go),其执行入口是 pipelines.UninstallTerminusPipeline(cli/pkg/pipelines/uninstall_terminus.go),底层调用 cluster.UninstallTerminus(phase, runtime) 构建卸载管线(cli/pkg/phase/cluster/delete_cluster.go)。

该管线按阶段拆解卸载动作,理解这些阶段有助于你判断卸载的清理范围:

卸载阶段 主要清理内容(源码依据 cli/pkg/phase/cluster/delete_cluster.go)
install 阶段 删除 K3s / Kubernetes 集群(DeleteClusterModule / ResetClusterModule)、卸载自动续期证书(UninstallAutoRenewCertsModule)、清理容器运行时进程(KillContainerdProcessModule)、清理系统环境变量(ClearOSEnvironmentModule)、删除用户数据(DeleteUserDataModule)、移除 JuiceFS 与挂载点、删除已安装状态标记文件(DeletePhaseFlagModule)
storage 阶段 移除存储模块(RemoveStorageModule)
prepare 阶段 卸载 ZFS 挂载与容器运行时(DeleteZfsMountModule / UninstallContainerModule)、删除 Terminus 数据(DeleteTerminusDataModule)、卸载系统守护进程(UninstallTerminusdModule)、删除准备阶段标记文件

在 Linux 上不带 --all 参数执行时,命令会要求指定 --phase(支持 install、prepare、download),例如 --phase install 表示只回退 install 阶段、将系统恢复到 prepare 状态(见 cli/cmd/ctl/os/uninstall.go 与 cli/pkg/pipelines/uninstall_terminus.go)。文档场景下的完整卸载建议直接使用不带参数的默认行为(回退至未激活状态),等待卸载完成后进入下一步。

步骤 4:通过 LarePass 重新安装并激活

:::tip 重新安装前的关键提示 为确保时间同步准确,卸载完成后让设备保持通电几分钟,使其自动校准内部时间。这是避免证书再次带上未来时间戳的关键预防动作。 :::

根据你的网络环境,任选一种方式发现并关联设备:

方式 A:通过有线 LAN 设置

  • 确保 Olares One 通过网线连接路由器;
  • 在 LarePass 应用中点击 Discover nearby Olares,扫描局域网内设备:

发现附近的 Olares

方式 B:通过 Wi-Fi(蓝牙)设置

  • 有线不可用时,在 LarePass 应用中点击 Discover nearby Olares;
  • 点击底部的 Bluetooth network setup(蓝牙网络设置);
  • 从蓝牙设备列表中选择你的 Olares One,点击 Network setup(网络设置);
  • 按提示将 Olares One 连接到手机当前使用的 Wi-Fi 网络;
  • 连接成功后返回主界面,再次点击 Discover nearby Olares。

完成设备发现后,从可用设备列表中找到你的 Olares One,点击 Install now(立即安装)。此时安装应能顺利完成。

问题二:Windows 11 下 Thunderbolt 5 端口显示为 USB4

现象描述

在 Windows 11 双启动(dual-boot)方案中,Olares One 的 Thunderbolt 5 端口在设备管理器(Device Manager)中显示为 "USB4(TM) Host Router" 或 "USB4 Root Router",而不是以 "Thunderbolt 5" 字样呈现:

Windows 设备管理器中的 USB4 显示

这是设计行为,不是故障

官方文档明确指出:该显示行为是 Intel 与 Microsoft 的设计结果,不影响任何功能。其技术背景如下:

  • 从 Windows 11 开始,Thunderbolt 驱动已内置于操作系统,不再需要单独安装厂商驱动;
  • 系统统一通过 Usb4HostRouter.sys 驱动管理 Thunderbolt 3、4、5 设备;
  • 设备管理器中的 "USB4" 标签反映的正是这种统一驱动架构,不代表端口降速运行。

如何验证真实带宽

当连接 Thunderbolt 5 设备(如扩展坞)时,系统仍然会协商完整的 80 Gbps 带宽,Thunderbolt 5 扩展坞工作正常。若需核实连接速率,可按以下步骤验证:

  1. 在 Windows 设备管理器中找到该 USB4 设备;
  2. 打开设备属性(Properties)页面;
  3. 查看 Current bandwidth (down/up)(当前带宽:下行/上行)字段,确认其协商带宽。

只要该字段显示 80 Gbps 量级的协商值,且设备功能正常,就无需任何处理。相关行为的技术细节可参考 Intel 关于 Windows 11 下 Thunderbolt 驱动的说明文档,以及 Microsoft 关于 Windows USB4 连接管理器(USB4 connection manager)的硬件设计指南——这两份材料由官方文档在文末列出,用于解释该统一驱动架构的由来。

预防与注意事项总结

结合官方文档与仓库源码,给出三条实操建议:

  1. 给首次开机留出时间校准窗口:初次上电激活前,让设备保持通电数分钟,等待 NTP 同步自动校准内部时间(底层对应 TimeSync 任务将同步脚本写入 /etc/cron.daily/ntpdate,见 cli/pkg/bootstrap/os/tasks.go),可显著降低证书"未来时间戳"导致激活失败的概率;
  2. 卸载命令的权限与密码:olares-cli uninstall 需要 sudo 执行;SSH 与本地登录的默认凭据均为用户名 olares、密码 olares,请在首次登录后尽快修改;
  3. 区分"故障"与"设计行为":Windows 设备管理器中 USB4 标签是正常显示,判断依据是 USB4 设备属性页的 Current bandwidth (down/up) 字段与设备实际功能,切勿据此误判硬件故障而盲目更换设备或重装系统。

若你的设备问题不在本清单内,可进一步参考 Olares One 文档体系的 FAQ(常见问题) 与 故障排查指南 获取更多信息。

登录后查看全文
Terminus