Apache Arrow 的 Docker 化 CI 构建：Archery、docker-compose 与分层镜像体系完全指南

数据工程数据分析大数据【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow12/arrow点击查看免费下载Apache Arrow 将绝大多数基于 Linux 的持续集成CI任务与公共 CI 服务解耦统一封装在 Docker 与 docker-compose 之中从而在本地获得与 CI 完全一致的可复现构建环境。本文基于仓库中的 docker.rst 文档结合 docker-compose.yml、.env、dev/archery/archery/docker 源码与 ci/scripts 构建脚本系统讲解如何使用 Archery 驱动 Docker 构建、控制缓存策略、传递构建参数并理解分层镜像的架构设计。读完本文你将能够像 Arrow 核心开发者一样在本地完整复现任何一条 Linux CI 构建流水线。设计动机把 CI 从公共 CI 服务中解耦Arrow 是一个横跨 C、Python、R、Ruby、Java、Go、C#、Swift、JS 等多种语言的多语言数据交换工具库其 CI 矩阵极其庞大。文档明确指出其核心理念Most of our Linux based Continuous Integration tasks are decoupled from public CI services using Docker and docker-compose. Keeping the CI configuration minimal makes local reproducibility possible.把构建逻辑沉淀到 Docker 镜像中带来两个直接收益CI 配置最小化公共 CI如 GitHub Actions上的 YAML 只负责拉起容器并运行脚本繁琐的环境安装与依赖固定全部交给 Dockerfile本地可复现archery docker run conda-python与 CI 中执行的命令完全一致任何开发者在任何机器上都能复现 CI 结果。这一设计贯穿仓库的 CI 脚本体系例如 ci/scripts/cpp_build.sh、ci/scripts/cpp_test.sh、ci/scripts/python_build.sh 等全部设计为在容器内可独立运行的脚本详见后文「Build Scripts」小节。快速上手安装 ArcheryArchery 是 Arrow 开发者日常使用的 Python 命令行工具Docker 相关操作只是其子命令之一。安装方式见 archery.rstpip install -e dev/archery[all]要求 Python 3.8 及以上使用-eeditable模式安装拉取仓库更新后工具会自动同步Archery 的 Docker 操作依赖本机的docker与docker compose或旧版docker-compose命令。Docker 子命令的入口定义在 dev/archery/archery/docker/cli.py支持以下命令命令作用archery docker images列出所有可用的 compose 镜像archery docker run image拉取/构建并运行镜像archery docker build image仅构建镜像不运行archery docker pull image仅拉取镜像archery docker push image推送镜像到 registryarchery docker info service查看某个服务的 compose 定义可用-s过滤 keyarchery docker check-config校验 docker-compose 配置基础用法列出镜像、执行构建与 Dry-Run列出可用镜像archery docker images该命令来自docker_compose_images函数直接输出ComposeConfig中x-hierarchy定义的节点集合见 dev/archery/archery/docker/core.py 中images()方法。也就是说镜像清单并非扫描 services 段而是以x-hierarchy声明为准这也是新增镜像时必须同步维护x-hierarchy的原因见后文。执行一次构建archery docker run conda-python文档给出了这条命令背后实际展开的 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从中可以看到 Archery 的构建策略先拉取所有祖先镜像再按依赖顺序构建祖先最后构建目标leaf镜像并运行。conda-cpp是conda-python的祖先镜像因为 Python 绑定依赖 C 实现。只查看命令而不执行archery docker run --dry-run conda-python--dry-run对应 cli.py 中docker组命令的--dry-run/--execute选项其实现通过_mock_compose_calls把_execute_docker/_execute_compose替换为只打印命令的 mock见 core.py 顶部非常适合排查一条构建到底会触发哪些 Docker 调用。缓存控制--no-cache、--no-leaf-cache 与 --no-build构建缓存是 Docker CI 中最容易踩坑的部分Archery 为此提供了三个递进的缓存控制选项均实现于 core.py 的build()方法。完全禁用缓存同时关闭拉取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注意文档强调--no-cache场景下不会执行 pull等价于--no-pull --no-cache因为cli.py中docker_run的--force-pull默认开启但--no-cache会连带关闭拉取阶段。只禁用 leaf 镜像的缓存当需要强制构建某个依赖的开发版本时只清掉最末级镜像的缓存即可PANDASupstream_devel archery docker run --no-leaf-cache 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这里构建的是conda-cpp conda-python conda-python-pandas这一条镜像树分支祖先镜像照常拉取、照常走缓存只有 leaf 镜像conda-python-pandas被--no-cache强制重建且不拉取它自己。PANDAS是文档所指的 build 参数其默认值定义在仓库根目录的 .env 中当前默认PANDASlatest。在 core.py 中对应_build(service, use_cacheuse_cache and use_leaf_cache)这一行逻辑——祖先用全局use_cacheleaf 用两者的与运算。完全跳过构建阶段docker-compose 的层缓存机制在不同版本、cache_from配置以及后端docker-py、docker-cli、buildkit下可靠性不一可能导致同样的命令反复触发缓存未命中、进而整镜像重建。如果镜像已经构建成功可以跳过拉取与构建阶段# 第一次运行确保镜像已构建 archery docker run conda-python # 如果第二次运行仍尝试重建且 dockerfile 相关文件没有变化说明缓存未命中 archery docker run conda-python # 镜像已就绪跳过 pull 和 build 阶段以节省时间 archery docker run --no-pull --no-build conda-python在 cli.py 中对应docker_run的--force-pull/--no-pull与--force-build/--no-build选项对置为--no-*时pull()与build()均被跳过直接进入run()。运行时配置环境变量、自定义命令与进阶选项通过 --env / -e 传递环境变量容器内运行的构建脚本大多可通过环境变量配置archery docker run --env CMAKE_BUILD_TYPErelease ubuntu-cpp--env短选项-e可多次指定与docker run/docker-compose run的语义一致。C 构建可用的环境变量清单见 ci/scripts/cpp_build.sh。以该脚本为例几乎所有 CMake 选项都映射为环境变量并带默认值例如ARROW_BUILD_TYPE默认debug→CMAKE_BUILD_TYPEARROW_PARQUET默认OFF→-DARROW_PARQUETARROW_DATASET默认OFF→-DARROW_DATASETARROW_BUILD_TESTS默认OFF→-DARROW_BUILD_TESTSARROW_USE_CCACHE默认ON→-DARROW_USE_CCACHEARROW_SIMD_LEVEL默认DEFAULT与ARROW_RUNTIME_SIMD_LEVEL默认MAX→ 对应 SIMD 编译级别。脚本通过: ${VAR:default}的 Bash 惯用法提供有用的默认值从而让同一份脚本在不同配置下无需修改即可复用——这正是文档强调的声明式配置设计。其余脚本同理例如 python_build.sh、python_test.sh 均从环境变量读取配置。自定义容器命令archery docker run的第二个参数是自定义命令。最常见的用法是启动交互式 bash 会话调试构建archery docker run ubuntu-cpp bash在 core.py 的run()中当命令为bash、sh、cmd.exe、powershell之一时会自动追加-it参数以启用交互式终端。其他实用选项从 cli.py 的docker_run命令声明中可以挖掘出更多能力# 以指定用户运行容器 archery docker run -u 1000 ubuntu-cpp # 挂载额外卷 archery docker run -v $PWD/build:/build ubuntu-cpp # 只拉取/构建不运行 archery docker run --build-only conda-python # 模拟 GitHub Actions 的资源限制CPU 与内存 # 通常需要 export ARCHERY_DOCKER_BINsudo docker archery docker run --resource-limitgithub ubuntu-cpp其中--resource-limitgithub会读取 docker-compose.yml 中x-limit-presets段定义的限制cpuset_cpus: [0, 1]、memory: 7g通过--cpuset-cpus与--memory/--memory-swap传入 Docker用于在本地复现 CI 机器的资源约束。此外x-with-gpus段声明了ubuntu-cuda-cpp、ubuntu-cuda-python两个需要 GPU 的服务运行时自动追加--gpus all见core.py的run()。Docker Volume 缓存.docker 目录与 ccache/maven 复用大多数 compose 服务把宿主机目录挂载进容器以复用ccache与maven等构建缓存这些卷统一放在仓库的.docker目录下。清理缓存的建议文档原话直接删除.docker下的一个或多个目录或整个.docker目录无需任何额外命令。下次构建时 Docker 会自动重新创建。卷的具体定义见 docker-compose.yml 末尾的volumes:段例如volumes: conda-ccache: name: ${ARCH}-conda-ccache debian-ccache: name: ${ARCH}-debian-${DEBIAN}-ccache maven-cache: name: maven-cache ubuntu-ccache: name: ${ARCH}-ubuntu-${UBUNTU}-ccache同时 .env 中的DOCKER_VOLUME_PREFIX控制卷的挂载方式空值默认使用 docker 命名卷在 Docker for macOS/Windows 上性能更好且避免污染源码目录非空值改为宿主机目录 bind-mount例如 GitHub Actions 上设置为.docker/以保持缓存插件如 buildkit inline cache可用。容器内 ccache 的行为由x-ccache公共锚点定义docker-compose.yml 顶部x-ccache: ccache CCACHE_COMPILERCHECK: content CCACHE_COMPRESS: 1 CCACHE_COMPRESSLEVEL: 6 CCACHE_MAXSIZE: 1G CCACHE_DIR: /ccache即缓存目录固定在/ccache开启压缩、设置 1G 上限并以编译器内容而非时间戳作为校验依据。架构设计分层镜像Hierarchical Imagesdocker-compose 配置被刻意设计为可复用的分层开发容器。文档给出了核心动机multiple language bindings are dependent on the C implementation, so instead of redefining the C environment multiple Dockerfiles, we can reuse the exact same base C image when building Glib, Ruby, R and Python bindings.即以 C 实现为基座各语言绑定GLib、Ruby、R、Python 等复用同一个基础镜像避免在每个 Dockerfile 中重复定义 C 环境。收益是大幅减少重复、简化维护代价是 compose 配置变得更复杂。这套依赖关系显式记录在 docker-compose.yml 的x-hierarchy段。以当前仓库的子树为例节选x-hierarchy: - almalinux-verify-rc - alpine-linux-cpp - conda: - conda-cpp: - conda-integration - conda-cpp-valgrind - conda-python: - conda-python-pandas: - conda-python-docs - conda-python-cpython-debug - conda-python-dask - conda-python-hdfs - conda-python-spark - debian-cpp: - debian-c-glib: - debian-ruby - debian-python: - debian-docs - ubuntu-cpp: - ubuntu-cpp-static - ubuntu-c-glib: - ubuntu-ruby - ubuntu-python - ubuntu-rx-hierarchy被 core.py 解析成扁平字典flatten()函数用于pull()、build()、push()时按祖先顺序递归执行。例如只需archery docker run debian-rubyArchery 就会自动依次构建debian-cpp → debian-c-glib → debian-ruby而不必手动执行一串docker-compose build命令这正是 docker-compose.yml 顶部注释中说明的用法。分层镜像实例conda 系conda系镜像的层级关系可在 docker-compose.yml 的services段逐一验证conda基础镜像ci/docker/conda.dockerfile只安装 conda 环境conda-cpp基于conda做 C 构建ci/docker/conda-cpp.dockerfile包含 doxygen 文档生成conda-python基于conda-cpp构建 Python 绑定ci/docker/conda-python.dockerfileconda-python-pandas在 Python 之上叠加 pandas 集成测试ci/docker/conda-python-pandas.dockerfile。每个服务的build.cache_from都指向${REPO}:${ARCH}-os-version-component格式的公共镜像其中REPO默认apache/arrow-dev见 .env从而支持跨主机复用公共缓存的镜像层。Docker Build Parameters.env 与构建参数体系构建期参数build time parameters被下推到 dockerfile 中以提升镜像构建的灵活性。文档明确指出这些参数通常被称为 docker build args但 Arrow通过环境变量传给 docker-compose.yml实现Archery 从进程环境变量与.env中收集参数并注入 compose 配置见 core.py 的ComposeConfig._read_env。这些参数被广泛用于控制用于缓存的 docker registry如REPOapache/arrow-dev平台架构ARCHamd64/arm64v8操作系统及版本ALMALINUX8、ALPINE_LINUX3.16、DEBIAN12、FEDORA39、UBUNTU20.04各种依赖的版本CUDA、LLVM、JDK、PYTHON、R、GO、DOTNET、PANDAS、NUMPY等。所有默认值都保存在仓库根目录的 .env 文件中docker-compose.yml 顶部注释明确说明defaults are set in .env file。节选当前仓库的关键默认值# registry 与架构 REPOapache/arrow-dev ARCHamd64 ARCH_ALIASx86_64 ARCH_SHORTamd64 # 操作系统默认版本 ALMALINUX8 ALPINE_LINUX3.16 DEBIAN12 FEDORA39 UBUNTU20.04 # 依赖默认版本 CLANG_TOOLS14 CUDA11.2.2 DOTNET8.0 GO1.21.8 HDFS3.2.1 JDK11 LLVM14 MAVEN3.8.7 NODE18 PANDASlatest PYTHON3.8 R4.4 # 构建缓存相关 BUILDKIT_INLINE_CACHE1 COMPOSE_DOCKER_CLI_BUILD1 DOCKER_BUILDKIT1 ULIMIT_CORE-1使用方法与docker-compose保持一致——直接在命令行前缀环境变量PYTHON3.12 archery docker run conda-python ARCHarm64v8 docker-compose build ubuntu-cppcore.py会做两件事一是只把.env中已有的键从进程环境变量透传下去防止无关环境变量污染 compose 展开二是把 docker 的架构记号翻译为通用记号amd64→x86_64、arm64v8→aarch64/arm64。此外还支持docker compose新、docker-compose旧、docker CLI、docker buildx四种后端切换--using-legacy-docker-compose、--using-docker-cli、--using-docker-buildx其中 buildx 模式会把构建缓存以typeregistry的方式推送到 registry实现跨主机复用。Build Scriptsci/scripts 下的构建脚本约定文档强调ci/scripts目录下的脚本应当可参数化但保持合理精简parameterizable but reasonably minimal每个脚本只清晰封装自己负责的任务。文档列出的核心脚本职责如下脚本职责cpp_build.sh构建 C 实现不运行测试cpp_test.sh执行 C 测试python_build.sh构建 Python 绑定不运行测试python_test.sh执行 Python 测试docs_build.sh构建 Sphinx 文档integration_dask.sh执行 dask 集成测试integration_pandas.sh执行 pandas 集成测试install_minio.sh为多平台安装 minio serverinstall_conda.sh为多平台安装 minicondainstall_gcs_testbench.sh为多平台安装 GCS testbench在当前仓库的 ci/scripts 目录中可以逐一验证这些脚本的存在与职责例如 install_conda.sh、install_minio.sh、install_gcs_testbench.sh、integration_dask.sh、integration_hdfs.sh、integration_spark.sh 等另外还有 cpp_test.sh、python_test.sh 以及大量平台安装脚本如 install_azurite.sh、install_emscripten.sh、install_vcpkg.sh。需要注意文档中提到的docs_build.sh与integration_pandas.sh在当前仓库快照中尚未找到同名文件可能对应版本演进后的其他脚本如 ci/scripts 下的文档/集成类脚本引用时以实际文件为准。参数化方式脚本通过环境变量含合理默认值实现参数化使构建配置保持声明式。最佳范例是cpp_build.sh——它把环境变量直接转发为 CMake 选项同一脚本可在不同配置下原样复用常规 release 构建docker-compose run -e ARROW_BUILD_TYPErelease conda-cpp仅共享库docker-compose run -e ARROW_BUILD_STATICOFF conda-cpp仅静态库docker-compose run -e ARROW_BUILD_SHAREDOFF -e ARROW_TEST_LINKAGEstatic conda-cpp这些用法示例直接写在 docker-compose.yml 的services段注释中。cpp_build.sh还会根据平台自动推导并行任务数nproc/sysctl -n hw.ncpu/NUMBER_OF_PROCESSORS支持ARROW_USE_CCACHEON时的 ccache 统计输出、BUILD_DOCS_CPPON时的 doxygen 生成以及ARROW_EMSCRIPTENON时的 Emscripten 特殊分支——体现出脚本保持精简但覆盖关键分支的设计取舍。新增镜像如何添加一个服务文档给出的指引非常简洁查看 docker-compose.yml 文件中的内联注释。结合x-hierarchy的解析逻辑core.py添加新镜像需要满足三条硬性校验在services:段定义服务包含image、build.dockerfile、build.cache_from等在x-hierarchy:段登记该服务及其子孙节点保持两处名称一致。ComposeConfig._read_config会做双向校验x-hierarchy里定义了但services中没有或services中存在但未登记到x-hierarchy都会在archery docker run ...或archery docker check-config时直接报错错误信息形如 Servicexxxis defined inx-hierarchybut not inservices。x-with-gpus中的服务同样必须存在于services。这保证了镜像清单archery docker images与构建依赖树的完整性。常见问题与排查思路缓存反复失效、整镜像重建docker-compose 的层缓存可能因cache_from与后端差异导致哈希不一致。先archery docker run image确认镜像已构建再改用archery docker run --no-pull --no-build image跳过重建阶段需要强制重建某个依赖的开发版本对目标 leaf 镜像使用--no-leaf-cache如PANDASupstream_devel archery docker run --no-leaf-cache conda-python-pandas祖先镜像继续享受缓存想确认一条命令到底会执行什么archery docker run --dry-run image只打印命令不执行构建失败但想知道环境参数Archery 在 compose 命令失败时会打印.env中的默认值与你显式传入的参数见core.py中_execute_compose的错误包装便于定位是哪个参数出了问题跨主机复用构建缓存使用--using-docker-buildx并通过BUILDKIT_INLINE_CACHE1.env 中已默认开启把缓存随镜像推送到 registry。小结Apache Arrow 的 Docker 化 CI 是一套分层镜像 参数化脚本 Archery 编排的完整体系x-hierarchy声明镜像依赖树.env统一管理构建参数默认值ci/scripts提供可参数化、可独立运行的构建测试脚本而 dev/archery/archery/docker 则把这三者串成一条条与 CI 完全一致的本地命令。掌握archery docker run的 pull/build/run 三段式流程与缓存控制选项后你就能在本地精确复现、调试和扩展 Arrow 的任何一条 Linux 构建流水线。进一步阅读可参考 archery.rstArchery 全量子命令与 overview.rstCI 整体概览。赞分享数据工程数据分析大数据【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow12/arrow点击查看免费下载相关推荐Apache Arrow Docker 构建实战用 Archery 与 Docker Compose 复现可移植的 CI 构建环境Apache Arrow Docker 构建实战用 Archery 与 Docker Compose 复现可移植的 CI 构建环境 Apache Arrow大数据数据分析数据工程序列化Apache SkyWalking OAP 镜像构建与 Docker Compose 快速启动完全指南Apache SkyWalking OAP 镜像构建与 Docker Compose 快速启动完全指南 导读 本文基于 Apache SkyWalking 仓库可观测性APM链路追踪指标监控日志分析微服务LibrePhotos Docker 部署体系解析镜像分层、Compose 配置与 GPU 构建实践LibrePhotos Docker 部署体系解析镜像分层、Compose 配置与 GPU 构建实践 本文以 LibrePhotos 仓库中贡献者文档 doc后端前端移动开发计算机视觉机器学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考