Apache OpenWhisk 构建辅助脚本 `redo` 与 `citool` 实战指南

• 后端
• 云原生

导读

本文以 tools/build/README.md 为主线，系统讲解 Apache OpenWhisk 仓库中两个核心开发/CI 辅助工具：封装 Ansible 与 Gradle 命令的redo，以及用于监控 Jenkins / Travis CI 构建的citool。读完本文，你将掌握 OpenWhisk 的"编译—部署—测试"一键式开发循环、单组件增量重建技巧、CI 构建监控与日志分析流程，以及 Gradle Build Scan 的接入方式，可直接投入本地开发与持续集成排障场景。

redo与citool均为 Python 脚本，位于仓库 tools/build/ 目录下（同目录还包含用于校验日志/数据库规模的 checkLogs.py）。redo之所以叫redo，正如文档所言：大多数开发场景下你只是反复地"重做"编译与部署——这也是它设计的出发点。

一、redo：Ansible 与 Gradle 的统一封装

1.1 设计思路与执行模型

redo的核心思想是把 OpenWhisk 的部署体系抽象为两类底层执行器：

• Playbook：封装ansible-playbook命令，对应 ansible/ 目录下各.yml部署剧本（如 openwhisk.yml、wipe.yml、teardown.yml），并支持按mode=clean执行清理动作；
• Gradle：封装gradlew命令，对应 settings.gradle 中声明的各 Gradle 子项目（common:scala、core:controller、core:scheduler、core:invoker、core:standalone、tests等），默认任务为distDocker。

从源码看，redo将每个"组件（component）"建模为一张配置表：名称、描述、对应的 playbook 与 gradle 目标，甚至可以是一组按顺序执行的子组件步骤（steps）。执行时（redo 中doComponentSequence/doOne逻辑）：

1. 若指定了-b/--build且组件可 Gradle 构建，则先执行 Gradle 任务；
2. 若指定了-x/--teardown且组件带 playbook，则执行ansible-playbook ... -e mode=clean清理；
3. 若指定了-d/--deploy且组件带 playbook，则执行 playbook 完成部署。

当-b、-x、-d均未给出时，三个开关默认全部开启（build + teardown + deploy）——这解释了为什么redo controller单独执行时即是"重建并重部署 controller"的完整循环。

redo还自动处理部署目标（target）：在 Linux 上默认local，在 macOS 上若环境变量DOCKER_HOST已设置则推断为docker-machine，否则为local；无法自动推断时，会提示用--target显式指定。

1.2 常用命令一览（文档原文继承）

以下命令均来自 tools/build/README.md，可直接在 OpenWhisk 仓库根目录执行：

首次部署一条命令搞定：

redo setup prereq couchdb initdb deploy tests

每个步骤依序串行执行，等价于完整走一遍"环境准备 → 数据库 → 部署 → 测试"。

1.3 单组件增量构建

redo支持对单个组件（如controller）独立执行构建/清理/部署：

redo controller -b # 仅构建 redo controller -x # 仅清理（teardown） redo controller -d # 仅重新部署 redo controller -bxd # 构建+清理+部署（默认行为）

将-b、-x、-d自由组合即可控制每个阶段；不传任何开关时即等价于-bxd。

1.4 透传参数：-a与-e

redo提供两个透传开关，把额外参数交给底层命令：

• -a/--additional-task-arguments：追加给 Gradle 构建。最典型的用法是从命令行运行部分测试：

redo tests -a '--tests package.name.TestClass.evenMethodName'

源码中该参数会被拼接到gradlew命令行尾部（Gradle.execcmd组装--parallel与-PdockerHost等参数后拼接extraArgs）。

• -e/--extra-ansible-vars：追加给ansible-playbook的额外变量，会以-e 'key=value'形式注入，用于覆盖部署变量。

1.5 动态生成组件：runtime 镜像重建

某些组件名是动态匹配的。redo支持用正则定义通用组件名，例如runtime:([\w.-]+)，用于重建 action runtime 容器镜像。以runtime:nodejs6action为例，redo会将其解析为 Gradle 目标core:nodejs6action:distDocker（源码getComponent中的正则回退逻辑），因此需要把 runtime 仓库路径通过--dir指过去：

redo --dir /path/to/openwhisk-runtime-nodejs runtime:nodejs6action

1.6 完整组件目录（来自redo源码）

redo内置组件表（可用redo -c/--list-components查看彩色列表）如下，覆盖从初始化到测试的完整生命周期：

其中deploy组件背后是 ansible/openwhisk.yml，该剧本按enable_scheduler、lean等变量条件式导入etcd.yml、kafka.yml、controller.yml、scheduler.yml、invoker.yml、edge.yml、downloadcli.yml——这解释了为何一条redo deploy就能按拓扑装配整套系统。props组件对应的 ansible/properties.yml 在mode == "deploy"时导入tasks/writeWhiskProperties.yml，将部署信息写回whisk.properties供测试读取。

1.7 其他实用开关

• -n/--just-print：只打印将要执行的组件配置与命令，不真正运行（dry-run）；
• -c/--list-components：列出所有已知组件名后退出；
• --dir：指定 OpenWhisk 仓库根目录（默认取脚本自身位置推算的../../，也可用环境变量WHISK_HOME覆盖）；
• -t/--target：指定部署目标（docker-machine或local）。

