中文

应用程序

安装 Portainer CE 并保护其访问

使用 Docker Compose 在 Debian 或 Ubuntu 上安装 Portainer Community Edition:通过 SSH 隧道或受限 HTTPS 访问、Docker 套接字的风险、更新与备份。

阅读约 10 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

Portainer Community Edition(CE)是一个 Web 界面,用于管理 Docker 服务器上的容器、镜像、数据卷、网络和 stack。本指南将向您介绍如何使用 Docker Compose 安装它,同时不将其界面暴露到互联网。

完成本指南后,Portainer 只监听服务器的本地地址。您可以通过 SSH 隧道访问它,也可以根据需要仅从您的 IP 地址通过 HTTPS 访问。您还将了解如何评估 Docker 套接字带来的风险、更新 Portainer 以及备份其数据。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

  • 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的服务器
  • 使用具有 sudo 权限的用户进行 SSH 访问
  • 已从官方仓库安装 Docker Engine 和 Docker Compose,具体请参阅指南安装 Docker Engine 和 Docker Compose。请勿使用 Docker 的 snap 软件包
  • 您电脑上的 SSH 客户端

docker 命令假定您的用户属于 docker 组。否则,请在命令前加上 sudo。

本指南使用 2.45.3 版本,这是撰写本文时最新的 LTS 版本。请在 Portainer 版本页面查看最新版本,并查阅受支持的 Docker 版本列表。

使用的端口

端口 作用 本指南中的发布方式 是否需要在防火墙中开放
22/tcp SSH 以及通往 Portainer 的隧道 服务器的 SSH 服务 是,如果尚未开放
9443/tcp Portainer 的 HTTPS 界面 仅 127.0.0.1 否
9000/tcp HTTP 界面,供本地反向代理使用 127.0.0.1,仅在使用 Caddy 选项时 否
8000/tcp Edge Agents 隧道 不发布 否
80 和 443/tcp Caddy 仅在使用 Caddy 选项时 仅在使用 Caddy 选项时

了解 Docker 套接字的风险

Portainer 通过挂载到其容器中的套接字 /var/run/docker.sock 控制 Docker。该套接字可访问 Docker 的全部 API,而 Docker 守护进程以 root 身份运行。

例如,能够控制 Docker 的账户可以启动特权容器,或将服务器的根目录 / 挂载到容器中,然后读取和修改任意文件。Docker 文档也提醒,只有受信任的用户才应能够控制守护进程。

一些实际影响:

  • 以 :ro 方式挂载套接字并不能保护您:它只作用于文件本身,而不限制发送给 Docker API 的操作
  • 仅将管理员角色授予本就可以在服务器上成为 root 的人员
  • 及时应用 Portainer 更新
  • 优先使用 SSH 隧道,这样无需暴露界面

步骤 1:创建 Compose 项目

为 Portainer 创建一个文件夹:

终端
sudo mkdir -p /opt/portainer
sudo chown "$USER": /opt/portainer
cd /opt/portainer
nano compose.yaml

粘贴以下配置:

YAML
services:
  portainer:
    image: portainer/portainer-ce:2.45.3
    container_name: portainer
    restart: unless-stopped
    ports:
      - "127.0.0.1:9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:
    name: portainer_data

端口 8000 未发布,因为它仅供 Edge Agents 使用。请验证该文件并下载镜像:

终端
docker compose config --quiet
docker compose pull

步骤 2:打开 SSH 隧道

Portainer 启动后,您有 5 分钟 时间创建第一个管理员。因此,请在启动容器之前准备好隧道。

在您的电脑上的终端中运行:

终端
ssh -N -L 9443:127.0.0.1:9443 您的用户名@您的服务器IP

该命令不会输出任何内容并保持运行,这是正常现象。使用 Portainer 期间请保持此终端打开,之后用 Ctrl+C 关闭隧道。如果您电脑上的 9443 端口已被占用,可以改用例如 -L 19443:127.0.0.1:9443 和地址 https://localhost:19443。

步骤 3:启动 Portainer

