OneUptime CLI 完整指南多环境认证、资源 CRUD 与 CI/CD 自动化【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文以 OneUptime 官方 CLI 文档CLI 文档入口为核心骨架展开覆盖 CLI 的安装与快速上手、多环境上下文认证机制、资源的自动发现与完整 CRUD 操作、三种输出格式、以及面向 CI/CD 的脚本化用法并结合仓库内CLI/目录的源码实现解释凭据解析优先级、配置落盘权限、API 路由映射等底层细节帮助你把 OneUptime 的监控资源管理完整地搬进终端与流水线。一、CLI 定位与核心特性OneUptime CLI 是面向 OneUptime 实例的命令行管理工具允许你直接从终端对 OneUptime 资源执行完整的 CRUD 操作监控器、事件、告警、状态页等。根据官方文档它的核心特性包括多环境支持通过命名上下文context管理生产、预发布、开发等不同环境自动资源发现从 OneUptime 实例中自动发现可操作的资源类型无需硬编码资源列表灵活认证支持 CLI 参数、环境变量、已保存上下文三种凭据来源且可混合使用智能输出格式化提供json、table、wide三种输出视图可脚本化适配 CI/CD 流水线与自动化工作流具备明确的退出码约定。从源码结构看整个 CLI 由入口文件 CLI/Index.ts 组装它基于commander框架创建根命令并注册三大命令组——配置命令login/context/whoami、工具命令resources/version 等与资源命令自动发现后为每类资源动态注册子命令。入口文件中同时声明了所有全局参数--api-key、--url、--context、-o/--output、--no-color版本号为1.0.0见 CLI/Index.ts#L10-L25。二、安装与快速上手安装通过 npm 全局安装官方发布的包npm install -g oneuptime/cli快速开始# 1. 使用 API 密钥认证到 OneUptime 实例 oneuptime login your-api-key https://oneuptime.com # 2. 列出你的监控器 oneuptime monitor list # 3. 查看某个具体事件incident oneuptime incident get incident-id # 4. 查看实例上所有可用的资源类型 oneuptime resources这四步构成最小可用闭环先认证、再读取、最后通过resources命令确认当前实例暴露了哪些可操作资源。三、认证与多环境上下文CLI 支持三种认证入口命名上下文、环境变量、或直接以参数传入凭据详见 认证文档。3.1 login登录并创建上下文oneuptime login api-key instance-url参数/选项说明api-keyOneUptime API 密钥例如sk-your-api-keyinstance-url实例 URL例如https://oneuptime.com--context-name name该上下文的名称默认为default示例# 登录到默认上下文 oneuptime login sk-abc123 https://oneuptime.com # 使用命名上下文登录 oneuptime login sk-abc123 https://oneuptime.com --context-name production # 同时配置多个环境 oneuptime login sk-prod-key https://oneuptime.com --context-name production oneuptime login sk-staging-key https://staging.oneuptime.com --context-name staging从源码看login 动作会做三件事见 CLI/Commands/ConfigCommands.ts#L19-L44将实例 URL 尾部的斜杠统一剥除instanceUrl.replace(/\/$/, )以便规范化比较通过ConfigManager.addContext把上下文写入配置随后setCurrentContext将该上下文设为当前活跃上下文。也就是说登录即切换新登录的环境会立即可用。3.2 上下文管理命令作用oneuptime context list列出所有已配置上下文当前上下文以*标记oneuptime context use name切换到指定上下文oneuptime context current显示当前上下文名称、实例 URL 与打码后的 API 密钥oneuptime context delete name删除指定上下文oneuptime context use staging # 切到预发布环境 oneuptime context use production # 切回生产环境 oneuptime context current # 确认当前环境 oneuptime context delete staging # 清理不再使用的环境两个实现细节值得注意删除回退逻辑removeContext在删除当前活跃上下文时会自动把currentContext回退到剩余上下文中的第一个无剩余则置空见 CLI/Core/ConfigManager.ts#L67-L78密钥打码规则context current展示密钥时长度超过 8 位则显示前 4 位 **** 后 4 位否则整体显示为****见 CLI/Commands/ConfigCommands.ts#L113-L118。3.3 凭据解析优先级CLI 按以下优先级依次解析认证信息前者优先CLI 参数--api-key与--url环境变量ONEUPTIME_API_KEY与ONEUPTIME_URL指定上下文--context name指向的已保存上下文当前活跃上下文配置文件中的currentContext这个顺序在源码getResolvedCredentials中有明确实现见 CLI/Core/ConfigManager.ts#L98-L141。此外源码还揭示了一个文档未展开的混合模式当环境变量只提供了 API 密钥或 URL 之一时缺失的那一项会自动从当前上下文补齐见 CLI/Core/ConfigManager.ts#L129-L136如果四种来源都解析不出完整凭据则抛出错误并提示执行oneuptime login。三种典型用法# 1. 直接传参最高优先级 oneuptime --api-key sk-abc123 --url https://oneuptime.com incident list # 2. 环境变量 export ONEUPTIME_API_KEYsk-abc123 export ONEUPTIME_URLhttps://oneuptime.com oneuptime incident list # 3. 指定上下文 oneuptime --context production incident list3.4 whoami确认认证状态oneuptime whoami输出包括实例 URL、打码后的 API 密钥若有已保存上下文处于激活状态还会显示上下文名称。未认证时命令会打印一条引导信息提示先执行oneuptime login。3.5 配置文件凭据保存在用户主目录下的~/.oneuptime/config.json。源码中save函数以0o600仅属主可读写的文件权限写入避免 API 密钥被同机其他用户读取见 CLI/Core/ConfigManager.ts#L32-L39。配置文件结构示例{ currentContext: production, contexts: { production: { name: production, apiUrl: https://oneuptime.com, apiKey: sk-... }, staging: { name: staging, apiUrl: https://staging.oneuptime.com, apiKey: sk-... } }, defaults: { output: table, limit: 10 } }其中defaults的默认值输出格式table、分页大小10与源码getDefaultConfig的初始化逻辑一致见 CLI/Core/ConfigManager.ts#L9-L18。四、资源操作自动发现与完整 CRUD4.1 资源自动发现OneUptime 的资源列表不是写死在 CLI 里的而是运行时自动发现的。oneuptime resources列出实例上所有可操作资源可用--type过滤oneuptime resources # 全部资源 oneuptime resources --type database # 仅数据库类资源 oneuptime resources --type analytics # 仅分析类资源源码实现见 CLI/Commands/ResourceCommands.ts#L30-L82CLI 遍历Common/Models/DatabaseModels与Common/Models/AnalyticsModels中的全部模型类仅当模型同时满足「有表名 开启 MCP 能力enableMCP 声明了 CRUD API 路径crudApiPath」三个条件时才注册为可操作资源。资源命令名由模型单数名经toKebabCase转换生成——这正是「Status Page」变成status-page、「On-Call Policy」变成on-call-policy的原因。常见资源与命令对照资源命令Incidentoneuptime incidentAlertoneuptime alertMonitoroneuptime monitorMonitor Statusoneuptime monitor-statusIncident Stateoneuptime incident-stateStatus Pageoneuptime status-pageOn-Call Policyoneuptime on-call-policyTeamoneuptime teamScheduled Maintenance Eventoneuptime scheduled-maintenance-event数据库类资源注册完整的六个子命令list/get/create/update/delete/count分析类资源仅注册 list/create/count见 CLI/Commands/ResourceCommands.ts#L331-L356与文档中「Analytics 资源受限操作」的说明完全对应操作Analytics 资源支持情况list支持create支持count支持get/update/delete不支持4.2 list过滤、分页与排序oneuptime resource list [options]选项说明默认值--query jsonJSON 格式的过滤条件无--limit n最大返回条数10--skip n跳过的结果数分页0--sort jsonJSON 格式的排序规则无-o, --output format输出格式table--limit 10与--skip 0的默认值直接来自 commander 的 option 默认参数见 CLI/Commands/ResourceCommands.ts#L102-L109。示例# 列出最近 10 个 incident oneuptime incident list # 按状态 ID 过滤 oneuptime incident list --query {currentIncidentStateId:state-id} # 分页跳过 40 条、取 20 条 oneuptime incident list --limit 20 --skip 40 # 按创建时间倒序 oneuptime incident list --sort {createdAt:-1} # JSON 输出 oneuptime incident list -o json4.3 get / create / update / delete / countget按 ID 获取单个资源UUID。oneuptime incident get 550e8400-e29b-41d4-a716-446655440000 oneuptime monitor get abc-123 -o jsoncreate从内联 JSON 或文件创建资源--data与--file二者必选其一源码中缺省会直接抛出Either --data or --file is required for create.见 CLI/Commands/ResourceCommands.ts#L200-L209。# 内联 JSON 创建 incident oneuptime incident create --data {title:API Outage,currentIncidentStateId:state-id,incidentSeverityId:severity-id,declaredAt:2025-01-15T10:30:00Z} # 从 JSON 文件创建 oneuptime incident create --file incident.json # 创建后以 JSON 输出以便捕获新资源 ID oneuptime monitor create --data {name:API Health Check} -o jsonupdate按 ID 局部更新--data为必填项源码中使用requiredOption声明见 CLI/Commands/ResourceCommands.ts#L236-L239。# 将 incident 流转到已解决状态 oneuptime incident update abc-123 --data {currentIncidentStateId:resolved-state-id} # 重命名监控器 oneuptime monitor update abc-123 --data {name:Updated Monitor Name}delete按 ID 删除默认带确认提示--force跳过。oneuptime incident delete abc-123 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 --forcecount统计匹配过滤条件的资源数量响应体中的count字段会被提取后直接以数字形式打印见 CLI/Commands/ResourceCommands.ts#L312-L324。oneuptime incident count oneuptime incident count --query {currentIncidentStateId:state-id} oneuptime monitor count4.4 命令与 API 端点的映射所有资源命令最终收敛到 API 客户端。buildApiRoute按操作类型构造目标路由见 CLI/Core/ApiClient.ts#L33-L65与官方文档给出的映射表一致命令HTTP 方法端点listPOST/api/resource/get-listgetPOST/api/resource/id/get-itemcreatePOST/api/resourceupdatePUT/api/resource/id/deleteDELETE/api/resource/id/countPOST/api/resource/count所有请求统一携带APIKey请求头完成认证并固定Content-Type/Accept为application/json见 CLI/Core/ApiClient.ts#L67-L73。请求体的组装规则也可在buildRequestData中确认list/count发送query、select、skip、limit、sort五元组其中未显式传值时limit回退为10、skip回退为0见 CLI/Core/ApiClient.ts#L75-L98。五、输出格式CLI 提供三种输出格式通过任意命令上的-o/--output指定详见 输出格式文档。表格默认交互式终端下的默认格式渲染为 ASCII 表格并智能选择列最多选 6 列列优先级为_id、name、title、createdAt、updatedAt超过 60 字符的值会被截断并追加...表头带颜色可用--no-color关闭。oneuptime incident listJSON2 空格缩进的格式化 JSON最适合脚本与管道处理。当输出流向管道非 TTY时CLI 会自动改用 JSON 格式因此如下用法无需显式-o jsononeuptime incident list | jq .[].title显式指定时oneuptime incident list -o json[ { _id: abc-123, title: API Outage, currentIncidentStateId: 550e8400-e29b-41d4-a716-446655440000, createdAt: 2025-01-15T10:30:00Z } ]Wide显示全部列且不截断适合逐字段核查但输出可能非常宽oneuptime incident list -o wide关闭颜色oneuptime --no-color incident list # 参数方式 NO_COLOR1 oneuptime incident list # 环境变量方式特殊输出场景场景输出空结果集No results found.未返回数据No data returned.单对象如get键值对表格count命令纯数字六、脚本化与 CI/CD 集成CLI 从设计上就是为自动化准备的环境变量认证、机器可读的 JSON 输出、明确的退出码详见 脚本化文档。6.1 环境变量认证export ONEUPTIME_API_KEYsk-your-api-key export ONEUPTIME_URLhttps://oneuptime.com环境变量优先于已保存的上下文但会被 CLI 参数覆盖——这与第 3.3 节的优先级顺序一致。6.2 退出码退出码含义0成功1一般错误2认证失败凭据缺失或无效3资源不存在404错误统一由 错误处理器 映射到对应退出码脚本中据此分支处理if ! oneuptime monitor list /dev/null 21; then echo Failed to list monitors exit 1 fi6.3 用 jq 处理 JSON 输出# 提取全部 incident 标题 oneuptime incident list -o json | jq .[].title # 捕获新创建监控器的 ID NEW_ID$(oneuptime monitor create --data {name:API Health} -o json | jq -r ._id) echo Created monitor: $NEW_ID # 按严重级别统计 incident oneuptime incident count --query {incidentSeverityId:severity-id}6.4 从文件批量创建资源--file便于把资源定义纳入版本管理配合jq可批量创建# monitor.json 内容示例 # { # name: API Health Check, # projectId: your-project-id # } oneuptime monitor create --file monitor.json # 从 JSON 数组文件批量创建 cat monitors.json | jq -r .[] | json | while read monitor; do oneuptime monitor create --data $monitor done6.5 GitHub Actions 定时巡检每 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 fi6.6 部署事件自动开/关在发布流水线中自动创建「Deployment Started」事件发布成功后流转到已解决状态#!/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) # ……在此执行部署步骤…… # 部署成功后解决事件 oneuptime incident update $INCIDENT_ID --data {currentIncidentStateId:$RESOLVED_STATE_ID}6.7 Docker 容器化运行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 list6.8 脚本中指定上下文若本机已保存多个环境脚本里可用--context精确指向目标环境无需切换全局状态oneuptime --context production incident list oneuptime --context staging monitor count七、全局选项与完整命令参考以下全局参数可用于任意命令声明于 CLI/Index.ts#L16-L20参数说明--api-key key本次命令覆盖 API 密钥--url url本次命令覆盖实例 URL--context name使用指定命名上下文-o, --output format输出格式json、table、wide--no-color关闭彩色输出--help显示命令帮助--version显示 CLI 版本认证类命令命令说明oneuptime login api-key instance-url [--context-name name]登录实例上下文名默认defaultoneuptime context list列出所有已保存上下文oneuptime context use name切换到指定上下文oneuptime context current显示当前上下文密钥打码oneuptime context delete name删除上下文资源类命令所有资源命令遵循同一模式将resource替换为支持的资源名incident、monitor、alert、status-page等命令参数说明resource list--query json、--limit n默认 10、--skip n默认 0、--sort json、-o过滤、分页、排序列表resource get id-o按 ID 获取单个资源resource create--data json或--file path二选一必填、-o创建资源resource update id--data json必填、-o按 ID 更新resource delete id--force删除可跳过确认resource count--query json统计匹配数工具类命令命令说明oneuptime version显示 CLI 版本oneuptime whoami显示当前认证详情oneuptime resources [--type type]列出可用资源类型可按database/analytics过滤获取帮助oneuptime --help # 全局帮助 oneuptime monitor --help # 单个资源命令帮助 oneuptime monitor list --help # 具体子命令帮助八、小结与延伸阅读OneUptime CLI 的设计要点可以概括为三层认证层login 多环境上下文 四级凭据解析配置以0600权限落盘于~/.oneuptime/config.json、资源层基于模型元数据自动发现命令、数据库与 Analytics 资源分级注册操作、交互层table/JSON/wide 三种输出、管道自动切 JSON、面向 CI/CD 的退出码约定。这三层在源码中分别对应 配置与凭据解析、资源命令与自动发现 和 输出格式化配合 API 客户端 的路由映射构成了完整的终端管理链路。更多细节可参考官方文档集群认证、资源操作、输出格式、脚本化与 CI/CD、命令参考以及 CLI 模块说明。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OneUptime CLI 完整指南：多环境认证、资源 CRUD 与 CI/CD 自动化
OneUptime CLI 完整指南多环境认证、资源 CRUD 与 CI/CD 自动化【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文以 OneUptime 官方 CLI 文档CLI 文档入口为核心骨架展开覆盖 CLI 的安装与快速上手、多环境上下文认证机制、资源的自动发现与完整 CRUD 操作、三种输出格式、以及面向 CI/CD 的脚本化用法并结合仓库内CLI/目录的源码实现解释凭据解析优先级、配置落盘权限、API 路由映射等底层细节帮助你把 OneUptime 的监控资源管理完整地搬进终端与流水线。一、CLI 定位与核心特性OneUptime CLI 是面向 OneUptime 实例的命令行管理工具允许你直接从终端对 OneUptime 资源执行完整的 CRUD 操作监控器、事件、告警、状态页等。根据官方文档它的核心特性包括多环境支持通过命名上下文context管理生产、预发布、开发等不同环境自动资源发现从 OneUptime 实例中自动发现可操作的资源类型无需硬编码资源列表灵活认证支持 CLI 参数、环境变量、已保存上下文三种凭据来源且可混合使用智能输出格式化提供json、table、wide三种输出视图可脚本化适配 CI/CD 流水线与自动化工作流具备明确的退出码约定。从源码结构看整个 CLI 由入口文件 CLI/Index.ts 组装它基于commander框架创建根命令并注册三大命令组——配置命令login/context/whoami、工具命令resources/version 等与资源命令自动发现后为每类资源动态注册子命令。入口文件中同时声明了所有全局参数--api-key、--url、--context、-o/--output、--no-color版本号为1.0.0见 CLI/Index.ts#L10-L25。二、安装与快速上手安装通过 npm 全局安装官方发布的包npm install -g oneuptime/cli快速开始# 1. 使用 API 密钥认证到 OneUptime 实例 oneuptime login your-api-key https://oneuptime.com # 2. 列出你的监控器 oneuptime monitor list # 3. 查看某个具体事件incident oneuptime incident get incident-id # 4. 查看实例上所有可用的资源类型 oneuptime resources这四步构成最小可用闭环先认证、再读取、最后通过resources命令确认当前实例暴露了哪些可操作资源。三、认证与多环境上下文CLI 支持三种认证入口命名上下文、环境变量、或直接以参数传入凭据详见 认证文档。3.1 login登录并创建上下文oneuptime login api-key instance-url参数/选项说明api-keyOneUptime API 密钥例如sk-your-api-keyinstance-url实例 URL例如https://oneuptime.com--context-name name该上下文的名称默认为default示例# 登录到默认上下文 oneuptime login sk-abc123 https://oneuptime.com # 使用命名上下文登录 oneuptime login sk-abc123 https://oneuptime.com --context-name production # 同时配置多个环境 oneuptime login sk-prod-key https://oneuptime.com --context-name production oneuptime login sk-staging-key https://staging.oneuptime.com --context-name staging从源码看login 动作会做三件事见 CLI/Commands/ConfigCommands.ts#L19-L44将实例 URL 尾部的斜杠统一剥除instanceUrl.replace(/\/$/, )以便规范化比较通过ConfigManager.addContext把上下文写入配置随后setCurrentContext将该上下文设为当前活跃上下文。也就是说登录即切换新登录的环境会立即可用。3.2 上下文管理命令作用oneuptime context list列出所有已配置上下文当前上下文以*标记oneuptime context use name切换到指定上下文oneuptime context current显示当前上下文名称、实例 URL 与打码后的 API 密钥oneuptime context delete name删除指定上下文oneuptime context use staging # 切到预发布环境 oneuptime context use production # 切回生产环境 oneuptime context current # 确认当前环境 oneuptime context delete staging # 清理不再使用的环境两个实现细节值得注意删除回退逻辑removeContext在删除当前活跃上下文时会自动把currentContext回退到剩余上下文中的第一个无剩余则置空见 CLI/Core/ConfigManager.ts#L67-L78密钥打码规则context current展示密钥时长度超过 8 位则显示前 4 位 **** 后 4 位否则整体显示为****见 CLI/Commands/ConfigCommands.ts#L113-L118。3.3 凭据解析优先级CLI 按以下优先级依次解析认证信息前者优先CLI 参数--api-key与--url环境变量ONEUPTIME_API_KEY与ONEUPTIME_URL指定上下文--context name指向的已保存上下文当前活跃上下文配置文件中的currentContext这个顺序在源码getResolvedCredentials中有明确实现见 CLI/Core/ConfigManager.ts#L98-L141。此外源码还揭示了一个文档未展开的混合模式当环境变量只提供了 API 密钥或 URL 之一时缺失的那一项会自动从当前上下文补齐见 CLI/Core/ConfigManager.ts#L129-L136如果四种来源都解析不出完整凭据则抛出错误并提示执行oneuptime login。三种典型用法# 1. 直接传参最高优先级 oneuptime --api-key sk-abc123 --url https://oneuptime.com incident list # 2. 环境变量 export ONEUPTIME_API_KEYsk-abc123 export ONEUPTIME_URLhttps://oneuptime.com oneuptime incident list # 3. 指定上下文 oneuptime --context production incident list3.4 whoami确认认证状态oneuptime whoami输出包括实例 URL、打码后的 API 密钥若有已保存上下文处于激活状态还会显示上下文名称。未认证时命令会打印一条引导信息提示先执行oneuptime login。3.5 配置文件凭据保存在用户主目录下的~/.oneuptime/config.json。源码中save函数以0o600仅属主可读写的文件权限写入避免 API 密钥被同机其他用户读取见 CLI/Core/ConfigManager.ts#L32-L39。配置文件结构示例{ currentContext: production, contexts: { production: { name: production, apiUrl: https://oneuptime.com, apiKey: sk-... }, staging: { name: staging, apiUrl: https://staging.oneuptime.com, apiKey: sk-... } }, defaults: { output: table, limit: 10 } }其中defaults的默认值输出格式table、分页大小10与源码getDefaultConfig的初始化逻辑一致见 CLI/Core/ConfigManager.ts#L9-L18。四、资源操作自动发现与完整 CRUD4.1 资源自动发现OneUptime 的资源列表不是写死在 CLI 里的而是运行时自动发现的。oneuptime resources列出实例上所有可操作资源可用--type过滤oneuptime resources # 全部资源 oneuptime resources --type database # 仅数据库类资源 oneuptime resources --type analytics # 仅分析类资源源码实现见 CLI/Commands/ResourceCommands.ts#L30-L82CLI 遍历Common/Models/DatabaseModels与Common/Models/AnalyticsModels中的全部模型类仅当模型同时满足「有表名 开启 MCP 能力enableMCP 声明了 CRUD API 路径crudApiPath」三个条件时才注册为可操作资源。资源命令名由模型单数名经toKebabCase转换生成——这正是「Status Page」变成status-page、「On-Call Policy」变成on-call-policy的原因。常见资源与命令对照资源命令Incidentoneuptime incidentAlertoneuptime alertMonitoroneuptime monitorMonitor Statusoneuptime monitor-statusIncident Stateoneuptime incident-stateStatus Pageoneuptime status-pageOn-Call Policyoneuptime on-call-policyTeamoneuptime teamScheduled Maintenance Eventoneuptime scheduled-maintenance-event数据库类资源注册完整的六个子命令list/get/create/update/delete/count分析类资源仅注册 list/create/count见 CLI/Commands/ResourceCommands.ts#L331-L356与文档中「Analytics 资源受限操作」的说明完全对应操作Analytics 资源支持情况list支持create支持count支持get/update/delete不支持4.2 list过滤、分页与排序oneuptime resource list [options]选项说明默认值--query jsonJSON 格式的过滤条件无--limit n最大返回条数10--skip n跳过的结果数分页0--sort jsonJSON 格式的排序规则无-o, --output format输出格式table--limit 10与--skip 0的默认值直接来自 commander 的 option 默认参数见 CLI/Commands/ResourceCommands.ts#L102-L109。示例# 列出最近 10 个 incident oneuptime incident list # 按状态 ID 过滤 oneuptime incident list --query {currentIncidentStateId:state-id} # 分页跳过 40 条、取 20 条 oneuptime incident list --limit 20 --skip 40 # 按创建时间倒序 oneuptime incident list --sort {createdAt:-1} # JSON 输出 oneuptime incident list -o json4.3 get / create / update / delete / countget按 ID 获取单个资源UUID。oneuptime incident get 550e8400-e29b-41d4-a716-446655440000 oneuptime monitor get abc-123 -o jsoncreate从内联 JSON 或文件创建资源--data与--file二者必选其一源码中缺省会直接抛出Either --data or --file is required for create.见 CLI/Commands/ResourceCommands.ts#L200-L209。# 内联 JSON 创建 incident oneuptime incident create --data {title:API Outage,currentIncidentStateId:state-id,incidentSeverityId:severity-id,declaredAt:2025-01-15T10:30:00Z} # 从 JSON 文件创建 oneuptime incident create --file incident.json # 创建后以 JSON 输出以便捕获新资源 ID oneuptime monitor create --data {name:API Health Check} -o jsonupdate按 ID 局部更新--data为必填项源码中使用requiredOption声明见 CLI/Commands/ResourceCommands.ts#L236-L239。# 将 incident 流转到已解决状态 oneuptime incident update abc-123 --data {currentIncidentStateId:resolved-state-id} # 重命名监控器 oneuptime monitor update abc-123 --data {name:Updated Monitor Name}delete按 ID 删除默认带确认提示--force跳过。oneuptime incident delete abc-123 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 --forcecount统计匹配过滤条件的资源数量响应体中的count字段会被提取后直接以数字形式打印见 CLI/Commands/ResourceCommands.ts#L312-L324。oneuptime incident count oneuptime incident count --query {currentIncidentStateId:state-id} oneuptime monitor count4.4 命令与 API 端点的映射所有资源命令最终收敛到 API 客户端。buildApiRoute按操作类型构造目标路由见 CLI/Core/ApiClient.ts#L33-L65与官方文档给出的映射表一致命令HTTP 方法端点listPOST/api/resource/get-listgetPOST/api/resource/id/get-itemcreatePOST/api/resourceupdatePUT/api/resource/id/deleteDELETE/api/resource/id/countPOST/api/resource/count所有请求统一携带APIKey请求头完成认证并固定Content-Type/Accept为application/json见 CLI/Core/ApiClient.ts#L67-L73。请求体的组装规则也可在buildRequestData中确认list/count发送query、select、skip、limit、sort五元组其中未显式传值时limit回退为10、skip回退为0见 CLI/Core/ApiClient.ts#L75-L98。五、输出格式CLI 提供三种输出格式通过任意命令上的-o/--output指定详见 输出格式文档。表格默认交互式终端下的默认格式渲染为 ASCII 表格并智能选择列最多选 6 列列优先级为_id、name、title、createdAt、updatedAt超过 60 字符的值会被截断并追加...表头带颜色可用--no-color关闭。oneuptime incident listJSON2 空格缩进的格式化 JSON最适合脚本与管道处理。当输出流向管道非 TTY时CLI 会自动改用 JSON 格式因此如下用法无需显式-o jsononeuptime incident list | jq .[].title显式指定时oneuptime incident list -o json[ { _id: abc-123, title: API Outage, currentIncidentStateId: 550e8400-e29b-41d4-a716-446655440000, createdAt: 2025-01-15T10:30:00Z } ]Wide显示全部列且不截断适合逐字段核查但输出可能非常宽oneuptime incident list -o wide关闭颜色oneuptime --no-color incident list # 参数方式 NO_COLOR1 oneuptime incident list # 环境变量方式特殊输出场景场景输出空结果集No results found.未返回数据No data returned.单对象如get键值对表格count命令纯数字六、脚本化与 CI/CD 集成CLI 从设计上就是为自动化准备的环境变量认证、机器可读的 JSON 输出、明确的退出码详见 脚本化文档。6.1 环境变量认证export ONEUPTIME_API_KEYsk-your-api-key export ONEUPTIME_URLhttps://oneuptime.com环境变量优先于已保存的上下文但会被 CLI 参数覆盖——这与第 3.3 节的优先级顺序一致。6.2 退出码退出码含义0成功1一般错误2认证失败凭据缺失或无效3资源不存在404错误统一由 错误处理器 映射到对应退出码脚本中据此分支处理if ! oneuptime monitor list /dev/null 21; then echo Failed to list monitors exit 1 fi6.3 用 jq 处理 JSON 输出# 提取全部 incident 标题 oneuptime incident list -o json | jq .[].title # 捕获新创建监控器的 ID NEW_ID$(oneuptime monitor create --data {name:API Health} -o json | jq -r ._id) echo Created monitor: $NEW_ID # 按严重级别统计 incident oneuptime incident count --query {incidentSeverityId:severity-id}6.4 从文件批量创建资源--file便于把资源定义纳入版本管理配合jq可批量创建# monitor.json 内容示例 # { # name: API Health Check, # projectId: your-project-id # } oneuptime monitor create --file monitor.json # 从 JSON 数组文件批量创建 cat monitors.json | jq -r .[] | json | while read monitor; do oneuptime monitor create --data $monitor done6.5 GitHub Actions 定时巡检每 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 fi6.6 部署事件自动开/关在发布流水线中自动创建「Deployment Started」事件发布成功后流转到已解决状态#!/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) # ……在此执行部署步骤…… # 部署成功后解决事件 oneuptime incident update $INCIDENT_ID --data {currentIncidentStateId:$RESOLVED_STATE_ID}6.7 Docker 容器化运行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 list6.8 脚本中指定上下文若本机已保存多个环境脚本里可用--context精确指向目标环境无需切换全局状态oneuptime --context production incident list oneuptime --context staging monitor count七、全局选项与完整命令参考以下全局参数可用于任意命令声明于 CLI/Index.ts#L16-L20参数说明--api-key key本次命令覆盖 API 密钥--url url本次命令覆盖实例 URL--context name使用指定命名上下文-o, --output format输出格式json、table、wide--no-color关闭彩色输出--help显示命令帮助--version显示 CLI 版本认证类命令命令说明oneuptime login api-key instance-url [--context-name name]登录实例上下文名默认defaultoneuptime context list列出所有已保存上下文oneuptime context use name切换到指定上下文oneuptime context current显示当前上下文密钥打码oneuptime context delete name删除上下文资源类命令所有资源命令遵循同一模式将resource替换为支持的资源名incident、monitor、alert、status-page等命令参数说明resource list--query json、--limit n默认 10、--skip n默认 0、--sort json、-o过滤、分页、排序列表resource get id-o按 ID 获取单个资源resource create--data json或--file path二选一必填、-o创建资源resource update id--data json必填、-o按 ID 更新resource delete id--force删除可跳过确认resource count--query json统计匹配数工具类命令命令说明oneuptime version显示 CLI 版本oneuptime whoami显示当前认证详情oneuptime resources [--type type]列出可用资源类型可按database/analytics过滤获取帮助oneuptime --help # 全局帮助 oneuptime monitor --help # 单个资源命令帮助 oneuptime monitor list --help # 具体子命令帮助八、小结与延伸阅读OneUptime CLI 的设计要点可以概括为三层认证层login 多环境上下文 四级凭据解析配置以0600权限落盘于~/.oneuptime/config.json、资源层基于模型元数据自动发现命令、数据库与 Analytics 资源分级注册操作、交互层table/JSON/wide 三种输出、管道自动切 JSON、面向 CI/CD 的退出码约定。这三层在源码中分别对应 配置与凭据解析、资源命令与自动发现 和 输出格式化配合 API 客户端 的路由映射构成了完整的终端管理链路。更多细节可参考官方文档集群认证、资源操作、输出格式、脚本化与 CI/CD、命令参考以及 CLI 模块说明。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考