# 树莓派 5 8G 部署指南

Nginx Stream + SSL Preread 自动分流方案在树莓派 5 上的完整安装、编译和运行指南。

> **适用系统**：Ubuntu 24.04 for Raspberry Pi / Raspberry Pi OS (Bookworm)  
> **硬件**：Raspberry Pi 5 8GB  
> **最后更新**：2026-10-06

---

## 目录

1. [系统准备](#1-系统准备)
2. [Nginx 安装](#2-nginx-安装)
3. [从源码编译 Nginx（可选）](#3-从源码编译-nginx可选)
4. [SSL 证书配置](#4-ssl-证书配置)
5. [配置部署](#5-配置部署)
6. [防火墙设置](#6-防火墙设置)
7. [性能优化](#7-性能优化)
8. [开机自启与守护进程](#8-开机自启与守护进程)
9. [验证与测试](#9-验证与测试)
10. [常见问题](#10-常见问题)

---

## 1. 系统准备

### 1.1 系统更新

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git vim htop net-tools build-essential
```

### 1.2 确认系统版本

```bash
lsb_release -a
uname -r
uname -m          # 应为 aarch64
free -h           # 应为 8GB
```

### 1.3 设置静态 IP（推荐）

```bash
sudo vim /etc/netplan/50-cloud-init.yaml
```

```yaml
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: no
      addresses:
        - 192.168.1.100/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 114.114.114.114]
```

```bash
sudo netplan apply
```

### 1.4 设置时区

```bash
sudo timedatectl set-timezone Asia/Shanghai
timedatectl
```

---

## 2. Nginx 安装

### 2.1 方式一：APT 安装（推荐）

```bash
sudo apt install -y nginx-full
nginx -v
nginx -V 2>&1 | grep -o "with-stream"
```

### 2.2 方式二：PPA 安装（获取更新版本）

```bash
sudo add-apt-repository ppa:nginx/stable
sudo apt update
sudo apt install -y nginx-full
```

### 2.3 验证模块完整性

```bash
nginx -V 2>&1 | grep -E "with-stream|with-http_ssl_module|with-http_v2_module"
```

**必需模块清单**：

| 模块 | 用途 |
|------|------|
| `with-stream` | TCP/UDP 代理 |
| `with-stream_ssl_module` | Stream SSL 支持 |
| `with-stream_ssl_preread_module` | TLS ClientHello 预读 |
| `with-http_ssl_module` | HTTP SSL 终结 |
| `with-http_v2_module` | HTTP/2 支持 |

---

## 3. 从源码编译 Nginx（可选）

### 3.1 安装编译依赖

```bash
sudo apt install -y \
    build-essential libpcre3 libpcre3-dev \
    zlib1g zlib1g-dev libssl-dev \
    libgd-dev libgeoip-dev libxml2-dev libxslt1-dev
```

### 3.2 下载源码

```bash
NGINX_VERSION="1.26.3"
cd /tmp
wget https://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz
tar -xzf nginx-${NGINX_VERSION}.tar.gz
cd nginx-${NGINX_VERSION}
```

### 3.3 编译配置

```bash
./configure \
    --prefix=/etc/nginx \
    --sbin-path=/usr/sbin/nginx \
    --modules-path=/usr/lib/nginx/modules \
    --conf-path=/etc/nginx/nginx.conf \
    --error-log-path=/var/log/nginx/error.log \
    --http-log-path=/var/log/nginx/access.log \
    --pid-path=/var/run/nginx.pid \
    --lock-path=/var/run/nginx.lock \
    --user=www-data \
    --group=www-data \
    --with-stream \
    --with-stream_ssl_module \
    --with-stream_ssl_preread_module \
    --with-http_ssl_module \
    --with-http_v2_module \
    --with-http_geoip_module \
    --with-http_realip_module \
    --with-http_gzip_static_module \
    --with-http_sub_module \
    --with-http_stub_status_module \
    --with-pcre-jit \
    --with-cc-opt="-march=armv8-a+crc -mtune=cortex-a76" \
    --with-ld-opt="-Wl,-z,relro -Wl,-z,now"
```

**树莓派特定编译优化**：

| 参数 | 说明 |
|------|------|
| `-march=armv8-a+crc` | 利用 ARMv8 CRC 指令加速 |
| `-mtune=cortex-a76` | 针对树莓派 5 的 Cortex-A76 优化 |
| `-Wl,-z,relro` | 只读重定位，安全加固 |
| `--with-pcre-jit` | PCRE JIT 编译，正则加速 |

### 3.4 编译安装

```bash
make -j4    # 4 核并行编译，约 5-15 分钟
sudo make install
nginx -V
```

### 3.5 创建 Systemd 服务

```bash
sudo vim /etc/systemd/system/nginx.service
```

```ini
[Unit]
Description=The nginx HTTP and reverse proxy server
After=network-online.target remote-fs.target nss-lookup.target
Wants=network-online.target

[Service]
Type=forking
PIDFile=/var/run/nginx.pid
ExecStartPre=/usr/sbin/nginx -t
ExecStart=/usr/sbin/nginx
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s QUIT $MAINPID
PrivateTmp=true
TimeoutStopSec=5
KillMode=mixed

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable nginx
```

---

## 4. SSL 证书配置

### 4.1 安装 Certbot

```bash
sudo apt install -y certbot python3-certbot-nginx
```

### 4.2 申请通配符证书

```bash
sudo certbot certonly --manual --preferred-challenges dns \
    -d zhonjin.com -d "*.zhonjin.com"
```

按提示添加 DNS TXT 记录，覆盖所有子域名：
- `zhonjin.com`
- `chanking.zhonjin.com`
- `mqtt.zhonjin.com`
- `baolin.zhonjin.com`

### 4.3 证书目录权限

```bash
sudo chmod 755 /etc/letsencrypt/live/
sudo chmod 644 /etc/letsencrypt/live/zhonjin.com/fullchain.pem
sudo chmod 600 /etc/letsencrypt/live/zhonjin.com/privkey.pem
sudo chown root:root /etc/letsencrypt/live/zhonjin.com/privkey.pem
```

### 4.4 自动续期

```bash
sudo certbot renew --dry-run    # 测试续期
sudo crontab -e
# 添加：
0 3 * * * certbot renew --quiet --post-hook "nginx -s reload"
```

---

## 5. 配置部署

### 5.1 部署配置文件

```bash
# 创建配置目录
sudo mkdir -p /etc/nginx/conf.d /etc/nginx/stream.d

# 备份原始配置
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

# 部署新配置
sudo cp nginx.conf /etc/nginx/nginx.conf
sudo cp zhonjin_http.conf /etc/nginx/conf.d/zhonjin_http.conf
sudo cp zhonjin_stream.conf /etc/nginx/stream.d/zhonjin_stream.conf

# 测试并重载
sudo nginx -t
sudo systemctl reload nginx
```

### 5.2 验证端口监听

```bash
sudo ss -tlnp | grep nginx

# 预期输出应包含：
# 0.0.0.0:40130    (stream 外网 - chanking)
# 0.0.0.0:40715    (stream 外网 - mqtt)
# 0.0.0.0:40716    (stream 外网 - baolin)
# 0.0.0.0:40719    (stream 外网 - baolin)
# 127.0.0.1:5005   (HTTPS 内网)
# 127.0.0.1:5006   (HTTP 跳转)
# ... 其他内部端口
```

---

## 6. 防火墙设置

### 6.1 UFW 防火墙（推荐）

```bash
sudo ufw enable
sudo ufw allow 22/tcp          # SSH
sudo ufw allow 40130/tcp       # chanking
sudo ufw allow 40715/tcp       # mqtt
sudo ufw allow 40716/tcp       # baolin
sudo ufw allow 40719/tcp       # baolin
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw status verbose
```

### 6.2 iptables（备选）

```bash
sudo iptables -A INPUT -p tcp --dport 40130 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 40715 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 40716 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 40719 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A INPUT -j DROP

sudo apt install -y iptables-persistent
sudo netfilter-persistent save
```

---

## 7. 性能优化

### 7.1 内核参数优化

```bash
sudo vim /etc/sysctl.d/99-nginx-performance.conf
```

```ini
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_keepalive_time = 600
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216
fs.file-max = 2097152
```

```bash
sudo sysctl -p /etc/sysctl.d/99-nginx-performance.conf
```

### 7.2 文件描述符限制

```bash
sudo vim /etc/security/limits.conf
```

```
* soft nofile 65535
* hard nofile 65535
www-data soft nofile 65535
www-data hard nofile 65535
```

### 7.3 Systemd 服务优化

```bash
sudo mkdir -p /etc/systemd/system/nginx.service.d
sudo vim /etc/systemd/system/nginx.service.d/override.conf
```

```ini
[Service]
LimitNOFILE=65535
Nice=-5
CPUQuota=80%
```

```bash
sudo systemctl daemon-reload
sudo systemctl restart nginx
```

### 7.4 树莓派特定优化

```bash
# 禁用 swap（减少 SD 卡写入）
sudo dphys-swapfile swapoff
sudo apt remove -y dphys-swapfile

# 使用 tmpfs 存储日志（减少 SD 卡写入）
sudo vim /etc/fstab
# 添加：
tmpfs /var/log/nginx tmpfs defaults,noatime,size=50m 0 0
```

> **注意**：使用 tmpfs 存储日志时，日志在重启后会丢失。如需持久化日志，建议使用外接 USB 存储。

---

## 8. 开机自启与守护进程

### 8.1 启用开机自启

```bash
sudo systemctl enable nginx
sudo systemctl start nginx
sudo systemctl status nginx
```

### 8.2 监控脚本

```bash
sudo vim /usr/local/bin/nginx-monitor.sh
```

```bash
#!/bin/bash
if ! pgrep -x nginx > /dev/null; then
    echo "$(date): Nginx 进程不存在，尝试重启..." >> /var/log/nginx-monitor.log
    sudo systemctl start nginx
    echo "$(date): Nginx 已重启" >> /var/log/nginx-monitor.log
fi
```

```bash
sudo chmod +x /usr/local/bin/nginx-monitor.sh

# 每 5 分钟检查一次
sudo crontab -e
# 添加：
*/5 * * * * /usr/local/bin/nginx-monitor.sh
```

---

## 9. 验证与测试

### 9.1 完整功能验证

```bash
# 测试 HTTPS 访问（各域名）
curl -I https://chanking.zhonjin.com:40130
curl -I https://mqtt.zhonjin.com:40715
curl -I https://baolin.zhonjin.com:40716
curl -I https://baolin.zhonjin.com:40719

# 测试 HTTP → HTTPS 跳转（各域名）
curl -I http://chanking.zhonjin.com:40130    # 应返回 301
curl -I http://mqtt.zhonjin.com:40715        # 应返回 301
curl -I http://baolin.zhonjin.com:40716      # 应返回 301
curl -I http://baolin.zhonjin.com:40719      # 应返回 301

# 验证 SSL 证书
echo | openssl s_client -connect chanking.zhonjin.com:40130 -servername chanking.zhonjin.com 2>/dev/null | openssl x509 -noout -dates
echo | openssl s_client -connect mqtt.zhonjin.com:40715 -servername mqtt.zhonjin.com 2>/dev/null | openssl x509 -noout -dates
```

### 9.2 性能基准测试

```bash
sudo apt install -y apache2-utils

# 压力测试
ab -n 1000 -c 50 https://chanking.zhonjin.com:40130/
ab -n 1000 -c 50 https://mqtt.zhonjin.com:40715/
```

---

## 10. 常见问题

### Q1: 编译时报内存不足

```bash
# 添加临时 swap
sudo fallocate -l 2G /tmp/swapfile
sudo chmod 600 /tmp/swapfile
sudo mkswap /tmp/swapfile
sudo swapon /tmp/swapfile
# 编译完成后移除
sudo swapoff /tmp/swapfile && sudo rm /tmp/swapfile
```

### Q2: stream 模块报 "unknown directive"

```bash
dpkg -l | grep nginx
sudo apt install -y nginx-full    # 替换 nginx-light
```

### Q3: include 文件找不到

```bash
sudo mkdir -p /etc/nginx/conf.d /etc/nginx/stream.d
sudo cp zhonjin_http.conf /etc/nginx/conf.d/
sudo cp zhonjin_stream.conf /etc/nginx/stream.d/
```

### Q4: 通配符证书不生效

```bash
# 检查证书覆盖域名
openssl x509 -in /etc/letsencrypt/live/zhonjin.com/fullchain.pem \
    -noout -text | grep -A1 "Subject Alternative Name"
# 应包含 *.zhonjin.com
```

### Q5: 树莓派 SD 卡写入寿命
- 将日志目录挂载为 tmpfs
- 使用外接 SSD/USB 存储持久化日志
- 关闭不必要的日志

---

## 快速部署脚本

```bash
#!/bin/bash
set -e
echo "=== 树莓派 5 Nginx 快速部署 ==="
sudo apt update && sudo apt upgrade -y
sudo apt install -y nginx-full certbot python3-certbot-nginx
sudo mkdir -p /etc/nginx/conf.d /etc/nginx/stream.d
sudo cp nginx.conf /etc/nginx/nginx.conf
sudo cp zhonjin_http.conf /etc/nginx/conf.d/zhonjin_http.conf
sudo cp zhonjin_stream.conf /etc/nginx/stream.d/zhonjin_stream.conf
sudo nginx -t && sudo systemctl reload nginx
sudo ufw allow 40130/tcp 40715/tcp 40716/tcp 40719/tcp
echo "=== 部署完成，请配置 SSL 证书 ==="
```