树莓派 Docker 化网页服务器：从吃灰到家庭服务器实战指南

去年我把一块树莓派 4B 从抽屉里翻出来的时候SD 卡里还躺着一个大三装的 WordPress。当时搭它费了整整两天后来因为搬家懒得迁移就一直吃灰。今年决定重新把它用起来方向很明确用 Docker 把整个网页服务器容器化。这个决定改变的不只是部署方式连我对待这台小主机的态度都变了。所以我打算把这个过程整理成一个专栏而这篇文章就是整个专栏的地图。如果你手里也有一块树莓派或者单纯想用一个低功耗小机器跑点正经服务那这个专栏可以给你一条非常清晰的路从硬件选型、系统安装到 Docker 部署网页服务器再到域名、HTTPS、数据备份全部按真实项目流程来写。我会直接把命令、配置、目录结构、坑位都摆在明面上不绕弯子。1. 吃灰树莓派的第二次生命这个专栏到底在做什么1.1 为什么是 Docker 网页服务器而不是其他玩法树莓派能做的事情很多GPIO 控制、机器人、软路由、复古游戏机、NAS随便一个方向都能玩半年。但如果你只是想用它“稳定跑一个服务”而且希望这个服务以后迁移到别的机器上还能一键恢复那 Docker 化几乎是唯一省心的选择。传统玩法是在系统里直接装 Nginx、MySQL、PHP这样的问题在树莓派上尤其致命系统本身跑在 SD 卡上一旦卡片损坏整个环境就全没了时间久了系统依赖升级某个扩展和 PHP 版本不兼容排查起来非常费劲换一块新板子想迁移什么东西都得重新配一遍。容器化解决的就是这三个痛点环境隔离、启动可重复、迁移成本极低。而网页服务器恰恰是容器化收益最大的场景。一个像样的站点至少由 Nginx 反代、Web 应用、数据库、缓存组成这么多组件如果用传统方式安装每个都有自己的配置文件、进程管理方式、依赖关系组合起来就是一场灾难。用 Docker 把每个组件装进独立容器再用 docker-compose 把它们串起来整个服务的生命周期都能用几条命令控制这对树莓派这种小机器来说太合适了。1.2 看完这个专栏你能得到什么这个专栏不是讲零散命令而是带着你从一块裸板跑到一个能对外提供访问的完整网页服务器。最终你会得到几个非常具体的东西一台装好 64 位 Linux 系统、SSH 可连、基础环境干净的树莓派一套正确安装并配置好的 Docker 引擎以及自己手写的一批常用命令一个用 docker-compose 管理起来的网页项目包含 Nginx 反代、一个动态 Web 应用、MySQL 数据库和 Redis 缓存一台只要插上电就能自动拉起所有服务的“家用服务器”重启之后不用再手工敲命令你知道怎么在系统崩溃后从备份里把整个站点恢复回来而不是抱着 SD 卡哭。对我来说最有价值的其实是最后一条。树莓派这种设备最大的敌人不是性能而是 SD 卡突然损坏。把服务容器化之后我只需要定期备份几个数据目录和一份 docker-compose.yml恢复一台新机器只需要十分钟。1.3 适合谁读谁可以先划走这个专栏适合三类人第一类是有树莓派但一直吃灰想用起来又不知道从哪下手的人第二类是想学 Docker但不想在虚拟机和云服务器上折腾想用一个真实的小设备练手的人第三类是做毕设或课程设计需要快速搭一个“物联网 Web 管理平台”的学生。不太适合的人也有如果你主要想在树莓派上做桌面办公、看视频、写文档那容器化帮不了你太多如果你要做的是实时性极强的硬件控制比如舵机、电机、传感器闭环那第一优先应该选裸机或实时系统容器在这里只适合做旁路服务不适合做控制主链路。2. 先选对硬件和系统再谈容器化2.1 树莓派 4B、5、3B 怎么挑我做这个专栏用的主力机是树莓派 4B4GB 版本因为这是目前保有量最大、资料最全、性价比最均衡的型号。如果你手头已经有树莓派先不要急着买新的看看手里的型号和内存再决定。型号CPU 架构常见内存Docker 适用度主要限制树莓派 3B/3Barmv7l1GB勉强可用很多镜像没有 32 位 ARM 版本跑内存密集型应用吃力树莓派 4Barm642GB/4GB/8GB很推荐散热要做好USB 启动需要较新 BootLoader树莓派 5arm644GB/8GB/16GB非常推荐价格偏贵但对 AI 和并发场景提升明显树莓派 3B 不是不能用只是很多 Docker 官方镜像只发布 linux/arm64 版本没有 linux/arm/v7你拉镜像的时候会直接报 “no matching manifest for linux/arm/v7”这时候要么找第三方构建的 armhf 镜像要么自己源码构建时间成本很高。所以我建议如果是 3B最多跑个 Nginx 或轻量容器别指望跑全家桶。4B 起步才谈得上“网页服务器”。内存方面2GB 版本跑单容器还可以如果要跑 Web 应用 MySQL Redis 再加反代最好上 4GB。我实测一个典型 LEMP 容器栈空闲时占 700MB 左右跑起来之后轻松破 1.5GB2GB 会很紧张。2.2 系统镜像Lite 版还是 Ubuntu Server确定了硬件之后系统选择也要认真。树莓派官网提供的 Raspberry Pi OS 分两个版本带桌面的完整版和无桌面的 Lite 版。做服务器一定要选 Lite因为桌面环境会吃掉大量内存和 CPU而且没键盘没显示器时桌面版反而更容易出问题。如果你想用 Ubuntu可以选 Ubuntu Server 24.04 的树莓派版本。它的优势在生态更接近云服务器很多部署文档里的命令可以直接照抄劣势是树莓派专属的一些硬件支持不如官方系统及时比如摄像头、GPIO、硬件编解码更新节奏也慢一些。我给你的建议很简单第一次用树莓派做服务器选 Raspberry Pi OS Lite64-bit最稳因为官方对 4B/5 的 64 位支持已经非常成熟社区资料最多换源、装 Docker、调内核参数都有现成答案。等你对这套流程很熟了再换 Ubuntu Server 不迟。2.3 无屏幕安装与初始连接做服务器基本不会给它配显示器所以“无头安装”是第一个要跨过的坎。现在官方烧录工具 Raspberry Pi Imager 已经做得非常友好在烧录前可以点右下角的齿轮图标直接预配置开启 SSH设置用户名和密码配置 WiFi 或以太网设置地区、语言、时区给主机起一个固定名字比如 webpi。这样烧完系统把卡插回树莓派开机然后去路由器后台找到 webpi 的 IP或者直接用ping webpi.local/ SSH 连接ssh piwebpi.local。如果你用的是 Windows 10/11 系统可以直接在终端里用ssh piwebpi.local连不需要装 PuTTY。这里有一个常被忽略的细节树莓派首次开机会自动扩展分区但如果用的是不带官方引导的第三方镜像可能会有分区没扩完的情况。建议连接后先跑一下sudo raspi-config在 Advanced Options 里确认“Expand Filesystem”已生效否则后面 Docker 数据一多根分区就满了。2.4 换源、时区、基础依赖一次搞定系统连上之后第一步不是装 Docker而是把基础环境收拾干净。换软件源这个动作在国内网络环境下尤其重要。默认源在国外跑apt update可能慢到怀疑人生。我的习惯是先备份/etc/apt/sources.list然后用一个稳定的软件源镜像替换掉默认地址。这里不固定推荐哪个源因为不同网络环境下的延迟差异很大你只要选择一台在自己网络里实测速度最快的镜像就好。换完源马上做三件事更新系统、设置时区、装基础工具。sudo apt update sudo apt upgrade -y sudo timedatectl set-timezone Asia/Shanghai sudo apt install -y curl git vim htop tmux时区这个问题在 Docker 容器里更容易踩后面你会看到很多镜像默认 UTC 时间和宿主机差 8 小时。所以从一开始就把系统时区设好至少容器启动时少一个变量。3. Docker 化网页服务器的核心设计思路3.1 传统部署方式为什么不推荐我在文章开头说传统部署很麻烦你可能觉得有点夸张。这里说一个我真实遇到过的场景之前我在树莓派上直接apt install nginx php-mysql一开始站点很正常后来因为毕设要加一个 WebSocket 服务我顺手把系统里的 PHP 升级了一下结果 WordPress 的某个插件彻底打不开了。类似这种“升级一个组件带崩整个环境”的问题在传统部署里几乎无法根治。容器化的思路是把每个组件锁在自己的镜像里PHP 应用跑在 PHP 容器里Nginx 跑在 Nginx 容器里MySQL 跑在 MySQL 容器里它们之间通过网络通信而不是在同一个文件系统里互相踩脚。生活化的类比是这样传统部署像是把一家人全塞进同一个房间有人要睡觉、有人要唱歌、有人要煮饭互相干扰Docker 是给每个人分了一间带独立家具的房间需要交流时开门说话不想被打扰时完全隔离。网页服务器天然是多组件协作的场景容器化之后每个组件可以独立升级、回滚、重新部署这套体验用传统方式很难做到。3.2 一个网页服务器的容器化拆解假设你的目标是一个带动态数据的站点至少需要拆成四个角色Nginx 容器负责接收外部请求把静态文件直接返回把动态请求转发给 Web 应用Web 应用容器运行 Python/Node/PHP 代码处理业务逻辑MySQL 容器持久化业务数据Redis 容器处理缓存和会话。先拿 Nginx 举例最小化的启动命令是docker run -d --name nginx-web -p 80:80 -v /home/pi/site:/usr/share/nginx/html:ro nginx:alpine这条命令做了三件事-d表示后台运行-p 80:80把宿主机 80 端口映射到容器 80 端口-v /home/pi/site:/usr/share/nginx/html:ro把宿主机里的站点目录挂载进容器ro表示只读防止容器内部意外改动宿主机文件。理解端口映射的方向很重要-p 宿主机端口:容器端口访问者永远先到宿主机 IP 的端口再由 Docker 转发给容器内部端口。所以如果你以后要改对外端口只动冒号左边冒号右边默认是容器里服务监听的端口轻易不要改。3.3 docker-compose用一份 YAML 管理整个站点容器一多纯docker run命令就会变得失控。创建一个网络、挂三个数据卷、设五个环境变量每次手工敲都很容易错。这时候用 docker-compose 把整个服务栈的定义写进一份docker-compose.yml好处是可读、可版本管理、一条命令拉起或关掉全部服务。一个基础示例services: nginx: image: nginx:alpine ports: - 80:80 volumes: - ./site:/usr/share/nginx/html:ro restart: unless-stopped web: build: ./app environment: - DB_HOSTdb - REDIS_HOSTredis depends_on: - db - redis restart: unless-stopped db: image: mysql:8 environment: MYSQL_ROOT_PASSWORD: change-me MYSQL_DATABASE: webapp volumes: - db_data:/var/lib/mysql restart: unless-stopped redis: image: redis:7-alpine restart: unless-stopped volumes: db_data:这份文件并不复杂但几个细节非常关键。第一restart: unless-stopped保证了树莓派重启之后容器能自动拉起来这是服务器长期稳定运行的基础。第二db容器通过MYSQL_DATABASE这个环境变量自动创建数据库省去初始化手工执行 SQL 的步骤。第三depends_on只保证启动顺序不保证数据库“已经就绪”所以应用代码里最好有重连逻辑。3.4 arm64 架构带来的镜像差异与兼容性树莓派 4B/5 都是 arm64 架构这本身不是问题现在主流镜像几乎都有 arm64 版本。真正的问题是有些个人或小团队维护的镜像只提供了 x86_64 版本你在树莓派上docker pull时会一直卡住然后报no matching manifest。遇到这种情况第一步用docker manifest inspect 镜像名看看它支持哪些架构。如果确实没有 arm64你有两条路一是找替代镜像很多常见软件都能找到官方或多架构镜像二是自己在树莓派上用源码构建但编译时间可能很长而且内存小的版本容易直接 OOM。我个人的经验是在一个家庭服务器项目里优先选择官方镜像或知名社区镜像不要为了一个“看起来很酷”的小众镜像浪费大量时间。稳定压倒一切。4. 专栏实操路线六个阶段跑通一个真实站点4.1 阶段一烧录与初始化这个阶段的目标是让树莓派通电就能连上基础环境干净可操作。你需要准备一张至少 32GB 的高质量 SD 卡、读卡器、一块树莓派 4B/5、电源和数据线。用 Raspberry Pi Imager 选择 Raspberry Pi OS Lite64-bit预配置 SSH、WiFi、主机名。烧录完成后插卡开机通过路由器后台或webpi.local找到设备地址SSH 登录。然后执行系统更新、时区设置、基础依赖安装。整个过程不复杂但至少预留 30 分钟因为首次开机后系统会自动扩展分区并做初始化SSH 可能前一两分钟连不上这是正常现象。我会建议你写一个简单的部署笔记把 IP、用户名、安装日期、使用过的镜像源记下来。树莓派这种设备很容易被遗忘等三个月后再去操作没有笔记几乎等于重新开始。4.2 阶段二装好 Docker 引擎并跑通 hello-world树莓派上装 Docker 最省事的方式是用官方安装脚本curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER执行完第二条命令后先注销再重新登录让docker组权限生效。然后用docker version确认客户端和服务端都在运行。跑一次 hello-world 不只是验证安装还能顺便检查镜像拉取速度是否正常docker run hello-world如果这条命令卡住说明网络到 Docker Hub 不通畅。这时候可以考虑配置 registry mirror编辑/etc/docker/daemon.json加入registry-mirrors配置然后重启 Docker 服务。镜像加速地址要根据你所在网络实测选择没有统一标准但配置完之后docker run hello-world应该明显变快。4.3 阶段三Nginx 静态站点与局域网访问这一步能让你快速获得成就感。在树莓派上建一个目录写一个最简单的 HTML 页面mkdir -p ~/site echo h1hello from raspberry pi/h1 ~/site/index.html然后启动一个 Nginx 容器挂载这个目录docker run -d --name web -p 80:80 -v /home/pi/site:/usr/share/nginx/html:ro nginx:alpine浏览器访问http://树莓派IP看到页面的那一刻你的树莓派就已经是一台正式的 Web 服务器了。这个阶段只有两个坑一是防火墙或路由器没有放行 80 端口二是容器启动后改了本地文件但浏览器没刷新缓存。如果你要修改页面直接改~/site/index.html容器会实时读到不需要重启。4.4 阶段四Web 应用 MySQL Redis 的容器化实战静态页面不够这个阶段进入真正有业务逻辑的动态站点。以一个简单的 Python Flask 应用为例你的代码里要读取数据库连接信息不能写死 IP而是使用服务名db。这就是容器网络的作用在同一个 Docker 网络里容器之间可以通过服务名互相访问。创建自定义网络docker network create webnet然后分别启动 MySQL 容器和应用容器并加入同一个webnet。应用容器里配置DB_HOSTdb而不是127.0.0.1因为在容器网络里127.0.0.1指向容器自己不是数据库容器。这个阶段的重点不是“应用代码怎么写”而是理解容器之间的网络模型。很多新手第一次死在“为什么我在容器里连不上数据库”上多半就是没搞懂这个逻辑。4.5 阶段五用 docker-compose 一键拉起全栈项目把上一阶段手动执行的多条命令整理成docker-compose.yml这是整个专栏最关键的一次升级。你不再需要记顺序也不需要关心哪个容器先启动哪个后启动只需要docker compose up -d然后观察日志docker compose logs -f这个阶段我会特别强调“数据卷”的重要性。MySQL 数据目录必须挂到 volume 或宿主机目录否则删除容器就意味着删库跑路。资源有限的树莓派上你还要学会用docker compose ps查看每个容器的状态和资源占用及时发现某个容器的日志在疯狂增长。4.6 阶段六反代、域名与 HTTPS 收尾到了这个阶段你的站点已经可以用http://IP:端口访问了。但要让它看起来像一个真正正式的网站还需要统一入口和加密。我的推荐是加一个 Nginx 或 Caddy 作为反向代理容器把所有外部请求收进来再按路径转发到不同后端容器。Caddy 的好处是能自动申请和管理 HTTPS 证书配置文件极短Nginx 的好处是通用性更强网上资料最多。如果你有一个自己的域名并且路由器支持端口映射可以配置 A 记录指向家庭宽带的公网 IP然后把 80 和 443 端口映射到树莓派。这个阶段要格外小心安全不要用默认密码不要暴露 SSH 到公网不要开放不必要的端口。家庭服务器被扫到是常态安全习惯必须从第一天就养成。5. 踩坑清单这些内容值得重点划线5.1 电源和散热性能不稳定的头号元凶我见过太多“树莓派为什么老是重启”的案例最后发现都是电源问题。树莓派 4B 满载时电流接近 3A5V 供电如果不足系统会瞬间掉压轻则性能骤降重则直接重启。最明显的征兆是系统日志里出现under-voltage警告。排查方法运行vcgencmd get_throttled如果返回的不是0x0说明发生过欠压或温度降频。使用建议用 5V/3A 以上、线材质量好的电源不要让树莓派从 USB 口或老手机充电器取电。散热方面4B 至少要加一个散热片加风扇的套装长时间跑容器负载温度控制在 60 度以内比较安全。5 的发热比 4B 更猛如果你要跑多容器高负载被动散热完全不够。5.2 存储卡与数据卷日志暴涨的清理方案SD 卡是树莓派里最容易坏的部件而 Docker 默认会把所有容器日志写到宿主机/var/lib/docker/containers/id/下如果不做限制一个日志文件轻松涨到几个 GB直接把 SD 卡塞满。我建议你在/etc/docker/daemon.json里加上日志轮转配置{ log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } }配置后重启 Docker 服务新的容器就会按这个策略写日志。对于已经运行很久的老容器需要重新创建容器才会生效所以我会在专栏里专门安排一课如何在不影响数据卷的前提下重建容器。另外如果条件允许把 Docker 的数据目录/var/lib/docker迁到 SSD 或高速 U 盘上。方法是在daemon.json中加一句data-root: /mnt/ssd/docker然后把旧目录复制过去。迁移后容器的启动速度和数据库的稳定性都会明显提升。5.3 docker 权限、容器时区、镜像架构等高频问题这三个问题几乎每次上手都会遇到我直接给结论。一是权限。执行docker ps报permission denied说明你的用户不在docker组里。执行sudo usermod -aG docker $USER后重新登录。二是时区。容器默认 UTC和北京时间差 8 小时。启动容器时加-e TZAsia/Shanghai或者在 compose 文件里的每个服务中配置环境变量。如果应用内部依赖数据库时间数据库容器也必须设。三是镜像架构。拉镜像时报no matching manifest for linux/arm64说明这个镜像没有 arm64 版本。先docker manifest inspect确认再决定是换替代镜像还是自己构建。不要在 3B 上死磕 armhf很多轮子早就不维护了。5.4 Windows 环境连接树莓派时的常见误区很多同学是在 Windows 笔记本上操作树莓派的有一个非常常见的思路误区为了管理树莓派上的 Docker先在 Windows 上装一个 Docker Desktop然后试图用图形界面连接远程节点。这个思路本身没错但 Docker Desktop 在 Windows 上经常因为虚拟化没有开启而启动失败报错提示类似virtualisation support wasnt detected。这跟你的树莓派一点关系都没有纯粹是 Windows 宿主机的虚拟化设置问题。在 BIOS 里开启虚拟化、开启 WSL2才能解决。如果你不想折腾这些更省心的做法是Windows 上只装一个 SSH 客户端直接 SSH 到树莓派所有的 Docker 操作都在树莓派终端里完成。图形化管理可以在树莓派上装 Portainer 之类的 Web 管理工具用浏览器打开管理界面比 Docker Desktop 轻得多。6. 专栏之外的扩展从网页服务器走向更多项目6.1 摄像头、USB 设备与容器化树莓派最常见的扩展之一是摄像头模块。如果你想把摄像头画面接入网页可以在容器启动时把设备挂载进去docker run -d --name cam \ --device /dev/video0 \ -p 8080:8080 \ your-camera-image--device参数把宿主机上的/dev/video0设备节点直接暴露给容器容器里的应用就能访问摄像头。这个方法对 USB 摄像头、串口设备都适用。需要注意容器对设备的访问权限和宿主机用户组有关如果报权限错误可以在docker run时加--group-add video。专栏里我会放一个实际案例让树莓派摄像头拍到的画面通过网页实时预览容器里跑的是一个轻量视频服务宿主机只负责供电和网络。6.2 本地 AI 模型与树莓派 5树莓派 5 的性能比 4B 有明显提升16GB 内存版本可以跑一些量化后的小参数语言模型。现在社区里有不少针对 ARM 平台优化的部署方案我自己在树莓派 5 上试过轻量模型的推理速度虽然比不上桌面级 GPU但作为学习工具完全够用。如果你想往这个方向走建议先把基础打好会写 docker-compose、会看容器日志、会管理数据卷。因为 AI 模型的镜像通常很大如果不小心把镜像塞满 SD 卡运维经验就是救命稻草。6.3 毕设和课设的选题思路很多学生朋友找到我说毕设想做“树莓派 网页平台”但不知道具体做什么。我推荐几个方向环境监测系统传感器数据定时写入 MySQL网页用图表展示Docker 负责打包整个后端和数据库RabbitMQ 消息队列管理平台在树莓派上容器化部署 RabbitMQ用它自带的管理后台做消息收发演示家庭媒体中心Nginx 做反代容器里跑媒体服务网页端管理播放列表设备管理后台多个树莓派上报状态用 Docker 部署一个集中管理页面。这些方向有一个共同点不是单纯“跑一个网页”而是把物联网数据流和 Web 展示串起来既能体现工作量又能把 Docker 技术点写进论文里。6.4 数据备份与长期运行建议网页服务器跑起来之后最重要的事就是备份。我的做法是每周做一次全量备份工具就是 tar 加 crontabtar -czf /mnt/backup/webpi-$(date %F).tar.gz \ /home/pi/site \ /home/pi/app \ /var/lib/docker/volumes恢复时只需要在新系统上装好 Docker把备份解压回到项目目录执行docker compose up -d数据卷里的内容原样恢复。这就是容器化最大的红利系统和软件全部可重建只有数据需要备份。长期运行建议也一并写在最后定期apt upgrade和升级镜像不要在树莓派上同时跑太多无状态服务给重要数据目录做独立备份保持系统日志可查记住服务器稳定运行的秘诀不是“不重启”而是“重启后能自动恢复”。我在实际搭建这个环境的过程中最大的体会是树莓派 Docker 化网页服务器根本不是“跑一个容器”的事而是一套完整的运维思维训练。从硬件供电、系统裁剪、网络模型到日志、备份、安全每一个环节都会在你真正遇到故障时体现出价值。这个专栏会把这些内容按顺序拆给你看你可以把它当教程也可以当手册遇到问题再回来查对应章节。最后再分享一个小技巧每完成一个阶段就把当前的 docker-compose.yml、配置文件和踩坑记录塞进一个 Git 仓库。树莓派上跑的服务总有一天要迁移或重构到时候你会感谢自己留下的这些痕迹。