架构概述

相关源文件

• README.md
• cmd/input.go
• cmd/root.go
• pkg/runner/run_context.go
• pkg/runner/runner.go
• pkg/runner/runner_test.go

本文档提供了 act 系统的核心架构技术概述。它描述了主要组件、它们的职责以及它们在工作流执行期间如何交互。有关 act 的用户导向介绍，请参阅Act 介绍。有关详细的实现指南，请参阅“核心组件”部分中的特定组件页面。

系统组件

Act 由几个关键组件组成，它们协同工作以实现 GitHub Actions 工作流的本地执行。下图展示了主要组件及其关系

来源：cmd/root.go47-66 pkg/runner/runner.go16-65 pkg/runner/run_context.go31-56

执行流程

下图展示了 Act 如何从最初的 CLI 命令到执行完成处理工作流

来源：cmd/root.go387-703 pkg/runner/runner.go107-221 pkg/runner/run_context.go655-664

关键组件

命令行界面

CLI 是 Act 的主要入口点。它负责

• 解析命令行参数
• 从 .actrc 文件加载配置
• 创建执行环境
• 启动工作流执行

CLI 使用 Cobra 进行命令行解析，并提供了大量选项用于配置工作流执行。

来源：cmd/root.go47-132 cmd/input.go9-114

运行器系统

Runner 是核心编排组件，负责

• 从工作流文件创建执行计划
• 管理作业的并行和顺序执行
• 协调容器和服务的生命周期
• 处理作业的矩阵策略扩展

来源：pkg/runner/runner.go16-255

运行上下文

RunContext 维护每个作业执行的状态和环境。它负责

• 管理容器配置和生命周期
• 处理环境变量、密钥和输入
• 为操作提供 GitHub 上下文
• 协调服务容器
• 管理作业的文件操作

来源：pkg/runner/run_context.go31-56 pkg/runner/run_context.go178-205 pkg/runner/run_context.go247-428

容器系统

容器系统提供了对 Docker 的抽象，以实现以下功能：

• 创建和管理作业及服务容器
• 处理容器网络
• 挂载卷并绑定工作区
• 在容器内执行命令
• 复制文件进出容器

Act 同时支持 Docker 容器和备用的主机环境来运行操作。

来源：pkg/runner/run_context.go127-176 pkg/runner/run_context.go246-428

步骤执行系统

步骤执行系统处理作业中单个步骤的执行。它支持不同类型的步骤：

• 运行步骤（在作业容器中执行的命令）
• 操作步骤（通过 Docker 或 JavaScript 执行的 GitHub Actions）
• 复合操作步骤（由多个步骤组成的操作）

来源：pkg/runner/runner_test.go231-327

数据流

下图展示了工作流文件、执行计划和运行时对象之间的关系

来源：pkg/runner/runner.go107-255 pkg/runner/run_context.go31-56 pkg/runner/run_context.go642-664

执行器模式

Act 广泛使用了执行器模式，它提供了一种可组合的方式来构建执行管道

这种模式使得复杂的工作流可以被建模为一系列可执行单元，这些单元可以组合、并行运行或有条件地执行。

来源：pkg/runner/runner.go107-221 pkg/runner/run_context.go430-435 pkg/runner/run_context.go553-619

总结

Act 的架构旨在通过以下方式实现 GitHub Actions 工作流的本地执行：

1. 解析工作流文件以创建执行计划
2. 创建模拟 GitHub Actions 环境的容器
3. 在这些容器中执行步骤
4. 处理步骤和作业之间的数据流
5. 管理制品和缓存持久性

模块化设计使 Act 能够支持复杂的 GitHub Actions 功能，例如矩阵作业、服务容器、复合操作等，所有这些都完全在本地开发机器上运行。