1. 环境准备与系统配置

树莓派5到手后第一件事就是系统安装和环境配置。我推荐使用官方的Raspberry Pi Imager工具，它不仅支持多种操作系统版本，还能在烧录前直接配置SSH、Wi-Fi等参数，特别适合无头模式（无显示器）部署。

系统烧录实战步骤：

1. 下载并安装Raspberry Pi Imager（Windows/Mac/Linux均支持）
2. 插入TF卡（建议32GB以上），选择Raspberry Pi OS Lite（无桌面版更轻量）
3. 点击齿轮图标开启高级选项：
   • 启用SSH：设置密码认证或公钥登录
   • 配置Wi-Fi：填写SSID和密码
   • 设置区域选项：时区、键盘布局
4. 点击烧录，等待完成后插入树莓派启动

注意：如果烧录中途中断导致TF卡无法识别，可以用diskpart工具清理：

diskpart
list disk
select disk X  # X替换为你的TF卡磁盘号
attributes disk clear readonly
clean

基础环境调优：

# 首次登录后立即更新
sudo apt update && sudo apt upgrade -y

# 安装基础工具包
sudo apt install -y vim git curl wget tmux

# 设置交换文件（避免内存不足）
sudo dphys-swapfile swapoff
sudo sed -i 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile
sudo dphys-swapfile setup && sudo dphys-swapfile swapon

国内用户建议换源加速下载，虽然原始文章提到chsrc工具，但我实测发现手动换源更稳定。编辑/etc/apt/sources.list和/etc/apt/sources.list.d/raspi.list，将官方源替换为清华源或中科大源。

2. 远程开发环境搭建

2.1 SSH基础配置

树莓派默认开启SSH服务，但为了安全建议修改默认端口并禁用密码登录：

sudo nano /etc/ssh/sshd_config

修改以下参数：

Port 2022  # 改为非常用端口
PermitRootLogin no
PasswordAuthentication no  # 禁用密码登录
PubkeyAuthentication yes

重启服务：sudo systemctl restart ssh

2.2 VSCode远程开发

在本地电脑安装VSCode后，安装Remote-SSH扩展（ms-vscode-remote.remote-ssh）。点击左下角绿色按钮 > "Connect to Host" > "Configure SSH Hosts"，编辑配置文件：

Host RaspberryPi5
  HostName 192.168.1.100  # 树莓派IP
  User pi
  Port 2022
  IdentityFile ~/.ssh/pi_rsa  # 你的私钥路径

保存后即可在远程主机列表看到"RaspberryPi5"，点击连接后VSCode会自动在树莓派上安装服务端组件。首次连接较慢，成功后你就可以在本地直接编辑树莓派上的文件了。

实用技巧：

• 使用Remote Explorer管理多个设备
• 通过端口转发调试Web服务（比如将树莓派的3000端口转发到本地）
• 安装Python扩展后，VSCode会自动识别远程解释器

2.3 GUI应用远程调试

虽然无头模式足够开发，但有时需要调试OpenCV等图形应用。推荐两种方案：

方案A：X11转发（轻量级） 在树莓派安装X11基础包：

sudo apt install x11-apps xauth

本地电脑安装XServer（Windows用VcXsrv，Mac用XQuartz）。启动XLaunch时选择"Disable access control"。

连接时添加-Y参数：

ssh -Y pi@192.168.1.100

测试：运行xeyes会出现两个眼睛窗口。

方案B：VNC远程桌面 安装RealVNC更稳定：

sudo apt install realvnc-vnc-server
sudo raspi-config  # 进入Interfacing Options启用VNC

手机和电脑安装VNC Viewer客户端，输入树莓派IP即可连接。

3. 容器化开发环境

用Docker容器隔离开发环境，避免污染主机系统，也方便团队统一环境。

3.1 Docker安装

树莓派5是ARM64架构，官方已提供支持：

# 一键安装脚本
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 添加用户到docker组
sudo usermod -aG docker pi
newgrp docker  # 立即生效

# 国内用户配置镜像加速
sudo nano /etc/docker/daemon.json

添加内容：

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

重启服务：sudo systemctl restart docker

3.2 开发容器实战

创建一个Python开发环境的Dockerfile：

FROM python:3.9-slim-bullseye

WORKDIR /app
COPY requirements.txt .

# 换源并安装依赖
RUN sed -i 's/deb.debian.org/mirrors.ustc.edu.cn/g' /etc/apt/sources.list && \
    apt update && apt install -y libopencv-dev && \
    pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

VOLUME ["/app"]
CMD ["tail", "-f", "/dev/null"]

构建镜像：docker build -t pi-pydev .

