mitigram/portainer-ce

易于配置的Portainer (CE版)

本项目创建了https://hub.docker.com/r/mitigram/portainer-ce Docker镜像，基于https://portainer.io/，可通过环境变量（均以PORTAINER_开头）、JSON文件和命令行选项组合配置。此外，该项目提供团队和用户初始化功能，便于在使用LDAP自动创建用户并关联现有团队时，实现LDAP组与Portainer团队的匹配。其目标是自动跟进Portainer的https://github.com/portainer/portainer/releases节奏，通过镜像https://hub.docker.com/r/mitigram/portainer-ce/tags体现。

假设镜像为mitigram/portainer-ce，以下命令将：

• 在8080端口启动Portainer
• 为管理员生成密码
• 禁用遥测
• 创建名为devs和admins的两个团队

shell
docker run -it --rm \
  -e PORTAINER_ENABLETELEMETRY=false \
  docker.xuanyuan.run/mitigram/portainer-ce \
  --port 8080 \
  --teams devs,admins

重要提示：本项目使用git https://git-scm.com/book/en/v2/Git-Tools-Submodules！克隆时需添加--recurse命令行选项，若未添加需后续补充。

使用镜像

基本原理

本项目在常规https://portainer.io/ https://hub.docker.com/r/portainer/portainer-ce基础上叠加了初始化阶段，以简化配置并便于与复杂项目集成。该实现可自动配置Portainer的所有设置，还能创建用户和/或团队。与初始化阶段及底层Portainer交互有三种方式：

• 若遵循12-factor原则，可通过设置环境变量（均以PORTAINER_开头）修改Portainer的初始化行为和配置。为增强安全性，敏感信息可通过以_FILE结尾的变量从Docker或Kubernetes密钥中读取。
• 可通过settings JSON文件提供Portainer设置，必要时可结合编排平台的密钥支持。
• 入口脚本支持部分Portainer命令行选项的替代，并能原样传递其他所有选项。

本项目遵循密钥安全最佳实践，但在debug模式下，密码可能会泄露到日志中，这是为了便于排查配置错误。用户创建功能支持生成密码，这些密码仅作临时使用，应尽快修改。

环境变量

本实现的脚本行为可通过以PORTAINER_开头的环境变量控制。

影响通用行为的变量

通常，这些变量名称中PORTAINER_后的后缀与对应的命令行选项名称（大写形式）一致，具体如下：

Portainer启动时若管理员用户不存在，可自动创建。为此，可指定以下两个变量之一。当两者及对应命令行选项均为空（默认情况）时，入口脚本portainer.sh将生成随机密码并在notice级别日志中打印。

• PORTAINER_ADMIN_PASSWORD：管理员用户的明文密码。出于安全考虑，应避免使用此变量或对应的--password选项。
• PORTAINER_ADMIN_PASSWORD_FILE：包含管理员密码的文件路径。由于文件系统可保护该文件，这是更安全的密码指定方式，符合Docker或Kubernetes将密钥传入容器的机制。

部分变量会传递给settings.sh，后者通过API初始化Portainer实例：

• PORTAINER_SETTINGS：指向包含API的/settings端点可识别的所有已知设置的JSON配置文件（见下文）。默认值为portainer.sh所在目录下的settings.json文件。
• PORTAINER_TEAMS：用于在Portainer实例中创建多个团队，默认不创建。该变量有两种格式：
  • 若以@开头，剩余部分为包含团队名称的文件路径。文件中空白行和以#开头的注释行将被忽略，其他行应为要创建的团队名称。示例见examples/teams.lst。
  • 否则，值为逗号分隔的团队名称列表。
• PORTAINER_USERS：包含用户规范的文件路径，示例见examples/users.db，默认不创建用户。文件中空白行和以#开头的注释行将被忽略，其他行包含以冒号:分隔的字段，顺序如下：
  1. 要创建的用户名。
  2. 用户密码。若密码为小写字母x，将生成随机密码并在info级别日志中显示。
  3. 用户角色（整数）：1为管理员，2为普通用户，为空时默认2。
  4. 逗号分隔的团队规范。团队规范格式为团队名称/角色，角色为整数：1为领导者，2为成员。若省略/角色，用户默认为团队成员（角色2）。

