Che插件Broker镜像文档

1. 镜像概述与主要用途

本仓库包含多个Che插件Broker的实现，主要用于Eclipse Che环境中插件的生命周期管理。这些Broker负责插件的下载、解析、配置评估、依赖处理及部署协调，确保插件在Che工作空间中正确集成（如部署至sidecar容器或本地目录），是Che插件生态的核心组件。

2. 核心功能与特性

2.1 che-plugin-broker

• 功能：处理tar.gz格式的插件归档文件，完成以下操作：
  • 解析插件归档中che-plugin.yaml的配置，结合工作目录（或通过参数指定路径）下config.json（包含插件/编辑器元数据meta.yaml信息），评估Che工作空间sidecar配置。
  • 复制插件归档内dependencies.yaml中指定的依赖文件/目录至目标位置。

2.2 theia-plugin-broker

• 功能：处理.theia格式的插件归档文件，支持Theia插件在Che工作空间中的本地或远程部署，具体流程：
  • 将.theia归档解压至临时目录。
  • 解析解压后package.json：
    • 若包含{"engines.cheRuntimeContainer"}字段，则以此值作为远程插件sidecar的容器镜像；若缺失或为空，则判定为非远程插件。
  • 非远程插件：将.theia文件复制至/plugins/目录。
  • 远程插件：将解压后的.theia目录复制至/plugins/目录，并生成sidecar配置，包括：
    • 挂载projects卷和plugin卷。
    • 分配4000-6000随机端口，创建名为port<port>的端点。
    • 添加工作空间级环境变量：THEIA_PLUGIN_REMOTE_ENDPOINT_<plugin_publisher_and_name>（值为ws://port<port>:<port>，其中<plugin_publisher_and_name>取自package.json）。
    • 添加sidecar级环境变量：THEIA_PLUGIN_ENDPOINT_PORT（值为分配的端口）。
  • 评估并生成Che工作空间sidecar配置，使Theia插件以远程插件形式运行在sidecar中。

2.3 init-plugin-broker

• 功能：清理/plugins/目录内容，确保插件目录初始状态一致。
• 运行要求：必须在其他Broker之前启动，避免误删后续Broker添加的插件文件。

3. 使用场景与适用范围

• 适用环境：Eclipse Che云原生IDE工作空间。
• 核心场景：
  • Che工作空间插件的自动化部署与配置（如语言支持、工具集成插件）。
  • Theia插件的本地/远程模式管理（远程插件通过sidecar隔离运行）。
  • 插件目录初始化与清理，确保多Broker协同工作时的文件一致性。
• 用户群体：Che平台管理员、插件开发者、依赖Che工作空间进行开发的终端用户。

4. 使用方法与配置说明

4.1 配置参数

4.2 环境变量（theia-plugin-broker生成）

4.3 部署示例

4.3.1 启动顺序（Che工作空间内）

1. 初始化插件目录：先运行init-plugin-broker清理/plugins/。

   shell
   docker run --rm -v /path/to/plugins:/plugins eclipse/init-plugin-broker:latest
   

2. 部署Che插件：运行che-plugin-broker处理tar.gz插件包。

   shell
   docker run --rm -v /path/to/plugins:/plugins -v /path/to/config:/config \
     eclipse/che-plugin-broker:latest --config-path /config/config.json
   

3. 部署Theia插件：运行theia-plugin-broker处理.theia插件包。

   shell
   docker run --rm -v /path/to/plugins:/plugins -v /path/to/theia-archive:/archive \
     eclipse/theia-plugin-broker:latest /archive/plugin.theia
   

5. 开发指南

5.1 构建代码

构建所有二进制

shell
CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-w -s' -a -installsuffix cgo ./...

构建指定Broker二进制

• che-plugin-broker：

  shell
  CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-w -s' -a -installsuffix cgo -o che-plugin-broker brokers/che-plugin-broker/main.go
  

• theia-plugin-broker：

  shell
  CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-w -s' -a -installsuffix cgo -o theia-plugin-broker brokers/theia-plugin-broker/main.go
  

• init-plugin-broker：

  shell
  CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-w -s' -a -installsuffix cgo -o init-plugin-broker brokers/init/main.go
  

5.2 测试与代码检查

• 运行测试：

  shell
  go test -v -race ./...
  

• 代码 lint：

  shell
  golangci-lint run -v
  

• 本地CI检查（含构建/测试/lint）：

  shell
  docker build -f Dockerfile.CI .
  

5.3 依赖管理

• 使用Go Dep管理依赖。新增或更新依赖后，执行以下命令更新vendor目录和依赖锁文件，并提交变更：

  shell
  dep ensure
  

• 注意：dep ensure不会自动修改Gopkg.toml（依赖约束文件），需手动更新以反映依赖变更。

5.4 构建Docker镜像

• che-plugin-broker：

  shell
  docker build -t eclipse/che-plugin-broker:latest -f Dockerfile.cpb .
  

• theia-plugin-broker：

  shell
  docker build -t eclipse/theia-plugin-broker:latest -f Dockerfile.tpb .
  

• init-plugin-broker：

  shell
  docker build -t eclipse/init-plugin-broker:latest -f Dockerfile.ipb .