用 Raspberry Pi 和 Docker 搭建家庭实验室：安装、备份与恢复

要点：从受支持的 64 位 Raspberry Pi OS、可用 SSH 和一个小型 Compose 服务开始。让网页端口只监听 localhost，用 SSH 隧道访问，并在放入重要数据之前验证备份。容器运行起来，只是实验室的起点，不代表已经能够恢复。

这里刻意采用简单例子：nginx 提供一个静态网页。它让主机、容器、网络和数据边界更容易理解，而不必一开始就部署数据库、密码管理器或公开管理面板。命令是建议的搭建示例，不是 AYXWORKS 对这套确切硬件配置的实测记录。

1. 准备干净主机，明确范围

你需要适合预期负载的树莓派、兼容型号的电源与散热、可靠存储及网络。运行受支持 64 位系统的 Pi 4 或 Pi 5，可作为这个小例子的合理起点，但不保证能承载以后添加的所有服务。存储和启动兼容性应遵循板卡文档。

使用 Raspberry Pi Imager 和官方远程访问说明配置自己的账户和 SSH。本教程示例用户名为 labuser，主机名为 lab，请替换成实际值。安装应用之前，先在可信家庭网络确认 SSH 可用。.local 名称无法解析时，可从路由器查询设备地址。

不要为了照做而给现有服务器重新写系统镜像。写入会清除所选存储。请使用备用介质或已经明确备份的介质，并仔细确认目标。已有 Docker 或其他服务时，应先核对现有安装，不要直接用以下命令替换。

2. 核实系统与架构

在树莓派上检查：

cat /etc/os-release
dpkg --print-architecture
uname -m

下面流程面向基于受支持 Debian 版本的 64 位 Raspberry Pi OS。确认 dpkg 返回 arm64，并查看实际 Debian 代号。核查时的 Docker Debian 文档将 Bookworm 和 Trixie 列为支持版本。仅有 64 位内核，不能证明用户空间也是 64 位。

如果安装的是 32 位系统、不受支持版本或其他发行版，请停止并采用对应官方说明。不要随意替换发行版代号，让软件仓库勉强接受当前系统。

3. 通过受支持的软件仓库安装 Docker

在干净且兼容的主机上，使用 Docker 的 Debian 仓库安装流程。逐项检查包管理器提示，出现错误就停下。下面会写入 Docker 仓库配置文件；不要在未检查的情况下覆盖已有自定义配置。

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run --rm hello-world
sudo docker compose version

预期验证是 hello-world 成功信息和 Compose 版本输出，而不是本文编造的某个固定版本。示例保留 sudo 管理 Docker。Docker 文档提醒，加入 docker 组会获得相当于 root 的权限，并非无关紧要的便利设置。

4. 创建独立的 Compose 项目

下面的代码块会拒绝覆盖已有的 ~/homelab/web。它创建示例网页与 Compose 文件。子 shell 的错误处理会在目录已存在或命令失败时停止整个块。

(
  set -eu
  test ! -e "$HOME/homelab/web"
  mkdir -p "$HOME/homelab/web/site"
  cd "$HOME/homelab/web"
  printf '%s\n' '<!doctype html><title>Home lab</title><h1>Home lab is running</h1>' > site/index.html
  cat > compose.yaml <<'YAML'
name: lab-web
services:
  web:
    image: nginx:stable-alpine
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    restart: unless-stopped
    logging:
      driver: local
YAML
)

镜像提供服务器，网页则存放在主机的 site 目录，并以只读方式挂入容器。端口仅监听树莓派的回环地址，这是刻意设计：服务并没有开放给局域网或互联网。local 日志驱动提供有限轮转，避免默认无界日志不知不觉占满空间。

镜像标签方便入门，但不是不可变版本。测试后记录解析出的 digest，需要可重复部署时将其固定。几个月后拉取同一标签，不保证得到相同软件。

5. 启动服务，检查真实页面

在新项目目录执行以下命令，任何一步失败都应先调查：

cd "$HOME/homelab/web" || exit 1
sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
curl --fail http://127.0.0.1:8080/

配置验证应无错误，服务应处于运行状态，curl 应返回示例 HTML。只有“running”并不能证明应用正常。curl 失败时，先检查日志、端口绑定和页面挂载，再考虑添加软件。

6. 不公开端口，也能从笔记本访问

