Olares One 已知问题排查指南：初始设置卡在 9% 与 Windows 下 Thunderbolt 5 显示为 USB4-平芜编程栈

云原生
后端
运维

【免费下载链接】Terminus

Open-Source Personal Cloud OS for Always-On Agents

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

Olares One 在初始设置与双启动场景中可能遇到两个典型问题：初始激活卡在约 9% 并提示卸载重装，以及 Windows 11 设备管理器中 Thunderbolt 5 端口显示为 "USB4"。本文依据 docs/zh/one/known-issues.md（英文原文见 docs/one/known-issues.md），结合 Terminus 仓库中 NTP 时间同步、证书签发与卸载流水线的源码实现，完整说明问题成因、逐步恢复流程与验证方法。

问题一：Olares One 初始设置在 9% 处失败

故障现象

Olares One 在首次初始设置（激活）过程中失败，安装进度停在约 9%，界面会提示用户卸载或重新安装。该问题并非硬件故障，而是由启动时序与证书签发之间的时间偏差引起，属于可自行恢复的软件级问题。

根因分析：异步 NTP 同步与证书未来时间戳

根据官方文档的描述，根因链条如下：

设备启动时，系统在签发安全证书之前会执行一次异步 NTP 时间同步；
NTP 同步通常瞬间完成，但在网络抖动或时间源响应较慢时可能发生延迟；
若 NTP 校准尚未完成，证书签发流程就会基于尚未校准的系统时间生成证书，导致证书被盖上"未来时间戳"（future timestamp）；
该现象在设备仍使用出厂默认时区UTC+8时尤其常见；
未来时间戳的证书无法通过校验，最终导致激活（activation）失败。

仓库源码印证了这一时间敏感链路。在 cli/pkg/bootstrap/os/tasks.go 中，UpdateNtpDateTask会优先调用ntpdate -b -u pool.ntp.org强制校时，找不到ntpdate时退化为timedatectl set-ntp 1；同一文件中的TimeSyncTask还会将校时命令写入cron.ntpdate（cli/pkg/bootstrap/os/tasks.go），并调用hwclock -w将系统时间写回硬件时钟（RTC），保证重启后时间依然准确。

证书签发侧则位于 cli/pkg/utils/certs/certs.go：NewSignedCert直接使用time.Now().Add(CertificateValidity)计算证书的NotAfter，并以 CA 证书的NotBefore作为新证书的生效起点。一旦系统时钟被错误地拨到未来（例如 NTP 延迟期间时钟仍停留在未来），生成的证书时间戳就会超出合理区间，进而触发校验失败，中断激活流程。

变通方法：卸载未完成安装并重新激活

官方给出的变通方案是卸载未完成的安装，然后重新激活设备，完整流程包含四个步骤。

步骤 1：尝试 SSH 连接（无显示器/键盘时优先）

如果你尚未给 Olares 设备连接显示器和键盘，优先通过 SSH 远程登录：

打开 LarePass 应用中的Activate Olares页面，获取 Olares One 的本地IP地址：
在你的电脑上打开终端；
输入以下命令（将<local_ip_address>替换为上述本地 IP 地址）并回车：
```
ssh olares@<local_ip_address>
```
按提示输入默认 SSH 密码olares并回车；
如果连接成功，直接跳转到步骤 3。

步骤 2：本地登录（SSH 不可用时）

当 SSH 访问不可用时，使用显示器与键盘本地登录：

将显示器和键盘连接到 Olares One，屏幕会自动显示基于文本的登录提示：
```
olares login:
```
输入用户名olares，按Enter；
按提示输入默认 SSH 密码olares，按Enter。

说明：默认登录凭据（用户olares/ 密码olares）是出厂初态凭据，仅在设备尚未配置自定义密码时有效；若你已修改过密码，请使用修改后的凭据。

步骤 3：运行卸载命令

登录成功后执行卸载，将设备恢复为未激活状态：

sudo olares-cli uninstall

等待卸载完成即可。从源码看，该命令的入口位于 cli/cmd/ctl/os/uninstall.go：NewCmdUninstallOs定义了olares-cli uninstall，其实际执行体为pipelines.UninstallTerminusPipeline（cli/pkg/pipelines/uninstall_terminus.go），该流水线会清理已安装组件与数据，并在卸载日志uninstall.log中记录全过程。该命令还支持两个可选参数：

