Apache Arrow 持续集成体系全解：Docker 构建、Archery 与 Crossbow 的协作架构与实战

数据工程数据分析大数据【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow12/arrow点击查看免费下载Apache Arrow 是一个跨语言的数据交换与内存处理工具箱其持续集成CI体系需要覆盖多种包管理器、编译器、依赖版本、操作系统与硬件架构的组合。本篇技术指南以仓库中 docs/source/developers/continuous_integration 系列文档为主线系统讲解 Arrow 的 CI 总体架构、基于 Docker 的可复现构建流程、开发者日常工具 Archery 的安装与使用以及用于打包与集成测试调度的 Crossbow 队列机制。读完本文你将掌握 Arrow CI 的目录结构、关键配置文件的作用、archery docker的完整命令用法以及如何用 Crossbow 手动触发一次打包/测试构建。一、Arrow CI 的总体架构从文件到两类构建模式Arrow 的持续集成相当复杂它必须覆盖不同的包管理器conda、pip、vcpkg 等、编译器GCC、Clang、MSVC、多种第三方库版本、操作系统Linux、macOS、Windows以及其他可能的差异来源。其核心组件与关键文件如下。1.1 CI 中心配置文件在仓库根目录下有三份文件直接定义了 CI 的行为docker-compose.yml仓库根目录定义了一组 Docker 服务可以通过环境变量或环境变量的默认值来配置。例如文件头部注释给出了用法示例$ ARCHarm64v8 docker-compose build ubuntu-cpp表明服务通过环境变量参数化。.env仓库根目录定义用于配置docker-compose.yml中各服务的默认值如ARCHamd64、UBUNTU20.04、DEBIAN12、PYTHON3.8、PANDASlatest、REPOapache/arrow-dev等。appveyor.yml仓库根目录定义在 Appveyor 上运行的工作流。1.2 CI 相关目录Arrow 项目中有多个与 CI 直接相关的重要目录.github/workflows/存放由 GitHub Actions 运行的工作流由诸如 PR 提交、PR 合并等事件触发。仓库中实际包含archery.yml、comment_bot.yml、dev.yml、dev_pr.yml、cpp.yml、python.yml、java.yml、r.yml、go.yml、js.yml、swift.yml等大量按语言区分的流程文件。dev/tasks/存放通过archery crossbow submit ...触发/提交的扩展任务通常是 nightly 构建或与发布流程相关的任务。ci/存放脚本、Dockerfile 及补充文件例如补丁文件、conda 环境文件、vcpkg triplet 文件等。其中的 ci/scripts 目录包含了cpp_build.sh、cpp_test.sh、python_build.sh、integration_dask.sh等大量构建/测试脚本。1.3 两类构建模式与其按文件和文件夹来理解更清晰的方式是把 Arrow CI 分为两大类action-triggered builds动作触发构建由 GitHub 上的特定动作如 PR 打开、PR 合并触发的 CI 任务。extended builds扩展构建手动触发其中多数按 nightly 节奏运行。1.4 服务依赖与 archery 的自动解析需要注意docker-compose.yml中定义的部分服务之间存在依赖关系。在本地运行服务时你必须手动先构建其依赖或者通过archery docker run ...来运行——后者会自动查找并构建依赖。这一点在docker-compose.yml的x-hierarchy节中体现Archery 依据该层级声明实现嵌套镜像的自动构建例如调用一次archery docker run debian-ruby即可替代依次执行docker-compose build debian-cpp、debian-c-glib、debian-ruby再run --rm debian-ruby的完整序列。二、动作触发构建GitHub Actions 工作流解析.github/workflows/中的.yml文件是响应特定动作运行的 GitHub Actions 工作流。其中绝大多数是针对具体语言实现C、Python、Java、R、Go、JS、Swift、Ruby、C#、MATLAB 等的流程仅在影响对应语言代码的变更发生时运行。除语言实现外值得注意的通用工作流有工作流文件作用archery.yml当 Archery 工具或其运行的任务发生变更时运行必要的验证检查comment_bot.yml通过监听 GitHub PR 评论触发特定动作见下文dev.yml任何 PR 有活动或 PR 被合并时运行负责 lint 检查与可合并性测试dev_pr.yml任何 PR 打开或更新时运行检查 PR 标题格式、必要时为对应 GitHub issue 添加 assignee或添加评论要求用户在标题中带上 issue id并添加相关 GitHub 标签2.1 comment_bot用评论驱动 CIcomment_bot.yml 监听 GitHub PR 评论中的以下字符串并触发相应动作源码中可见对应的autotune、rebase等工作流分支github-actions crossbow submit ...运行指定的 Crossbow 命令github-actions autotune运行一批样式/格式化工具、构建部分文档并提交结果github-actions rebase把 PR rebase 到主分支源码中对应git rebase upstream/${{ github.event.repository.default_branch }}。另外还有两份文件定义了动作触发的构建appveyor.yml在涉及 Python 或 C 的提交上运行。三、扩展构建Crossbow 与 dev/tasksCrossbow 是 Archery 的一个子组件用于手动触发构建。可运行的 Crossbow 任务都定义在dev/tasks目录中该目录包含dev/tasks/tasks.ymltasks.yml各类可通过 Crossbow 运行的任务配置若干子目录存放不同的任务模板使用 Jinja2 语法编写大致按语言或包管理系统划分。大多数任务作为 nightly 构建运行但也可以在 PR 上添加以github-actions crossbow submit开头、后跟任务名的评论来手动触发。3.1 任务分组机制为方便起见dev/tasks/tasks.yml中的任务按“组groups”定义便于一次性向 Crossbow 提交多个任务。例如源码中的分组定义包括conan匹配conan-*conda匹配conda-*wheel匹配wheel-*linux匹配almalinux-*、amazon-linux-*、centos-*、debian-*、ubuntu-*packaging汇总 almalinux、conan、debian、java-jars、matlab、nuget、python-sdist、wheel 等打包类任务test/cpp/c-glib/java/python/r/ruby/go/vcpkg按语言划分的测试任务组。任务定义中包含了在docker-compose.yml中运行哪个服务、在哪个 CI 服务上运行任务、以哪个模板文件作为任务基础等关键信息。3.2 Crossbow 覆盖的打包与集成测试范围arrow/dev/tasks目录的目标是自动化 Arrow 的打包与集成测试流程。打包范围包括C 与 Python 的 conda-forge 包面向 Linux、macOS、Windows面向 Linux、macOS、Windows 的 Python Wheels面向多个 Linux 发行版的 C 与 GLib 包Java for Gandiva。集成测试范围包括各类 Docker 测试、Pandas、Dask、Turbodbc、HDFS、Spark。四、Docker 构建可复现的本地化 CIArrow 的大部分 Linux CI 任务通过 Docker 与 docker-compose 与公共 CI 服务解耦。把 CI 配置保持在公共服务端最小化使得本地可复现成为可能。构建镜像本身定义在 ci/docker 目录下的各*.dockerfile中。4.1 执行 Docker 构建的多种方式执行基于 Docker 的构建有多种方式推荐的方式是使用 Archery 工具。列出可用镜像archery docker images执行一次构建archery docker run conda-pythonArchery 底层会依次调用如下 docker-compose 命令等价序列docker-compose pull --ignore-pull-failures conda-cpp docker-compose pull --ignore-pull-failures conda-python docker-compose build conda-cpp docker-compose build conda-python docker-compose run --rm conda-python注意由于conda-python依赖conda-cppArchery 依据docker-compose.yml的x-hierarchy声明自动补齐了依赖镜像的拉取与构建。4.2 常用运行选项只显示要执行的 docker-compose 命令而不实际执行archery docker run --dry-run conda-python禁用镜像拉取用于已有镜像时加速archery docker run --no-cache conda-python等价于docker-compose build --no-cache conda-cpp docker-compose build --no-cache conda-python docker-compose run --rm conda-python仅对叶子镜像禁用缓存强制构建依赖的开发版本PANDASupstream_devel archery docker run --no-leaf-cache conda-python-pandas该命令构建conda-cpp conda-python conda-python-pandas这一镜像分支其中叶子镜像为conda-python-pandas并注意它不拉取conda-python-pandas镜像、构建时也不使用缓存。等价序列为export PANDASupstream_devel docker-compose pull --ignore-pull-failures conda-cpp docker-compose pull --ignore-pull-failures conda-python docker-compose build conda-cpp docker-compose build conda-python docker-compose build --no-cache conda-python-pandas docker-compose run --rm conda-python-pandas这里PANDAS是一个构建参数见下文“Docker 构建参数”其默认值定义在.env文件中。完全跳过镜像构建应对缓存失效docker-compose 的层缓存机制在某些版本、cache_from构建项与不同后端docker-py、docker-cli、docker-clibuildkit组合下并不可靠即使重复执行相同构建命令也可能产生不同的层哈希导致缓存未命中、触发整镜像重建。如果镜像已构建好但缓存工作不正常可以跳过构建阶段# 第一次运行确保镜像已构建 archery docker run conda-python # 如果第二次运行又尝试构建镜像、且相关 dockerfile 引用的文件都没有变化 # 则说明出现了上述缓存未命中问题 archery docker run conda-python # 由于镜像已被第一次命令正确构建无需重建 # 手动禁用 pull 和 build 阶段以节省时间 archery docker run --no-pull --no-build conda-python向容器传递环境变量容器内使用的大多数构建脚本可通过环境变量配置。使用--env或-eCLI 选项传入与docker run和docker-compose run接口类似archery docker run --env CMAKE_BUILD_TYPErelease ubuntu-cppC 构建可用的环境变量详见 ci/scripts/cpp_build.sh 脚本。以自定义命令运行镜像自定义 docker 命令可作为archery docker run的第二个参数传入。以下示例在容器内启动交互式bash会话便于交互式调试构建archery docker run ubuntu-cpp bash4.3 Docker 卷缓存大多数 compose 容器会挂载宿主机的特定目录以复用ccache与maven制品。这些 docker 卷位于.docker目录中。清理缓存只需删除其中的一个或多个目录或整个.docker目录。4.4 Docker 构建参数构建期参数被下推到 Dockerfile 中以增强镜像构建的灵活性。这些参数通常被称为 docker build args但 Arrow 以环境变量的形式传给 docker-compose.yml。构建参数广泛用于定义用于缓存的 docker registry平台架构操作系统及其版本定义各种依赖的版本。参数默认值存放在顶层.env文件中。仓库中的 .env 文件实际定义了如下的默认参数节选参数默认值说明ARCHamd64架构REPOapache/arrow-dev拉取/推送镜像的默认仓库ULIMIT_CORE-1coredump 生成开关设为 0 可禁用ALMALINUX/ALPINE_LINUX/DEBIAN/FEDORA/UBUNTU8/3.16/12/39/20.04各发行版默认版本CUDA11.2.2CUDA 版本DOTNET8.0.NET 版本GO1.21.8Go 版本JDK11JDK 版本LLVM14LLVM 版本MAVEN3.8.7Maven 版本NODE18Node.js 版本PYTHON3.8Python 版本R4.4R 版本PANDAS/DASK/NUMBA/NUMPY/TURBODBClatest各 Python 依赖默认版本VCPKG指定 commit SHAvcpkg 依赖版本4.5 构建脚本设计原则ci/scripts目录下维护的脚本应保持可参数化、但尽量精简以清晰封装各自负责的任务例如cpp_build.sh构建 C 实现但不运行测试cpp_test.sh执行 C 测试python_build.sh构建 Python 绑定但不运行测试python_test.sh执行 Python 测试docs_build.sh构建 Sphinx 文档integration_dask.sh/integration_pandas.sh执行 dask / pandas 集成测试install_minio.sh为多平台安装 minio 服务器install_conda.sh为多平台安装 minicondainstall_gcs_testbench.sh为多平台安装 GCS testbench。参数化如 C 的 CMake 选项通过带有合理默认值的环境变量实现使构建配置保持声明式。以 ci/scripts/cpp_build.sh 为例脚本开头即通过: ${ARROW_USE_CCACHE:OFF}、: ${BUILD_DOCS_CPP:OFF}等形式为环境变量设置默认值并将ARROW_CMAKE_ARGS、ARROW_GANDIVA_PC_CXX_FLAGS等环境变量转发为 CMake 选项——同一脚本可以在多种配置下被调用而无需修改自身。具体的变量传递示例可参见docker-compose.yml中的 C 镜像定义。4.6 开发视角层次化镜像设计docker-compose 配置面向可复用的开发容器采用层次化镜像设计。例如多个语言绑定依赖 C 实现因此无需在多个 Dockerfile 中重复定义 C 环境而是在构建 GLib、Ruby、R 与 Python 绑定时直接复用完全相同的底层 C 镜像。这一设计减少了重复并简化了维护但也使 docker-compose 配置更复杂。docker-compose.yml文件头部还给出了 coredump 相关的内核参数设置建议如 Linux 主机上执行sudo sysctl -w kernel.core_patterncore.%e.%p以及用ULIMIT_CORE0禁用 coredump 生成。五、Archery日常开发与 CI 的瑞士军刀为简化日常开发任务Arrow 开发了一个用 Python 编写的工具名为 Archery。其源码位于 dev/archery 目录。5.1 安装Archery 要求 Python 3.8 或更高版本。推荐以editable模式-e标志安装这样在拉取 Arrow 仓库后安装会自动更新。克隆 Arrow 仓库后在顶层目录执行$ pip install -e dev/archery[all]Archery 的许多操作依赖 Docker 与 docker-compose你可能也需要安装它们。5.2 用法概览通过--help标志查看用法$ archery --help Usage: archery [OPTIONS] COMMAND [ARGS]... Apache Arrow developer utilities. See sub-commands help with archery cmd --help. Options: --debug Increase logging with debugging output. --pdb Invoke pdb on uncaught exception. -q, --quiet Silence executed commands. --help Show this message and exit. Commands: benchmark Arrow benchmarking. build Initialize an Arrow C build crossbow Schedule packaging tasks or nightly builds on CI services. docker Interact with docker-compose based builds. integration Execute protocol and Flight integration tests linking Quick and dirty utilities for checking library linkage. lint Check Arrow source tree for errors numpydoc Lint python docstring with NumpyDoc release Release related commands. trigger-botArchery 暴露了相互独立的子命令每个子命令都有专门的帮助输出例如$ archery docker --help Usage: archery docker [OPTIONS] COMMAND [ARGS]... Interact with docker-compose based builds. Options: --src arrow_src Specify Arrow source directory. --help Show this message and exit. Commands: images List the available docker-compose images. push Push the generated docker-compose image. run Execute docker-compose builds.5.3 从源码看 Archery docker 子命令的实现Archery docker 子命令的 CLI 实现在 dev/archery/archery/docker/cli.py 中前文介绍的各选项都可以在源码中找到对应声明--dry-run/--execute只打印 docker-compose 命令而不执行--force-pull/--no-pull控制是否拉取基础镜像--force-build/--no-build控制是否构建镜像--use-leaf-cache/--no-leaf-cache控制叶子镜像是否使用缓存。其对应的测试用例位于 dev/archery/archery/docker/tests/test_docker_cli.py其中验证了run --no-pull --no-build ubuntu-cpp、--no-leaf-cache等选项的组合行为。若需完整了解 Docker 与 Archery 的配合使用可继续阅读 docker.rst。六、Crossbow打包与测试的队列化调度Crossbow 的目标是自动化 Arrow 的打包与集成测试流程其任务模板与配置集中在dev/tasks目录。6.1 架构Executor、Queue 与 SchedulerCrossbow 的架构由三部分组成Executors执行器单个任务运行在公共 CI 服务上当前包括LinuxGitHub Actions、Travis CI、Azure PipelinesmacOSGitHub Actions、Azure PipelinesWindowsGitHub Actions、Azure Pipelines。Queue队列由于 CI 服务的调度方式限制任务调度通过一个额外的 git 仓库进行该仓库充当任务的作业队列。任何人都可以托管一个 queue 仓库通常命名为ghuser/crossbow。一个 job 就是某个 git 分支上的一个 git commit其中包含运行请求构建所需的配置文件如.travis.yml、azure-pipelines.yml或供 GitHub Actions 使用的crossbow.yml。Scheduler调度器Crossbow 负责版本生成、任务渲染与提交任务定义在tasks.yml中。6.2 安装与准备以 GitHub 为例以下指南以 GitHub 为例但理论上任何 git 服务器都可以使用。如果你不打算使用现成的 queue 仓库如 ursacomputing/crossbow需要先完成前两步否则直接从第 3 步开始创建 queue 仓库为新创建的 queue 仓库启用 Travis CI 与 Azure Pipelines 集成克隆 queue 仓库到 arrow 仓库旁边默认情况下脚本会在arrow目录旁边查找crossbow克隆但可以通过命令行参数配置。git clone https://github.com/user/crossbow crossbow重要提示Crossbow 仅支持基于 GitHub token 的认证。虽然它会覆盖以 ssh 协议提供的仓库 URL仍建议使用 HTTPS 仓库 URL。创建 Personal Access Token需要repo与workflow权限不需要其他权限在本地把 token 导出为环境变量export CROSSBOW_GITHUB_TOKENtoken或作为 CLI 脚本的参数传入--github-token把上述 GitHub token 添加到Travis CI使用名为CROSSBOW_GITHUB_TOKEN的加密环境变量可在 Travis CI 的仓库设置页面中配置。同时确认分支构建的 auto cancellation 功能已关闭通常为默认设置安装 Python最低支持版本为 3.8推荐使用 Miniconda安装包含 crossbow 的 archery 工具集$ pip install -e arrow/dev/archery[crossbow]尝试运行$ archery crossbow --help6.3 使用流程Crossbow 脚本执行以下步骤检测当前仓库支持 fork例如下面的片段会构建 kszucs 的 fork 而不是上游仓库$ git clone https://github.com/kszucs/arrow $ git clone https://github.com/kszucs/crossbow $ cd arrow/dev/tasks $ archery crossbow submit --help # 显示可用选项 $ archery crossbow submit conda-win conda-linux conda-osx获取当前 checkout 分支的 HEAD commit并基于 setuptools_scm 生成版本号。因此要构建某个特定分支请在运行脚本前先 checkout$ git checkout ARROW-ticket number $ archery crossbow submit --dry-run conda-linux conda-osx注意arrow 分支必须事先推送因为脚本会克隆选定的分支。读取并渲染所需的构建配置替换其中的参数为每个任务创建一个分支以 job id 为前缀。例如构建 Linux 上的 conda recipes 时会创建名为crossbowbuild-id-conda-linux的新分支将修改后的分支推送到 GitHub 以触发构建认证使用安装一节中描述的 GitHub OAuth token。6.4 查询构建状态与下载制品submit命令会返回 build id它在 queue 仓库中对应一个分支$ archery crossbow status build id / branch name下载构建制品$ archery crossbow artifacts build id / branch name6.5 实战示例submit 命令接受任务名列表和/或任务组名列表来选择要构建的任务。运行多个构建$ archery crossbow submit debian-stretch conda-linux-gcc-py37-r40 Repository: https://github.com/kszucs/arrowtasks Commit SHA: 810a718836bb3a8cefc053055600bdcc440e6702 Version: 0.9.1.dev48g810a7188.d20180414 Pushed branches: - debian-stretch - conda-linux-gcc-py37-r40只渲染而不应用或提交变更dry-run$ archery crossbow submit --dry-run task_name只运行 conda 包构建与一个 Linux 构建$ archery crossbow submit --group conda centos-7运行 wheel 构建$ archery crossbow submit --group wheeltasks.yml中还有多个任务组如 docker、integration 和 cpp-python用于运行基于 docker 的测试。archery crossbow submit支持多个选项与参数更多内容请查看其帮助页$ archery crossbow submit --help七、CI 全景速查与延伸阅读综合来看Arrow 的 CI 体系可以概括为一张速查表组件位置作用GitHub Actions 工作流.github/workflows按 PR/合并等动作触发的语言级与通用校验lint、标题检查、评论机器人Appveyor 工作流appveyor.yml与 Python/C 提交相关的 Windows 构建Docker 服务定义docker-compose.yml参数化定义全部构建/测试镜像及其层次依赖构建参数默认值.env提供架构、发行版、依赖版本的默认值构建/测试脚本ci/scripts可参数化的单任务脚本作为容器内执行入口Dockerfileci/docker各镜像的具体构建定义Crossbow 任务配置dev/tasks/tasks.yml定义可调度的打包与测试任务及任务组任务模板dev/tasks 子目录基于 Jinja2 的各类任务模板conda、wheel、linux 包等Archery 工具源码dev/archery提供 docker、crossbow、lint、benchmark 等子命令若希望深入某个主题仓库内提供了完整的原始文档CI 概览见 overview.rstDocker 构建细节见 docker.rstArchery 日常使用见 archery.rstCrossbow 打包与测试见 crossbow.rst。实际动手时请以当前仓库中的配置与脚本为准——例如docker-compose.yml中的服务名、.env中的默认版本都会随项目迭代而变化。赞分享数据工程数据分析大数据【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow12/arrow点击查看免费下载相关推荐ReadCat深度解析构建安全可信赖的现代小说阅读器架构ReadCat深度解析构建安全可信赖的现代小说阅读器架构 在数字阅读日益普及的今天一款优秀的阅读器不仅需要提供流畅的阅读体验更要确保用户数据的安全和隐私保数据工程大数据序列化数据分析Apache Arrow 持续集成体系全解析从 compose.yaml 到 Crossbow 的 CI 架构与实践Apache Arrow 持续集成体系全解析从 compose.yaml 到 Crossbow 的 CI 架构与实践 Apache Arrow 是横跨 C大数据数据分析数据工程序列化Apache Arrow 持续集成体系全解析GitHub Actions 触发构建与 Crossbow 扩展构建实战指南Apache Arrow 持续集成体系全解析GitHub Actions 触发构建与 Crossbow 扩展构建实战指南 Apache Arrow 是一个横跨数据工程数据分析大数据上一篇GitHub_Trending/rea/react-conf-appReact 项目中的计算机视觉应用下一篇让 AI 安全跑 shell 命令Hermes Agent 的 7 种终端后端 20 分钟上手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考