Raspberry Pi 5 完全实战指南：从入门到边缘计算

前言：Raspberry Pi 5 —— 树莓派的性能飞跃

2023年9月，树莓派基金会发布了 Raspberry Pi 5，这是自 2019 年 Raspberry Pi 4 以来最重大的一次升级。搭载博通 BCM2712 四核 Cortex-A76 处理器（2.4GHz）、VideoCore VII GPU、以及首次亮相的 RP1 I/O 控制器，Pi 5 的综合性能较 Pi 4 提升了 2-3 倍。更重要的是，它为边缘计算、轻量级 Kubernetes 集群、甚至小型桌面办公开辟了全新的可能性。本文将带你从零开始，全面掌握 Raspberry Pi 5 的硬件架构、系统配置、GPIO 编程、Docker/K3s 部署以及边缘计算实战。

Chapter 1: 硬件架构深度解析

1.1 核心硬件规格

Raspberry Pi 5 的核心是一颗博通 BCM2712 SoC，采用 16nm 工艺制造，搭载四核 ARM Cortex-A76 架构处理器，主频 2.4GHz，每个核心拥有 32KB L1 缓存和 512KB L2 缓存，共享 1MB L2 缓存（注：具体缓存配置因版本可能略有差异）。内存方面提供 4GB 和 8GB 两个 LPDDR4X 版本，实测内存带宽较 Pi 4 提升约 50%。

1.2 RP1 I/O 控制器 —— 树莓派自研芯片首秀

RPi 5 最大的架构变化是引入了树莓派自研的 RP1 南桥芯片。此前所有 I/O 功能直接由 SoC 处理，而 RP1 接管了 USB 3.0、千兆以太网、MIPI CSI/DSI、GPIO 等所有外设接口。这不仅释放了 BCM2712 的计算资源，还带来了显著的外置 I/O 性能提升：

• USB 3.0：两个独立 USB 3.0 控制器（5Gbps 共享），支持同时满速读写
• 千兆以太网：通过 RGMII 直连 RP1，实测吞吐可达 940Mbps 线速
• PCIe 2.0 x1：首次支持 PCIe 总线，可通过转接板连接 NVMe SSD
• 双 4K HDMI：支持同时驱动两台 4Kp60 显示器

1.3 电源管理与新增特性

RPi 5 引入了独立的电源管理 IC（PSMC），首次支持通过电源按钮硬关机/开机。同时新增了低速串口调试接口（UART，3-pin JST-SH），方便无网络环境下的系统调试。官方推荐电源提升至 5V 5A（27W），若外设较多建议使用主动散热方案。

Chapter 2: 系统安装与基础配置

2.1 系统镜像烧录

树莓派官方推荐使用 Raspberry Pi Imager 工具烧录系统。推荐选择 Raspberry Pi OS (64-bit)，其内核已针对 Cortex-A76 做了完整优化。安装步骤如下：

# 下载并安装 Raspberry Pi Imager（以 Linux 为例）
sudo apt install rpi-imager

# 或使用命令行直接烧录（高级用法）
# sudo dd if=2024-07-04-raspi-bookworm-arm64.img of=/dev/sdX bs=4M conv=fsync status=progress

2.2 首次启动与基础配置

首次启动后建议执行以下配置流程：

# 1. 更新系统
sudo apt update && sudo apt full-upgrade -y

# 2. 使用 raspi-config 进行基础配置
sudo raspi-config
#    → System Options → 设置主机名、密码
#    → Interface Options → 开启 SSH、I2C、SPI、Serial
#    → Performance Options → 设置 GPU 内存（桌面建议 128MB，无头模式 16MB）
#    → Localisation Options → 设置时区 Asia/Shanghai、zh_CN.UTF-8

# 3. 配置 Wi-Fi（无头模式提前在 boot 分区创建 wpa_supplicant.conf）
# country=CN
# network={
#     ssid="your-ssid"
#     psk="your-password"
# }

2.3 性能调优

