使用 Docker Compose 部署汉化版 Portainer 并通过 Caddy 反向代理（含 Basic Auth）

2025-10-25 portainer docker-compose caddy reverse-proxy basic-auth chinese-ui https

Portainer 是一款轻量级的 Docker 可视化管理平台。社区维护的 汉化版镜像（6053537/portainer-ce）为中文用户提供了更友好的操作界面。本文将指导你：

使用 docker-compose.yml 部署汉化版 Portainer；
接入已有的 caddy_bridge 网络；
通过 Caddy 实现：
- 自动 HTTPS（Let’s Encrypt 证书）
- 安全响应头（HSTS、XSS Protection 等）
- Basic Auth 基础认证，防止未授权访问

📌 前提条件：

已安装 Docker 与 Docker Compose
> → 参考：Linux 一键安装 Docker（支持国内镜像加速）

已部署 Caddy 并创建了 caddy_bridge 网络
> → 参考：使用 Docker Compose 部署 Caddy 并配置安全增强

域名（如 portainer.yourdomain.com）已解析到服务器公网 IP

1. 创建 Portainer 的 `docker-compose.yml`

在项目目录（如 ~/portainer/）中创建以下文件：

version: "3.8"

services:
  portainer:
    image: 6053537/portainer-ce:latest  # 社区汉化版（中文 UI）
    # image: hub-mirror.c.163.com/6053537/portainer-ce  # 国内加速镜像（如拉取慢可启用）
    container_name: portainer
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 接管本地 Docker 引擎
      - ./portainer_data:/data                     # 持久化用户与配置数据
    networks:
      - caddy_bridge

networks:
  caddy_bridge:
    external: true
    name: caddy_bridge

✅ 说明：

汉化镜像由社区维护，非官方，但广泛使用；

若在国内服务器拉取缓慢，可取消注释网易镜像源行；

/var/run/docker.sock 是 Portainer 管理容器的关键；

portainer_data 目录用于保存设置，避免重建容器后丢失数据。

启动服务：

cd ~/portainer
docker-compose up -d

2. 配置 Caddy：启用 HTTPS + 安全头 + Basic Auth

编辑你的 Caddyfile（通常位于 Caddy 项目目录），添加以下站点配置：

portainer.yourdomain.com {
    import common_config
    
    # === 1. WebSocket 隧道：必须代理到 8000 端口 ===
    @websocket {
        header Connection *Upgrade*
        header Upgrade websocket
    }
    handle @websocket {
        reverse_proxy portainer:8000 {
            flush_interval -1
            header_up Connection {http.request.header.Connection}
            header_up Upgrade {http.request.header.Upgrade}
        }
    }

    # === 2. 所有 API 和 Edge 路径 → 9000 端口，无认证 ===
    @api path /api/* /edge/*
    handle @api {
        reverse_proxy portainer:9000 {
            header_up X-Forwarded-Proto https
            header_up X-Forwarded-Host {host}
        }
    }
    
    # === 3. 其余所有路径（Web UI）→ 启用 BasicAuth + 代理到 9000 ===
    handle {
        basicauth {
            admin $2a$14$VpF6lO1.BSuQepgowmHsz.kl9ELHfhwVHJ4F0nQQMBTU.IFbr6HRy
        }
        reverse_proxy portainer:9000 {
            header_up X-Forwarded-Proto https
            header_up X-Forwarded-Host {host}
        }
    }
}

🔐 如何生成 bcrypt 密码？

Caddy 不支持明文密码，必须使用 bcrypt 哈希。推荐使用以下命令生成：

caddy hash-password -p "your_password"

输出示例：

# 我使用本地Windows环境生成的密码
D:\caddy>caddy hash-password -p 123456
$2a$14$VpF6lO1.BSuQepgowmHsz.kl9ELHfhwVHJ4F0nQQMBTU.IFbr6HRy

将 $2y$... 部分复制到 Caddyfile 中即可。

🛡️ 安全建议：

使用强密码（至少 12 位，含大小写、数字、符号）；

不要复用其他系统的密码；

可添加多行实现多用户认证。

3. 完整 Caddyfile 示例（含公共安全配置）

# =============== 公共安全配置片段 ===============
(common_config) {
    tls {
        protocols tls1.2 tls1.3
    }
    header {
        Permissions-Policy interest-cohort=()
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        X-XSS-Protection "1; mode=block"
        -Server
        -Via
        -Alt-Svc
    }
    log {
        output file /var/log/caddy/global.log {
            roll_size 50mb
            roll_keep 5
            roll_keep_for 720h  # 保留30天
        }
    }
}

# =============== Portainer 站点 ===============
portainer.yourdomain.com {
    import common_config

    # === 1. WebSocket 隧道：必须代理到 8000 端口 ===
    @websocket {
        header Connection *Upgrade*
        header Upgrade websocket
    }
    handle @websocket {
        reverse_proxy portainer:8000 {
            flush_interval -1
            header_up Connection {http.request.header.Connection}
            header_up Upgrade {http.request.header.Upgrade}
        }
    }

    # === 2. 所有 API 和 Edge 路径 → 9000 端口，无认证 ===
    @api path /api/* /edge/*
    handle @api {
        reverse_proxy portainer:9000 {
            header_up X-Forwarded-Proto https
            header_up X-Forwarded-Host {host}
        }
    }
    
    # === 3. 其余所有路径（Web UI）→ 启用 BasicAuth + 代理到 9000 ===
    handle {
        basicauth {
            admin $2y$05$your_generated_bcrypt_hash_here
        }
        reverse_proxy portainer:9000 {
            header_up X-Forwarded-Proto https
            header_up X-Forwarded-Host {host}
        }
    }
}

4. 重载 Caddy 配置

Caddy 支持热重载，无需重启容器：

# 进入 Caddy 项目目录
cd /path/to/caddy
docker-compose exec caddy caddy reload --config /etc/caddy/Caddyfile

或直接重启（更稳妥）：

docker-compose restart caddy

5. 访问与验证

浏览器访问 https://portainer.yourdomain.com
弹出登录框，输入你设置的用户名和密码
首次登录需设置管理员密码，之后即可管理 Docker

✅ 此时你已拥有：

中文界面 ✅

自动 HTTPS（绿色锁）✅

安全响应头 ✅

基础认证防护 ✅

📌 补充建议

备份：定期备份 portainer_data 目录；
更新：升级时执行 docker-compose pull && docker-compose up -d；
高安全场景：可结合 IP 白名单（Caddy 的 remote_ip 模块）或 OAuth；
国内加速：若拉取 6053537/portainer-ce 缓慢，可使用网易镜像源（需确认镜像存在）。

通过以上步骤，你已构建了一个安全、易用、中文友好的 Docker 可视化管理平台，兼顾开发便利性与生产环境安全性。