在远程 Mac 或自托管 Runner 上跑 Ansible 流水线时，Galaxy 集合（HTTPS 制品与 API）与 Git 元数据角色（克隆、子模块、标签解析）往往共用出境带宽与文件句柄，却不是同一套重试语义。本文刻意从双源切入，避免与站内已发的 Bundler、Composer 等题材在「包管理器」层面重复。你将得到一张可执行参数表、双通道决策矩阵与缓存目录隔离清单。延伸阅读 Git 与 Docker 拉取加速指南、跨境 Git/npm 镜像优化；入口 技术博客列表 与 首页免登录可阅。
为何要把 Galaxy 与 Git 角色分开决策
集合（collections）多走 Galaxy 或私有 Hub 的 REST/归档下载，失败形态以超时、429、TLS 中断为主；roles/requirements.yml 中的 src: git+https://... 则受 Git 浅克隆、凭据、LFS、子模块影响。把两者混在同一缓存树下而不加 ANSIBLE_HOME 隔离，常见症状是「上一轮 Job 的半包 tarball」污染下一轮解析。远程 Mac 上若多流水线共享用户，更应用每 Job 工作区根锚定配置与缓存。
| 维度 | Galaxy 集合为主 | Git 角色 / scm 为主 |
|---|---|---|
| 瓶颈 | 大 tarball、API 限流、索引解析 | clone 深度、网络抖动、凭据过期 |
| 并行策略 | 分批 requirements + 受控外层并发 | 串行化关键仓库或降低 simultaneous clone |
| 缓存键 | requirements 文件哈希 + Ansible 次版本 | requirements + 显式 commit/tag |
可执行参数表（ansible.cfg / 环境 / 外层脚本）
下列取值面向跨境弱网 + 共享 Runner的起点；稳定后再上调 forks。剧本任务级 retries/delay/until 仍建议在 YAML 中声明，此处聚焦引擎与传输层。
| 键 / 变量 | 推荐写入 | 用途与备注 |
|---|---|---|
[defaults] forks |
4（共享出口 2~4） |
控制对多台被管主机的并发；过高会放大 SSH 与_facts 压力，与 Galaxy 下载阶段无关但影响同一时段总连接数。 |
[defaults] timeout |
45~120 |
任务/连接插件层面的默认超时（秒）；跨境建议从 60 起步再按模块日志收紧。 |
[ssh_connection] retries |
3 |
SSH 建立与会话闪断的内置重试；与 shell 外层退避互补而非替代。 |
[defaults] retry_files_enabled |
False |
CI 中避免写 *.retry 脏文件；失败信息进日志与制品即可。 |
ANSIBLE_HOME |
$PWD/.ansible-ci-$CI_JOB_ID |
自 Ansible 2.14 起集中配置、缓存、集合元数据的根；每 Job 一树，避免多流水线互踩。 |
TMPDIR |
$PWD/tmp/$CI_JOB_ID |
解压与临时文件目录；与 ANSIBLE_HOME 组合可显著降低「系统默认 /tmp 竞态」。 |
collections_paths / roles_path |
工作区内 ./collections、./roles |
便于流水线 restore/cache 键直接绑定目录哈希；勿写全局 ~/.ansible。 |
| 外层「并发拉取」 | xargs -P 2~4 分批 requirements |
ansible-galaxy 解析依赖时不要盲目开大；用受控进程数换吞吐，配合 Hub 配额观察。 |
| 失败退避 | sleep 2 / 4 / 8，最多 3 轮 |
包裹 ansible-galaxy collection install 与 ansible-galaxy role install；仍失败则降并发或检查令牌与镜像。 |
export CI_JOB_ID="${CI_JOB_ID:-dev}"
export ANSIBLE_HOME="$PWD/.ansible-ci-$CI_JOB_ID"
export TMPDIR="$PWD/tmp/$CI_JOB_ID"
mkdir -p "$TMPDIR" "$ANSIBLE_HOME"
export ANSIBLE_RETRY_FILES_ENABLED=false
export GIT_TERMINAL_PROMPT=0
# ansible.cfg 建议写入工作区，含 [defaults] forks/timeout、[ssh_connection] retries、collections_paths、roles_path
决策矩阵：何时优先「制品缓存」vs「Git 镜像 / 代理」
| 症状 | 优先动作 |
|---|---|
| Galaxy 下载 tarball 频繁中断 | 固定 ANSIBLE_HOME + 流水线缓存该树；Hub 侧开启私有镜像或近源同步；外层退避。 |
| roles 自 Git 拉取慢但稳定 | 改 git clone --depth 1（在 requirements 允许范围内）、企业内镜像裸库、或预置 vendor roles 目录。 |
| 同一时段多 Job 429 | 错峰 forks 与 Galaxy 外层 -P；拆分大 requirements；升级更高出口带宽的节点池。 |
上线前验收清单
对照勾选
- 打印
ansible --version与ansible-galaxy --version，缓存键含次版本。 ansible.cfg已入库，CI 使用ANSIBLE_CONFIG=$PWD/ansible.cfg显式指向。- collections、roles 的 requirements 哈希变更后执行一次冷装并记录耗时基线。
- Git 源已关闭交互（
GIT_TERMINAL_PROMPT=0），HTTPS 令牌来自 CI 密钥而非明文。
FAQ
forks 降低后 Galaxy 仍慢？
瓶颈多半在安装阶段而非 playbook 执行；检查 requirements 体积、是否可改内网聚合 Hub，并验证 ANSIBLE_HOME 是否命中流水线缓存。
能否只靠提高 timeout 解决？
timeout 只缓解「慢」，不解决「限流」；应与退避、降并发、镜像组合，否则会把失败拉长成挂起。
与站内其他 CI 文关系？
本文强调 Galaxy + Git 双源 与 ANSIBLE_HOME/TMPDIR；通用 Git 代理与跨境策略请交叉阅读上文内链中的 Git/npm 与 Git·Docker 加速文。