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-key>	OneUptime API 密钥（例如sk-your-api-key）
<instance-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 按以下优先级依次解析认证信息（前者优先）：

1. CLI 参数（--api-key与--url）
2. 环境变量（ONEUPTIME_API_KEY与ONEUPTIME_URL）
3. 指定上下文（--context <name>指向的已保存上下文）
4. 当前活跃上下文（配置文件中的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_KEY=sk-abc123 export ONEUPTIME_URL=https://oneuptime.com oneuptime incident list # 3. 指定上下文 oneuptime --context production incident list

3.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）。

四、资源操作：自动发现与完整 CRUD

4.1 资源自动发现

OneUptime 的资源列表不是写死在 CLI 里的，而是运行时自动发现的。oneuptime resources列出实例上所有可操作资源，可用--type过滤：

oneuptime resources # 全部资源 oneuptime resources --type database # 仅数据库类资源 oneuptime resources --type analytics # 仅分析类资源

源码实现见 CLI/Commands/ResourceCommands.ts#L30-L82：CLI 遍历Common/Models/DatabaseModels与Common/Models/AnalyticsModels中的全部模型类，仅当模型同时满足「有表名 + 开启 MCP 能力（enableMCP）+ 声明了 CRUD API 路径（crudApiPath）」三个条件时才注册为可操作资源。资源命令名由模型单数名经toKebabCase转换生成——这正是「Status Page」变成status-page、「On-Call Policy」变成on-call-policy的原因。常见资源与命令对照：

资源	命令
Incident	oneuptime incident
Alert	oneuptime alert
Monitor	oneuptime monitor
Monitor Status	oneuptime monitor-status
Incident State	oneuptime incident-state
Status Page	oneuptime status-page
On-Call Policy	oneuptime on-call-policy
Team	oneuptime team
Scheduled Maintenance Event	oneuptime 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 <json>	JSON 格式的过滤条件	无
--limit <n>	最大返回条数	10
--skip <n>	跳过的结果数（分页）	0
--sort <json>	JSON 格式的排序规则	无
-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 json

4.3 get / create / update / delete / count

get：按 ID 获取单个资源（UUID）。

oneuptime incident get 550e8400-e29b-41d4-a716-446655440000 oneuptime monitor get abc-123 -o json

create：从内联 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 json

update：按 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 --force

count：统计匹配过滤条件的资源数量，响应体中的count字段会被提取后直接以数字形式打印（见 CLI/Commands/ResourceCommands.ts#L312-L324）。

oneuptime incident count oneuptime incident count --query '{"currentIncidentStateId":"<state-id>"}' oneuptime monitor count

4.4 命令与 API 端点的映射

所有资源命令最终收敛到 API 客户端。buildApiRoute按操作类型构造目标路由（见 CLI/Core/ApiClient.ts#L33-L65），与官方文档给出的映射表一致：

命令	HTTP 方法	端点
list	POST	/api/<resource>/get-list
get	POST	/api/<resource>/<id>/get-item
create	POST	/api/<resource>
update	PUT	/api/<resource>/<id>/
delete	DELETE	/api/<resource>/<id>/
count	POST	/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 list

JSON

2 空格缩进的格式化 JSON，最适合脚本与管道处理。当输出流向管道（非 TTY）时，CLI 会自动改用 JSON 格式，因此如下用法无需显式-o json：

oneuptime 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_COLOR=1 oneuptime incident list # 环境变量方式

特殊输出场景

场景	输出
空结果集	No results found.
未返回数据	No data returned.
单对象（如get）	键值对表格
count命令	纯数字

六、脚本化与 CI/CD 集成

CLI 从设计上就是为自动化准备的：环境变量认证、机器可读的 JSON 输出、明确的退出码（详见 脚本化文档）。

6.1 环境变量认证

export ONEUPTIME_API_KEY=sk-your-api-key export ONEUPTIME_URL=https://oneuptime.com

环境变量优先于已保存的上下文，但会被 CLI 参数覆盖——这与第 3.3 节的优先级顺序一致。

6.2 退出码

退出码	含义
0	成功
1	一般错误
2	认证失败（凭据缺失或无效）
3	资源不存在（404）

错误统一由 错误处理器 映射到对应退出码，脚本中据此分支处理：

if ! oneuptime monitor list > /dev/null 2>&1; then echo "Failed to list monitors" exit 1 fi

6.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" done

6.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 fi

6.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_KEY=sk-abc123 \ -e ONEUPTIME_URL=https://oneuptime.com \ oneuptime-cli incident list

6.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>]	登录实例，上下文名默认default
oneuptime 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