针对 Pi 5 的高性能特性，进行以下调优：

# 启用 ZRAM 提升内存利用效率
sudo apt install zram-tools -y
sudo systemctl enable --now zramswap.service

# 配置 ZRAM（/etc/default/zramswap）
ALGO=zstd
PERCENT=50

# 开启硬件看门狗（提升长期运行稳定性）
echo "dtparam=on_watchdog" | sudo tee -a /boot/firmware/config.txt
sudo apt install watchdog -y
sudo systemctl enable watchdog

# 设置 CPU 高性能模式
echo 'governor="performance"' | sudo tee -a /boot/firmware/config.txt

Chapter 3: GPIO 编程实战

3.1 GPIO 引脚布局

Raspberry Pi 5 延续了 40-pin GPIO 排针（兼容 Pi 4），但 RP1 控制器带来了更快的 GPIO 翻转速度。下表为常用引脚映射：

3.2 Python GPIO 控制

推荐使用 gpiozero 库，它是树莓派官方维护的高级 GPIO 库，API 简洁且功能丰富：

#!/usr/bin/env python3
# LED blink + button control example
from gpiozero import LED, Button
from signal import pause

led = LED(17)        # GPIO17
button = Button(2)   # GPIO2 (internal pull-up)

# LED blink
led.blink(on_time=0.5, off_time=0.5)

# Button control
button.when_pressed = lambda: led.on()
button.when_released = lambda: led.off()

print("Press Ctrl+C to exit")
pause()

3.3 I2C 传感器读取（BME280 温湿度气压）

#!/usr/bin/env python3
# Read BME280 sensor via I2C
import smbus2
import bme280

# Initialize I2C bus
bus = smbus2.SMBus(1)  # Pi uses I2C-1
calibration_params = bme280.load_calibration_params(bus, 0x76)

# Read data
data = bme280.sample(bus, 0x76, calibration_params)
print(f"Temperature: {data.temperature:.1f} degree C")
print(f"Humidity: {data.humidity:.1f} %")
print(f"Pressure: {data.pressure:.1f} hPa")

3.4 PWM 控制伺服电机

#!/usr/bin/env python3
from gpiozero import Servo
from time import sleep

servo = Servo(18)  # GPIO18 supports hardware PWM

# Sweep servo
while True:
    servo.min()
    sleep(1)
    servo.mid()
    sleep(1)
    servo.max()
    sleep(1)

Chapter 4: Docker 与 K3s 边缘集群

4.1 Docker 安装与配置

Raspberry Pi OS (64-bit) 安装 Docker 非常简单，官方提供了自动化脚本：

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker run --rm arm64v8/alpine uname -m
# Expected output: aarch64

# Install Docker Compose plugin
sudo apt install docker-compose-plugin -y

# Configure Docker with systemd cgroup driver (required for K3s)
sudo sh -c 'echo "{\"exec-opts\": [\"native.cgroupdriver=systemd\"]}" > /etc/docker/daemon.json'
sudo systemctl restart docker

4.2 部署 K3s 边缘集群

K3s 是 Rancher Labs 推出的轻量级 Kubernetes 发行版，整个二进制包不到 100MB，非常适合 ARM 设备。使用 3 台 Pi 5 即可搭建一个完整的边缘计算集群：

# ===== On master node (pi-master) =====
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik --node-name=pi-master" sh -

# Get join token
cat /var/lib/rancher/k3s/server/node-token

# ===== On worker nodes (pi-worker-1, pi-worker-2) =====
curl -sfL https://get.k3s.io | K3S_URL=https://pi-master:6443 \
  K3S_TOKEN= \
  INSTALL_K3S_EXEC="--node-name=pi-worker-1" sh -

# ===== Verify cluster =====
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes
# NAME          STATUS   ROLES                  AGE   VERSION
# pi-master     Ready    control-plane,master   5m    v1.28+k3s2
# pi-worker-1   Ready                     2m    v1.28+k3s2
# pi-worker-2   Ready                     1m    v1.28+k3s2