使用docker-compose管理更便捷：

version: '3'
services:
  dev:
    image: pi-pydev
    volumes:
      - .:/app
      - /tmp/.X11-unix:/tmp/.X11-unix  # 图形支持
    environment:
      - DISPLAY=host.docker.internal:0
    network_mode: host  # 使用主机网络

运行：docker-compose up -d

4. 自动化部署流水线

4.1 Git钩子自动同步

在树莓派创建Git仓库作为中转站，实现代码自动部署：

mkdir /home/pi/repo/myproject.git
cd /home/pi/repo/myproject.git
git init --bare

编辑钩子脚本hooks/post-receive：

#!/bin/bash
TARGET="/home/pi/projects/myproject"
while read oldrev newrev refname
do
    if [[ $refname = "refs/heads/main" ]]; then
        echo "Deploying to $TARGET..."
        git --work-tree=$TARGET --git-dir=/home/pi/repo/myproject.git checkout -f
        cd $TARGET
        pip install -r requirements.txt
        systemctl restart myapp.service
    fi
done

赋予执行权限：chmod +x hooks/post-receive

本地开发机添加远程仓库：

git remote add pi pi@192.168.1.100:repo/myproject.git
git push pi main  # 推送后自动部署

4.2 系统服务管理

用systemd管理应用服务，确保宕机后自动重启：

sudo nano /etc/systemd/system/myapp.service

内容如下：

[Unit]
Description=My Python App
After=network.target docker.service

[Service]
User=pi
WorkingDirectory=/home/pi/projects/myproject
ExecStart=/usr/bin/docker-compose up
ExecStop=/usr/bin/docker-compose down
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable myapp.service
sudo systemctl start myapp.service

查看日志：journalctl -u myapp.service -f

4.3 监控与告警

安装监控组件实时掌握资源使用情况：

# 安装监控工具
sudo apt install htop glances

# 使用Glances Web界面
glances -w

访问http://树莓派IP:61208查看实时监控。

配置资源阈值告警：

# 创建监控脚本
nano ~/check_resource.sh

内容：

#!/bin/bash
CPU=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}')
if (( $(echo "$CPU > 80" | bc -l) )); then
    echo "High CPU usage: $CPU%" | mail -s "Alert" your@email.com
fi

添加定时任务：crontab -e

*/5 * * * * /home/pi/check_resource.sh

5. 实战案例：IoT项目开发流

以一个温湿度监控项目为例，演示完整开发部署流程。

硬件准备：

• DHT11传感器连接GPIO4引脚
• 树莓派5 + 电源 + 存储卡

代码结构：

project/
├── app.py
├── requirements.txt
├── Dockerfile
└── docker-compose.yml

app.py核心代码：

import Adafruit_DHT
import time
from flask import Flask

app = Flask(__name__)
sensor = Adafruit_DHT.DHT11
pin = 4

@app.route('/metrics')
def metrics():
    humidity, temperature = Adafruit_DHT.read_retry(sensor, pin)
    return f'temperature {temperature}\nhumidity {humidity}'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

docker-compose.yml：

version: '3'
services:
  sensor-app:
    build: .
    ports:
      - "5000:5000"
    devices:
      - "/dev/gpiomem:/dev/gpiomem"
    restart: unless-stopped

部署命令：

# 构建并启动
docker-compose up --build -d

# 查看日志
docker-compose logs -f

# 测试接口
curl http://localhost:5000/metrics

自动化集成： 在项目根目录创建.github/workflows/deploy.yml实现GitHub Actions自动部署：

name: Deploy to Pi
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Copy files via SSH
      uses: appleboy/scp-action@v0.1.3
      with:
        host: ${{ secrets.PI_HOST }}
        username: ${{ secrets.PI_USER }}
        key: ${{ secrets.PI_SSH_KEY }}
        source: "."
        target: "/home/pi/projects/sensor"
    - name: Restart service
      uses: appleboy/ssh-action@v0.1.10
      with:
        host: ${{ secrets.PI_HOST }}
        username: ${{ secrets.PI_USER }}
        key: ${{ secrets.PI_SSH_KEY }}
        script: |
          cd /home/pi/projects/sensor
          docker-compose up --build -d

这套流程让我在多次迭代中节省了大量部署时间，特别是团队协作时，所有人都通过统一的开发环境工作，避免了"在我机器上是好的"这类问题。

最后分享一个踩坑经验：树莓派5的GPIO驱动与前代略有不同，如果遇到权限问题，需要将用户加入gpio组：sudo usermod -aG gpio pi，并在容器内映射设备文件/dev/gpiomem。