Bruno CLI 官方 Docker 镜像使用指南：容器化运行 API 集合测试与 CI/CD 集成

Bruno CLI 官方 Docker 镜像使用指南容器化运行 API 集合测试与 CI/CD 集成【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/brunoBruno CLIbru是开源 API 客户端 Bruno 的命令行引擎。官方将其封装为 Docker 镜像usebruno/cli使你在宿主机无需安装 Node.js 或 npm的前提下即可在本地与 CI/CD 流水线中原生执行 Bruno 集合Collection、批量发起请求并校验断言。本文以 packages/bruno-cli/docker/README.md 为骨架结合本仓库中的 Dockerfile、发布冒烟测试脚本与 CLI 源码系统讲解镜像变体选择、版本标签约定、运行方式、报告输出与主流 CI 集成方案。读完本文你将掌握如何拉取与固定镜像版本、如何把宿主机集合目录挂载进容器一键跑测试、如何产出 JUnit/JSON/HTML 报告以及如何在 GitHub Actions、GitLab CI 和 Docker Compose 中复用这套流程。bru CLI 运行集合时的终端输出示例为什么需要 Docker 镜像形态的 Bruno CLIBruno CLI 本身以 npm 包usebruno/cli分发。直接使用 Docker 镜像有几点价值零宿主依赖运行镜像不需要在主机上安装 Node.js、npm 或 Bruno适合锁定的 CI runner 镜像环境。版本可复现通过镜像 tag 精确固定 CLI 版本配合不可变版本号避免在我机器上是好的这类漂移问题。环境一致请求执行、断言校验、JS 沙箱全部发生在容器内部与宿主机文件系统、全局工具互不干扰。镜像内部完成的事本质就是两行核心逻辑见 packages/bruno-cli/docker/images/alpine/Dockerfile 与 packages/bruno-cli/docker/images/debian/Dockerfile全局安装usebruno/cli然后把容器的入口命令ENTRYPOINT固定为bruWORKDIR指向/bruno。镜像仓库Registries官方同时把镜像推送到 Docker Hub 和 GitHub Container Registry拉取命令如下docker pull usebruno/cli:latest docker pull ghcr.io/usebruno/cli:latest两条命令对应同一组发布产物可任选其一使用企业内网环境如果拉取 Docker Hub 受限可优先尝试 GHCR 地址。镜像变体Variants与选择策略官方维护两个变体均由同一套源码目录构建packages/bruno-cli/docker/images/下分别有独立的Dockerfile变体基础镜像说明Alpine默认node:22-alpine体积小、拉取快见 packages/bruno-cli/docker/images/alpine/README.mdDebiannode:22-slim基于 Debian slim见 packages/bruno-cli/docker/images/debian/README.md快速决策默认使用 Alpine除非你有明确理由官方建议约 90% 的用户都直接选它。遇到 SSL/glibc 兼容问题再换 Debian如果你的请求目标或自定义 CA 链路在 musl libc 环境Alpine 使用下行为异常切换到基于 glibc 的 Debian 变体往往可以解决。两个变体的 Dockerfile 内容几乎一致唯一差异就是FROM基础镜像行其余如构建参数、环境变量、用户与工作目录配置完全相同。版本标签Tags约定每次发版都会向Docker Hubusebruno/cli和GHCRghcr.io/usebruno/cli同时发布如下标签。Alpine 变体默认标签模式示例说明latestusebruno/cli:latest最新一次被标记为 latest 的版本。只有发布工作流勾选Tag this version as latest时才会移动latest-alpineusebruno/cli:latest-alpinelatest的别名——同样是 Alpinealpineusebruno/cli:alpine最新的 Alpine 构建每次发布 Alpine 都会更新versionusebruno/cli:3.3.0精确版本号不可变内容一经发布不再改变version-alpineusebruno/cli:3.3.0-alpine精确版本号显式标注 Alpinemajor.minorusebruno/cli:3.3浮动标签随补丁版本3.3.x自动前进major.minor-alpineusebruno/cli:3.3-alpine同上显式标注 Alpinemajorusebruno/cli:3浮动标签随任意 3.x.x 发布前进major-alpineusebruno/cli:3-alpine同上显式标注 AlpineDebian 变体标签模式示例说明latest-debianusebruno/cli:latest-debian最新被标记为 latest 的 Debian 版本同样受发布工作流勾选控制debianusebruno/cli:debian最新的 Debian 构建每次 Debian 发布都会更新version-debianusebruno/cli:3.3.0-debian精确版本号Debian 变体major.minor-debianusebruno/cli:3.3-debian浮动标签随 Debian 补丁版本前进major-debianusebruno/cli:3-debian浮动标签随任意 3.x.x Debian 发布前进一个容易被忽略的约定无后缀标签:latest、:3.3.0、:3.3、:3、:alpine永远解析到 Alpine 变体。因此想用最新且最小的镜像 →usebruno/cli:latest即 Alpine想在 CI 里锁定某个具体的发布 →usebruno/cli:3.3.0这类精确不可变标签文档中的 3.3.0 仅为示例请按你实际需要的版本替换想跟随补丁更新又不想每次手动改 →usebruno/cli:3.3major.minor浮动标签明确需要 glibc 环境 → 使用带-debian后缀的标签。快速上手拉取镜像并验证第一步拉取镜像# latest默认 Alpine体积最小、拉取最快 docker pull usebruno/cli:latest # 精确版本生产 CI 推荐 docker pull usebruno/cli:3.3.0 # major.minor —— 自动获得补丁更新 docker pull usebruno/cli:3.3 # Debian 变体 docker pull usebruno/cli:debian docker pull usebruno/cli:3.3.0-debian验证镜像可用docker run --rm usebruno/cli --version镜像的 ENTRYPOINT 是bru所以该命令等价于在容器里执行bru --version。如果打印出版本号说明 CLI 已正确安装。仓库中配套的发布冒烟测试脚本 packages/bruno-cli/docker/smoke-test.sh 也会用同样方式做首项自检确保每次发版时bru可执行、可输出版本。运行你的集合目录挂载即运行使用姿势可以总结为一句话把存放 Bruno 集合的宿主机目录挂载到容器的/bruno然后在镜像名之后直接追加bru的参数。下面的示例都假定你正位于 Bruno 集合所在目录执行docker。跨平台提示以下示例使用$(pwd)适用于 Bash / Zsh / Git Bash / WSL。在 Windows 原生 Shell 中请把$(pwd)替换为${PWD}PowerShell或%cd%CMD。# 运行当前目录 Bruno 集合中的每一个请求 docker run -v $(pwd):/bruno usebruno/cli run # 运行该集合下的某个子文件夹一组请求 docker run -v $(pwd):/bruno usebruno/cli run ./api-tests # 运行该集合中的单个 .bru 请求文件 docker run -v $(pwd):/bruno usebruno/cli run ./api-tests/login.bru # 产出 JUnit XML 报告因绑定挂载而落在当前目录 docker run -v $(pwd):/bruno usebruno/cli run --reporter-junit results.xmlWindows CMD 用户请用%cd%替换$(pwd)docker run -v %cd%:/bruno usebruno/cli run关于bru run的更多选项——递归执行-r、环境切换、变量覆盖、reporter、--bail等本文后续会结合源码给出说明完整选项表可以在 CLI 的 packages/bruno-cli/src/commands/run.js 中查看builder定义。集合位于其他路径时怎么办如果集合不在当前目录直接把docker的挂载源指向该集合的真实路径相对或绝对路径均可容器内依旧统一挂到/bruno# 运行任意路径下集合的每一个请求 docker run -v /path/to/your/collection:/bruno usebruno/cli run # 运行任意路径下集合中的单个 .bru 文件 docker run -v /path/to/your/collection:/bruno usebruno/cli run ./auth/login.bru关于--rmDocker 在容器退出后默认会保留已停止的容器以便之后通过docker logs或docker inspect排查问题。如果你希望bru一结束 Docker 就自动删除容器——CI 场景常用也能避免docker ps -a堆积陈旧条目——在任意docker run或docker compose run命令后追加--rm即可docker run --rm -v $(pwd):/bruno usebruno/cli run--rm纯粹是清理便利选项不影响镜像、挂载、stdout 输出或退出码因此 CI 中通常可以放心加上。深入理解容器内执行的bru runbru的可执行入口定义在 packages/bruno-cli/src/index.js它基于 yargs 严格模式加载commands目录其中核心的run命令签名是run [paths...]见 packages/bruno-cli/src/commands/run.jspaths...正是你在镜像名后传入的集合路径、文件夹或.bru文件。也就是说docker run ... usebruno/cli run ./api-tests中./api-tests会被当作run的位置参数在容器内解析执行。常用的执行选项源码builder中均有定义包括选项作用说明-r递归运行传入文件夹时递归处理子级请求--env name选择环境运行集合中的某个命名环境--env-file path使用环境文件从.bru/.json环境文件读取支持绝对/相对路径--env-var keyvalue覆盖单个环境变量可多次使用--tests-only只跑带测试的请求仅执行含 test 或启用断言的请求--bail遇错即停请求/测试/断言任一失败即停止执行--delay ms请求间隔每个请求之间的延时毫秒--tags / --exclude-tags按标签筛选仅执行包含/排除指定标签的请求--insecure允许不安全连接关闭证书校验的逃生舱--verbose详细日志便于调试--sandboxJS 沙箱模式safe默认/developer报告输出的两种风格从源码的选项定义看packages/bruno-cli/src/commands/run.js报告支持两种等价写法任选一种风格即可不要混用通用组合--output path --format json|junit|html--output/--format也可写作-o/-f例如 GitHub Actions 示例里的--output results.xml --format junit独立 reporter 开关--reporter-json path、--reporter-junit path、--reporter-html path各自独立、互不影响可同时输出多种格式对应底层 packages/bruno-cli/src/reporters/junit.js 与 packages/bruno-cli/src/reporters/html.js 两个渲染器。另外bru执行结束会在 stdout 打印摘要表格Status / Requests / Tests / Assertions / Duration。发布冒烟脚本 packages/bruno-cli/docker/smoke-test.sh 在解析这段输出时同时兼容新旧两种格式新格式表格Requests | 14 (12 Passed, 2 Failed)旧格式单行Requests: 14, Passed: 12, Failed: 2。这解释了为什么bru的终端输出类似上方 cli-demo 截图中的请求状态与统计在不同版本间可能有格式差异但在容器里行为一致。CI/CD 集成GitHub Actions在.github/workflows中新建 job先actions/checkout拉代码再用docker run挂载github.workspace运行集合最后把 JUnit 结果交给dorny/test-reporter发布报告jobs: api-tests: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Run Bruno collection run: | docker run --rm \ -v ${{ github.workspace }}:/bruno \ usebruno/cli:latest run --output results.xml --format junit - name: Publish Test Report uses: dorny/test-reporterv3 if: success() || failure() with: name: Bruno Test Results path: ${{github.workspace}}/results.xml reporter: java-junit注意--rm被加入以确保每次 CI 运行不留残留容器if: success() || failure()保证即使测试失败即bru以非零码退出也会发布报告方便在 PR 中直接看到失败细节。为复现性考虑生产流水线建议把:latest换成精确版本标签如:3.3.0。GitLab CIGitLab 中更简单——直接把镜像声明为 job 的image脚本里正常使用bruapi-tests: image: usebruno/cli:latest script: - bru run --output results.xml --format junit artifacts: reports: junit: results.xml此处gitlab-runner会把项目目录自动挂载到容器工作目录因此无需手动-v随后通过artifacts.reports.junit声明results.xmlGitLab 即能在 Merge Request 页面上渲染出测试报告。Docker Compose 用法最小示例在项目内放置一份docker-compose.yml把集合目录和报告目录都挂载进来services: bruno-cli: image: usebruno/cli:latest container_name: bruno-cli-runner volumes: - /path/to/collection:/bruno - /path/to/reports:/reports command: run . -r --env ci --reporter-json /reports/results.json --reporter-junit /reports/results.xml --reporter-html /reports/results.html然后运行docker compose run bruno-cli这里的/path/to/reports:/reports挂载会捕获容器内写出的 JSON、JUnit XML 与 HTML 报告到宿主机如果不需要某种格式去掉对应的--reporter-*标志即可。command使用 YAML 列表形式逐项声明参数避免 Shell 转义问题——其中-r表示递归执行run .--env ci切换为ci环境。本仓库自带的可运行示例本仓库内置了一份开箱即用的 Compose 文件 packages/bruno-tests/docker-compose.yml它把同级的collection/目录挂载进容器对echo文件夹以Prod环境执行并把 JSON、JUnit XML、HTML 报告写入packages/bruno-tests/reports/cd packages/bruno-tests docker compose run bruno-cli在发布流程中packages/bruno-cli/docker/smoke-test.sh 还会用类似方式对镜像做端到端验证它使用--mount typebind,source...,target/bruno语法而不是-v这样即使在 Windows 风格路径如C:\repo\collection下也不会与-v的host:container冒号分隔符冲突脚本判断标准是bru能正常输出运行摘要且至少 1 个请求通过而单个测试/断言失败只记为 warning不会阻塞镜像发布。镜像规格与安全基线所有变体统一具备以下规格Entrypointbru工作目录/bruno运行用户nodeUID 1000非 root架构linux/amd64、linux/arm64从 packages/bruno-cli/docker/images/alpine/Dockerfile 可以看到这些规格背后的实现细节声明org.opencontainers.image.*系列 OCI 标签来源仓库、许可证 MIT、文档地址等通过ARG BRUNO_VERSION注入版本并以ENV固化构建时若传入该参数会先用正则^[0-9]\.[0-9]\.[0-9]$校验其为合法 semver再执行npm install -g usebruno/cliversion否则直接报错退出——防止意外安装到错误的版本格式设置LC_ALL、LANG、LANGUAGE为en_US.UTF-8保证容器内日志与输出编码稳定USER node指定非 root 用户运行即使容器被投递到不受信环境也能显著收敛提权面。因此你在宿主机上看到的bru集合文件.bru、环境配置、报告输出需要保证node用户对挂载目录具备读写权限——尤其是写报告到挂载卷时注意避免目录权限问题导致的EACCES。本地构建自定义镜像如果你希望基于官方 Dockerfile 自行构建例如离线环境推送内网镜像仓库可参考各变体 README 中的构建方式从镜像目录相对本 README 为 packages/bruno-cli/docker/images/alpine 或 packages/bruno-cli/docker/images/debian执行# 构建默认最新版 docker build -t usebruno/cli:alpine ./images/alpine # 指定 Bruno CLI 精确版本 docker build \ --build-arg BRUNO_VERSION3.3.0 \ -t usebruno/cli:3.3.0-alpine \ ./images/alpineDebian 变体把./images/alpine换成./images/debian、标签后缀换成-debian即可。构建完成后用上面冒烟测试脚本做一次本地体检版本、非 root 用户、工作目录、--help以及可选的真实集合执行./smoke-test.sh usebruno/cli:alpine ./smoke-test.sh usebruno/cli:alpine /abs/path/to/collection echo Prod小结Bruno CLI Docker 镜像把执行 API 集合这件事完全容器化用major.minor浮动标签跟随补丁、用精确版本标签锁定生产发布-v $(pwd):/bruno一条命令即可把集合塞进容器运行--reporter-*或--output/--format两种风格产出 JUnit 等报告并回传宿主机。结合本仓库的 DockerfileAlpine 默认 / Debian 备选、冒烟脚本 packages/bruno-cli/docker/smoke-test.sh 与开箱示例 packages/bruno-tests/docker-compose.yml你可以直接把这套模式复制进自己的 GitHub Actions、GitLab CI 或本地 Compose 工作流中让 API 测试与代码构建保持同等水准的可复现性。【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考