具身智能工程师的 Ubuntu CLI 命令手册

6 阅读10分钟

适用对象与使用方法

面向机器人、ROS/ROS 2、仿真、边缘计算和模型部署开发。读者会基本使用终端,希望快速查找常见命令并建立排障思路。命令示例以 Ubuntu 22.04/24.04 为主;ROS 1 部分会单独标注。不同 ROS 发行版、驱动和容器环境可能有差异,执行前请核对当前项目版本。

遇到问题时按层向下定位:确认现象 → 看系统资源与权限 → 查进程和日志 → 查设备与网络 → 查 ROS 图与消息 → 查容器及依赖 → 做最小复现。

一张知识地图:命令对应机器人软件栈

应用与部署:模型推理、Docker、日志、监控、远程调试
    ↓
机器人中间件:ROS 2 节点、Topic、Service、Action、TF、参数、Launch
    ↓
开发环境:Python、虚拟环境、依赖、编译器、Git
    ↓
操作系统:文件、权限、进程、内存、磁盘、网络、服务
    ↓
硬件与设备:USB、串口、GPU、相机、雷达、机械臂

从上往下看是软件依赖关系;排障时通常从症状所在层开始,再向下验证它依赖的资源。机器人问题还要特别核对时间戳、坐标系、QoS、网络发现和设备权限。

命令行基本功

目的

命令

说明

路径与文件

pwd、ls -lah

查看当前目录;显示隐藏文件、权限与大小

切换目录

cd ~/ws、cd -

进入工作区;切回上一个目录

创建、复制、移动

mkdir -p dir、cp -a src dst、mv a b

-p 自动创建父目录

查找文件/文本

find . -name '*.launch.py'、rg 'frame_id' src/

没有 rg 时可用 grep -Rni 'frame_id' src/

看文件与日志

less file.log、tail -f file.log

分页查看;持续跟踪日志,按 q 退出

帮助与历史

man ps、cmd --help、history | tail -30

查询手册、选项和最近命令

Ctrl+C 通常中断前台程序;Ctrl+Z 暂停进程;jobs 查看当前 shell 任务;fg 恢复到前台。路径含空格时用引号包裹。使用 sudo 前先确认命令的影响范围。

软件安装、压缩包与文件权限

Ubuntu 软件常见来源有 APT 软件仓库、独立 deb 包、Snap、AppImage 和源码。优先选择 Ubuntu/ROS 官方仓库或项目官方安装说明;安装 ROS 时要匹配 Ubuntu 版本与 ROS 发行版。

APT:查找、安装、更新与卸载

sudo apt update                         # 更新软件包索引,不会升级已安装软件
apt search <关键词>                    # 搜索仓库软件
apt show <软件包名>                    # 查看版本、依赖和说明
sudo apt install <软件包名>             # 安装
sudo apt install -y <软件包名>          # 自动确认;脚本使用前确认目标包
sudo apt upgrade                        # 升级已安装软件
sudo apt remove <软件包名>              # 卸载程序,保留部分配置
sudo apt purge <软件包名>               # 卸载并删除系统配置
sudo apt autoremove                     # 清理不再需要的依赖

apt update 只刷新索引;安装前可用 apt show 核对包名和来源。remove 与 purge 的差别是是否清理系统级配置。不要随意删除不熟悉的依赖包。

deb、Snap、AppImage 与源码

sudo apt install ./package.deb          # 安装本地 deb 包,apt 会尝试补齐依赖
sudo dpkg -i package.deb                # 用 dpkg 安装 deb;遇到缺依赖时执行下一行
sudo apt --fix-broken install           # 修复并安装缺失依赖
snap list                               # 列出当前已安装的 Snap 软件
sudo snap install <软件名>              # 安装 Snap 软件;软件名替换为真实包名
chmod +x AppName.AppImage               # 给 AppImage 文件添加可执行权限
./AppName.AppImage                      # 从当前目录启动 AppImage
sudo apt install build-essential cmake  # 安装常见 C/C++ 编译工具
cmake -S . -B build                     # 用当前目录源码生成 build 构建目录
cmake --build build -j$(nproc)          # 编译项目;nproc 表示可用 CPU 核数

