jetson_yolo_deployment 01_linux_dev_env

01 --- Linux 开发环境搭建

作者：智汇嵌入式实验室 · 7yewh

本文件是 Jetson YOLO 部署系列的第 1 篇。

目标：从"能用 Linux"到"能在 Linux 上高效开发"。

你现在的水平 vs 部署需要的水平

复制代码

你现在会的：              部署 YOLO 需要的：
  ls / cd / mkdir           ✓ 已会
  cat / cp / mv             ✓ 已会
  基本文件操作              ✓ 已会
  ──────────────────────────────────────
  SSH 远程连接              ← 必须熟练（Jetson 没有显示器时全靠它）
  包管理（apt）             ← 必须熟练（装依赖全靠它）
  Python 虚拟环境           ← 必须会（避免系统 Python 被污染）
  Docker 基础               ← 建议会（NVIDIA 官方容器镜像）
  环境变量 / PATH           ← 必须理解（CUDA 路径配置）
  权限与用户                ← 必须理解（GPU 访问权限）

1. SSH 远程连接（最重要的技能）

Jetson 开发 90% 的时间都是通过 SSH 远程操作，不接显示器。

1.1 基本连接

bash 复制代码

# 从你的 PC 连接 Jetson（需要知道 Jetson 的 IP）
ssh username@192.168.1.100

# 第一次连接会问你是否信任，输入 yes
# 然后输入密码

1.2 查看 Jetson IP 地址

bash 复制代码

# 在 Jetson 上执行（如果接了显示器）
ip addr show
# 或
hostname -I

# 看 eth0（有线）或 wlan0（WiFi）的 inet 地址

1.3 免密登录（强烈推荐）

每次输密码很烦，配置 SSH 密钥后自动登录：

bash 复制代码

# 在你的 PC 上执行（Windows 用 PowerShell 或 Git Bash）

# 第一步：生成密钥对（如果没有的话）
ssh-keygen -t ed25519
# 一路回车，不设密码

# 第二步：把公钥复制到 Jetson
ssh-copy-id username@192.168.1.100
# 输入一次密码

# 之后再 ssh 就不需要密码了
ssh username@192.168.1.100

1.4 SSH 配置文件（简化命令）

编辑 ~/.ssh/config，以后只需 ssh jetson 即可连接：

复制代码

Host jetson
    HostName 192.168.1.100
    User username
    IdentityFile ~/.ssh/id_ed25519

bash 复制代码

# 配置后
ssh jetson          # 等价于 ssh username@192.168.1.100
scp file jetson:~/  # 复制文件到 Jetson 家目录

1.5 文件传输

bash 复制代码

# PC → Jetson（上传）
scp model.onnx jetson:~/projects/

# Jetson → PC（下载）
scp jetson:~/results/output.jpg ./

# 传整个目录
scp -r ./dataset jetson:~/projects/

# 大文件推荐用 rsync（断点续传）
rsync -avz --progress ./dataset/ jetson:~/projects/dataset/

1.6 VS Code 远程开发（强烈推荐）

VS Code 的 Remote-SSH 插件可以直接在 Jetson 上编辑代码：

复制代码

1. 安装 VS Code 插件：Remote - SSH
2. Ctrl+Shift+P → "Remote-SSH: Connect to Host"
3. 输入 jetson（如果配了 config）或 username@IP
4. 连接后，VS Code 就像在本地一样编辑 Jetson 上的文件
5. 终端也是 Jetson 的终端，可以直接运行程序

这是 Jetson 开发最推荐的方式，比纯命令行效率高很多。

2. 包管理（apt）

Ubuntu/Debian 系统用 apt 管理软件包。Jetson 的系统就是 Ubuntu。

2.1 基本命令

bash 复制代码

# 更新包列表（安装任何东西之前先执行）
sudo apt update

# 安装软件
sudo apt install <包名>

# 安装多个
sudo apt install vim git curl wget htop

# 卸载
sudo apt remove <包名>

# 搜索包
apt search <关键词>

# 查看已安装的包
dpkg -l | grep <关键词>

2.2 Jetson 上常装的包

bash 复制代码

# 基础开发工具
sudo apt install build-essential cmake git curl wget

# Python 开发
sudo apt install python3-pip python3-venv python3-dev

# 视频/图像处理
sudo apt install libopencv-dev v4l-utils

# 系统监控
sudo apt install htop iotop

