算力舱手册

简体中文

English

简体中文

English

Appearance

LC-X5 配置与 lzc-thor 使用 ​

LC-X5 刷机后，可以使用 lzc-thor 完成系统初始化、MGBE 网络测试、VNC 配置和磁盘管理。

除查看帮助外，本文命令均建议使用 sudo 执行。先用下面的命令确认当前系统支持的命令：

bash
sudo lzc-thor help

命令速查 ​

使用场景命令
完成新设备的常规初始化sudo lzc-thor all
单独安装 JetPack 和监控工具sudo lzc-thor packages
修复克隆系统的机器和网卡身份sudo lzc-thor clone-identity
安装 Docker 和 NVIDIA 容器运行时sudo lzc-thor docker
安装独立的 docker-compose 命令sudo lzc-thor docker-compose
关闭 Ubuntu 自动升级sudo lzc-thor disable-upgrades
配置 MGBE 性能参数sudo lzc-thor mgbe
配置或执行 MGBE 带宽测试sudo lzc-thor mgbe serve ...、sudo lzc-thor mgbe client ...
配置时区、时间同步、最大频率和 Firefoxsudo lzc-thor startup
安装并启动 lzc-ai-agentsudo lzc-thor agent
配置桌面 VNCsudo lzc-thor vnc ...
扩大当前系统盘上的根文件系统sudo lzc-thor resizefs
建立只读 APP 恢复系统和 LVM 运行系统sudo lzc-thor provision ...
把一块新 NVMe 整盘加入根文件系统sudo lzc-thor expand-lvm ...
从 APP recovery 恢复出厂运行系统sudo lzc-thor factory-reset ...

vnc、MGBE 测试、resizefs、provision、expand-lvm 和 factory-reset 不包含在 all 中，必须按需单独执行。

新设备快速初始化 ​

使用默认用户 ​

bash
sudo lzc-thor all

该命令按下面的顺序执行：

  1. 安装 JetPack、编译工具和 GPU 监控工具。
  2. 重新生成克隆系统的机器身份，并配置稳定且每台设备不同的以太网 MAC。
  3. 安装 Docker CE、Buildx、Compose 插件和 NVIDIA Container Toolkit。
  4. 安装独立的 /usr/bin/docker-compose。
  5. 关闭 Ubuntu 自动升级。
  6. 配置全部已发现 MGBE 接口的 threaded NAPI 和 IOMMU DMA-FQ，并运行 jetson_clocks。
  7. 配置时区、网络时间同步、开机运行 jetson_clocks 和 Firefox。
  8. 安装并启动 lzc-ai-agent。

默认将 nvidia 用户加入 docker 组。完整初始化后建议重启设备，使机器身份、网卡身份和用户组等配置全部生效；重新登录后可以执行 docker ps 验证 Docker 权限。

指定 Docker 用户 ​

如果系统的日常登录用户不是 nvidia，使用 --docker-user 指定用户：

bash
sudo lzc-thor all --docker-user ubuntu

也支持下面的等价写法：

bash
sudo lzc-thor all --user ubuntu
sudo lzc-thor all ubuntu

lzc-thor-init-all 是 lzc-thor all 的等价入口：

bash
sudo lzc-thor-init-all --docker-user ubuntu

常规配置命令 ​

help：查看命令帮助 ​

bash
sudo lzc-thor help
sudo lzc-thor --help

查看带参数命令的详细用法时，将 --help 放在对应命令后：

bash
sudo lzc-thor clone-identity --help
sudo lzc-thor mgbe serve --help
sudo lzc-thor provision --help
sudo lzc-thor expand-lvm --help
sudo lzc-thor factory-reset --help

packages：安装 Jetson 软件包 ​

bash
sudo lzc-thor packages

该命令通过 apt 安装以下软件包：

  • nvidia-jetpack：Jetson 平台软件栈。
  • build-essential：常用编译工具。
  • nvitop、gpustat、nvtop：GPU 状态监控工具。

适用于只需要补装或修复这些软件包，而不想执行完整初始化的场景。该命令没有额外参数。

clone-identity：修复克隆设备身份 ​

从同一个母盘克隆多台 LC-X5 后，设备可能带有相同的 /etc/machine-id、NetworkManager 密钥或有线网络身份，导致 DHCP 和局域网设备识别异常。

先预览将执行的操作：

bash
sudo lzc-thor clone-identity --dry-run