AppImage 通常解压后赋予当前用户执行权限即可,不需要 sudo。源码构建前先读项目 README,按其要求准备依赖和构建目录;不要把未知来源的安装脚本直接用 root 权限运行。

解压与打包

tar -tf archive.tar.gz                  # 只列出压缩包内容,不解压
tar -xzf archive.tar.gz                # 解压 gzip 格式的 tar 包到当前目录
tar -xf archive.tar.xz                 # 解压 xz 格式的 tar 包到当前目录
tar -czf logs.tar.gz logs/              # 把 logs 目录压缩为 logs.tar.gz
unzip archive.zip -d ./output           # 把 zip 解压到 output 目录
zip -r project.zip project/             # 递归压缩整个 project 目录
7z x archive.7z -o./output              # 把 7z 解压到 output 目录;需安装 7z

不确定压缩包内容或来源时,先列出文件再解压;注意压缩包可能含有覆盖同名文件的路径。文件名带空格时用引号,例如 unzip "my data.zip" -d ./data。

权限与归属

ls -l file                              # 查看权限、属主和属组
stat file                               # 查看文件大小、时间和权限等详细信息
chmod u+x script.sh                     # 只给文件所有者添加执行权限
chmod 644 file                          # 所有者读写,用户组和其他人只读
chmod 755 script.sh                     # 所有者读写执行,其他人可读和执行
chown user:group file                   # 修改文件所有者和所属组;通常需要 sudo
id                                      # 查看当前账号的用户 ID 和所属组
sudo usermod -aG dialout $USER          # 将当前用户加入串口组;重新登录后生效

权限数字按“所有者/用户组/其他用户”三位理解:4=读、2=写、1=执行,组合相加。避免对整个工作区或设备无差别设置 chmod -R 777;先确认需要访问的用户、目录和设备组。

系统资源:CPU、内存、磁盘与 GPU

lsb_release -a                 # 查看 Ubuntu 发行版信息
uname -a                       # 查看内核版本、系统架构等信息
uptime                         # 查看运行时长和系统负载
free -h                        # 以易读单位查看内存与 swap 使用情况
df -h                          # 查看各磁盘分区的已用和剩余空间
du -sh ~/.ros ~/ws             # 查看 ROS 日志和工作区目录总占用
lsblk                          # 查看磁盘、分区和挂载结构
top                            # 实时查看进程和 CPU/内存;按 q 退出
htop                           # 交互式进程查看器;需先安装
nvidia-smi                     # 查看 NVIDIA GPU、显存和计算进程
nvidia-smi -l 1                # 每隔 1 秒刷新 GPU 状态
journalctl -k -n 100           # 查看最近 100 条内核日志

磁盘空间不足先用 df -h 看哪个文件系统满,再用 du -sh 找大目录;内存压力看 free -h 和 top;GPU 不可见先确认宿主机 nvidia-smi,再检查容器 GPU 映射和驱动兼容性。

进程、服务与日志

ps aux | grep -E 'ros|python|rviz'       # 搜索相关进程;可能会显示 grep 自身
pgrep -af 'component_container|my_node' # 搜进程名并显示 PID 与完整命令行
pstree -ap <PID>                         # 把 PID 替换为进程号,查看其父子进程
kill -SIGINT <PID>                       # 请求程序像收到 Ctrl+C 一样退出
kill -TERM <PID>                         # 请求系统正常结束该进程
kill -KILL <PID>                         # 强制结束进程;前两种无效时再用
systemctl status docker                  # 查看 Docker 后台服务是否正常
sudo systemctl restart docker            # 重启 Docker 服务,容器可能受影响
journalctl -u docker -f                  # 持续查看 Docker 服务日志;按 Ctrl+C 退出
dmesg -T | tail -80                      # 查看最近 80 条设备/驱动内核消息

优先用 SIGINT 或 TERM 让 ROS 节点清理资源;不要习惯性使用强制终止。systemctl 管理系统服务,普通用户启动的程序不一定由 systemd 管理。

Python、uv 与依赖环境