--all：彻底卸载，包括已准备的依赖（prepared dependencies）；
--phase <install|prepare|download>：从指定阶段开始回退卸载，例如--phase install会移除 install 阶段执行的任务，将系统恢复到 prepare 状态。

一般情况下，故障恢复直接执行sudo olares-cli uninstall即可。

步骤 4：使用 LarePass 重新安装并激活

:::tip 重新安装前为确保时间同步准确，重新安装前让设备保持通电几分钟，使其自动校准内部时间（含 RTC 硬件时钟）。 :::

根据你的网络设置发现并关联 Olares One：
通过有线 LAN 设置
- 确保 Olares One 通过网线连接到路由器；
- 在 LarePass 应用中点击Discover nearby Olares。
通过 Wi-Fi（蓝牙）设置如果没有有线连接，可以使用蓝牙配置 Wi-Fi 凭据：
- 在 LarePass 应用中点击Discover nearby Olares；
- 点击底部的Bluetooth network setup；
- 从蓝牙列表中选择你的设备，点击Network setup；
- 按照提示将 Olares One 连接到手机当前使用的 Wi-Fi 网络；
- 连接完成后返回主屏幕，再次点击Discover nearby Olares。
从可用设备列表中找到你的 Olares One，点击Install now。此时设备内部时间已经校准，安装应能顺利推进并成功完成。

预防要点

等待时间校准再重装：重启/重装前保持设备通电数分钟，让ntpdate -b -u pool.ntp.org或timedatectl set-ntp 1（cli/pkg/bootstrap/os/tasks.go）完成校时，并通过hwclock -w写入 RTC；
确认时区已从出厂默认 UTC+8 更新：文档明确指出出厂默认时区为 UTC+8，未更新的设备更容易命中证书时间戳问题；
保持网络可达：NTP 同步依赖公共时间源pool.ntp.org，若网络受限，时间偏差会持续存在。

问题二：Thunderbolt 5 端口在 Windows 设备管理器中显示为 USB4

现象描述

在双启动方案中安装 Windows 11 后，Olares One 的 Thunderbolt 5 端口在设备管理器中显示为"USB4(TM) Host Router"或"USB4 Root Router"。这是正常行为，不影响功能。

原因：Windows 11 的内置统一驱动架构

该显示行为是 Intel 与 Microsoft 的设计使然：

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

换句话说，看到 "USB4" 只是 Windows 对 Thunderbolt 3/4/5 统一管理后的显示名称，Thunderbolt 5 的硬件能力并未被降级。

功能验证：带宽与扩展坞仍正常

连接 Thunderbolt 5 设备时，系统仍会协商完整的 80 Gbps 带宽；
Thunderbolt 5 扩展坞可以正常工作；
你可以在 USB4 设备属性页面的Current bandwidth (down/up)字段中验证实际协商的连接速度。

如果该字段显示接近 80 Gbps（双向均协商完整带宽），即说明 Thunderbolt 5 链路以全速工作，设备管理器中的 "USB4" 标签只是命名差异。

小结

初始设置卡在 9%：根因是证书签发前异步 NTP 同步偶发延迟，导致证书带未来时间戳、激活失败。恢复流程为ssh olares@<ip>（或本地登录）→sudo olares-cli uninstall→ 等待设备通电校准时间 → 通过 LarePass 重新安装激活；
Windows 下端口显示为 USB4：属正常设计，Windows 11 通过Usb4HostRouter.sys统一管理 Thunderbolt 3/4/5，不影响 80 Gbps 带宽协商与扩展坞功能。

仓库中与之相关的实现参考：NTP 校时与 RTC 回写见 cli/pkg/bootstrap/os/tasks.go，证书时间戳生成见 cli/pkg/utils/certs/certs.go，卸载命令与流水线见 cli/cmd/ctl/os/uninstall.go 与 cli/pkg/pipelines/uninstall_terminus.go，olares-cli的完整系统命令组见 cli/cmd/ctl/os/root.go。