确认后执行修复，并在完成后重启：

bash
sudo lzc-thor clone-identity
sudo reboot

该命令会重新生成 /etc/machine-id，删除克隆带来的 NetworkManager 主机密钥，并将现有以太网连接配置为按设备生成稳定的本地管理 MAC。默认只重新加载 NetworkManager 配置，不会重启正在使用的网络连接。

如果正在本机控制台操作，并且可以接受网络立即中断，可以直接应用：

bash
sudo lzc-thor clone-identity --apply-now

--apply-now 会重启 NetworkManager，SSH 会话可能立即断开。通过 SSH 操作时，优先使用不带该参数的命令，然后重启设备。

可用参数：

参数说明
--apply-now写入配置后立即重启 NetworkManager。
--no-machine-id不重新生成 /etc/machine-id。
--no-profile-update不修改现有 NetworkManager 连接配置。
--dry-run只显示计划，不修改系统。

维护已挂载但未启动的克隆系统时，可以使用 LZC_THOR_ROOT 指定其根目录。离线模式只修改该目录下的文件，不操作当前系统的 NetworkManager：

bash
sudo LZC_THOR_ROOT=/mnt/thor-root lzc-thor clone-identity

docker：安装 Docker 和 NVIDIA 运行时 ​

只安装 Docker，不修改任何用户组：

bash
sudo lzc-thor docker

同时允许指定用户不加 sudo 使用 Docker：

bash
sudo lzc-thor docker --docker-user ubuntu

--user ubuntu 和直接写 ubuntu 也是等价写法。该命令会：

  • 配置 Docker 官方 apt 软件源。
  • 安装 Docker CE、Docker CLI、containerd、Buildx 和 Compose 插件。
  • 安装 NVIDIA Container Toolkit，并将 NVIDIA runtime 配置为 Docker 默认运行时。
  • 启用并重启 docker.service。
  • 在指定用户时，将该用户加入 docker 组。

修改用户组后，已有登录会话通常需要退出并重新登录才能获得新权限。

docker-compose：安装独立 Compose 命令 ​

bash
sudo lzc-thor docker-compose
docker-compose version

该命令从 Docker Compose 的 GitHub 最新 release 下载 Linux aarch64 二进制文件，校验 .sha256 后安装到 /usr/bin/docker-compose。它与 Docker 软件包提供的 docker compose 插件并存。

设备需要能够访问 GitHub。该命令总是获取执行时的最新版本，没有版本选择参数。

disable-upgrades：关闭自动升级 ​

bash
sudo lzc-thor disable-upgrades

该命令关闭并屏蔽 apt 定时更新、unattended-upgrades 和 update-notifier 相关服务，同时卸载相关软件包。适用于需要固定 JetPack、内核和驱动环境的设备。

关闭自动升级后，系统不会自动安装安全更新；需要由管理员安排兼容性验证和手动更新。

startup：配置启动环境 ​

bash
sudo lzc-thor startup

该命令会：

  • 根据当前公网 IP 查询时区；查询失败时使用 Asia/Shanghai。
  • 启用 systemd-timesyncd，并配置 Cloudflare、阿里云等 NTP 服务。
  • 创建并启用 lzc-jetson-clocks.service，开机时锁定 Jetson 最大频率。
  • 通过 Snap 安装 Firefox。

执行时需要访问时区查询服务、Ubuntu 软件源和 Snap 服务。该命令没有额外参数。

agent：安装算力舱代理 ​

bash
sudo lzc-thor agent
sudo systemctl status lzc-ai-agent.service

该命令使用安装包内附带的 ARM64 客户端安装 lzc-ai-agent，然后启用并重启 lzc-ai-agent.service。适用于单独重装或修复算力舱代理。该命令没有额外参数。

MGBE 配置与带宽测试 ​

mgbe：配置 MGBE 性能参数 ​

bash
sudo lzc-thor mgbe

该命令自动发现名称类似 mgbe0_0 的全部物理 MGBE 接口，并执行以下配置：

  • 开启 threaded NAPI。
  • 运行 jetson_clocks。
  • 将各接口所在的 IOMMU group 设置为 DMA-FQ。

该命令只负责性能参数，不分配测试 IP，也不启动 iperf3。它包含在 lzc-thor all 中。

MGBE 测试的工作方式 ​

MGBE 测试需要两台设备：一台运行服务端命令，另一台运行客户端命令。测试前，两端都应执行：

