适用对象与使用方法
面向机器人、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、网络发现和设备权限。
命令行基本功
目的 | 命令 | 说明 |
路径与文件 |
| 查看当前目录;显示隐藏文件、权限与大小 |
切换目录 |
| 进入工作区;切回上一个目录 |
创建、复制、移动 |
|
|
查找文件/文本 |
| 没有 rg 时可用 |
看文件与日志 |
| 分页查看;持续跟踪日志,按 q 退出 |
帮助与历史 |
| 查询手册、选项和最近命令 |
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 和关键日志。
- 长期项目固定依赖和镜像版本,并记录设备固件与驱动版本。
- 执行机器人运动或力控命令前,确认仿真/安全状态、急停可用,速度与工作空间限制正确。
症状速查
症状 | 先看什么 |
程序没启动或卡死 |
|
磁盘或内存问题 |
|
GPU 不可用 |
|
ROS Topic 无数据 |
|
TF 或定位异常 |
|
设备权限或找不到设备 |
|
Python import 失败 |
|
本手册作为命令入口索引。具体项目仍应以所用 Ubuntu、ROS 发行版、硬件驱动和部署规范为准;未知根因问题应继续收集日志与环境信息,不要只凭症状直接定因。