容器系统

相关源文件

• go.mod
• go.sum
• pkg/container/container_types.go
• pkg/container/docker_run.go
• pkg/container/host_environment.go
• pkg/runner/container_mock_test.go
• pkg/runner/testdata/mysql-service-container-with-health-check/push.yml

act 项目中的容器系统提供了一个健壮的抽象层，用于创建、管理和与容器交互。该系统主要负责在容器化环境中执行 GitHub Actions 工作流程，处理容器生命周期操作、文件传输、命令执行和环境设置。

本页面重点介绍核心容器管理组件。有关 Docker 集成详情，请参阅 Docker 集成；有关不使用 Docker 运行操作的信息，请参阅 主机环境。

核心组件

容器系统围绕几个关键接口和实现构建，这些接口和实现提供了一个超越特定容器技术的抽象层。

来源：pkg/container/container_types.go10-85 pkg/container/docker_run.go206-213 pkg/container/host_environment.go28-36

容器接口

容器系统以 Container 接口为中心，该接口定义了可在容器上执行的标准操作。

每个方法都返回一个 common.Executor，这是一个执行操作的函数，允许操作的组合和延迟执行。

来源：pkg/container/container_types.go43-58

容器实现

act 系统主要通过两种方式实现 Container 接口：

1. containerReference - 基于 Docker 的实现，用于管理 Docker 容器
2. HostEnvironment - 本地环境实现，直接在主机上运行命令

这种双重实现方法提供了灵活性，允许用户使用或不使用 Docker 运行 GitHub Actions。

Docker 容器实现

containerReference 结构体为 Docker 容器实现了 Container 接口。

它通过 Docker API 客户端管理 Docker 容器，并提供 GitHub Actions 执行所需的所有功能。

来源：pkg/container/docker_run.go206-213

主机环境实现

HostEnvironment 结构体提供了 Container 接口的一个无需 Docker 的实现。

此实现直接在主机系统上执行命令，而不是在容器中执行，因此适用于没有 Docker 的环境。

来源：pkg/container/host_environment.go28-36

容器生命周期

容器系统为 GitHub Actions 执行中使用的容器提供完整的生命周期管理。

来源：pkg/container/docker_run.go42-47 pkg/container/docker_run.go67-170 pkg/container/host_environment.go38-470

容器创建与初始化

容器系统通过 NewContainerInput 结构体支持灵活的容器创建，并提供多种配置选项。

来源：pkg/container/container_types.go11-33

容器创建遵循以下步骤：

1. 连接 - 连接到 Docker 守护进程
2. 查找 - 检查容器是否已存在
3. 创建 - 使用指定配置创建容器
4. 启动 - 启动容器
5. 设置 - 执行额外设置（用户权限等）

来源：pkg/container/docker_run.go67-100

命令执行

容器系统提供了一个健壮的机制，用于在容器内执行命令。

来源：pkg/container/docker_run.go542-613

执行过程：

1. Exec() 方法在容器中创建一个执行实例。
2. 它附加到执行实例以捕获输出。
3. 它等待命令完成。
4. 它检查执行结果以获取退出码。
5. 如果退出码非零，则返回错误。

文件操作

容器系统提供全面的文件操作，用于在主机和容器之间传输文件。

文件复制操作

文件操作有多种方法：

1. Copy() - 将单个文件复制到容器。
2. CopyDir() - 将目录复制到容器。
3. CopyTarStream() - 将 tar 流复制到容器。
4. GetContainerArchive() - 从容器中检索文件。

来源：pkg/container/docker_run.go116-144 pkg/container/docker_run.go730-798 pkg/container/docker_run.go801-832

容器健康管理

该系统提供容器的健康检查功能，这对于工作流程在使用服务容器之前需要确保其健康状态的服务容器尤其有用。

来源：pkg/container/docker_run.go172-194 pkg/container/container_types.go78-84

健康状态包括：

• HealthStarting - 容器健康检查正在启动
• HealthHealthy - 容器健康
• HealthUnHealthy - 容器不健康

这在 GitHub Actions 服务容器中得到利用，以确保服务在运行工作流程步骤之前就绪。

Docker 和平台支持

容器系统通过 NewContainerInput 结构体中的 Platform 字段支持不同的 Docker 平台。这允许指定操作系统和架构的组合（例如，linux/amd64，linux/arm64）。

该系统还会检测 Docker API 版本，以确定是否支持平台规范。

来源：pkg/container/docker_run.go49-65 pkg/container/docker_run.go446-456

运行器架构信息

容器系统还提供与 GitHub Actions 上下文兼容的运行器架构信息。

这将 Docker 架构名称映射到 GitHub Actions 运行器架构名称，确保与检查运行器架构的 GitHub Actions 兼容。

来源：pkg/container/docker_run.go259-276

总结

容器系统在 act 项目中提供了一个关键的抽象层，使得 GitHub Actions 工作流程能够在高度模仿 GitHub 自身运行器环境的受控环境中执行。通过同时支持基于 Docker 和基于主机的执行环境，它为不同的用户需求和环境提供了灵活性。

主要功能包括

• 完整的容器生命周期管理
• 健壮的命令执行
• 全面的文件操作
• 服务容器的健康管理
• 平台和架构支持

这个抽象层使得 act 代码库的其余部分能够以一致的方式与容器交互，无论它们是 Docker 容器还是本地环境。