# 网络工具
sudo apt install net-tools openssh-server

2.3 apt 换源（国内加速）

Jetson 默认用国外源，下载很慢。换成清华/阿里源：

bash 复制代码

# 备份原始源
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 编辑（以 Ubuntu 20.04 ARM64 为例，Jetson 是 ARM 架构）
sudo vim /etc/apt/sources.list

# 注意：Jetson 是 arm64 架构，不能用普通 x86 的源
# 要用 ports.ubuntu.com 对应的镜像
# 清华源示例：
# deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports/ focal main restricted
# deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports/ focal-updates main restricted

sudo apt update

3. Python 环境管理

核心原则：永远不要在系统 Python 里直接 pip install。

Jetson 系统自带 Python 3.8（JetPack 5.x），系统很多组件依赖它。

如果你 sudo pip install 装了不兼容的包，可能搞坏系统。

3.1 虚拟环境（venv，推荐）

bash 复制代码

# 创建虚拟环境
python3 -m venv ~/envs/yolo

# 激活
source ~/envs/yolo/bin/activate

# 激活后，终端提示符会变成：
(yolo) user@jetson:~$

# 在虚拟环境里安装包（不需要 sudo）
pip install ultralytics opencv-python numpy

# 退出虚拟环境
deactivate

3.2 pip 换源（国内加速）

bash 复制代码

# 临时使用清华源
pip install ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久配置
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << 'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

3.3 Jetson 上 PyTorch 的特殊安装

重要：Jetson 不能直接 pip install torch！

因为 Jetson 是 ARM 架构 + CUDA，需要 NVIDIA 专门编译的 PyTorch：

bash 复制代码

# 错误做法（会装到 CPU 版本，无法用 GPU）
pip install torch  # ❌

# 正确做法：从 NVIDIA 论坛下载预编译 wheel
# https://forums.developer.nvidia.com/t/pytorch-for-jetson/72048

# 示例（JetPack 5.x, PyTorch 2.1）
wget https://developer.download.nvidia.com/...torch-2.1.0-cp38-cp38-linux_aarch64.whl
pip install torch-2.1.0-cp38-cp38-linux_aarch64.whl

# 验证 CUDA 可用
python3 -c "import torch; print(torch.cuda.is_available())"
# 应输出 True

3.4 Conda（可选，但 Jetson 上不太推荐）

Conda 在 Jetson 上可以用 Miniforge（ARM 版），但：

占用空间大
有些包没有 ARM 预编译版
和 JetPack 的 CUDA 环境可能冲突

建议用 venv + pip，更轻量更可控。

4. 环境变量与 PATH

部署时经常遇到"找不到 CUDA"、"找不到 TensorRT"，本质都是 PATH 没配对。

4.1 什么是环境变量

bash 复制代码

# 查看所有环境变量
env

# 查看某个变量
echo $PATH
echo $HOME
echo $CUDA_HOME

# PATH 是一个目录列表，用冒号分隔
# 当你输入 python3 时，系统按 PATH 里的目录顺序查找 python3 可执行文件

4.2 Jetson 上必须配的环境变量

bash 复制代码

# 编辑 ~/.bashrc（每次登录自动执行）
vim ~/.bashrc

# 在文件末尾添加：

# CUDA
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

# TensorRT（JetPack 已自带，但有时需要显式指定）
export LD_LIBRARY_PATH=/usr/lib/aarch64-linux-gnu:$LD_LIBRARY_PATH

# 保存后，让配置生效
source ~/.bashrc

# 验证
nvcc --version       # 应该显示 CUDA 版本
python3 -c "import tensorrt; print(tensorrt.__version__)"

4.3 常见坑

复制代码

问题：python3 找不到某个包
原因：你在虚拟环境外安装的，但在虚拟环境内运行
解决：激活虚拟环境后再 pip install

问题：nvcc 找不到
原因：CUDA 的 bin 目录没加到 PATH
解决：按上面配 ~/.bashrc

问题：import torch 报错 CUDA 不可用
原因：装了 CPU 版 PyTorch
解决：用 NVIDIA 提供的 ARM CUDA 版 wheel

问题：运行推理程序时 "cannot open shared object file"
原因：动态库路径没配
解决：把库所在目录加到 LD_LIBRARY_PATH

5. Docker 基础（建议了解）

NVIDIA 提供了官方 Docker 容器，包含完整的 CUDA + TensorRT + DeepStream 环境。