两个影响与portainer主二进制交互的变量：

• PORTAINER_PORT_NUMBER：实例监听UI和API调用的端口，默认9000。此选项替代常规portainer二进制的--bind选项。为避免在k8s中命名冲突，特意不命名为PORTAINER_PORT。
• PORTAINER_BIN：portainer二进制的路径（或在PATH中查找的名称），默认portainer。

Portainer JSON设置相关变量

另一组以PORTAINER_开头的变量对应JSON settings对象中的各个键。设置对象是分层结构，可能包含数组，环境变量有对应的表示方式。要匹配（替换）JSON数组中的单个设置，变量名称应由层级中的键名（转为大写，.替换为_）构成。若JSON键为数组，可在名称中插入索引（如0、1等，最大索引可通过PORTAINER_MAX环境变量修改，默认为10）。若变量名以_FILE结尾，其值应为包含要放入JSON结构内容的文件路径，可用于传递密钥。

以下基于示例设置结构说明命名规则：

json
{
  "AllowBindMountsForRegularUsers": false,
  "AllowContainerCapabilitiesForRegularUsers": true,
  "AllowDeviceMappingForRegularUsers": true,
  "AllowHostNamespaceForRegularUsers": true,
  "AllowPrivilegedModeForRegularUsers": false,
  "AllowStackManagementForRegularUsers": true,
  "AllowVolumeBrowserForRegularUsers": true,
  "AuthenticationMethod": 1,
  "BlackListedLabels": [
    {
      "name": "",
      "value": ""
    }
  ],
  "EdgeAgentCheckinInterval": 5,
  "EnableEdgeComputeFeatures": true,
  "EnableHostManagementFeatures": true,
  "EnableTelemetry": false,
  "LDAPSettings": {
    "AnonymousMode": true,
    "AutoCreateUsers": true,
    "GroupSearchSettings": [
      {
        "GroupAttribute": "",
        "GroupBaseDN": "",
        "GroupFilter": ""
      }
    ],
    "Password": "",
    "ReaderDN": "",
    "SearchSettings": [
      {
        "BaseDN": "",
        "Filter": "",
        "UserNameAttribute": ""
      }
    ],
    "StartTLS": true,
    "TLSConfig": {
      "TLS": true,
      "TLSCACert": "",
      "TLSCert": "",
      "TLSKey": "",
      "TLSSkipVerify": false
    },
    "URL": ""
  },
  "LogoURL": "",
  "OAuthSettings": {
    "AccessTokenURI": "",
    "AuthorizationURI": "",
    "ClientID": "",
    "ClientSecret": "",
    "DefaultTeamID": 0,
    "OAuthAutoCreateUsers": true,
    "RedirectURI": "",
    "ResourceURI": "",
    "Scopes": "",
    "UserIdentifier": ""
  },
  "SnapshotInterval": "5m",
  "TemplatesURL": "https://raw.githubusercontent.com/portainer/templates/master/templates.json",
  "UserSessionTimeout": "5m",
  "displayDonationHeader": true,
  "displayExternalContributors": true
}

要禁用主机管理功能，可设置PORTAINER_ENABLEHOSTMANAGEMENT_FEATURES=false；要指定黑名单标签名称，可设置PORTAINER_BLACKLISTEDLABELS0_NAME（注意BLACKLISTEDLABELS后紧跟0）；要从/var/run/secrets/LDAP_password文件读取LDAP只读用户密码，可设置PORTAINER_LDAPSETTINGS_PASSWORD_FILE=/var/run/secrets/LDAP_password。

命令行选项

本实现的主脚本portainer.sh支持多个命令行选项。部分选项替代直接传递给portainer的选项，多数影响初始化阶段行为。若要向portainer传递特定选项，可在命令行中使用--标记，其后所有内容将原样传递给portainer。运行portainer.sh --help（或-h）可获取帮助。

命令行选项（若存在且相关）优先级高于环境变量。

仓库根目录下的所有其他脚本均可通过--help（或-h）获取帮助。

