树莓派 Docker 化网页服务器 · 专栏导览提起树莓派很多人的第一反应是“一块能跑 Linux 的小板子”。没错但它能做的事远不止刷个系统、点个灯。把树莓派和 Docker 组合起来你会得到一台功耗只有几瓦、24 小时不关机、随时能跑网页服务的迷你服务器——用来挂个人博客、内网导航页、API 接口甚至小型数据库都绰绰有余。这个专栏就是围绕这套组合从零开始把一台裸板变成能对外提供网页服务的 Docker 主机。这个专栏适合谁如果你手里有一块吃灰的树莓派 4B 或 5想让它干点正事如果你在电脑上装过 Docker Desktop 但没跑过正式项目如果你写了个小网站想低成本部署出去让手机随时访问——那这篇文章就是你的起点。我按照自己的实操经验把整个路线拆成了七个大块思路、选型、系统、容器、服务、扩展、排错每一块都对应实际踩坑后的结论不是文档复读。1. 为什么偏偏要用 Docker 跑网页服务器1.1 传统部署方式的问题在哪里不装 Docker直接在树莓派上装 Nginx、装数据库、跑 PHP 或 Python这条路能走通但维护成本很高。举个例子你今天给博客加了 Redis 缓存系统里就多了一串编译依赖明天升个 Python 小版本某个 pip 包直接编译失败换一张 SD 卡重新部署光记步骤就能记两页纸。更头疼的是污染系统。树莓派的系统分区就那么大eMMC 或 SD 卡读写寿命也有限每装一个软件就往系统里写东西出问题还得想着清理。时间一长系统状态完全不可控你根本说不清这台上一次做了什么操作。1.2 容器化给树莓派带来了什么Docker 解决的问题本质上是把“运行环境”和“底层系统”剥离开。每个容器自带运行时、依赖和配置文件跑在树莓派上就像装在盒子里的小房间——互不干扰拆了重建都很快。你这辈子有没有想过为什么 Nginx 跑在 Ubuntu 上都发行版相关的问题少因为 Docker 镜像把 Nginx 和它的运行环境打包在一起了你拉一个nginx:alpine无论底层是树莓派 OS 还是 Debian运行行为完全一致。这样带来的直接好处是重装系统后不用一个个装软件写个docker-compose.yml跑起来就恢复服务版本回滚简单下载旧镜像即可服务隔离干净一个容器被折腾坏了其他完全不受影响资源占用可预期一个 Nginx 容器也就二三十兆内存最关键的是树莓派是 ARM 架构很多软件从源码编译又慢又容易失败。而 Docker Hub 上大量官方镜像都提供 ARM64 版本一键拉取就能用相当于绕过了“编译地狱”。1.3 什么场景适合树莓派 Docker 化注意不是所有网页服务都适合放树莓派上。像高并发业务接口、需要大内存的应用、依赖特定硬件直通的服务这些更适合上云服务器。但下面这些场景树莓派体验非常好个人博客或文档站一天几百次访问那种内网 Web 服务比如家庭智能中枢面板、NAS 管理界面轻量 API 转发或爬虫定时任务开发测试环境本地先跑通再搬到云上带摄像头或传感器的网页监控服务也就是把你的静态页面、单个应用、本地服务容器化放在低功耗小主机上一直运行。这正好是树莓派的甜点区。2. 选型思路树莓派硬件与系统准备2.1 硬件怎么选从 3B 到 5 的取舍树莓派型号对 Docker 化部署的影响主要在内存和 CPU 架构上。架构方面树莓派全系都是 ARM6464 位系统下主流 Docker 镜像基本都提供arm64v8标签兼容性没问题。内存方面4B 建议起跳 4GB5 建议 8GB 版本。我实测下来的感受是跑 3~5 个轻量容器Nginx、MySQL、Redis、Portainer4GB 内存的树莓派 4B 稳稳的内存占用大概在 2GB 左右。如果你打算跑带界面的应用、Grafana 这类面板或者本地部署大模型那 8GB 的 5 更从容。存储也很关键。SD 卡的 IO 性能和寿命会直接拖垮 Docker 体验——容器层写入非常频繁。建议优先考虑 NVMe 硬盘通过 USB 3.0 转接板外接系统放 eMMC 或 SDDocker 的数据目录和数据卷放到外接硬盘上。没有条件的话买一张好一点的 A2 级别 SD 卡也能跑但要注意定期备份。散热是另一个容易被忽略的点。树莓派满载跑容器时CPU 温度很容易飙到 80 度以上过热降频会导致网页响应变慢。加个铝制散热壳或主动散热风扇效果好得多。2.2 系统选择树莓派 OS 还是纯命令行做服务器用我个人推荐装 64 位 Lite 版树莓派 OS不要装桌面环境。桌面版光启动就占三四百兆内存对服务器来说是纯浪费。无桌面系统开机后占用的内存不到 200MB剩余的全部给容器用这账非常划算。刷系统推荐用官方 Raspberry Pi Imager在“选择操作系统”里挑 “Raspberry Pi OS (64-bit)”然后点设置图标提前配置用户名、密码、WiFi 和 SSH。这一步非常关键——先把 SSH 打开后续就不用接显示器键盘了。开机后用ssh pi树莓派IP登录第一件事是执行更新并换源。树莓派官方源在国外国内拉包速度惨不忍睹。修改/etc/apt/sources.list和/etc/apt/sources.list.d/raspi.list把deb.debian.org和archive.raspberrypi.org换成可用的国内镜像站地址接着执行sudo apt update sudo apt upgrade -y。换源这块各家镜像站的路径格式有差异具体以你选的那家镜像站说明为准。2.3 静态 IP 与远程管理准备服务器必须固定 IP不然 DHCP 重新分配后你就找不到它了。两种方式在路由器后台给树莓派绑定 MAC 地址固定 IP或者在/etc/dhcpcd.conf里配置静态 IP。我建议两个都做路由器层面优先系统层面兜底。顺便说一下如果不想每次都记 IP可以在路由器里配置自定义域名比如pi.lan指向树莓派内网 IP之后直接访问http://pi.lan即可。3. 在树莓派上安装 Docker 与 Docker Compose3.1 用官方脚本一键安装树莓派 OS 是基于 Debian 的安装 Docker 不用从源码编译用官方脚本最省事。SSH 登录后依次执行curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh脚本会自动检测系统架构ARM64、配置 Docker 软件源、安装 containerd 和 Docker Engine最后把当前用户加入 docker 组免得每次都要 sudosudo usermod -aG docker $USER newgrp docker记得docker version看一下客户端和服务端版本服务端存在说明安装成功。如果提示权限问题大概率是没重登或者 docker 组没生效。3.2 注意这里别用 Docker Desktop很多网友搜“docker 安装教程”看到的是 Docker Desktop 的图形界面安装法。这里特别提醒树莓派上没有 Docker Desktop也装不了对应 Windows 上报 “virtualization support not detected” 之类的问题也不适用于树莓派。树莓派上的 Docker 是纯命令行操作的这才符合服务器的定位。你需要的图形管理工具是 Portainer一个网页版的容器管理面板之后在浏览器里点点点就能看到容器状态、日志和控制台——这才是“网页如何看和管理”的正解。3.3 安装 Docker Compose现在 Multi-container 项目基本都是用 Compose 定义的。树莓派系统通过 apt 装的可能版本旧推荐直接下载二进制sudo apt install docker-compose-pluginDocker 官方已经把 compose 作为插件打进了 Docker 里只要装这个插件就能使用docker compose注意中间有空格命令。测试一下docker compose version能输出版本号比如 v2.20Compose 就绪后面整套专栏的部署文件都用它来跑。4. 容器目录规划与镜像加速4.1 目录布署原则容器虽然隔离了进程和依赖但数据必须持久化到宿主机。我的目录方案长这样/data ├── docker/ │ ├── nginx/ │ │ ├── conf.d/ │ │ └── html/ │ ├── mysql/ │ │ └── data/ │ ├── redis/ │ │ └── data/ │ └── portainer/原则就一个凡是容器里可能改变的数据一律通过卷volume或 bind mount 映射出来。conf.d映射 Nginx 配置data目录映射数据库数据。这样容器删了重建数据不丢。4.2 镜像加速配置树莓派拉镜像默认走 Docker Hub国内网络环境下经常超时。虽然官方没有提供长期稳定的加速地址但不少云厂商和高校提供了镜像加速器。配置方式编辑/etc/docker/daemon.json{ registry-mirrors: [ https://你的加速地址 ] }然后重启 Dockersudo systemctl restart docker docker info | grep -A 5 Registry Mirrors需要注意一些加速器需要登录验证或已经停止提供公共加速。如果找不到可用的可以用代理或换时间段拉取。另外可以多用docker pull带--platform linux/arm64参数避免拉错架构镜像虽然大多数镜像会自动识别但遇到多架构镜像混乱时可以强制指定。4.3 基础镜像选择建议选镜像不要贪大。Nginx 建议用nginx:alpineMySQL 用mysql:8.0-oracle或mariadb:10.11ARM 兼容性更好Redis 用redis:7-alpine。alpine 系镜像体积小ARM 支持好就是自带 musl libc个别软件包可能需要编译但网页服务这几个主流软件完全没问题。还有一点树莓派上跑 MySQL 记得设platform: linux/arm64如果 Compose 文件里没有遇到exec format error就是架构不匹配加一行就解决。5. 核心实操部署一个能访问的网页服务5.1 第一个实例Nginx 静态服务器直接用命令跑一个最简单的 Nginx验证 Docker 链路是否正常docker run -d --name web-1 -p 8080:80 -v /data/docker/nginx/html:/usr/share/nginx/html:ro nginx:alpine访问http://树莓派IP:8080看到 Nginx 欢迎页。然后把你的静态文件丢进/data/docker/nginx/html刷新浏览器欢迎页就变成你的页面了。ro是只读挂载避免容器内部误改文件这个是安全习惯。5.2 第二步用 Compose 管理多个服务单容器命令好理解但项目一多就没法维护了。下面这个docker-compose.yml是我博客的完整部署文件标注了注释直接抄作业version: 3.8 services: nginx: image: nginx:alpine container_name: blog-nginx ports: - 80:80 volumes: - /data/docker/nginx/html:/usr/share/nginx/html:ro - /data/docker/nginx/conf.d:/etc/nginx/conf.d:ro restart: unless-stopped networks: - webnet mysql: image: mysql:8.0 container_name: blog-mysql environment: MYSQL_ROOT_PASSWORD: 你的强密码 MYSQL_DATABASE: blog volumes: - /data/docker/mysql/data:/var/lib/mysql restart: unless-stopped networks: - webnet networks: webnet: driver: bridge在文件目录下执行docker compose up -d两个服务会同时启动并通过webnet网络内部通信。restart: unless-stopped保证开机自启和异常退出自动拉起这是服务器长期运行的核心配置。5.3 第三步配置反向代理与 HTTPS树莓派公网 IP 不好申请内网服务建议用反代做统一入口。在conf.d下新建reverse.confserver { listen 80; server_name blog.example.com; location / { proxy_pass http://blog-nginx; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这样所有请求先进宿主机 Nginx再转发到容器内的 Nginx。为什么套两层因为你后续可能跑多个服务博客、面板、接口都用宿主机 Nginx 统一做路由和 SSL 证书管理容器内部不用管这些。HTTPS 证书用 acme.sh 或 certbot 申请就行免费证书三个月一续配置好自动续期脚本基本不用管。5.4 文件同步与内容更新网页文件更新频繁每次都scp传文件太原始。我用的是rclone挂载云盘目录或者干脆用 Git 仓库配合 Webhook 自动拉取。简单方案是 Samba 共享映射目录在电脑上改完保存容器里立刻生效适合小团队或个人用。6. 进阶扩展把树莓派变成多功能家庭服务器6.1 数据库与缓存MySQL Redis 是网页服务最常见的组合。MySQL 8.0 在 ARM 上已经很成熟容器方式部署完全没毛病。Redis 主要用来做缓存和 Session 存储redis:7-alpine镜像极小启动即用。数据卷映射和密码配置参照第 5 节的 Compose 文件即可注意给 MySQL 设置character-set-serverutf8mb4和collation-serverutf8mb4_unicode_ci避免中文乱码。6.2 摄像头与串口外设的容器化这是树莓派特有的优势。搜热词时很多人问“摄像头怎么打开”“舵机怎么控制”这类硬件外设一样可以容器化。OV5647 摄像头模块用uv4l或mjpg-streamer的容器镜像通过--device /dev/video0把摄像头设备直通给容器网页端就能实时看画面。GPIO 控制舵机同理容器里加--device /dev/gpiomem --privileged就能直接操作。数据采集、网页展示都能封装成独立容器互相不污染系统环境。6.3 监控与运维面板容器跑多了状态总用命令行看也不方便。用 Portainer 统一管理非常直观docker run -d -p 9000:9000 \ --name portainer \ --restartalways \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /data/docker/portainer:/data \ portainer/portainer-ce:latest浏览器打开http://树莓派IP:9000设置管理员账号后就能在网页上看到所有容器状态、日志还能点按钮启停容器、编辑 Compose 栈。资源监控再配一个netdata容器CPU、内存、网络流量面板化一目了然。6.4 备份策略容器化最大的教训就是容器可以随便删数据必须永远有备份。数据都在映射目录里最简单的方式是crontab定时打包0 3 * * * tar czf /backup/docker-$(date \%F).tar.gz -C /data/docker .再加一个 rsync 同步到另一台主机或 NAS双保险。我吃过亏——SD 卡突然损坏容器配置全没只有靠备份恢复。树莓派做服务器数据无价。7. 常见问题与排查技巧实录7.1 速查表下面这些是我在实际操作中反复遇到的问题整理成表方便查阅现象常见原因排查/解决exec format error拉取了 amd64 架构镜像加platform: linux/arm64重新拉取容器启动后立刻退出配置文件错误或端口冲突docker logs 容器名看日志docker ps -a看退出码网页访问超时防火墙或网络配置异常先curl 127.0.0.1:端口测本机再查防火墙和路由器端口转发容器内写文件没权限目录属主不是容器用户chown -R 1000:1000或映射目录用user: 1000:1000树莓派过热降频散热不足加散热片风扇vcgencmd measure_temp监控温度Docker 拉镜像慢网络问题配置 registry-mirrors或用加速器或错峰拉取断电后容器没自启缺restart策略Compose 文件加restart: unless-stopped7.2 日志排查方法论容器日志是排查问题的第一入口。看日志docker logs --tail 100 blog-nginx实时跟踪docker logs -f blog-nginx如果日志太多了还可以按时间过滤docker logs --since 10m blog-nginx记住先看日志再猜原因不要一上来就删容器重建很多问题其实只是配置写错了。7.3 我踩过的坑第一个坑是关于 apt 源和 Docker 源的混淆。树莓派换 apt 源只解决系统软件安装速度Docker 镜像拉取走的是 Docker Hub两个完全独立别换完 apt 源后以为 Docker 也提速了。第二个坑是docker compose和docker-compose的差异。旧版本用docker-compose带横杆新版用docker compose空格。网上教程混着用抄命令时注意一下版本报command not found多半是这两个混用了。第三个坑是 SD 卡的写放大问题。Docker 日志文件默认是 json-file 格式长时间运行日志能涨到好几个 GSD 卡直接写满。解决方法是加上日志轮转配置在/etc/docker/daemon.json里加{ log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } }这样每个容器的日志最大 30MB杜绝日志撑爆磁盘。这类细节官方文档不会特意强调踩过坑才长记性。7.4 这个专栏后面还会写什么目前规划的路线是这样的第一部分是环境基础本篇第二部分是 Nginx 静态网站实战第三部分是 Compose 多服务编排第四部分是 PHP/Node/Python 动态应用容器化第五部分是 HTTPS 与域名接入第六部分是监控与备份第七部分是摄像头、GPIO 这类硬件容器化专题第八部分是性能调优和系统瘦身。每一篇我都会覆盖“为什么这么做”和“踩了什么坑”尽量让读者避开那些我花了好几个晚上才弄明白的问题。如果你手里正有一块吃灰的树莓派跟着这个专栏从零到一搭建一套自己的 Docker 化网页服务器这是个很有意思也很有成就感的过程。