bash
sudo lzc-thor mgbe
sudo apt install -y iperf3

测试辅助命令分为三个步骤：

  1. serve config 和 client config 分配各链路的静态 IP，将配置写入 /etc/netplan/99-mgbe-test.yaml，并把链路分配保存到 /var/lib/lzc-thor/mgbe-test。
  2. serve run 从已保存的服务端配置启动 iperf3；client run 从已保存的客户端配置发起测试。
  3. 两端执行 clean，停止测试进程并删除临时网络配置和状态。

config 与 run 必须在同一端按角色配套使用。修改 IP 或测试链路数后，需要重新执行对应的 config。

各测试命令的参数和用途如下：

命令参数用法
mgbe serve config必须提供 --base-ip IP；可选 --mode 3x|4x、--dry-run为服务端接口分配 IP、应用 netplan 并保存服务端状态。
mgbe serve run可选 --dry-run读取服务端状态，并为每条链路启动 8 个不同端口的 iperf3 服务。
mgbe client config必须提供 --server-base-ip IP 和 --local-suffix 1-254；可选 --mode 3x|4x、--dry-run根据服务端基准 IP 计算两端地址、应用客户端 netplan 并保存状态。
mgbe client run可选 --duration SEC、--parallel N、--udp、--dry-run检查每条链路是否可达，同时运行所有 iperf3 客户端并汇总发送端带宽。
mgbe clean可选 --dry-run停止已记录的服务进程，删除测试 netplan 和两端状态。

三链路测试示例 ​

以下示例适用于 T4000 与 T5000 连接并使用 3 条 25GbE 链路的场景。

服务端执行：

bash
sudo lzc-thor mgbe clean
sudo lzc-thor mgbe serve config --base-ip 192.168.100.10 --mode 3x
sudo lzc-thor mgbe serve run

客户端执行：

bash
sudo lzc-thor mgbe clean
sudo lzc-thor mgbe client config \
  --server-base-ip 192.168.100.10 \
  --local-suffix 20 \
  --mode 3x
sudo lzc-thor mgbe client run

IP 会按链路递增第三段：

链路服务端 IP客户端 IP
第 1 条192.168.100.10192.168.100.20
第 2 条192.168.101.10192.168.101.20
第 3 条192.168.102.10192.168.102.20

--local-suffix 是客户端 IP 的最后一段，范围为 1 到 254，并且不能与服务端 IP 的最后一段相同。

选择 3x、4x 或自动模式 ​

--mode 只用于 serve config 和 client config：

写法使用的接口
不写 --modeauto 模式，使用全部自动发现的 MGBE 接口。
--mode 3x按接口名称排序后使用前 3 个接口。
--mode 4x按接口名称排序后使用前 4 个接口。

两端必须选择相同的模式。四链路测试示例：

bash
# 服务端
sudo lzc-thor mgbe serve config --base-ip 192.168.100.10 --mode 4x
sudo lzc-thor mgbe serve run

# 客户端
sudo lzc-thor mgbe client config \
  --server-base-ip 192.168.100.10 \
  --local-suffix 20 \
  --mode 4x
sudo lzc-thor mgbe client run

run 会读取 config 保存的模式，不接受 --mode。旧的 lzc-thor mgbe test 已被移除。

调整测试参数 ​

客户端默认测试 10 秒，每个 iperf3 客户端进程使用 24 条并行流：

bash
sudo lzc-thor mgbe client run --duration 30 --parallel 32

使用 UDP 测试：

bash
sudo lzc-thor mgbe client run --udp

每条 MGBE 链路会使用 8 个 TOS 值启动 8 个客户端进程。因此 3x 模式会并发启动 24 个客户端进程，4x 模式会启动 32 个；--parallel 是每个进程内部的并行流数量，不是进程总数。

执行 run 时，工具会检查已保存接口的 MTU 9000、threaded NAPI、IOMMU DMA-FQ 和对应的 ODMDATA 25GbE 配置；无法确认 jetson_clocks 或 ODMDATA 时会给出警告。检查失败时，应先重新执行 sudo lzc-thor mgbe 并核对设备的链路模式，不要直接使用不完整的测试结果。

测试完成后会输出 Concurrent aggregate sender bandwidth。该数值只汇总同一个并发测试窗口内可解析的发送端结果，不应将多轮串行测试结果相加后当作链路带宽。

