Portainer 安全加固的紧迫性来自一个事实:它通过 Docker socket 控制守护进程,而 Docker 守护进程等价于宿主机 root。Portainer 一旦被攻破,攻击者不需要提权,直接就能在任意容器里挂载宿主根目录。现实中大量事故的入口并不是漏洞,而是 9443 端口对公网开放、初始化页面未及时创建管理员、以及容器被赋予 --privileged。本篇从网络收口、TLS、初始化、RBAC、socket 代理白名单五个层次给出可复现的配置。
适用场景
- 用 Portainer CE / BE 管理单机 Docker、Swarm 或 Kubernetes 集群,9443 或 9000 端口可从公网访问。
- 团队多人共用一套 Portainer,需要区分「谁能操作哪个环境」。
- Portainer 容器直接挂载了
/var/run/docker.sock,担心被容器逃逸后横向拿到宿主控制权。 - 需要为安全审计提供容器管理平台的访问控制与操作记录证据。
前置条件
- Docker Engine 24 以上,Portainer CE 2.19 以上(
docker exec portainer portainer --version确认)。 - 宿主机已签发域名证书(示例
panel.example.com),或接受先用自签证书再替换。 - 具备 docker 命令权限的管理账号,建议加入
docker组而非长期使用 root。 - 一套内网地址规划:Portainer 只绑
127.0.0.1,对外由 nginx 或 VPN 暴露。
原理说明:为什么 Portainer 等于 root
Portainer Server 是一个 Go 编写的 Web 应用,它把 HTTP 请求翻译成 Docker Engine API 调用。请求路径有两类:一类走挂载进容器的 /var/run/docker.sock(Unix socket),另一类走 tcp://host:2375 或 2376(远程 Agent 模式)。Docker Engine API 本身没有权限模型——能调 API 就能 docker run -v /:/host --privileged,因此 Portainer 的授权体系只是「应用层的门」,门后是完整 root。
据此,加固要解决四个问题:
- 入口:谁能连到 9443,是否能绕开反向代理直连。
- 身份:初始管理员是否被抢注,口令是否可爆破,是否接入统一身份源。
- 授权:团队成员是否只能看/操作被分配的环境与命名空间。
- 能力:Portainer 到底能对 Docker API 说哪些话,是否能 exec 进容器、是否能读 secrets。
操作步骤
第一步:网络收口,只绑回环地址
端口映射写成 127.0.0.1:9443:9443 而不是 9443:9443。这一处差别决定了 9443 是否暴露在公网,比任何 WAF 规则都有效。同时用 --http-disabled 关闭 9000 明文端口。
docker volume create portainer_data
docker network create portainer-net 2>/dev/null || true
install -d -m 0700 /etc/portainer/secrets
printf '%s' 'ChangeMe-Str0ng-Passw0rd-2026' > /etc/portainer/secrets/admin_password
chmod 0600 /etc/portainer/secrets/admin_password
第二步:挂载自有证书并设置初始口令
Portainer 启动时若无管理员账号,会进入「创建初始管理员」页面,谁先访问谁就是管理员——这是最常见的失陷原因。用 --admin-password-file 预先写入口令可以彻底消除这个时间窗。该文件内容是明文口令,长度至少 12 位。
docker rm -f portainer 2>/dev/null || true
docker run -d --name portainer --restart=always \
--network portainer-net \
-p 127.0.0.1:9443:9443 \
-v /etc/portainer/secrets/admin_password:/run/secrets/portainer_admin:ro \
-v /etc/letsencrypt/live/panel.example.com:/certs:ro \
-v portainer_data:/data \
portainer/portainer-ce:2.21.5 \
--sslcert /certs/fullchain.pem \
--sslkey /certs/privkey.pem \
--http-disabled \
--admin-password-file /run/secrets/portainer_admin
注意 --sslcert、--sslkey、--http-disabled 必须写在镜像名之后,它们由 Portainer 自己解析而不是 Docker。启动后立即登录,在 My account 里把初始口令换成个人口令,然后删除磁盘上的明文文件:
shred -u /etc/portainer/secrets/admin_password
第三步:反向代理对外,禁止直连
Portainer 前端是单页应用 + WebSocket(/api/websocket),反代同样要透传 Upgrade。这里用客户端证书做第二道门,无证书的请求在 TLS 握手阶段就被拒绝,扫描器拿不到任何响应。
server {
listen 443 ssl http2;
server_name panel.example.com;
ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;
ssl_client_certificate /etc/nginx/client-ca.crt;
ssl_verify_client on;
ssl_verify_depth 2;
ssl_protocols TLSv1.2 TLSv1.3;
location / {
proxy_pass https://127.0.0.1:9443;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 3600s;
proxy_buffering off;
}
}
如果不想维护客户端证书,退一档用 IP 白名单,但至少要保住「9443 不直连」这条底线:
allow 203.0.113.0/24;
deny all;
第四步:用 socket 代理限制 Docker API 能力
直接把宿主 docker.sock 挂进 Portainer,等于把 root 交给它。更稳的做法是加一层代理,只放行 Portainer 真正需要的 API 分组。下面这份白名单允许管理容器、镜像、网络,但禁止 exec、禁止读 secrets、禁止 Swarm 与系统级操作。
docker run -d --name portainer-sock --restart=always \
--network portainer-net \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-e CONTAINERS=1 -e IMAGES=1 -e NETWORKS=1 -e VOLUMES=1 \
-e INFO=1 -e VERSION=1 -e EVENTS=1 \
-e POST=1 -e EXEC=0 -e DELETE=0 \
-e SECRETS=0 -e CONFIGS=0 -e SWARM=0 -e NODES=0 \
-e SERVICES=0 -e TASKS=0 -e SYSTEM=0 -e AUTH=0 \
-e BUILD=0 -e COMMIT=0 -e DISTRIBUTION=0 -e PLUGINS=0 \
tecnativa/docker-socket-proxy:latest
POST=1 是必需的,否则创建容器、部署 Stack 都会失败;DELETE=0 意味着可以通过 API 但删不掉容器——如果团队需要删除能力,改为 1 并接受相应风险。EXEC=0 是最关键的一条,它切断了「通过 Portainer 在容器内执行命令」这条最直接的横向路径。
随后在 Portainer 中新增环境时,把连接地址填写为 tcp://portainer-sock:2375,而不是 unix:///var/run/docker.sock。这一步做完,Portainer 容器本身不再需要挂载宿主 socket。
第五步:RBAC 与身份源
Portainer 的权限模型是三级:Team → Environment(环境)→ Resource control(资源控制)。落地顺序如下:
- Settings → Authentication:接入 OIDC(Keycloak、Authentik、Azure AD 均可),关闭内部账号自助注册。
- Teams:按职能建
dev、ops、audit三个组,audit只给 Read-Only。 - Environments → Access:每个环境单独指定 Team 权限,默认不勾选 Administrators 之外的任何组。
- Resource control:对生产环境的 Network、Volume 加 owner 限制,防止误删。
需要说明的是:Portainer CE 没有内置 TOTP 双因素,2FA 属于 Business Edition 能力。CE 用户的等效方案是 OIDC 身份源侧开启 MFA,再加上前一步的客户端证书——两层叠加,强度不低于内置 2FA。
第六步:留痕与备份
CE 版没有审计日志模块,用 Docker events 兜底,把容器的创建、启停、exec 全部落到独立日志文件,再交给日志平台收走:
docker events --filter type=container --filter type=image \
--format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.ID}} {{.Actor.Attributes.name}}' \
>> /var/log/portainer-events.log &
生产环境建议用 systemd 单元托管这条命令而不是 &,避免终端断开后丢失。备份方面,Portainer 的全部状态都在 portainer_data 卷里:
docker run --rm -v portainer_data:/data -v /backup:/backup alpine \
tar czf /backup/portainer-$(date +%F).tar.gz -C /data .
配置验证
# 1) 确认端口只绑在 127.0.0.1
docker port portainer
# 2) 本机访问应 200
curl -sk -o /dev/null -w 'local=%{http_code}\n' https://127.0.0.1:9443/
# 3) 从外部机器执行,应连接失败而非 200
curl -s -o /dev/null -w 'ext=%{http_code}\n' --max-time 5 https://<公网IP>:9443/
# 4) 确认 9000 明文端口已关闭
curl -s -o /dev/null -w 'plain=%{http_code}\n' --max-time 5 http://127.0.0.1:9000/
# 5) 确认 socket 代理拦截了未授权 API
docker run --rm --network portainer-net curlimages/curl:8.8.0 \
-s -o /dev/null -w 'secrets=%{http_code}\n' http://portainer-sock:2375/secrets
docker run --rm --network portainer-net curlimages/curl:8.8.0 \
-s -o /dev/null -w 'version=%{http_code}\n' http://portainer-sock:2375/version
预期结果:第 1 步输出 127.0.0.1:9443;第 3 步为 000;第 4 步为 000;第 5 步 /secrets 返回 403,/version 返回 200(因为放行了 VERSION=1)。若 /secrets 也返回 200,说明 SECRETS=0 没生效,检查代理容器是否重启。
常见问题
Q1:只绑 127.0.0.1 之后,异地同事无法访问怎么办?
首选组网方案:WireGuard 或 Tailscale 打通后再访问虚拟内网地址,端口不出公网,也不需要维护客户端证书。次选 nginx + 客户端证书,按第三步配置即可,证书通过内部系统下发。把 9443 直接开到公网再加一条 WAF 规则,属于把风险转移到 WAF 上,不建议作为长期方案。
Q2:管理员口令忘了,或者初始创建页面被别人抢先?
Portainer 自带重置工具,不需要删卷:
docker exec -it portainer /helper-reset-password
执行后按提示输入新口令并重启容器即可,环境、Stack、用户配置全部保留。如果连容器都进不去,只能停容器后挂载 portainer_data 卷,删除 /data/portainer.db 重建——代价是所有配置丢失,因此口令务必存进密码管理器。
Q3:加了 socket 代理后,部署 Stack 报 403 或权限错误?
按报错路径逐项放开,不要一次性全开。常见对应关系:创建容器需要 POST=1;拉取镜像需要 DISTRIBUTION=1;构建镜像需要 BUILD=1;查看节点信息需要 INFO=1。定位方法是看代理容器日志里被拒绝的 HTTP 路径:
docker logs --tail 50 portainer-sock
日志会打印 403 Forbidden 及对应 endpoint,把它映射到环境变量名即可。不要为了省事把 EXEC 和 SECRETS 一起打开,那等于取消了这层防护的全部价值。
Q4:容器里需要 --privileged,是不是就等于放弃加固?
不是。特权容器确实削弱了隔离,但仍可叠加三道限制:宿主侧开启 userns-remap,让容器内 root 映射到非 root 用户;给容器加 --security-opt no-new-privileges 阻止 setuid 提权;把宿主的敏感挂载点(/etc、/root、/var/run/docker.sock)在 daemon 层用 --userns-remap 之外的挂载白名单约束。真正的原则是:特权容器只跑必须特权的负载,业务容器一律非特权。
总结
Portainer 加固的优先级排序很清楚:先让它不出公网,再让管理员账号不可能被抢注,最后才谈 RBAC。前两条各自只需要一条端口映射参数和一个口令文件,收益却覆盖了绝大多数真实事故;socket 代理白名单解决的是「被拿下之后」的损失范围,属于纵深防御里性价比最高的一层。
落地后请把验证脚本里的五条检查固化成巡检项。特别提醒:docker port portainer 的输出是最直观的健康指标,只要出现 0.0.0.0:9443,说明收口已经被某次手工重启覆盖掉了。