python3 --version                         # 查看已安装的 Python 3 版本
which python3                             # 查看终端实际调用的 Python 路径
python3 -m venv .venv                     # 在当前目录创建独立虚拟环境
source .venv/bin/activate                 # 激活虚拟环境;命令提示符通常会显示 .venv
python -m pip install -U pip               # 在当前环境更新 pip 包管理器
python -m pip install -r requirements.txt  # 按依赖清单安装项目所需 Python 包
python -m pip freeze > requirements-lock.txt # 将当前环境包版本保存到文件
deactivate                                # 退出当前虚拟环境
  • 使用 python3 -m pip 确保 pip 对应当前解释器。
  • 项目依赖优先放在 venv、uv 或 Conda 环境中;避免用 sudo pip install 污染系统 Python。
  • ROS Python 包需要与 ROS 发行版、系统 Python 和工作区 overlay 匹配。Ubuntu 系统 Python 可能受 PEP 668 保护,应在虚拟环境中安装项目依赖。
uv --version                         # 查看 uv 是否安装以及版本号
uv python list                       # 查看 uv 可使用或管理的 Python 版本
uv init my_project                   # 创建名为 my_project 的 Python 项目
cd my_project                        # 进入刚创建的项目目录
uv add numpy opencv-python           # 添加运行依赖并更新锁文件
uv add --dev pytest ruff             # 添加仅用于开发/检查的依赖
uv run python app.py                 # 使用项目环境运行 app.py
uv run pytest                        # 在项目环境中运行 pytest
uv sync                              # 按项目配置和锁文件同步所有依赖

ROS 工作区与 uv 环境混用前,确认 PYTHONPATH、解释器路径和依赖 ABI。遇到 import 错误时检查 which python,并运行 python -c 'import sys; print(sys.executable); print(sys.path)'。

Git 与 ROS 工作区

git status --short                         # 简洁查看工作区有哪些未提交改动
git switch -c feature/teleop               # 新建并切换到功能分支
git diff                                   # 查看尚未暂存的代码差异
git log --oneline --decorate -10           # 查看最近 10 条提交记录
git submodule update --init --recursive    # 初始化并下载项目依赖的 Git 子模块

ROS 工程常见目录:src/ 放源码包,build/ 放构建中间产物,install/ 放安装空间,log/ 放构建日志。把生成目录加入 .gitignore,避免误提交大型 bag、模型权重和编译产物。

ROS 2:环境、构建与通信

环境与构建

source /opt/ros/$ROS_DISTRO/setup.bash     # 在当前终端加载已安装的 ROS 环境
source install/setup.bash                  # 再加载当前工作区构建出的包
printenv | grep -E 'ROS_DISTRO|ROS_DOMAIN_ID|RMW_IMPLEMENTATION|AMENT_PREFIX_PATH' # 查看关键 ROS 环境变量
ros2 doctor --report                       # 收集 ROS 环境诊断信息
ros2 pkg list | head                       # 列出 ROS 包;这里只显示前 10 行
ros2 pkg prefix <package_name>             # 查看某个包从哪个目录加载
colcon build --symlink-install             # 构建工作区并尽量链接源码,方便调试
colcon build --packages-select <package_name> # 只构建指定包
colcon build --packages-up-to <package_name>  # 构建指定包及其依赖
colcon test --packages-select <package_name>  # 运行指定包的测试
colcon test-result --verbose               # 显示测试通过/失败详情

每个新终端都要 source ROS 环境和工作区的 install/setup.bash。overlay 顺序会影响同名包的解析。构建报错时先读 colcon 输出和 log/ 中的具体包日志。

节点、Topic、Service、Action 与参数

ros2 node list                                  # 列出当前 ROS 2 网络中发现的节点
ros2 node info /node_name                      # 查看指定节点发布、订阅和服务
ros2 topic list -t                             # 列出 topic 及其消息类型
ros2 topic info /camera/image -v               # 查看图像 topic 的发布者、订阅者和 QoS
ros2 topic hz /scan                            # 统计雷达 topic 的实际发布频率
ros2 topic bw /camera/image                    # 估算图像 topic 的带宽占用
ros2 topic echo /joint_states --once           # 打印一条关节状态消息后退出
ros2 interface show sensor_msgs/msg/Image      # 查看 Image 消息有哪些字段
ros2 service list -t                           # 列出服务及其接口类型
ros2 action list -t                            # 列出 Action 名称及接口类型
ros2 param list /node_name                     # 列出节点参数
ros2 param get /node_name use_sim_time         # 查询节点是否使用仿真时间
ros2 param dump /node_name                     # 导出节点当前全部参数
ros2 run <package> <executable>                # 运行包中的单个可执行节点
ros2 launch <package> <file.launch.py>         # 按 launch 文件启动一个或多个节点