构建镜像

构建最新版本

从仓库主目录执行以下命令构建镜像：

shell
docker build -t mitigram/portainer-ce .

构建时配置

镜像支持两个构建参数以选择特定版本的依赖：

• PORTAINER_VERSION：Portainer版本，应与官方https://hub.docker.com/r/portainer/portainer-ce的https://hub.docker.com/r/portainer/portainer-ce/tags匹配，默认latest。
• GRON_VERSION：https://github.com/tomnomnom/gron版本，默认0.6.1，通常无需修改。

版本控制约定

由于本镜像基于官方Portainer https://hub.docker.com/r/portainer/portainer-ce并仅提供简化初始化功能，建议遵循Portainer的版本控制。例如，构建2.1.1版本：

shell
docker build -t mitigram/portainer-ce:2.1.1 --build-arg PORTAINER_VERSION=2.1.1 .

从命令行调用API

本项目包含脚本，用于从命令行调用Portainer REST API。除描述Portainer实例连接的选项外，该脚本至少需2个参数：第一个为HTTP方法（如GET、POST、PUT），第二个为API路径（不含前导/api，如获取当前设置的/settings）。其余参数将作为选项传递给curl（如通过--data传递POST数据）。

运行api.sh --help可获取在线帮助。

若管理员密码为s3cr3t，以下示例打印本地9000端口Portainer实例的当前设置：

shell
./api.sh --password s3cr3t GET /settings

以下示例创建名为bob的普通用户：

shell
./api.sh --password s3cr3t \
    POST /users --data '{"username": "bob", "password": "cg9Wgky3", "role": 2}'

实现说明

Portainer初始化

启动和初始化流程如下：

1. 启动portainer.sh，识别选项和/或环境变量，定位要使用的settings.json文件版本，根据键名和层级查找匹配的环境变量，将新的设置JSON结构保存到临时位置。
2. portainer.sh在后台启动settings.sh，传递必要参数（包括临时设置JSON文件路径）。
3. portainer.sh执行Portainer，选择与Portainer相关的选项，以及portainer.sh启动时--后的所有命令行选项。
4. Portainer启动，在portainer.sh指定的端口提供UI和API服务。
5. 后台的settings.sh等待Portainer API可用，通过Portainer API端点执行：
   1. 设置portainer.sh准备的临时JSON设置。
   2. 创建指定的团队（若有）。
   3. 创建指定的用户（若有），并关联到相关团队。
6. 完成后，settings.sh清理portainer.sh创建的临时文件，配置结束。

Docker镜像

本项目使用多阶段构建：

• 第一阶段：基于官方https://hub.docker.com/r/portainer/portainer-ce镜像，引入构建Portainer UI所需的二进制依赖和资源。通过构建参数PORTAINER_VERSION控制Portainer版本，默认latest。
• 第二阶段：使用https://github.com/efrecon/bininstall项目安装https://github.com/tomnomnom/gron的https://github.com/portainer/portainer/releases版tar包（含二进制文件）。https://github.com/efrecon/bininstall是本项目的子模块。通过构建参数GRON_VERSION控制gron版本，默认0.6.1（编写时的最新版本）。
• 最后阶段：基于增强的Alpine https://github.com/YanziNetworks/alpine（支持运行https://github.com/sgerrand/alpine-pkg-glibc二进制，因gron依赖glibc），从之前阶段提取二进制文件和文件，添加初始化所需的shell脚本、库和文件。

最终阶段重建与原始https://hub.docker.com/r/portainer/portainer-ce镜像相似的环境：所有必要二进制文件置于文件系统根目录，工作目录设为根目录。这是因为Portainer需通过资产路径查找UI的HTML、js、CSS文件及kubectl、docker等二进制依赖。

与DockerHub和GitHub的交互

本镜像配置为在以下情况自动重建：

• Docker Hub上有新的Portainer版本发布时。
• 控制本镜像初始化的git仓库内容变更时。

镜像构建通过GitHub actions实现，这些action会为兼容性转发hooks，可用于DockerHub基础设施构建，如https://docs.docker.com/docker-hub/builds/advanced/自动构建手册所述。