在笔记本上，用前面配置的账户和主机名开启 SSH 隧道：

ssh -N -l labuser -L 127.0.0.1:8080:127.0.0.1:8080 lab.local

保持终端打开，在笔记本浏览器访问 http://127.0.0.1:8080/。SSH 会持续运行而不提供命令行，这是正常行为。完成后按 Ctrl+C 停止。如果笔记本的 8080 已被占用，修改转发参数中第一个本地端口，并在浏览器使用新端口。

这个练习不需要配置路由器端口转发，也不应暴露 Docker socket。Docker 发布端口的机制可能与主机防火墙规则相互影响；不能假定有防火墙就能让所有已发布容器保持私有。从家外访问需要单独审查访问设计，而不是开放管理面板。

7. 查看日志、存储与测试过的镜像

cd "$HOME/homelab/web" || exit 1
sudo docker compose ps
sudo docker compose logs --tail=50 web
df -h
sudo docker image inspect nginx:stable-alpine --format '{{index .RepoDigests 0}}'

应用错误看 Compose 日志，主机容量看磁盘使用。最后一条命令输出解析后的镜像引用，固定测试版本时应与 Compose 文件一并保存。真实服务的日志可能包含私人信息，分享前要先检查。

不要因为第一个网页能打开，就立即启动一大套服务。每次增加一个，检查 CPU 架构、内存、持久化数据、凭证、网络与恢复流程。容器不会自动让不兼容的软件适用于 ARM。

8. 创建并验证这个例子的备份

静态网页例子的项目目录包含重建所需数据和配置。没有同时编辑文件时，执行：

(
  set -eu
  umask 077
  mkdir -p "$HOME/backups"
  backup="$HOME/backups/lab-web-$(date +%Y%m%d-%H%M%S).tar.gz"
  test ! -e "$backup"
  tar -C "$HOME/homelab" -czf "$backup" web
  gzip -t "$backup"
  sha256sum "$backup"
  restore=$(mktemp -d "$HOME/lab-restore.XXXXXX")
  tar -xzf "$backup" -C "$restore"
  cmp "$HOME/homelab/web/site/index.html" "$restore/web/site/index.html"
  cmp "$HOME/homelab/web/compose.yaml" "$restore/web/compose.yaml"
  printf 'Backup: %s\nRestored copy: %s\n' "$backup" "$restore"
)

脚本检查压缩包，解压到新的临时目录，并与源文件比较。cmp 成功时不输出内容；任何失败会停止代码块。这证明的是文件级恢复，不是运行中应用的完整灾难恢复演练。检查之前先保留解压副本。

将归档复制到另一设备或备份目的地，并妥善保护。只放在树莓派上的备份，会随同一块存储一起损坏。真实数据库需要应用支持的一致性备份或导出，直接复制运行中的数据库目录并不自动有效。Docker 卷同样需要明确方案，参见卷文档。

9. 有计划地更新，并知道怎样停止

更新前保留当前 Compose、测试过的镜像引用和数据备份。查看发行说明，拉取目标镜像，重建服务并重新检查页面。应用若执行了数据库结构迁移，只退回旧镜像未必能撤销数据变化，应遵循它的恢复流程。

停止本例并移除其 Compose 容器与网络：

cd "$HOME/homelab/web" || exit 1
sudo docker compose down

这不会删除从主机绑定挂载的 site 目录。不要随意给其他项目的命令添加 -v，也不要用清理卷命令代替理解数据存放位置。保留 Compose 文件后，可用 up -d 重新创建本例。

基础运行后，再增加哪些能力

在实验室存放不可替代的信息之前，应按具体应用安排认证、TLS、异机备份、监测和更新策略。秘密信息不要提交到版本控制，并限制谁能管理 Docker 与 SSH。

第一个目标很朴素：能解释网页存在哪里、如何访问、用什么镜像、删除容器后保留什么，以及怎样检查备份。这比拥有满屏服务却从未尝试恢复更有价值。

来源与验证边界

所链接的 Raspberry Pi 和 Docker 文档于 2026 年 10 月 14 日复核。硬件容量、镜像可用性和安装兼容性仍需针对所选主机确认。本文以明确教程替代缺乏依据的第一人称搭建经历，不声称 AYXWORKS 已完成这套硬件部署或测得可靠性提升。