预览和清理测试配置 ​

测试辅助命令支持 --dry-run，可以在不修改主机的情况下检查计划：

bash
sudo lzc-thor mgbe serve config --base-ip 192.168.100.10 --mode 3x --dry-run
sudo lzc-thor mgbe client run --dry-run
sudo lzc-thor mgbe clean --dry-run

正式测试结束后，在服务端和客户端都执行：

bash
sudo lzc-thor mgbe clean

clean 会停止命令记录的 iperf3 服务端进程，删除 /etc/netplan/99-mgbe-test.yaml 和 /var/lib/lzc-thor/mgbe-test 下的状态，并重新应用网络配置。

VNC 配置 ​

vnc 不包含在 all 中。为默认的 nvidia 桌面用户配置 VNC：

bash
sudo lzc-thor vnc --password '<VNC密码>'

为其他桌面用户配置：

bash
sudo lzc-thor vnc --user ubuntu --password '<VNC密码>'

也可以用环境变量传入用户和密码：

bash
sudo LZC_THOR_VNC_USER=ubuntu \
  LZC_THOR_VNC_PASSWORD='<VNC密码>' \
  lzc-thor vnc
参数或变量说明
--user USER目标桌面用户；默认读取 LZC_THOR_VNC_USER，未设置时为 nvidia。
--password PASSWORD必填的 VNC 密码，也可以通过 LZC_THOR_VNC_PASSWORD 提供。

该命令按需安装 Vino、启用其桌面启动项并写入用户的 VNC 设置。完成后应重启设备。没有配置桌面自动登录时，通常需要目标用户先在本地登录图形桌面，VNC 才能连接。

存储命令 ​

resizefs、provision、expand-lvm 和 factory-reset 会操作分区、文件系统、LVM 或启动配置。执行前应备份重要数据，并先确认设备名和当前根文件系统。

bash
findmnt /
lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,PARTLABEL,MOUNTPOINTS
sudo pvs
sudo vgs
sudo lvs

resizefs：使用当前系统盘的剩余空间 ​

将较小的系统盘克隆到较大的磁盘后，可以执行：

bash
sudo lzc-thor resizefs

该命令根据当前 / 的布局自动选择处理方式：

  • 普通 ext4 分区根目录：将该分区扩展到磁盘剩余空间，再在线扩展 ext4。
  • 标准 aipod_vg/lv_root 且只有一个分区型 PV：扩展 PV 所在分区和 PV，将 VG 的全部空闲空间分配给 lv_root，再在线扩展 ext4。

该命令不支持多 PV、加密存储、整盘文件系统、非 ext4 根文件系统或非标准 LVM 布局。多盘 LVM 运行系统需要增加新磁盘时，应使用 expand-lvm，而不是 resizefs。

provision：建立 APP recovery 和 LVM runtime ​

provision 用于将带有 APP 和 DATA_PV 分区的 LC-X5 转换为以下布局：

  • APP：只读的出厂系统和恢复环境，同时保存 L4TLauncher 启动文件。
  • aipod_vg/lv_root：日常使用的可写 ext4 根文件系统。

这是一个分两阶段执行、每阶段都会自动重启的流程。

第 1 阶段：在可写 APP 中准备 ​

先检查当前状态和计划：

bash
sudo lzc-thor provision status
sudo lzc-thor provision --dry-run

确认无误后开始准备：

bash
sudo lzc-thor provision --yes

第 1 阶段会安装存储和 initramfs 工具、扩展 DATA_PV、检查 initrd 的 LVM 支持、写入受管理的启动项、将 APP 配置为只读，并把下次启动目标设为 LZC Thor APP recovery，然后重启。

第 2 阶段：在 APP recovery 中创建运行系统 ​

设备重启进入 LZC Thor APP recovery 后登录，再执行：

bash
sudo lzc-thor provision --maintenance --yes

第 2 阶段会确认当前根目录确实是只读 APP，创建 aipod_vg/lv_root，以块级方式把 APP 克隆到逻辑卷，扩展 ext4、生成新的文件系统 UUID 和机器身份，最后切换到 LVM runtime 并重启。

进入运行系统后，可以检查：

bash
sudo lzc-thor provision status
findmnt /
findmnt /factory

正常情况下，/ 来自 /dev/aipod_vg/lv_root，APP 以只读方式挂载在 /factory。当前启动文件对应的软件包会被 hold，因此不支持在线更新内核、DTB 和 initrd。

