Homegear构建环境Docker镜像文档

一、镜像概述与主要用途

本镜像为Homegear提供构建环境，用于基于GitHub最新版本源码构建Debian软件包，并支持通过SSH协议将构建结果自动上传至指定服务器。主要用途包括：

• 生成Homegear当前GitHub版本的Debian安装包；
• 自动化构建流程中集成包上传功能；
• 跨架构构建支持（如ARM架构需额外依赖）。

注意：运行ARM架构构建镜像时，需在宿主机预先安装qemu和qemu-user-static包，以支持架构模拟。

二、核心功能与特性

1. 源码构建能力：基于Homegear GitHub仓库最新代码自动构建Debian包，确保使用最新功能或修复。
2. 多线程构建支持：通过环境变量配置编译线程数，优化构建效率。
3. SSH自动上传：支持将构建后的Debian包通过SSH协议上传至远程服务器，无需手动干预。
4. 构建类型区分：可指定构建类型（stable/testing/nightly），对应不同发布渠道的包管理路径。
5. 服务器认证配置：支持通过私钥证书和已知主机公钥配置SSH登录，避免交互式确认，适用于自动化场景。

三、使用场景与适用范围

• Homegear开发者：快速构建自定义版本Debian包，用于本地测试或分发。
• 自动化CI/CD流程：集成到持续集成/部署 pipeline，实现代码提交后自动构建、上传包。
• 测试环境包管理：为测试环境定期生成nightly版本包，验证最新代码稳定性。
• 多架构包构建：在x86主机上通过qemu模拟构建ARM架构Debian包，简化跨平台部署。

四、使用方法与配置说明

4.1 环境变量详解

以下环境变量用于配置构建行为及上传参数，均为可选（未指定时可能仅执行构建，不上传）：

4.2 Docker部署示例

4.2.1 基础构建（仅生成Debian包，不上传）

bash
docker run -d \
  -e HOMEGEARBUILD_THREADS=4 \  # 使用4线程构建
  --name homegear-build \
  homegear/build-env

4.2.2 构建并上传至服务器（含认证配置）

假设需上传testing类型包至服务器example.com，端口22，用户builduser，APT仓库路径/var/apt/repos/testing，私钥证书已base64编码并替换换行符：

bash
docker run -d \
  -e HOMEGEARBUILD_THREADS=4 \
  -e HOMEGEARBUILD_TYPE=testing \
  -e HOMEGEARBUILD_SERVERNAME=example.com \
  -e HOMEGEARBUILD_SERVERPORT=22 \
  -e HOMEGEARBUILD_SERVERUSER=builduser \
  -e HOMEGEARBUILD_REPOSITORYSERVERPATH=/var/apt/repos/testing \
  -e HOMEGEARBUILD_SERVERCERT="LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQp...（base64编码的私钥，换行替换为\n）" \
  -e HOMEGEARBUILD_SERVER_KNOWNHOST_ENTRY="example.com ssh-rsa AAAAB3NzaC1yc2EAAA...（服务器公钥，换行替换为\n）" \
  --name homegear-build-upload \
  homegear/build-env

4.2.3 Docker Compose配置示例

yaml
version: '3'
services:
  homegear-build:
    image: homegear/build-env
    environment:
      - HOMEGEARBUILD_THREADS=4
      - HOMEGEARBUILD_TYPE=nightly
      - HOMEGEARBUILD_SERVERNAME=build-server.internal
      - HOMEGEARBUILD_SERVERPORT=2222
      - HOMEGEARBUILD_SERVERUSER=ci-user
      - HOMEGEARBUILD_NIGHTLYSERVERPATH=/data/nightly-builds
      - HOMEGEARBUILD_SERVERCERT=${SSH_PRIVATE_KEY_BASE64}  # 从环境变量传入base64证书
      - HOMEGEARBUILD_SERVER_KNOWNHOST_ENTRY=${SERVER_KNOWN_HOST}  # 从环境变量传入公钥
    restart: on-failure

4.3 注意事项

• ARM架构构建：宿主机需预先安装qemu和qemu-user-static，否则可能导致构建失败。
• 证书格式：HOMEGEARBUILD_SERVERCERT和HOMEGEARBUILD_SERVER_KNOWNHOST_ENTRY中的换行符必须替换为\n，避免命令解析错误。
• 上传路径区分：HOMEGEARBUILD_REPOSITORYSERVERPATH用于stable/testing类型（APT仓库），HOMEGEARBUILD_NIGHTLYSERVERPATH用于nightly类型（独立路径），需根据HOMEGEARBUILD_TYPE正确配置对应路径。