4.3 应用部署实战

在 Pi 集群上部署 Nginx Ingress 和示例应用：

# Deploy ARM-compatible NGINX Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.4/deploy/static/provider/baremetal/deploy.yaml

# Wait for ingress ready
kubectl rollout status deployment ingress-nginx-controller -n ingress-nginx --timeout=120s

# Deploy sample app (auto selects ARM64 image)
kubectl create deployment web --image=arm64v8/nginx:alpine --replicas=3
kubectl expose deployment web --port=80 --type=NodePort

# Create Ingress resource
kubectl apply -f - <

mkdir ~/home-assistant && cd ~/home-assistant

cat > docker-compose.yml <<'COMPOSE_EOF'
version: '3.8'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    privileged: true
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
      - /run/dbus:/run/dbus:ro
    network_mode: host
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0  # Zigbee dongle

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./zigbee2mqtt-data:/app/data
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    network_mode: host
    depends_on:
      - mosquitto

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:2
    restart: unless-stopped
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
    ports:
      - "1883:1883"
      - "9001:9001"
COMPOSE_EOF

docker compose up -d

# Backup script: /opt/scripts/backup.sh
#!/bin/bash
BACKUP_DIR="/mnt/nas/backups/pi5/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# Backup Home Assistant config
docker exec homeassistant tar czf - /config > $BACKUP_DIR/ha-config.tar.gz

# Backup K3s etcd
sudo k3s etcd-snapshot save --dir $BACKUP_DIR

# Keep last 7 days only
find /mnt/nas/backups/pi5 -maxdepth 1 -mtime +7 -type d -exec rm -rf {} \;

# Cron: 0 3 * * * /opt/scripts/backup.sh

# docker-compose addition for monitoring
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus:/etc/prometheus

  node-exporter:
    image: prom/node-exporter:latest
    ports:
      - "9100:9100"
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=pi5admin

# Update EEPROM to support NVMe boot priority
sudo rpi-eeprom-config --edit
# Modify: BOOT_ORDER=0xf4641 (NVMe first)

# Verify PCIe device detection
lspci

# Format and mount NVMe drive
sudo mkfs.ext4 /dev/nvme0n1p1
sudo mount /dev/nvme0n1p1 /mnt/ssd

# Get NVMe benchmark
sudo apt install fio -y
fio --name=randread --ioengine=libaio --iodepth=64 \
    --rw=randread --bs=4k --size=1G --numjobs=4 \
    --runtime=60 --time_based --directory=/mnt/ssd

# Clone kernel source
git clone --depth=1 https://github.com/raspberrypi/linux.git
cd linux
KERNEL=kernel8

# Apply RT preempt patch
# Download matching RT patch from kernel.org
patch -p1 < ../patch-6.x.x-rtxx.patch

# Configure kernel
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2712_defconfig
make ARCH=arm64 menuconfig
# Enable: Preemptible Kernel (Low-Latency Desktop)
#   and Full Kernel Preemption if needed

# Build
make -j$(nproc) ARCH=arm64 Image modules dtbs

# Install
sudo make ARCH=arm64 modules_install
sudo cp arch/arm64/boot/Image /boot/firmware/kernel8-rt.img
sudo cp arch/arm64/boot/dts/broadcom/*.dtb /boot/firmware/

# Compare latency
# Non-RT: ~100-500 microseconds
# RT: ~20-50 microseconds

#!/usr/bin/env python3
# UPS power monitor (Pijuice HAT)
from pijuice import PiJuice
from subprocess import call
import time

pj = PiJuice(1, 0x14)

while True:
    charge = pj.status.GetChargeLevel()
    if isinstance(charge, dict) and 'data' in charge:
        level = charge['data']
        if level < 10:
            print(f"Critical battery ({level}%), shutting down...")
            call(['sudo', 'shutdown', '-h', 'now'])
        elif level < 20:
            print(f"Low battery ({level}%), stopping non-essential services...")
    time.sleep(60)