provision 会修改分区和启动配置。不要跳过 --dry-run，也不要在不符合 APP、DATA_PV 布局的设备上强行执行。

expand-lvm：增加一块 NVMe 到根文件系统 ​

该命令只适用于根目录已经是可写的 /dev/aipod_vg/lv_root，用于把一块完整 NVMe 磁盘加入根文件系统。

先根据容量、型号和序列号确认目标盘：

bash
lsblk -d -o NAME,PATH,SIZE,MODEL,SERIAL

对空盘先执行只读检查和预览：

bash
sudo lzc-thor expand-lvm --disk /dev/nvme1n1 --dry-run

确认目标正确后正式扩容：

bash
sudo lzc-thor expand-lvm --disk /dev/nvme1n1

空盘会被创建 GPT，并建立一个标记为 LZC_THOR_PV 的分区。随后命令会执行 pvcreate、vgextend、lvextend 和 resize2fs，在线扩大根文件系统。

如果磁盘上已有分区或文件系统，命令默认拒绝操作。明确确认其中数据可以全部删除后，使用：

bash
# 交互式确认时，按提示完整输入目标磁盘路径
sudo lzc-thor expand-lvm --disk /dev/nvme1n1 --force-wipe

# 无人值守确认；会直接清空目标盘
sudo lzc-thor expand-lvm --disk /dev/nvme1n1 --force-wipe --yes
参数说明
--disk /dev/nvmeXnY必填；必须是完整 NVMe 设备，不能填写分区。
--dry-run执行运行环境和磁盘安全检查，并显示计划，不写磁盘。
--force-wipe授权清空非空目标盘；未带 --yes 时要求交互确认。
--yes只可与 --force-wipe 同时使用，跳过交互确认。

扩容后，每块成员盘都永久成为根文件系统的一部分。拔掉任意成员盘都可能导致系统无法启动。后续恢复出厂设置时，所有 DATA_PV 和 LZC_THOR_PV 成员盘都会被清空并重建。

命令支持从已完成的 pvcreate、vgextend 或扩容步骤继续执行；已经完整加入并分配空间的磁盘再次执行时不会重复扩容。

factory-reset：恢复 LVM 运行系统 ​

factory-reset 只能在手动选择的只读 LZC Thor APP recovery 中执行，不能在日常 LVM runtime 中执行。

  1. 重启设备，在 extlinux 菜单中手动选择 LZC Thor APP recovery。

  2. 如果系统使用多块 LVM 成员盘，确认所有扩容盘都已连接。

  3. 进入 recovery 后先查看状态并预演：

    bash
    sudo lzc-thor factory-reset status
sudo lzc-thor factory-reset --dry-run

  4. 确认后执行恢复：

    bash
    sudo lzc-thor factory-reset --yes

该命令会检查当前系统是否从只读 APP 启动、LVM 拓扑是否符合预期、所有成员盘是否在线，以及每个 PV 是否支持 discard。随后会清空所有 DATA_PV 和 LZC_THOR_PV，按原总容量重建 aipod_vg/lv_root，从 APP 克隆全新的运行系统并重启。APP、APP 中的 /etc/fstab 和 extlinux 默认启动项保持不变。

factory-reset --yes 会永久删除运行系统、Docker 数据、模型、应用和用户文件。--dry-run 不会写磁盘，但仍会执行恢复环境、成员盘和 discard 能力检查。

常见问题 ​

为什么执行 Docker 后仍提示权限不足？ ​

用户加入 docker 组后，当前登录会话不会自动刷新组信息。退出 SSH 或桌面会话并重新登录，再执行：

bash
docker ps

为什么 mgbe serve run 或 client run 提示没有状态？ ​

run 不接收 IP 和 --mode，只读取同一角色最近一次 config 保存的状态。先重新执行 serve config 或 client config，再执行对应的 run。

什么时候用 resizefs，什么时候用 expand-lvm？ ​

  • 原系统盘本身变大，想使用同一块盘尾部的剩余空间：使用 resizefs。
  • 已经运行在 aipod_vg/lv_root，想把另一块完整 NVMe 加入根文件系统：使用 expand-lvm。

如何只查看当前存储布局？ ​

bash
sudo lzc-thor provision status

provision status 和 factory-reset status 都只输出当前根目录、/factory、/boot、块设备、LVM 和 extlinux 默认启动项，不修改系统。