Portainer开发工具包 (portainer/dev-toolkit) 技术文档

镜像概述和主要用途

Portainer开发工具包是一个为Portainer打造的容器化开发环境，将完整的Portainer开发栈整合到容器中。该工具包支持Linux和macOS系统，提供了一致、可复现的开发环境，简化Portainer项目的开发流程。

注意：包含VSCode IDE的旧版本工具包，请参考2024.08分支。

核心功能和特性

基础环境

• 基于Ubuntu 24.04 LTS构建，提供稳定的底层系统
• 预装开发必备工具：
  • Golang（Go语言开发环境）
  • Docker CLI（容器管理工具）
  • NodeJS（JavaScript运行时）
  • Yarn（JavaScript包管理器）
• 支持多架构镜像：amd64、arm64

构建机制

• 自动构建：通过DockerHub自动构建，基于Git仓库标签生成对应版本镜像（如标签2024.10对应镜像portainer/dev-toolkit:2024.10）
• 手动构建：支持本地构建自定义镜像，满足个性化需求

使用场景和适用范围

适用人群

• Portainer核心开发人员
• 需要参与Portainer项目贡献的开发者
• 希望快速搭建Portainer开发环境的用户

典型场景

• 在不同设备间保持一致的开发环境配置
• 快速上手Portainer源码开发，无需手动配置依赖
• 自定义开发工具链（如更换shell、添加额外工具）
• 多架构开发测试（amd64/arm64平台适配）

环境要求

• 已安装Docker引擎（版本需支持多架构构建，推荐最新稳定版）
• 网络环境可访问DockerHub（用于拉取基础镜像和工具包镜像）

使用方法

1. 自动构建镜像使用

Portainer通过DockerHub分发portainer/dev-toolkit镜像，标签与Git仓库标签对应。可通过以下步骤使用：

1. 安装IDE的DevContainer扩展（如VSCode的Remote - Containers）
2. 配置工作区使用项目中的devcontainer.json文件
3. 通过IDE的"在容器中打开文件夹"选项打开项目，自动拉取并启动工具包容器

2. 手动构建镜像

如需自定义基础镜像，可按以下步骤手动构建：

警告
当前Linux ARM64和AMD64的多架构镜像必须在Linux AMD64主机上构建。详见相关Issue。

构建并推送基础镜像

1. 确保已登录DockerHub
2. 执行构建命令：

   bash
   make base
   

3. 自定义开发环境

工具包支持通过Dockerfile扩展自定义环境（如更换shell、添加工具），示例流程如下：

构建自定义镜像

以zsh shell为例（示例位于examples/zsh/）：

bash
docker buildx build -t my-devkit -f examples/zsh/Dockerfile .

配置DevContainer使用自定义镜像

修改项目中的devcontainer.json：

json
{
  "name": "portainer-dev-toolkit",
  "image": "my-devkit",  // 替换为自定义镜像名称
  // 其他配置保持不变
}

4. 用户工具包

user-toolkits/文件夹包含社区贡献的自定义工具包示例，可直接使用他人分享的配置或提交自己的配置。使用方法与自定义镜像一致，只需指定对应Dockerfile路径构建即可。

在工具包内构建Portainer

启动开发容器后，可通过以下步骤构建和运行Portainer：

1. 安装依赖并构建完整项目

bash
make build-all  # 安装依赖并构建客户端+服务端

2. 运行后端服务

bash
./dist/portainer --data /tmp/portainer --log-level=DEBUG

3. 客户端开发模式（如需修改前端）

bash
make dev-client  # 启动客户端热重载开发模式

参考链接

• VSCode DevContainer文档
• Development Containers规范
• 创建devcontainer.json文件
• DevContainer CLI预构建
• devcontainer.json参考