Topic 有名称但收不到消息时,检查 publisher/subscriber 是否存在、QoS 是否兼容、ROS_DOMAIN_ID 与 RMW 是否匹配、网络是否可达。图像或点云频率不稳时看带宽、CPU/GPU、QoS 和传输链路。

TF、时间与 rosbag

ros2 run tf2_tools view_frames                   # 生成 TF 坐标树图,便于检查连接关系
ros2 run tf2_ros tf2_echo base_link camera_link # 持续显示两个坐标系之间的变换
ros2 bag record /tf /tf_static /joint_states /camera/image # 录制这些 topic;Ctrl+C 停止
ros2 bag info <bag_directory>                   # 查看 rosbag 的时长、消息和 topic 信息
ros2 bag play <bag_directory> --clock           # 回放 bag 并发布仿真时钟

定位或感知异常时,核对 frame 名、TF 链是否连通、时间戳是否单调、各节点的仿真时间参数是否一致。录制图像和点云会快速占满磁盘,先选择必要 topic。

ROS 1(旧项目)

source /opt/ros/noetic/setup.bash        # 在当前终端加载 ROS 1 Noetic 环境
roscore                                   # 启动 ROS 1 主节点;通常先启动它
rosnode list                              # 列出 ROS 1 节点
rostopic list                             # 列出 ROS 1 topic
rostopic echo /topic                      # 持续打印 topic 消息;Ctrl+C 停止
rostopic hz /topic                        # 统计 topic 发布频率
rosservice list                           # 列出 ROS 1 服务
rosparam get /use_sim_time                # 查询是否使用仿真时间
roslaunch <package> <file.launch>         # 启动指定 ROS 1 launch 文件
rosbag record -O run.bag /tf /joint_states # 把 TF 与关节状态保存到 run.bag

ROS 1 与 ROS 2 的命令和通信机制不能直接混用。桥接项目需明确 bridge、消息类型以及 QoS 配置。

Docker 与 Compose

docker version                               # 查看客户端与服务端 Docker 版本
docker info                                  # 查看 Docker 配置、存储和运行信息
docker ps                                    # 列出正在运行的容器
docker ps -a                                 # 列出所有容器,包括已退出的
docker images                                # 列出本机已有镜像
docker logs -f --tail 200 <container>        # 跟踪容器最新 200 行日志;Ctrl+C 退出查看
docker exec -it <container> bash             # 进入运行中的容器交互式终端
docker inspect <container>                  # 查看容器详细配置和设备映射
docker stats                                 # 实时查看容器 CPU、内存和网络占用
docker compose up -d                         # 在后台启动 compose 中定义的服务
docker compose logs -f                       # 持续查看 compose 服务日志
docker compose down                          # 停止并移除 compose 创建的容器和网络

ROS 容器问题优先核对镜像中的 ROS distro、网络模式、ROS_DOMAIN_ID、时间同步、设备映射(如 /dev/ttyUSB0)、共享内存和 GPU 映射。设备权限不足时检查设备节点属组与 udev 规则,避免长期使用 --privileged。

网络与远程调试

ip addr                                      # 查看网卡、IP 地址和网卡状态
ip route                                     # 查看系统的网络路由规则
ping -c 3 <host>                             # 向主机发送 3 次连通性探测
ss -lntup                                    # 查看 TCP/UDP 监听端口及对应进程
hostname -I                                  # 显示本机 IP 地址
getent hosts <hostname>                      # 查询主机名能否解析为 IP
ssh user@robot-ip                            # 通过 SSH 登录机器人;替换用户名和地址
scp file user@robot-ip:/tmp/                 # 把本地文件复制到机器人 /tmp 目录
rsync -avP ./workspace/ user@robot-ip:~/workspace/ # 增量同步工作区并显示进度

ROS 2 跨机器通信要确认双方网络可达、域 ID 一致、DDS/RMW 配置匹配、防火墙允许所需流量。先用 ping、ip route 验证基础网络,再检查 ROS 发现和 topic。