在服务器上启动容器,然后获取安装令牌:

终端
cd /opt/portainer
docker compose up -d
docker compose ps
docker logs portainer 2>&1 | grep setup_token | tail -n 1

最后一条命令会显示一行 setup_token=...。这个一次性令牌自 2.39.4 和 2.43 版本起成为必需项,可防止他人抢占新实例。只要还没有管理员,每次启动时都会重新生成该令牌。

步骤 4:创建管理员账户

  1. 在浏览器中打开 https://localhost:9443。
  2. 接受安全警告:Portainer 默认使用自签名证书。流量经由 SSH 隧道传输。
  3. 选择用户名和至少 12 个字符 的唯一密码。
  4. 将令牌的值粘贴到 Setup token 字段,然后确认。
  5. 在 Edge Compute 界面上,如果您不管理 Edge Agents,请选择 Skip。
  6. 在向导中单击 Get Started:本地环境会被自动检测到。

请将此密码保存在密码管理器中。

验证结果

在 Portainer 中打开 local 环境:容器 portainer 应出现在 Containers 列表中。

然后在服务器上检查监听地址:

终端
docker ps --filter name=portainer --format '{{.Names}} {{.Ports}}'
curl -kI https://127.0.0.1:9443

输出应包含 127.0.0.1:9443->9443/tcp,curl 应返回 HTTP 响应。最后,从另一台机器上,在不使用隧道的情况下确认无法访问任何内容:

终端
nmap -Pn -p 8000,9000,9443 您的服务器IP

这些端口都不应显示为 open。

限制 Portainer 中的权限

如果有多人使用该界面,以下设置可以降低风险:

设置 位置 建议
个人账户 User-related > Users 每人一个账户,除非必要,否则不授予管理员角色
会话时长 Settings > Authentication 如有需要,缩短默认的 8 小时
Docker 限制 local 环境 > Host > Setup > Docker Security Settings 尤其要启用 Hide bind mounts for non-administrators 和 Hide privileged mode for non-administrators

这些限制仅针对非管理员账户,并不限制管理员可执行的操作。

可选:使用 Caddy 通过 HTTPS 发布 Portainer

大多数情况下,SSH 隧道已经足够。如果您需要一个网址,请将 Portainer 置于反向代理之后,并将访问限制为您的 IP 地址。

您需要已按照指南使用 Caddy 反向代理并自动启用 HTTPS完成配置,并已为 portainer.您的域名.com 创建指向 您的服务器IP 的 A 记录。

在 /opt/portainer/compose.yaml 中添加本地 HTTP 端口:

YAML
    ports:
      - "127.0.0.1:9443:9443"
      - "127.0.0.1:9000:9000"

应用此修改:

终端
cd /opt/portainer
docker compose up -d

然后将以下站点添加到 /etc/caddy/Caddyfile:

caddyfile
portainer.您的域名.com {
	@allowed client_ip 您的IP

	handle @allowed {
		reverse_proxy 127.0.0.1:9000
	}

	handle {
		abort
	}
}

由于 Caddy 安装在服务器上而不是 Docker 中,UFW 对其端口生效。请开放这些端口,然后重新加载配置:

终端
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

从您获准的地址打开 https://portainer.您的域名.com:应显示登录页面。从其他网络连接(例如使用移动数据的手机)访问时,连接应被断开。

如果您的 IP 地址经常变化,建议改为通过 WireGuard 或 Tailscale 将访问限定在私有网络中。

更新 Portainer

请先备份 Portainer,然后阅读发行说明。将 compose.yaml 中的镜像标签替换为新版本,然后执行:

终端
cd /opt/portainer
nano compose.yaml
docker compose pull
docker compose up -d
docker compose images

您的其他容器不会停止。之后请重新登录,确认 local 环境正常响应。数据保留在数据卷 portainer_data 中。

也可以使用滚动标签 lts,但指定明确的版本可让您自行选择更新时机,并确切了解正在运行的版本。

备份与恢复