用 Docker 可以避免大量环境配置问题。

5.1 核心概念

复制代码

Docker 镜像（Image）= 一个"打包好的系统快照"
  包含：Ubuntu + CUDA + Python + 所有依赖
  你不需要自己装任何东西

Docker 容器（Container）= 镜像的运行实例
  类比：镜像是类，容器是对象
  一个镜像可以启动多个容器
  容器里的修改不影响镜像

5.2 Jetson 上的 Docker

bash 复制代码

# Jetson 已预装 Docker 和 nvidia-container-runtime
# 验证
sudo docker info | grep -i nvidia

# 拉取 NVIDIA 官方容器（包含 TensorRT + CUDA）
sudo docker pull nvcr.io/nvidia/l4t-tensorrt:r8.5.2-runtime

# 启动容器（挂载 GPU 和本地目录）
sudo docker run -it --rm \
    --runtime nvidia \
    --network host \
    -v ~/projects:/workspace \
    nvcr.io/nvidia/l4t-tensorrt:r8.5.2-runtime \
    bash

# 现在你在容器里了
# /workspace 就是你本地的 ~/projects 目录
# CUDA、TensorRT 都已配好

5.3 常用 Docker 命令

bash 复制代码

# 查看本地镜像
sudo docker images

# 查看运行中的容器
sudo docker ps

# 查看所有容器（包括已停止的）
sudo docker ps -a

# 停止容器
sudo docker stop <container_id>

# 删除容器
sudo docker rm <container_id>

# 删除镜像
sudo docker rmi <image_id>

5.4 什么时候用 Docker

复制代码

建议用 Docker 的场景：
  - 你不想折腾环境配置
  - 需要特定版本的 TensorRT/CUDA
  - 要复现别人的项目
  - 部署到生产环境

建议不用 Docker 的场景：
  - 学习阶段，想理解每一步在干什么
  - 需要直接访问 CSI 摄像头（Docker 里配置更复杂）
  - 存储空间紧张（Docker 镜像很大，通常 5-10 GB）

6. 文件系统理解

6.1 Jetson 上的关键目录

bash 复制代码

/usr/local/cuda/          # CUDA 工具链
/usr/lib/aarch64-linux-gnu/ # 系统动态库（TensorRT 等）
/usr/src/tensorrt/          # TensorRT 示例代码
/opt/nvidia/                # NVIDIA 专有软件（DeepStream 等）
~/                          # 你的家目录，项目放这里
/tmp/                       # 临时文件，重启后清空
/media/                     # USB 设备挂载点

6.2 存储空间管理

Jetson Nano 用 SD 卡，空间有限（通常 32-64 GB）：

bash 复制代码

# 查看磁盘使用
df -h

# 查看当前目录占用
du -sh *

# 查看最大的文件/目录
du -h --max-depth=1 / | sort -hr | head -20

# 清理 apt 缓存
sudo apt clean
sudo apt autoremove

# 清理 Docker 缓存
sudo docker system prune -a

7. 权限管理

7.1 为什么重要

bash 复制代码

# 你会经常遇到这种报错：
Permission denied
# 或
CUDA error: insufficient permissions

# 原因：
# 1. 访问 GPU 设备需要权限
# 2. 某些系统目录需要 sudo
# 3. 脚本没有执行权限

7.2 基本操作

bash 复制代码

# 查看文件权限
ls -la

# 给脚本加执行权限
chmod +x run_inference.sh

# 把用户加入 docker 组（不用每次 sudo docker）
sudo usermod -aG docker $USER
# 重新登录后生效

# 把用户加入 video 组（访问摄像头）
sudo usermod -aG video $USER

8. 本章实操任务

完成以下任务验证你的环境搭建能力：

复制代码

□ 1. 通过 SSH 连接到 Jetson（或一台远程 Linux 机器）
□ 2. 配置 SSH 免密登录
□ 3. 用 scp 传一个文件到远程机器
□ 4. 安装 VS Code Remote-SSH 并连接
□ 5. 创建 Python 虚拟环境，安装 numpy 和 opencv-python
□ 6. 配置 pip 清华源
□ 7. 配置 ~/.bashrc 中的 CUDA 环境变量（如果有 Jetson）
□ 8. 拉取一个 Docker 镜像并进入容器（如果有 Docker）

完成后你就具备了在 Jetson 上进行开发的基本能力。

智汇嵌入式实验室 · 7yewh