二、citool：命令行监控 Jenkins / Travis CI 构建

2.1 基本用法

citool面向 CI 场景，默认监控托管在https://api.travis-ci.org/（源码中实际默认值为https://api.travis-ci.com）的 Travis 构建，也可通过-u切换到任意 Jenkins（或 Travis）主机 URL。

citool -h # 查看用法 citool monitor N # 监控 Travis 构建任务 N（默认仅汇报失败测试） citool monitor -p N # 每 10 秒轮询，直到构建完成（源码用 threading.Timer 实现） citool -o monitor N # 将任务输出保存到文件

对于 Travis 矩阵构建（matrix builds），在任务号后追加矩阵序号即可：citool monitor N.i，其中1 <= i <= 矩阵构建数。源码getTravisMatrixId会校验矩阵下标必须在[1..N]范围内，越界会直接报错退出。

2.2 监控 Jenkins 构建

Jenkins 场景需同时指定主机-u与构建名-b：

citool -u https://jenkins.host:port -b B monitor N

citool对 Travis 与 Jenkins 使用不同的日志接口：Travis 拉取<jobUrl>/log.txt（跟随 302 重定向），Jenkins 则请求<jobUrl>/logText/progressiveHtml（见源码monitorOnce）。监控输出默认只显示FAILED的测试任务行（通过grep -E "^> Task ... FAILED"实现）；加-a/--all可连 PASSED 一起显示；加-r/--relax可放宽匹配，连失败的 ansible 任务也纳入报告。构建是否结束通过识别Finished:、Done.或超时终止字样判断，未结束则打印Build: ONGOING并继续轮询。

2.3 收集并分析组件日志：cat

cat子命令用于从 Jenkins 构建中汇总 controller / scheduler / invoker 的日志产物。例如：从主机https://jenkins.host:port的构建B（任务号N）中，拉取 1 个 controller 与 1 个 invoker 的日志（产物位于 job URL 下whisk/logs相对路径）：

citool -u https://jenkins.host:port -b B cat whisk/logs N

组件数量通过-c（controllers，默认 1）、-n（invokers，默认 3）、-c（schedulers，默认 1）控制（注：源码中 schedulers 与 controllers 共用-c选项，默认值均为 1）。日志按controller0/controller1/.../invokerN_logs.log的规则拼接。

保存到本地反复分析：用-o把拼接结果写入./B-build.log，之后用-i从本地文件重放，避免重复请求 CI：

citool -o -u https://jenkins.host:port -b B cat -s -g "tid_123" whisk/logs N citool -i -b B cat -s -g "tid_124" whisk/logs N

其中：

• -s/--sort：按日志中的 ISO 时间戳（如2026-10-08T22:21:02.123Z，见源码extractDate正则）对行排序，便于还原跨组件的调用时间线；
• -g/--grep：对拼接后的日志执行 grep，例如用tid_123精确抽取某个事务（transaction）相关的所有日志行。

注意cat子命令仅支持 Jenkins（源码中对 Travis 会输出Feature not yet supported for Travis builds.），日志类功能是 Jenkins 专属。

三、Gradle Build Scan 集成

OpenWhisk 的 CI 构建（如 Travis / Jenkins）集成了 Gradle Build Scan。相关配置在 settings.gradle 中可见一斑：gradleEnterprise { server = "https://ge.apache.org" ... }，并设置了publishAlways()、publishIfAuthenticated()、后台上传（非 CI 环境）、IP 混淆（0.0.0.0）以及构建缓存（CI 下关闭本地缓存、远程缓存默认关闭）。

每次 Travis 构建都会把扫描报告发布到 Gradle Scan 社区托管服务器。要查看报告，只需在 Travis 构建日志中检索如下行：

Publishing build scan... https://gradle.com/s/reldo4qqlg3ka

其中的 URL 即该次构建独有的扫描报告地址（每次构建唯一）。该报告包含任务执行详情、输入文件快照、耗时与缓存命中情况，是定位 CI 构建性能瓶颈与差异构建问题的有力工具。

四、常见问题排查（Troubleshooting）

若运行redo时遇到如下错误：

ImportError: No module named pkg_resources

说明本机setuptools版本过旧或缺失，升级即可解决：

pip install --upgrade setuptools

升级后重新执行redo命令即可。该错误源于redo/citool依赖 Python 环境中的pkg_resources（用于解析包资源），属于本地 Python 环境问题而非 OpenWhisk 本身。

五、小结

• redo将 OpenWhisk 复杂的 Ansible 剧本 + Gradle 多项目构建封装为一行命令，redo setup prereq couchdb initdb deploy tests即可完成全新环境的端到端部署，redo controller -bxd实现单组件增量迭代，-a/-e透传保证灵活性，runtime:正则组件让 runtime 镜像重建同样走统一入口。
• citool为 CI 场景提供零依赖的命令行监控：Travis / Jenkins 双支持、矩阵构建定位、轮询直到完成、日志抓取 + 时间戳排序 + 事务级 grep，离线重放（-i）让日志分析不必反复请求 CI。
• 两者与 tools/build/checkLogs.py（日志/数据库规模断言）共同构成 OpenWhisk 开发者日常构建与 CI 排障的工具链，建议结合 ansible/ 下的剧本与 settings.gradle 理解其底层映射关系。

• 后端
• 云原生