Portainer 备份包含其数据库以及从 Portainer 部署的 stack 文件。它不包含您的容器、镜像及其数据卷中的数据:请按照指南安装 Docker Engine 和 Docker Compose中的说明单独备份。

通过界面

  1. 打开 Settings,然后向下滚动到 Back up Portainer。
  2. 启用 Password protect 并输入密码。
  3. 单击 Download backup。

在 CE 版中,此备份需要手动启动。计划备份和发送到 S3 的功能仅限 Business 版。

通过服务器

此方法可以设置为计划任务。它会短暂停止 Portainer,但不影响您的其他容器:

终端
cd /opt/portainer
mkdir -p backups
docker compose stop portainer
docker run --rm -v portainer_data:/data:ro -v "$PWD/backups":/backup alpine:3 tar czf "/backup/portainer-$(date +%F).tar.gz" -C /data .
docker compose start portainer
sudo chmod 600 backups/*.tar.gz

该归档包含凭据和 API 密钥。请将它和 compose.yaml 一起复制到服务器之外的加密位置。

恢复服务器上的归档

将 YYYY-MM-DD 替换为归档的日期。数据卷的现有内容将被删除:

终端
cd /opt/portainer
docker compose down
docker run --rm -v portainer_data:/data -v "$PWD/backups":/backup:ro alpine:3 sh -c 'find /data -mindepth 1 -delete && tar xzf /backup/portainer-YYYY-MM-DD.tar.gz -C /data'
docker compose up -d

请使用与备份时相同或更新的 Portainer 版本。

恢复下载的文件

只有在数据卷为空的全新实例上才能进行此恢复。在初始化界面上打开 Restore Portainer from backup,选择文件,输入其密码和 setup_token 令牌,然后单击 Restore Portainer。

故障排除

the Portainer instance timed out for security purposes

第一个管理员未在 5 分钟内创建。请重启容器,然后获取新的令牌:

终端
cd /opt/portainer
docker compose restart portainer
docker logs portainer 2>&1 | grep setup_token | tail -n 1

如果此消息出现在已配置好的实例上,请检查数据卷 portainer_data 是否已正确挂载:没有这些数据,Portainer 的行为就像全新安装一样。

安装令牌被拒绝

令牌在每次启动时都会变化。请使用上一条命令显示的最新值,并在复制时不要带空格。

open failed: connect failed: Connection refused

此消息显示在隧道所在的终端中。隧道本身正常,但服务器上的目标端口没有任何服务在监听。请用 docker compose ps 检查容器状态,并用 docker compose logs --tail=50 portainer 查看其日志。

bind [127.0.0.1]:9443: Address already in use

您电脑上的该端口已被占用,通常是旧的隧道所致。请将其关闭,或按步骤 2 的方法选择另一个本地端口。

Client sent an HTTP request to an HTTPS server

您在 9443 端口上使用了 http://。请打开 https://localhost:9443。

9443 端口可从互联网访问

该端口很可能在发布时没有指定本地地址。请检查 docker ps 的输出:如果其中包含 0.0.0.0:9443,请修改 compose.yaml,然后重新运行 docker compose up -d。

反向代理后出现 403 Forbidden 和 CSRF check failed

代理很可能修改了 Portainer 收到的主机名。使用本指南的 Caddy 配置块时,原始主机名会被保留。如果前面还有其他代理,请使用完整 URL 声明公开地址:

YAML
    command: --trusted-origins https://portainer.您的域名.com

不带 https:// 的名称会在启动时引发错误 invalid url for trusted origin。

Caddy 出现 502 错误

Caddy 无法连接到 9000 端口。请用 docker ps 检查它是否已发布,然后测试 curl -I http://127.0.0.1:9000。如果 Force HTTPS only 已启用,请通过 SSH 隧道将其禁用。

管理员密码丢失

其他管理员可以为您重置。否则,请使用官方工具,它会显示一个新密码:

终端
cd /opt/portainer
docker compose stop portainer
docker pull portainer/helper-reset-password
docker run --rm -v portainer_data:/data portainer/helper-reset-password
docker compose start portainer

参考资料