操作缓存

相关源文件

• pkg/runner/action_cache.go
• pkg/runner/action_cache_offline_mode.go
• pkg/runner/action_cache_test.go
• pkg/runner/local_repository_cache.go
• pkg/runner/testdata/local-remote-action-overrides/push.yml

目的与范围

act 中的操作缓存系统负责高效地从远程仓库获取和管理 GitHub Actions。它提供了缓存机制，通过避免在工作流执行期间重复下载相同的操作来提高性能。本文档详细介绍了操作缓存系统的架构和实现、它如何与 Git 仓库交互，以及代码库中可用的各种缓存实现。

有关工件和通用缓存管理的信息，请参阅工件和缓存管理。

来源: pkg/runner/action_cache.go25-28

操作缓存架构

操作缓存系统围绕一个中心接口构建，该接口具有多种实现，提供不同的缓存策略和功能。

接口定义

ActionCache 接口定义了两个主要操作：

• Fetch - 从其源（通常是 Git 仓库）检索一个操作并返回其 SHA
• GetTarArchive - 创建操作文件的 tar 归档，用于容器构建

来源: pkg/runner/action_cache.go25-28

组件架构

来源

• pkg/runner/action_cache.go30-32
• pkg/runner/action_cache_offline_mode.go13-15
• pkg/runner/local_repository_cache.go19-23

操作缓存实现

代码库提供了 ActionCache 接口的三种主要实现，每种实现服务于不同的用例。

GoGitActionCache

这是主要的实现，它使用 go-git 库来克隆和管理 Git 仓库。它以裸 Git 仓库格式存储操作，以便高效访问。

主要特性

• 在指定路径创建裸 Git 仓库
• 支持私有仓库的身份验证
• 处理各种引用类型（分支、标签、提交）
• 从仓库内容生成 tar 归档

来源: pkg/runner/action_cache.go30-90

GoGitActionCacheOfflineMode

此实现扩展了 GoGitActionCache 以支持离线模式。它首先尝试使用父缓存，但在网络访问受限时可以回退到本地缓存的引用。

主要特性

• 封装一个父 GoGitActionCache 实例
• 在特殊命名空间（refs/action-cache-offline/）中存储引用
• 离线时保持与缓存操作的兼容性

来源: pkg/runner/action_cache_offline_mode.go13-47

LocalRepositoryCache

此实现支持使用本地文件系统路径而不是远程仓库。这对于开发和测试场景特别有用。

主要特性

• 将仓库 URL 和引用映射到本地文件系统路径
• 对于未映射的仓库，回退到父缓存实现
• 支持从本地文件系统创建目录和文件 tar 归档

来源: pkg/runner/local_repository_cache.go19-100

缓存工作流

操作缓存系统在获取操作并将其提供给工作流执行引擎时遵循特定的工作流。

操作获取过程

来源: pkg/runner/action_cache.go34-90

Tar 归档创建

当一个操作需要被使用时（通常用于 Docker 构建），缓存会创建该操作内容的 tar 归档

来源: pkg/runner/action_cache.go130-173

特殊文件处理

操作缓存系统包含对操作内符号链接和目录结构的特殊处理。

符号链接解析

actionCacheCopyFileOrDir 函数通过以下方式处理仓库内容中的符号链接：

1. 检测文件是否为符号链接
2. 解析符号链接目标
3. 处理目标文件或目录

这确保了具有复杂文件关系的操作内容得到正确保留。

来源: pkg/runner/action_cache.go175-228

与运行器系统的集成

操作缓存是工作流执行过程中的关键组件，特别是对于操作步骤。

当工作流运行器需要执行一个操作时

1. 操作步骤执行器从缓存请求该操作
2. 缓存获取和/或提供缓存的操作内容
3. 该内容用于构建容器或执行复合操作

来源

• pkg/runner/action_cache.go25-28
• 系统组件架构图（在维基概述中）

操作缓存选择与配置

运行器系统根据运行时设置选择并配置适当的缓存实现

缓存类型	用例	配置
GoGitActionCache	标准操作	默认实现
GoGitActionCacheOfflineMode	有限连接	通过离线模式设置启用
LocalRepositoryCache	本地开发	通过本地仓库映射配置

缓存实现的选定会影响性能、网络使用以及离线工作的能力。

来源

• pkg/runner/action_cache.go30-32
• pkg/runner/action_cache_offline_mode.go13-15
• pkg/runner/local_repository_cache.go19-23

结论

操作缓存系统是 act 代码库中一个关键的性能优化组件。通过高效管理来自 Git 仓库的操作内容，它实现了快速可靠的工作流执行，同时最大限度地减少了网络使用并支持各种操作模式。