OneUptime CLI 脚本化与 CI/CD 集成指南环境变量认证、JSON 输出、退出码与流水线自动化【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本指南面向需要将 OneUptime CLI 接入自动化工作流的开发者系统讲解其在脚本与 CI/CD 场景下的核心设计ONEUPTIME_API_KEY/ONEUPTIME_URL环境变量认证、语义化退出码0/1/2/3、-o json机器可读输出、--file从文件创建资源、批量操作以及 GitHub Actions / 通用 CI / Docker 三种流水线接入方式。读完本文你将掌握一套可编程、可解析、可排错的 OneUptime 资源管理脚本范式并能结合仓库源码理解每条命令背后的实现原理。本文以 App/FeatureSet/Docs/Content/en/cli/scripting.md 为骨架辅以 CLI 目录下的源码与测试加以印证。一、为什么 OneUptime CLI 适合自动化三大设计基调OneUptime CLInpm 包名oneuptime/cli是为自动化场景设计的命令行工具其编程友好性体现在三个互相配合的机制上环境变量认证无需交互式login保存上下文即可在无状态脚本中完成认证JSON 输出通过-o json输出可被jq等工具解析的机器可读结果语义化退出码以 0~3 的退出码区分成功、一般错误、认证错误与资源不存在便于流水线精确分支处理。这三个机制在 CLI 入口处均有对应实现。从 CLI/Index.ts 可以看到oneuptime程序暴露了以下全局选项--api-key key API key覆盖配置 --url url OneUptime 实例 URL覆盖配置 --context name 指定使用某个已保存的 context -o, --output fmt 输出格式json / table / wide --no-color 关闭彩色输出适合日志落盘其中--no-color与NO_COLOR环境变量在 CLI/Core/OutputFormatter.ts 中被识别当输出重定向到文件或管道时建议启用避免 ANSI 转义序列污染日志。二、环境变量认证与凭证解析优先级在脚本中最简洁的认证方式是导出两个环境变量export ONEUPTIME_API_KEYsk-your-api-key export ONEUPTIME_URLhttps://oneuptime.com之后所有命令都会自动携带该凭证无需每次传入参数。文档明确环境变量优先于已保存的 context但被 CLI 全局 flag 覆盖。这一优先级规则并非约定而是硬编码在 CLI/Core/ConfigManager.ts 的getResolvedCredentials中完整解析顺序为优先级来源说明1--api-key--url命令行 flag同时提供两者时直接生效2ONEUPTIME_API_KEYONEUPTIME_URL环境变量两者都存在时生效3--context name指定 context从~/.oneuptime/config.json读取对应 API Key 与 URL4当前激活的 context配置文件中的currentContext5部分环境变量 部分 context例如只设置了ONEUPTIME_API_KEY时URL 回退到当前 context—全部缺失抛出No credentials found错误退出码 2值得注意的边界行为优先级 2 要求两个环境变量同时存在。若只设置其中一个解析器会继续向后回退把缺失项用当前 context 补齐见getResolvedCredentials中 Partial env vars partial context 分支。这意味着混用环境变量与保存的 context 时需确认预期行为。context 文件位于~/.oneuptime/config.json写入时以0o600权限保存见 CLI/Core/ConfigManager.ts避免 API Key 明文权限过宽。上述优先级在 CLI/Tests/ConfigManager.test.ts 中有完整单测覆盖包括 CLI flags 优先于 env vars、env vars 优先于 context、--context指向不存在 context 时报错等场景。# 仅设置部分环境变量时缺失项会回退到当前 context export ONEUPTIME_API_KEYsk-your-api-key oneuptime monitor list # URL 来自 ~/.oneuptime/config.json 中的当前 context三、退出码约定让脚本精确分流错误OneUptime CLI 将退出码语义化方便流水线判断失败原因。文档给出的约定如下退出码含义0成功1一般错误2认证错误凭据缺失或无效3资源不存在404这些常量定义在 CLI/Core/ErrorHandler.ts 的ExitCode枚举中并有 CLI/Tests/ErrorHandler.test.ts 直接断言枚举值。handleError通过错误消息的特征关键词完成归类CLI/Core/ErrorHandler.ts消息包含API key/credentials/Unauthorized/401→ 退出码2认证错误消息包含404/not found→ 退出码3资源不存在消息包含API error如 500→ 退出码1一般错误其余未知错误 → 退出码1。在脚本中利用退出码处理错误if ! oneuptime monitor list /dev/null 21; then echo Failed to list monitors exit 1 fi更细化的分支可以区分认证失败与资源不存在oneuptime incident get 66f0abc123 2/dev/null case $? in 0) echo incident found ;; 2) echo auth problem, check ONEUPTIME_API_KEY ;; 3) echo incident not found, nothing to do ;; *) echo general failure ;; esac注意错误信息统一通过console.error输出到 stderr见 CLI/Core/OutputFormatter.ts 的printError因此2/dev/null或21的重定向处理不会干扰 stdout 上的正常 JSON 数据流。四、JSON 输出与 jq 组合处理-o json让命令输出严格合法的 JSONJSON.stringify(data, null, 2)格式化见 CLI/Core/OutputFormatter.ts可安全交给jq解析# 提取所有 incident 的标题 oneuptime incident list -o json | jq .[].title # 获取新建 monitor 的 IDcreate 返回对象中的 _id 字段 NEW_ID$(oneuptime monitor create --data {name:API Health} -o json | jq -r ._id) echo Created monitor: $NEW_ID # 按 severity 统计 incident 数量 oneuptime incident count --query {incidentSeverityId:severity-id}4.1 管道场景下自动切换 JSON一个容易被忽视但非常实用的实现细节当 stdout 不是 TTY即输出被管道或重定向时CLI 会自动默认使用 JSON 输出。这由 CLI/Core/OutputFormatter.ts 的detectOutputFormat决定// If stdout is not a TTY (piped), default to JSON if (!process.stdout.isTTY) { return OutputFormat.JSON; } return OutputFormat.Table;也就是说oneuptime monitor list | jq .[]._id即使不写-o json也能工作而在交互式终端中默认是table表格默认列截断逻辑见同文件formatTable非 wide 模式下最多保留 6 列并优先_id、name、title、status、createdAt、updatedAt。4.2 count 命令输出纯数字count命令与list不同它直接打印数字而非 JSON 对象——在 CLI/Commands/ResourceCommands.ts 的registerCountCommand中当响应包含count字段时直接console.log(count)。因此INCIDENT_COUNT$(oneuptime incident count)拿到的就是一个可直接参与算术比较的整数这也是下节 CI 示例能写[ $INCIDENT_COUNT -gt 0 ]的原因。4.3 查询、排序与分页参数list命令支持完整的查询控制参数定义在 CLI/Commands/ResourceCommands.ts参数默认值说明--query json空MongoDB 风格过滤条件如{monitorId:id}--limit n10最大返回条数--skip n0跳过的条数用于分页--sort json空排序规则如{createdAt:-1}-o, --output fmt自动json/table/wide默认limit 10同时存在于 CLI/Core/ConfigManager.ts 的默认配置中因此在脚本中遍历全量数据时务必显式调大--limit或配合--skip翻页否则只能拿到前 10 条。五、从文件创建资源把基础设施写进版本库使用--file可以从 JSON 文件读取资源数据创建资源适合将监控配置纳入 Git 版本管理# monitor.json # { # name: API Health Check, # projectId: your-project-id # } oneuptime monitor create --file monitor.json从源码看create命令接受--data json内联 JSON与--file pathJSON 文件两种数据来源CLI/Commands/ResourceCommands.tsif (options.file) { const fileContent: string fs.readFileSync(options.file, utf-8); data JSON.parse(fileContent) as JSONObject; } else if (options.data) { data parseJsonArg(options.data); } else { throw new Error(Either --data or --file is required for create.); }两者二选一都缺时会直接报错退出码 1。组合使用惯例# 从版本库中的文件批量初始化并把新 ID 落盘以便后续更新 NEW_ID$(oneuptime monitor create --file config/monitors/api-health.json -o json | jq -r ._id) echo $NEW_ID .oneuptime/monitor-id除create外update id也支持--data且为必填delete id支持--force跳过确认get id用于按 ID 读取单个对象。六、批量操作循环处理 JSON 数组批量创建资源时最直接的方式是把多个资源定义放进一个 JSON 数组文件逐条循环# 从 JSON 数组文件创建多个 monitor cat monitors.json | jq -r .[] | json | while read monitor; do oneuptime monitor create --data $monitor done其中jq -r .[] | json的作用是把数组中的每个对象序列化为一行紧凑 JSON逐行喂给--data。两个实战建议失败隔离循环内不要直接依赖set -e整体退出建议捕获单条失败并记录最后统一统计ok0; failed0 while read -r monitor; do if oneuptime monitor create --data $monitor /dev/null 21; then ok$((ok1)) else echo failed: $monitor 2 failed$((failed1)) fi done (cat monitors.json | jq -c .[]) echo created$ok failed$failed [ $failed -eq 0 ] || exit 1幂等设计create是追加式操作重复执行同一脚本会创建重复资源。对于希望幂等的场景可以先list --query检查是否已存在再决定create或update。七、CI/CD 流水线实战示例7.1 GitHub Actions定时巡检活跃 Incident以下工作流每 5 分钟检查一次是否有活跃 incident若存在则让任务失败以触发告警name: Check Active Incidents on: schedule: - cron: */5 * * * * jobs: health-check: runs-on: ubuntu-latest steps: - name: Install OneUptime CLI run: npm install -g oneuptime/cli - name: Check for active incidents env: ONEUPTIME_API_KEY: ${{ secrets.ONEUPTIME_API_KEY }} ONEUPTIME_URL: https://oneuptime.com run: | INCIDENT_COUNT$(oneuptime incident count) if [ $INCIDENT_COUNT -gt 0 ]; then echo WARNING: $INCIDENT_COUNT incidents found exit 1 fi要点拆解通过env注入两个环境变量避免 Key 出现在日志或命令行参数中ONEUPTIME_API_KEY放在 GitHub Secrets 中符合最小暴露原则count输出纯数字天然适合数值比较主动exit 1让流水线步骤失败可触发告警通知。若希望按严重级别细分可结合查询参数CRITICAL$(oneuptime incident count --query {incidentSeverityId:critical-severity-id}) echo critical incidents: $CRITICAL7.2 通用 CI/CD 脚本用 Incident 记录部署生命周期在部署流水线中可以在发布开始时创建一条 incident、部署完成后关闭它形成完整的变更审计记录#!/bin/bash set -e export ONEUPTIME_API_KEY$CI_ONEUPTIME_API_KEY export ONEUPTIME_URL$CI_ONEUPTIME_URL # 创建部署事件并捕获 ID # 注意currentIncidentStateId 与 incidentSeverityId 必须引用项目中已存在的状态/严重级别 ID INCIDENT_ID$(oneuptime incident create --data { title: Deployment Started, currentIncidentStateId: $INVESTIGATING_STATE_ID, incidentSeverityId: $SEVERITY_ID, declaredAt: $(date -u %Y-%m-%dT%H:%M:%SZ) } -o json | jq -r ._id) # 执行部署步骤... # 部署成功后关闭 incident oneuptime incident update $INCIDENT_ID --data {currentIncidentStateId:$RESOLVED_STATE_ID}几点说明$VAR是 Bash 中在 JSON 字符串里内插 shell 变量的标准写法$(date -u ...)生成 UTC 时间戳保证declaredAt符合 ISO 8601 格式set -e保证任一步失败即中止若create因认证失败退出码为 2流水线立即失败不会带着空 ID 继续建议在set -e之外单独处理部署失败也要关闭/标记 incident的场景例如在trap中做清理避免 incident 永远停留在 Investigating 状态为了让脚本更稳健可在update前校验INCIDENT_ID非空[ -n $INCIDENT_ID ] || exit 1。7.3 Docker容器化的 CLI 运行环境将 CLI 封装进镜像可在任意容器环境如 Kubernetes Job、自建 Runner中运行FROM node:26-slim RUN npm install -g oneuptime/cli ENV ONEUPTIME_API_KEY ENV ONEUPTIME_URL ENTRYPOINT [oneuptime]docker run --rm \ -e ONEUPTIME_API_KEYsk-abc123 \ -e ONEUPTIME_URLhttps://oneuptime.com \ oneuptime-cli incident list--rm确保容器执行完即清理不残留中间状态通过-e注入凭证镜像内不固化任何密钥ENTRYPOINT [oneuptime]使得docker run ... oneuptime-cli subcommand直接等同于执行 CLI 子命令也便于在 K8s CronJob 中按调度执行巡检任务。八、脚本中指定 Context多环境切换若已通过oneuptime login保存了多个 context例如生产、预发可以在脚本中显式指定使用哪一个而不依赖当前激活 context这个可变状态oneuptime --context production incident list oneuptime --context staging monitor count--context是全局选项命令解析时通过getParentOptions向上回溯到根 program 读取CLI/Commands/ResourceCommands.ts。与之配合的 context 管理命令定义在 CLI/Commands/ConfigCommands.tsoneuptime login api-key instance-url --context-name production # 新增 context oneuptime context list # 列出全部 context oneuptime context use staging # 切换当前 context oneuptime context current # 查看当前 contextAPI Key 打码显示 oneuptime context delete staging # 删除 context组合用法——固定用某个 context 环境变量覆盖也可以共存因为优先级是 flag 环境变量 context。例如默认用--context production但临时用环境变量指向其他实例时环境变量会覆盖 context 中的 URL注意两者是同一优先级组的整体替换规则需同时设置ONEUPTIME_API_KEY与ONEUPTIME_URL才走优先级 2。九、脚本前的快速自检与排障在编写长脚本之前建议先用以下命令确认环境就绪# 确认安装与版本 oneuptime version # 或 oneuptime --version # 确认认证与目标实例显示打码后的 API Key oneuptime whoami # 查看当前可操作的资源类型及对应的 API 路径 oneuptime resources # 只看分析型资源 oneuptime resources --type analytics排障参考路径认证失败退出码 2检查ONEUPTIME_API_KEY/ONEUPTIME_URL是否同时导出或~/.oneuptime/config.json中 context 是否有效资源不存在退出码 3确认 ID 拼写或资源所属项目是否与当前 context 匹配JSON 解析失败确认--data/--query传入的是合法 JSONparseJsonArg会直接抛出Invalid JSON见 CLI/Commands/ResourceCommands.ts返回条数不符合预期检查--limit是否被默认值 10 截断输出被 ANSI 转义符污染日志场景下添加--no-color或导出NO_COLOR。十、小结OneUptime CLI 的脚本化能力由四个支柱构成环境变量认证无状态、可注入、语义化退出码可分支、可告警、JSON 输出可解析、管道友好以及--file/--data数据入口可版本化、可批量。它们分别对应仓库中的 ConfigManager.ts凭证解析优先级、ErrorHandler.ts退出码映射、OutputFormatter.tsTTY 自动切换 JSON与 ResourceCommands.tsCRUD 参数实现并有 CLI/Tests 下的单测为这些行为背书。将其组合进 GitHub Actions、通用 CI 脚本或 Docker 容器即可构建出从变更声明到监控巡检再到事件闭环的完整自动化链路。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OneUptime CLI 脚本化与 CI/CD 集成指南：环境变量认证、JSON 输出、退出码与流水线自动化
OneUptime CLI 脚本化与 CI/CD 集成指南环境变量认证、JSON 输出、退出码与流水线自动化【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本指南面向需要将 OneUptime CLI 接入自动化工作流的开发者系统讲解其在脚本与 CI/CD 场景下的核心设计ONEUPTIME_API_KEY/ONEUPTIME_URL环境变量认证、语义化退出码0/1/2/3、-o json机器可读输出、--file从文件创建资源、批量操作以及 GitHub Actions / 通用 CI / Docker 三种流水线接入方式。读完本文你将掌握一套可编程、可解析、可排错的 OneUptime 资源管理脚本范式并能结合仓库源码理解每条命令背后的实现原理。本文以 App/FeatureSet/Docs/Content/en/cli/scripting.md 为骨架辅以 CLI 目录下的源码与测试加以印证。一、为什么 OneUptime CLI 适合自动化三大设计基调OneUptime CLInpm 包名oneuptime/cli是为自动化场景设计的命令行工具其编程友好性体现在三个互相配合的机制上环境变量认证无需交互式login保存上下文即可在无状态脚本中完成认证JSON 输出通过-o json输出可被jq等工具解析的机器可读结果语义化退出码以 0~3 的退出码区分成功、一般错误、认证错误与资源不存在便于流水线精确分支处理。这三个机制在 CLI 入口处均有对应实现。从 CLI/Index.ts 可以看到oneuptime程序暴露了以下全局选项--api-key key API key覆盖配置 --url url OneUptime 实例 URL覆盖配置 --context name 指定使用某个已保存的 context -o, --output fmt 输出格式json / table / wide --no-color 关闭彩色输出适合日志落盘其中--no-color与NO_COLOR环境变量在 CLI/Core/OutputFormatter.ts 中被识别当输出重定向到文件或管道时建议启用避免 ANSI 转义序列污染日志。二、环境变量认证与凭证解析优先级在脚本中最简洁的认证方式是导出两个环境变量export ONEUPTIME_API_KEYsk-your-api-key export ONEUPTIME_URLhttps://oneuptime.com之后所有命令都会自动携带该凭证无需每次传入参数。文档明确环境变量优先于已保存的 context但被 CLI 全局 flag 覆盖。这一优先级规则并非约定而是硬编码在 CLI/Core/ConfigManager.ts 的getResolvedCredentials中完整解析顺序为优先级来源说明1--api-key--url命令行 flag同时提供两者时直接生效2ONEUPTIME_API_KEYONEUPTIME_URL环境变量两者都存在时生效3--context name指定 context从~/.oneuptime/config.json读取对应 API Key 与 URL4当前激活的 context配置文件中的currentContext5部分环境变量 部分 context例如只设置了ONEUPTIME_API_KEY时URL 回退到当前 context—全部缺失抛出No credentials found错误退出码 2值得注意的边界行为优先级 2 要求两个环境变量同时存在。若只设置其中一个解析器会继续向后回退把缺失项用当前 context 补齐见getResolvedCredentials中 Partial env vars partial context 分支。这意味着混用环境变量与保存的 context 时需确认预期行为。context 文件位于~/.oneuptime/config.json写入时以0o600权限保存见 CLI/Core/ConfigManager.ts避免 API Key 明文权限过宽。上述优先级在 CLI/Tests/ConfigManager.test.ts 中有完整单测覆盖包括 CLI flags 优先于 env vars、env vars 优先于 context、--context指向不存在 context 时报错等场景。# 仅设置部分环境变量时缺失项会回退到当前 context export ONEUPTIME_API_KEYsk-your-api-key oneuptime monitor list # URL 来自 ~/.oneuptime/config.json 中的当前 context三、退出码约定让脚本精确分流错误OneUptime CLI 将退出码语义化方便流水线判断失败原因。文档给出的约定如下退出码含义0成功1一般错误2认证错误凭据缺失或无效3资源不存在404这些常量定义在 CLI/Core/ErrorHandler.ts 的ExitCode枚举中并有 CLI/Tests/ErrorHandler.test.ts 直接断言枚举值。handleError通过错误消息的特征关键词完成归类CLI/Core/ErrorHandler.ts消息包含API key/credentials/Unauthorized/401→ 退出码2认证错误消息包含404/not found→ 退出码3资源不存在消息包含API error如 500→ 退出码1一般错误其余未知错误 → 退出码1。在脚本中利用退出码处理错误if ! oneuptime monitor list /dev/null 21; then echo Failed to list monitors exit 1 fi更细化的分支可以区分认证失败与资源不存在oneuptime incident get 66f0abc123 2/dev/null case $? in 0) echo incident found ;; 2) echo auth problem, check ONEUPTIME_API_KEY ;; 3) echo incident not found, nothing to do ;; *) echo general failure ;; esac注意错误信息统一通过console.error输出到 stderr见 CLI/Core/OutputFormatter.ts 的printError因此2/dev/null或21的重定向处理不会干扰 stdout 上的正常 JSON 数据流。四、JSON 输出与 jq 组合处理-o json让命令输出严格合法的 JSONJSON.stringify(data, null, 2)格式化见 CLI/Core/OutputFormatter.ts可安全交给jq解析# 提取所有 incident 的标题 oneuptime incident list -o json | jq .[].title # 获取新建 monitor 的 IDcreate 返回对象中的 _id 字段 NEW_ID$(oneuptime monitor create --data {name:API Health} -o json | jq -r ._id) echo Created monitor: $NEW_ID # 按 severity 统计 incident 数量 oneuptime incident count --query {incidentSeverityId:severity-id}4.1 管道场景下自动切换 JSON一个容易被忽视但非常实用的实现细节当 stdout 不是 TTY即输出被管道或重定向时CLI 会自动默认使用 JSON 输出。这由 CLI/Core/OutputFormatter.ts 的detectOutputFormat决定// If stdout is not a TTY (piped), default to JSON if (!process.stdout.isTTY) { return OutputFormat.JSON; } return OutputFormat.Table;也就是说oneuptime monitor list | jq .[]._id即使不写-o json也能工作而在交互式终端中默认是table表格默认列截断逻辑见同文件formatTable非 wide 模式下最多保留 6 列并优先_id、name、title、status、createdAt、updatedAt。4.2 count 命令输出纯数字count命令与list不同它直接打印数字而非 JSON 对象——在 CLI/Commands/ResourceCommands.ts 的registerCountCommand中当响应包含count字段时直接console.log(count)。因此INCIDENT_COUNT$(oneuptime incident count)拿到的就是一个可直接参与算术比较的整数这也是下节 CI 示例能写[ $INCIDENT_COUNT -gt 0 ]的原因。4.3 查询、排序与分页参数list命令支持完整的查询控制参数定义在 CLI/Commands/ResourceCommands.ts参数默认值说明--query json空MongoDB 风格过滤条件如{monitorId:id}--limit n10最大返回条数--skip n0跳过的条数用于分页--sort json空排序规则如{createdAt:-1}-o, --output fmt自动json/table/wide默认limit 10同时存在于 CLI/Core/ConfigManager.ts 的默认配置中因此在脚本中遍历全量数据时务必显式调大--limit或配合--skip翻页否则只能拿到前 10 条。五、从文件创建资源把基础设施写进版本库使用--file可以从 JSON 文件读取资源数据创建资源适合将监控配置纳入 Git 版本管理# monitor.json # { # name: API Health Check, # projectId: your-project-id # } oneuptime monitor create --file monitor.json从源码看create命令接受--data json内联 JSON与--file pathJSON 文件两种数据来源CLI/Commands/ResourceCommands.tsif (options.file) { const fileContent: string fs.readFileSync(options.file, utf-8); data JSON.parse(fileContent) as JSONObject; } else if (options.data) { data parseJsonArg(options.data); } else { throw new Error(Either --data or --file is required for create.); }两者二选一都缺时会直接报错退出码 1。组合使用惯例# 从版本库中的文件批量初始化并把新 ID 落盘以便后续更新 NEW_ID$(oneuptime monitor create --file config/monitors/api-health.json -o json | jq -r ._id) echo $NEW_ID .oneuptime/monitor-id除create外update id也支持--data且为必填delete id支持--force跳过确认get id用于按 ID 读取单个对象。六、批量操作循环处理 JSON 数组批量创建资源时最直接的方式是把多个资源定义放进一个 JSON 数组文件逐条循环# 从 JSON 数组文件创建多个 monitor cat monitors.json | jq -r .[] | json | while read monitor; do oneuptime monitor create --data $monitor done其中jq -r .[] | json的作用是把数组中的每个对象序列化为一行紧凑 JSON逐行喂给--data。两个实战建议失败隔离循环内不要直接依赖set -e整体退出建议捕获单条失败并记录最后统一统计ok0; failed0 while read -r monitor; do if oneuptime monitor create --data $monitor /dev/null 21; then ok$((ok1)) else echo failed: $monitor 2 failed$((failed1)) fi done (cat monitors.json | jq -c .[]) echo created$ok failed$failed [ $failed -eq 0 ] || exit 1幂等设计create是追加式操作重复执行同一脚本会创建重复资源。对于希望幂等的场景可以先list --query检查是否已存在再决定create或update。七、CI/CD 流水线实战示例7.1 GitHub Actions定时巡检活跃 Incident以下工作流每 5 分钟检查一次是否有活跃 incident若存在则让任务失败以触发告警name: Check Active Incidents on: schedule: - cron: */5 * * * * jobs: health-check: runs-on: ubuntu-latest steps: - name: Install OneUptime CLI run: npm install -g oneuptime/cli - name: Check for active incidents env: ONEUPTIME_API_KEY: ${{ secrets.ONEUPTIME_API_KEY }} ONEUPTIME_URL: https://oneuptime.com run: | INCIDENT_COUNT$(oneuptime incident count) if [ $INCIDENT_COUNT -gt 0 ]; then echo WARNING: $INCIDENT_COUNT incidents found exit 1 fi要点拆解通过env注入两个环境变量避免 Key 出现在日志或命令行参数中ONEUPTIME_API_KEY放在 GitHub Secrets 中符合最小暴露原则count输出纯数字天然适合数值比较主动exit 1让流水线步骤失败可触发告警通知。若希望按严重级别细分可结合查询参数CRITICAL$(oneuptime incident count --query {incidentSeverityId:critical-severity-id}) echo critical incidents: $CRITICAL7.2 通用 CI/CD 脚本用 Incident 记录部署生命周期在部署流水线中可以在发布开始时创建一条 incident、部署完成后关闭它形成完整的变更审计记录#!/bin/bash set -e export ONEUPTIME_API_KEY$CI_ONEUPTIME_API_KEY export ONEUPTIME_URL$CI_ONEUPTIME_URL # 创建部署事件并捕获 ID # 注意currentIncidentStateId 与 incidentSeverityId 必须引用项目中已存在的状态/严重级别 ID INCIDENT_ID$(oneuptime incident create --data { title: Deployment Started, currentIncidentStateId: $INVESTIGATING_STATE_ID, incidentSeverityId: $SEVERITY_ID, declaredAt: $(date -u %Y-%m-%dT%H:%M:%SZ) } -o json | jq -r ._id) # 执行部署步骤... # 部署成功后关闭 incident oneuptime incident update $INCIDENT_ID --data {currentIncidentStateId:$RESOLVED_STATE_ID}几点说明$VAR是 Bash 中在 JSON 字符串里内插 shell 变量的标准写法$(date -u ...)生成 UTC 时间戳保证declaredAt符合 ISO 8601 格式set -e保证任一步失败即中止若create因认证失败退出码为 2流水线立即失败不会带着空 ID 继续建议在set -e之外单独处理部署失败也要关闭/标记 incident的场景例如在trap中做清理避免 incident 永远停留在 Investigating 状态为了让脚本更稳健可在update前校验INCIDENT_ID非空[ -n $INCIDENT_ID ] || exit 1。7.3 Docker容器化的 CLI 运行环境将 CLI 封装进镜像可在任意容器环境如 Kubernetes Job、自建 Runner中运行FROM node:26-slim RUN npm install -g oneuptime/cli ENV ONEUPTIME_API_KEY ENV ONEUPTIME_URL ENTRYPOINT [oneuptime]docker run --rm \ -e ONEUPTIME_API_KEYsk-abc123 \ -e ONEUPTIME_URLhttps://oneuptime.com \ oneuptime-cli incident list--rm确保容器执行完即清理不残留中间状态通过-e注入凭证镜像内不固化任何密钥ENTRYPOINT [oneuptime]使得docker run ... oneuptime-cli subcommand直接等同于执行 CLI 子命令也便于在 K8s CronJob 中按调度执行巡检任务。八、脚本中指定 Context多环境切换若已通过oneuptime login保存了多个 context例如生产、预发可以在脚本中显式指定使用哪一个而不依赖当前激活 context这个可变状态oneuptime --context production incident list oneuptime --context staging monitor count--context是全局选项命令解析时通过getParentOptions向上回溯到根 program 读取CLI/Commands/ResourceCommands.ts。与之配合的 context 管理命令定义在 CLI/Commands/ConfigCommands.tsoneuptime login api-key instance-url --context-name production # 新增 context oneuptime context list # 列出全部 context oneuptime context use staging # 切换当前 context oneuptime context current # 查看当前 contextAPI Key 打码显示 oneuptime context delete staging # 删除 context组合用法——固定用某个 context 环境变量覆盖也可以共存因为优先级是 flag 环境变量 context。例如默认用--context production但临时用环境变量指向其他实例时环境变量会覆盖 context 中的 URL注意两者是同一优先级组的整体替换规则需同时设置ONEUPTIME_API_KEY与ONEUPTIME_URL才走优先级 2。九、脚本前的快速自检与排障在编写长脚本之前建议先用以下命令确认环境就绪# 确认安装与版本 oneuptime version # 或 oneuptime --version # 确认认证与目标实例显示打码后的 API Key oneuptime whoami # 查看当前可操作的资源类型及对应的 API 路径 oneuptime resources # 只看分析型资源 oneuptime resources --type analytics排障参考路径认证失败退出码 2检查ONEUPTIME_API_KEY/ONEUPTIME_URL是否同时导出或~/.oneuptime/config.json中 context 是否有效资源不存在退出码 3确认 ID 拼写或资源所属项目是否与当前 context 匹配JSON 解析失败确认--data/--query传入的是合法 JSONparseJsonArg会直接抛出Invalid JSON见 CLI/Commands/ResourceCommands.ts返回条数不符合预期检查--limit是否被默认值 10 截断输出被 ANSI 转义符污染日志场景下添加--no-color或导出NO_COLOR。十、小结OneUptime CLI 的脚本化能力由四个支柱构成环境变量认证无状态、可注入、语义化退出码可分支、可告警、JSON 输出可解析、管道友好以及--file/--data数据入口可版本化、可批量。它们分别对应仓库中的 ConfigManager.ts凭证解析优先级、ErrorHandler.ts退出码映射、OutputFormatter.tsTTY 自动切换 JSON与 ResourceCommands.tsCRUD 参数实现并有 CLI/Tests 下的单测为这些行为背书。将其组合进 GitHub Actions、通用 CI 脚本或 Docker 容器即可构建出从变更声明到监控巡检再到事件闭环的完整自动化链路。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考