USB、串口、摄像头与权限

lsusb                                        # 列出系统识别到的 USB 设备
ls -l /dev/ttyUSB* /dev/ttyACM* /dev/video*  # 查看串口、USB 串口和摄像头设备节点
udevadm info --query=all --name=/dev/ttyUSB0 # 查看指定串口设备的 udev 属性
groups                                       # 查看当前用户所属的权限组
sudo usermod -aG dialout $USER               # 将当前用户加入串口组;重新登录后生效
v4l2-ctl --list-devices                      # 列出摄像头设备;需安装 v4l-utils
v4l2-ctl --list-formats-ext -d /dev/video0   # 查看 video0 支持的分辨率和像素格式

设备找不到或权限错误时,检查线缆与供电、lsusb、内核日志 dmesg、udev 规则、用户组,以及容器设备映射。不要长期用 chmod 777 /dev/... 解决权限问题;设备重插后权限可能恢复,且开放范围过大。

常见排障工作流

节点启动了,但 ROS 2 Topic 没有数据

pgrep -af <node_or_launch_name>              # 按进程名查节点/launch 是否还在运行
ros2 node list                               # 查看 ROS 2 是否发现目标节点
ros2 topic list -t                           # 查看目标 topic 是否存在及其类型
ros2 topic info /target_topic -v              # 检查 topic 发布者、订阅者和 QoS 设置
ros2 topic hz /target_topic                   # 查看 topic 是否持续发布以及发布频率
echo "$ROS_DOMAIN_ID"; echo "$RMW_IMPLEMENTATION" # 显示本终端使用的域 ID 和通信实现

按“进程 → 节点 → topic 端点 → QoS → 网络与域 ID”的顺序逐层缩小范围。

宿主机能访问设备,容器里不能

ls -l /dev/video0 /dev/ttyUSB0          # 在宿主机检查设备节点和访问权限
docker inspect <container>                # 检查容器是否配置了设备映射
docker exec -it <container> bash          # 进入容器排查设备是否可见
# 在容器里运行:ls -l /dev/video0 /dev/ttyUSB0 # 与宿主机结果对比

核对容器启动参数的 --device、用户/组权限和 udev,再检查相机格式、帧率与驱动依赖。

控制或感知延迟、掉帧

top                                # 查看 CPU、内存占用最高的进程;按 q 退出
nvidia-smi                         # 查看 GPU 利用率和显存是否吃满
free -h                            # 查看内存和 swap 是否紧张
df -h                              # 查看录包或日志是否把磁盘写满
ros2 topic hz /camera/image        # 查看相机图像实际帧率
ros2 topic bw /camera/image        # 估算相机图像 topic 的带宽
docker stats                       # 查看是否是容器资源限制导致性能下降

先判断瓶颈来自 CPU、GPU/显存、内存、磁盘、网络还是消息 QoS。用 rosbag 记录代表性 topic,便于复现与对比。

安全与可复现习惯

  • 安装系统包使用 sudo apt install <package>,不要把 sudo 当默认前缀。
  • 运行来源不明的脚本前先阅读内容;避免直接执行 curl ... | sudo bash。
  • 保留启动参数、Ubuntu 与 ROS 版本、容器镜像 tag 和关键日志。
  • 长期项目固定依赖和镜像版本,并记录设备固件与驱动版本。
  • 执行机器人运动或力控命令前,确认仿真/安全状态、急停可用,速度与工作空间限制正确。

症状速查

症状

先看什么

程序没启动或卡死

pgrep -af、ps aux、journalctl、tail -f

磁盘或内存问题

df -h、du -sh、free -h、top

GPU 不可用

nvidia-smi、docker info、容器 GPU 配置

ROS Topic 无数据

ros2 node list、ros2 topic info -v、topic hz、QoS 与域 ID

TF 或定位异常

view_frames、tf2_echo、时间戳和 frame 名

设备权限或找不到设备

lsusb、ls -l /dev/...、groups、dmesg -T、docker inspect

Python import 失败

which python、python -m pip show ...、venv 和 ROS overlay

本手册作为命令入口索引。具体项目仍应以所用 Ubuntu、ROS 发行版、硬件驱动和部署规范为准;未知根因问题应继续收集日志与环境信息,不要只凭症状直接定因。