芯耀
1615
树莓派资讯1： 9 月23日-27日，树莓派团队将首次亮相上海工博会。树莓派团队九月亮相上海工博会！树莓派爱好者不来切磋一下？
树莓派资讯2：树莓派新品震撼来袭 ，开启内测资格！！树莓派资讯3：直播预约开启，跟随树莓派首席商务官 Mike Buffham 一起揭晓！
好！正文开始！
Portainer是什么？
Portainer在树莓派上广受欢迎，原因在于它是一款轻量级的Web界面工具，可用于运行和管理容器。它基于Docker构建（也可与Swarm/Kubernetes配合使用），简化了日常任务，让初学者管理树莓派上的Docker变得更加容易：可部署堆栈、查看日志、管理卷和网络、设置环境变量以及处理镜像更新。
与仅使用Docker命令行界面（CLI）相比，Portainer的主要功能和优势
? 容器、镜像、卷和网络的可视化控制。
? 一键从Docker Compose部署堆栈。
https://docs.docker.com/compose/
? 基于角色的访问控制（团队/用户）和注册表集成。
? 健康状态/运行状态可见。
? 在共享系统上执行常规操作更安全；与原始CLI相比，输入错误更少。
为何在树莓派上使用Portainer？
好处
Portainer适用于树莓派上的Docker项目，因为它在有限的硬件上也能运行良好；空闲时CPU占用极低。
? 在有限的硬件上也能运行良好；空闲时CPU占用极低。
? 生命周期管理简单：通过用户界面（UI）即可完成拉取→部署→更新→回滚操作。
? 非常适合边缘计算/物联网（IoT）：可与MQTT、Node-RED、InfluxDB、Grafana等工具配合使用。在资源有限的设备上使用更轻松。
? 支持ARM64镜像；可为每个容器设置CPU/内存限制。
? 可视化检查有助于发现失控日志、端口冲突和卷问题。Portainer与Docker CLI对比（快速概览）
? Portainer：用户体验佳、可见性高、共享使用更安全、可快速审计。
? CLI：功能全面、支持脚本编写/自动化、对高级用户来说速度最快。最佳实践：日常操作使用Portainer，脚本编写和深度故障排除使用CLI。
要求
Portainer对树莓派的要求不高：推荐使用树莓派4（4GB以上内存）和树莓派5。
? 推荐使用树莓派4（4GB以上内存）和树莓派5。
? 操作系统：树莓派操作系统（Bookworm）或Ubuntu Server 22.04/24.04（ARM64）
树莓派操作系统：版本、特性及设置完整指南！
? 存储：强烈建议数据库和媒体使用固态硬盘（SSD）/非易失性内存（NVMe）；轻量级服务可使用microSD卡（详见[树莓派5从NVMe SSD启动]
https://docs.sunfounder.com/projects/pironman5/en/latest/pironman5_max/install/install_raspberry_os.html
? 端口：9443/TCP（用户界面，HTTPS）。8000/TCP（可选，边缘代理）。
? Docker（重要）：Docker是此设置的重要组成部分。有关安装和高级用法，请查看此树莓派Docker指南。
树莓派上的Docker应用：从安装到高级用法与故障排除
在树莓派上安装Portainer
1.在终端中运行以下命令，快速完成设置并安装树莓派上的Portainer（详见官方[Portainer社区版（CE）Linux安装指南]
https://docs.portainer.io/start/install-ce/server/docker/linux
# Persistent data volumedocker?volume create portainer_data# Run Portainer CEdocker run -d? --name portainer?--restart=always?-p 9443:9443 -p 8000:8000?-v /var/run/docker.sock:/var/run/docker.sock?-v portainer_data:/data? portainer/portainer-ce:latest
2.在浏览器中打开https://<树莓派IP>:9443。
首次运行时，设置管理员密码并选择本地Docker环境。
3.在Portainer中配置环境（端点）：环境（以前称为“端点”）是Portainer管理的计算目标：
4.环境（以前称为“端点”）是Portainer管理的计算目标，这对于树莓派上的Portainer Docker设置特别有用。
? 本地Docker（运行Portainer的Docker主机）。
? 通过代理远程Docker（目标主机上的Portainer代理；入站TCP 9001）。
? 边缘代理（仅出站，兼容网络地址转换（NAT）/防火墙；Portainer监听8000端口）。
1）本地Docker（同一树莓派上）
当使用-v /var/run/docker.sock:/var/run/docker.sock部署Portainer时，会自动创建本地环境。
验证方法：
? 在“环境”中，应能看到状态为绿色的本地环境。
? 如果未显示，请转到“环境”→“添加环境”→“Docker”，然后选择“本地”。
最佳实践：
? 限制只有管理员/团队负责人可访问（基于角色的访问控制（RBAC）），因为这会暴露主机Docker套接字。
2) 通过Portainer代理远程Docker（局域网/广域网，端口开放）
当Portainer可通过TCP 9001访问远程主机时使用此方法。
在远程树莓派（目标主机）上：
docker run?-d??--name portainer_agent?--restart=always?-p?9001:9001??-v?/var/run/docker.sock:/var/run/docker.sock ?-v?/var/lib/docker/volumes:/var/lib/docker/volumes? portainer/agent:latest
在Portainer（服务器用户界面）中：
? “环境”→“添加环境”→“独立Docker”→“代理”
? 名称：例如，pi-gateway-01
? URL: tcp://<远程-ip>:9001
? 分配给一个“组”和“标签”（例如，物联网、边缘、实验室）。
? 保存
防火墙/网络：
? 在远程主机上开放9001/TCP端口。
? 建议使用静态/动态主机配置协议（DHCP）保留IP地址。
3) 通过边缘代理远程Docker（位于NAT/防火墙后）
当无法开放入站端口时使用此方法。边缘代理会向Portainer服务器发起出站连接。
Portainer服务器上的先决条件：
? 开放8000/TCP端口（运行Portainer时已映射-p 8000:8000）。在Portainer（服务器用户界面）中：
? “环境”→“添加环境”→“边缘代理”
? 选择“独立Docker”。
? 设置“名称”、“组”、“标签”。
? Portainer会生成边缘ID/密钥以及一条可直接运行的命令。
在远程树莓派（目标主机）上：
使用Portainer提供的命令：
docker run?-d??--name portainer_edge_agent??--restart=always??-v/var/run/docker.sock:/var/run/docker.sock??-v?/var/lib/docker/volumes:/var/lib/docker/volumes ?-e?EDGE=1???-e?EDGE_ID=<edge_id_from_portainer>???-e?EDGE_KEY=<edge_key_from_portainer>???-e?CAP_HOST_MANAGEMENT=1?? ?portainer/agent:latest
以下是一个简洁、实用的部分，可直接粘贴到您的指南中。措辞原创，从物联网从业者的角度撰写。
在树莓派上使用Portainer（图形用户界面）管理容器和工作负载
堆栈——部署Docker Compose应用程序
使用Portainer在树莓派上部署Docker Compose堆栈非常简单，非常适合多容器应用程序。
适用场景：多容器应用程序（例如，Mosquitto + Node-RED + InfluxDB + Grafana）、共享网络/卷的服务，或任何你想通过Compose文件进行版本控制的应用程序。
操作方法（用户界面流程）：
1.“堆栈”→“添加堆栈”→选择Web编辑器（粘贴YAML代码）或Git存储库（固定到标签/提交）。
2.环境变量：通过环境变量（Env）定义密钥/凭据，或在使用时引用密钥/配置。
3.卷：映射到主机路径，如/srv/docker/<应用>/...（便于备份）。
4.网络：让Portainer为每个堆栈创建一个网络，或附加到一个共享的反向代理网络。
5. 部署堆栈，然后打开“日志”和“健康状态”进行首次运行检查。
示例（物联网迷你堆栈）
services:??mosquitto:?image:?eclipse-mosquitto:2.0? ??restart:?unless-stopped? ? ?ports:?["1883:1883"]? ??volumes:?-?/srv/docker/mosquitto/config:/mosquitto/config:ro? ? ? -?/srv/docker/mosquitto/data:/mosquitto/data? ? ? -?/srv/docker/mosquitto/log:/mosquitto/log? ??healthcheck:? ? ??test:?["CMD-SHELL",?"nc -z localhost 1883 || exit 1"]? ? ??interval:?15s? ? ??retries:?5nodered:?image:?nodered/node-red:latest?depends_on:?[mosquitto]? ??restart:?unless-stopped?environment:? ? ? -?TZ=America/Argentina/Cordoba? ? ? -?NODE_RED_ENABLE_SAFE_MODE=false? ? ?ports:?["1880:1880"]? ? ?volumes:?-?/srv/docker/nodered:/data? ? ?healthcheck:? ? ?test:?["CMD",?"wget",?"-qO-",?"http://localhost:1880"]? ? ?interval:?30s? ? ?retries:?5networks:??default:? ??name:?iot_core_net? ??driver:?bridge
容器——创建和管理单个容器
适用场景：单服务工具（Pi-hole、Uptime Kuma、Zigbee2MQTT）、快速测试或一次性工具。
操作方法（用户界面流程）：
1.“容器”→“添加容器”
2.镜像：指定完整名称和标签；可选择设置注册表凭据。
3.运行时：命令/入口点、环境变量（时区（TZ）、用户ID/组ID（PUID/PGID））、设备（例如，无线电的/dev/ttyUSB0）、功能（丢弃所有功能；仅添加所需功能）。
4.端口：仅发布必要的端口；外部访问建议使用反向代理。
5.资源：设置CPU/内存限制；小型树莓派设置明确的上限更有益。
6.重启策略：对于设备，设置为“除非停止”；调试时避免使用“始终”。
日常操作：
? “日志”用于快速排查问题，“控制台/执行”用于在容器内打开shell。
? “复制/编辑”用于在不修改堆栈的情况下进行小改动。
? 更新固定标签的镜像时，“重新创建”并选择“拉取最新镜像”。
卷——数据持久性和挂载选项
重要性：SD卡磨损快；数据库和代理需要持久化存储。
选项与指导：
? 绑定挂载（推荐用于物联网）：映射明确路径，例如，/srv/docker/mosquitto:/mosquitto
使用tar或rsync轻松备份；布局透明。
? 命名卷：适用于一般用途；主机上的数据位置不太明显。
? 只读挂载：将配置挂载为只读；仅保持写入频繁的路径为可读写。
? 权限：使PUID/PGID与主机文件夹所有权一致，避免权限循环。
? 媒体和数据库：将时序数据库（InfluxDB）、SQLite和对象存储放在SSD/NVMe上。
? 备份：将/srv/docker/<应用>和你的Compose存储库一起快照；每季度测试恢复。
网络——容器网络与通信
设计目标：可预测的服务发现、最小端口暴露以及堆栈之间的清晰分离。
有效模式：
? 每个堆栈一个网桥：默认设置，保持服务隔离，并允许通过服务名称（mqtt、nodered）访问对等方。
? 共享“代理”网络：将Web应用程序附加到一个由反向代理使用的公共网络。
? 主机网络（谨慎使用）：仅在真正需要广播/多播（多播域名系统（mDNS）/通用即插即用（UPnP））或严格端口保真度时使用。注意端口冲突。
? macvlan（高级）：为容器分配自己的局域网IP（适用于旧设备）；记住，默认情况下主机无法与macvlan通信，必要时添加macvlan桥接。
? 域名系统（DNS）与发现：在同一网络内，使用服务名称而非IP地址。在外部，通过代理和单个传输层安全（TLS）入口点前置所有服务。
备份与更新
备份与更新（物联网级实践）
首先考虑恢复：如果树莓派出现故障，你应该能够快速重建Docker、恢复数据、重新部署堆栈并迅速恢复服务。本节提供了一个清晰、可重复的工作流程，多亏了Portainer简单的备份和恢复方法，你可以快速恢复服务。
备份内容
? Portainer状态：portainer_data卷。
? 应用数据：/srv/docker/<应用>下的绑定挂载和任何命名卷（数据库、MQTT、流）。
? 配置：包含compose.yml、.env和密钥（以文件形式存储，而非硬编码）的Git存储库。
备份绑定挂载（配置、流）
绑定挂载只是文件夹，使用rsync进行高效复制。
同步到外部驱动器或网络附加存储（NAS）挂载点/backups
sudo rsync -aHAX --delete?--numeric-ids /srv/docker/?/backups/srv-docker/?命名卷（数据库、Portainer）
使用辅助容器进行归档：
# Backup a named volume to /srv/backups docker run --rm? -v mydb:/from? -v /srv/backups:/to 、busybox sh -c?'cd /from && tar -czf /to/mydb_$(date +%F).tgz .'# Backup Portainer state docker run --rm? -v portainer_data:/from? -v /srv/backups:/to ?? ?busybox sh -c?'cd /from && tar -czf /to/portainer_$(date +%F).tgz .'?
监控与故障排除
用户界面已加载，但环境显示为红色
? 可能原因：代理无法访问（9001端口被阻止）或边缘隧道连接失败（8000端口被阻止，代理WebSocket未转发）。
? 解决方法：开放所需端口；对于边缘代理，允许向服务器的8000/9443端口出站连接，并在代理上启用WebSocket穿透。
“未授权”或频繁注销
? 可能原因：Cookie/域名不匹配或代理重写标头。
? 解决方法：在稳定的完全限定域名（FQDN）上提供Portainer服务；确保代理保留授权和升级标头。
边缘代理卡在“等待隧道”状态
? 可能原因：边缘密钥/ID错误或服务器8000端口无法通过代理的出站路径访问。
? 解决方法：在用户界面中轮换边缘密钥，在设备上重新部署提供的命令；验证到8000/9443端口的出站连接。
用户界面加载缓慢/超时
? 可能原因：树莓派上的磁盘输入/输出（I/O）争用或内存耗尽。
? 解决方法：将数据移动到SSD/NVMe，减少同时拉取操作，添加交换空间（zram），将镜像固定到已知良好的标签。
升级后用户界面无法启动
? 可能原因：镜像拉取不完整或标志不兼容。
? 解决方法：docker pull portainer/portainer-ce:latest，然后使用相同的portainer_data卷重新创建容器。
基于角色的访问控制/密码问题
? 解决方法：使用用户界面重置密码并查看团队访问权限。如果完全被锁定，停止Portainer，备份portainer_data，并咨询受控恢复方法（最后手段：重建+恢复）。
安全重启和更新Portainer
# Pull image, stop, remove, run (keeps state in portainer_data)docker pull portainer/portainer-ce:latestdocker stop portainer && docker?rm?portainerdocker run -d --name portainer --restart=always? -p 9443:9443 -p 8000:8000? -v /var/run/docker.sock:/var/run/docker.sock? -v portainer_data:/data? ?portainer/portainer-ce:latest
添加基本健康检查（可选，通过Compose）
services:? portainer:? ? image: portainer/portainer-ce:latest? ? ports: ["9443:9443","8000:8000"] volumes:? ? ? - /var/run/docker.sock:/var/run/docker.sock? ? ? - portainer_data:/data? ? restart: unless-stopped? ? ?healthcheck:?test: ["CMD-SHELL","nc -z localhost 9443 || exit 1"]? ? ? interval: 30s? ? ??timeout: 5s? ? ? retries: 5volumes:? portainer_data:
本树莓派Portainer指南展示了Portainer如何改变你在树莓派上管理Docker容器的方式，通过直观的Web界面简化复杂任务。Portainer通过直观的Web界面改变了你在树莓派上管理Docker容器的方式。从部署堆栈和管理卷到增强安全性和执行备份，它为家庭实验室和物联网爱好者提供了一套完整的工具包。将Portainer与树莓派的灵活性相结合，你可以获得一个轻量级但功能强大的平台，用于实验、学习和构建可靠的服务。通过正确的设置和最佳实践，你的树莓派可以成为一个稳定、高效和安全的容器主机，适用于各种项目。
很多人一直以为树莓派（Raspberry Pi）只是创客圈子里的小玩具——一块信用卡大小的开发板，用来点亮 LED、跑个 Python 脚本、或者给中学生上一堂入门编程课。然而，事实远比想象震撼：树莓派已经悄悄完成了从“教学演示”到“工业级主力”的华丽转身，正在产线、机房、实验室甚至外太空里 7×24 小时不间断服役。
如果觉得我们的内容不错，记得点赞+收藏+关注+转发~ 我们很乐意为您提供工业树莓派的解决方案，项目有需求请联系我们~?www.edatec.cn/cn
