OneUptime CLI 资源操作实战从自动发现到 CRUD 全生命周期的命令式运维【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime CLI 为其实例中所有启用了 MCP 的资源模型自动注册命令行接口提供list、get、create、update、delete、count六类标准操作无需为每种资源编写专门命令。本篇以仓库中 CLI 资源操作文档为骨架完整覆盖各子命令的参数表与示例并结合 CLI/Commands/ResourceCommands.ts 与 CLI/Core/ApiClient.ts 的源码实现讲清资源是如何被发现的、每条命令背后实际请求了哪个 API 路由以及输出格式的自动检测规则帮助你在脚本与 CI/CD 中稳定地编排 OneUptime 运维操作。可用资源从实例中自动发现OneUptime CLI 的核心理念是“资源即命令”所有受支持的资源都会从你的 OneUptime 实例更准确地说是从共享模型定义中自动发现并注册为独立的顶层子命令。运行以下命令即可查看全部资源类型oneuptime resources也可以按模型类型过滤# 仅显示数据库类资源 oneuptime resources --type database # 仅显示分析类资源 oneuptime resources --type analytics常见资源及其对应命令如下资源命令Incident事故oneuptime incidentAlert告警oneuptime alertMonitor监控项oneuptime monitorMonitor Status监控状态oneuptime monitor-statusIncident State事故状态oneuptime incident-stateStatus Page状态页oneuptime status-pageOn-Call Policy值班策略oneuptime on-call-policyTeam团队oneuptime teamScheduled Maintenance Event计划维护事件oneuptime scheduled-maintenance-event资源发现机制的源码实现oneuptime resources背后的核心是 CLI/Commands/ResourceCommands.ts 中的discoverResources()函数L30-L82。它分两步遍历两组模型注册表数据库模型遍历 Common/Models/DatabaseModels/Index 中导出的全部模型类逐个实例化后读取tableName、singularName、pluralName和crudApiPath分析模型以同样方式遍历 Common/Models/AnalyticsModels 中的 ClickHouse 侧模型如Metric、Span、Log、MonitorLog、RumSession、SecurityEvent、ChangeEvent等。一个模型要进入 CLI 的资源列表必须同时满足三个条件tableName非空、model.enableMCP true、crudApiPath已定义见discoverResources中的判断if (tableName model.enableMCP apiPath)。命令名由singularName经toKebabCase()转换而来——例如IncidentState变成incident-state、OnCallPolicy变成on-call-policy这也解释了命令表中连字符命名的由来。这意味着模型一旦在服务端启用 MCP就会自动出现在 CLI 中无需升级 CLI 二进制。enableMCP与crudApiPath均定义在 Common/Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel.ts 基类上crudApiPath见 L210各模型类按需声明自己的值。resources子命令的表格展示逻辑Command / Singular / Plural / Type / API Path五列在 CLI/Commands/UtilityCommands.ts 的registerUtilityCommands中实现结尾会打印Total: N resources统计。列出资源list过滤、分页与排序list子命令用于获取资源列表支持过滤、分页与排序oneuptime resource list [options]选项选项说明默认值--query json作为 JSON 的过滤条件无--limit n最大返回条数10--skip n跳过的结果条数0--sort json作为 JSON 的排序规则无-o, --output format输出格式json/table/widetable示例# 列出 10 个最近的事故 oneuptime incident list # 按状态 ID 过滤事故 oneuptime incident list --query {currentIncidentStateId:state-id} # 分页列出 oneuptime incident list --limit 20 --skip 40 # 按创建时间降序排序 oneuptime incident list --sort {createdAt:-1} # 以 JSON 格式输出 oneuptime incident list -o jsonlist 命令的底层请求链从源码看list的选项解析在registerListCommandCLI/Commands/ResourceCommands.ts L98-L151中完成--limit与--skip均以字符串接收后经parseInt转换默认值10与0由 commander 的.option第三个参数注入与上表一致。有两个容易被忽略的实现细节字段选择select是自动生成的。CLI 不会盲目SELECT *而是调用 CLI/Utils/SelectFieldGenerator.ts 中的generateAllFieldsSelect(tableName, modelType)对数据库模型它通过getTableColumns()取全部列名再调用模型的getColumnAccessControlForAllColumns()过滤掉受访问控制限制的列例如仅Permission.CurrentUser可读的列会被剔除见shouldIncludeField逻辑若模型解析失败或列集合为空则回退到只含_id、createdAt、updatedAt的默认 select。分析模型直接采用默认 select。list 是 POST 请求而非 GET。CLI/Core/ApiClient.ts 的buildApiRoute将list映射到/apiapiPath/get-listbuildRequestData将query、select、skip、limit、sort组装进请求体L81-L89executeApiRequest最终通过API.post发出L124-L130。由于过滤条件以 JSON 对象表达而非 URL 查询串POST 是承载复杂 query 的自然选择。响应处理上registerListCommand会先剥离响应中的data包裹层若存在再交给输出格式化器因此-o json时管道里得到的是结果数组本身可直接jq .[].title。获取单个资源get按 ID 获取单个资源oneuptime resource get id参数参数说明id资源 IDUUID示例# 获取指定事故 oneuptime incident get 550e8400-e29b-41d4-a716-446655440000 # 以 JSON 获取某个监控项 oneuptime monitor get abc-123 -o json从源码看get对应registerGetCommandL153-L185它在路由层映射为POST /apiapiPath/id/get-item见 CLI/Core/ApiClient.ts 的buildApiRouteL41-L45并同样附带generateAllFieldsSelect生成的字段 select——即单条读取与列表读取遵循同一套列级访问控制不会返回被权限隐藏的列。get结果若为单个对象table格式会渲染成键值对形式CLI/Core/OutputFormatter.ts 中的formatSingleObject长值统一截断到 60 字符。创建资源create内联 JSON 或文件从内联 JSON 或 JSON 文件创建新资源oneuptime resource create [options]选项选项说明--data json作为 JSON 对象的资源数据--file path包含资源数据的 JSON 文件路径-o, --output format输出格式--data与--file二者必须提供其一。示例# 用内联 JSON 创建事故 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实现上registerCreateCommandCLI/Commands/ResourceCommands.ts L187-L229的处理优先级是若提供了--file用fs.readFileSync读取文件并JSON.parse否则解析--data两者皆无则抛出Either --data or --file is required for create.。--file优先于--data的行为值得注意——同时传两个参数时以文件为准。请求侧create被映射为POST /apiapiPath数据包装为{ data: {...} }结构CLI/Core/ApiClient.ts 的buildRequestDataL77-L78。JSON 解析失败会抛出Invalid JSON: valueparseJsonArgL22-L28便于在脚本中快速定位语法错误。在 CI/CD 中捕获新资源 ID 的惯用写法是最后一条示例-o json后管道给jq -r ._id实现创建即登记的自动化流程。更新资源update按 ID 更新已有资源oneuptime resource update id [options]参数参数说明id资源 ID选项选项说明--data json作为 JSON 的待更新字段必填-o, --output format输出格式示例# 切换事故状态例如置为已解决 oneuptime incident update abc-123 --data {currentIncidentStateId:resolved-state-id} # 重命名监控项 oneuptime monitor update abc-123 --data {name:Updated Monitor Name}与create不同update通过.requiredOption(--data json, ...)声明了必填选项registerUpdateCommandL231-L261——缺少--data时 commander 会在动作执行前直接报错。HTTP 层映射为PUT /apiapiPath/id/注意尾部斜杠即 CLI/Core/ApiClient.ts 中update/delete共用的分支L46-L50。从请求体构造看update同样以{ data: ... }包装属于部分更新语义只传需要变更的字段即可例如仅切换currentIncidentStateId来“关闭”事故而不必回传完整对象。删除资源delete按 ID 删除资源oneuptime resource delete id [--force]参数参数说明id资源 ID选项选项说明--force跳过确认提示示例oneuptime incident delete abc-123 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 # 跳过确认 oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 --force实现上registerDeleteCommandL263-L289映射到DELETE /apiapiPath/id/请求成功后调用printSuccess输出singularName id deleted successfully.提示。这里有一个值得说明的细节--force选项在当前实现中被注册但并未被读取动作回调签名中参数为_options删除是直接执行的——从源码结构看该参数是为交互式确认场景保留的接口位当前版本没有阻塞式确认提示。因此在自动化脚本中直接使用delete即可无需额外传--force若要在人工操作时增加保护可以在脚本层自行加read确认。统计资源count按可选的过滤条件统计资源数量oneuptime resource count [options]选项选项说明--query json作为 JSON 的过滤条件示例# 统计所有事故 oneuptime incident count # 按状态统计事故 oneuptime incident count --query {currentIncidentStateId:state-id} # 统计监控项数量 oneuptime monitor countcount映射到POST /apiapiPath/countCLI/Core/ApiClient.ts L52-L54请求体携带query与selectL82-L89。输出逻辑专门做了收窄若响应对象含count字段则只打印这个数字registerCountCommandL312-L324因此在终端里得到的是可直接嵌入 shell 算术或if [ $(...) -gt 0 ]判断的裸数字而count没有--limit等分页选项——它本身就是聚合操作。分析类资源受限的操作集分析类资源ClickHouse 侧模型如metric、span、log、rum-session、security-event、change-event等与数据库资源相比只支持一个受限的操作集操作是否支持list是create是count是get否update否delete否用oneuptime resources --type analytics可查看你实例中实际可用的分析资源列表。这一差异直接由注册逻辑决定CLI/Commands/ResourceCommands.ts 的registerResourceCommandsL331-L356中modelType database的资源注册全部六个子命令而modelType analytics只注册list、create、count三个。从模型分布看AnalyticsModels目录下含enableMCP声明的模型包括Metric、Span、MonitorLog、RumSession、ExceptionInstance、KubernetesCostAllocation、SecurityEvent、Log、ChangeEvent等十余个。这体现了典型的可观测性数据面特征时序与日志类数据以高吞吐写入和聚合查询为主单行级的按 ID 读写/更新/删除在该存储上并不适用CLI 因此如实反映了这一边界——对分析资源执行get/update/delete会得到“子命令不存在”的提示而不是静默失败。凭据解析与输出格式让命令在脚本中可预测资源操作的每一条命令都依赖同一套凭据解析顺序理解它对调试至关重要CLI/Core/ConfigManager.ts 的getResolvedCredentialsL98 起CLI 全局选项--api-key key与--url url两者须同时提供见 CLI/Index.ts L16-L17环境变量ONEUPTIME_API_KEY与ONEUPTIME_URL同样须成对出现--context name指定的上下文或当前上下文均来自~/.oneuptime/config.json保存时权限为0600。因此 CI/CD 场景推荐ONEUPTIME_API_KEYsk-xxx ONEUPTIME_URLhttps://your-instance oneuptime incident list这种无状态用法多环境切换则依赖oneuptime login api-key url --context-name name建立的命名上下文与oneuptime context use name。输出格式由 CLI/Core/OutputFormatter.ts 的detectOutputFormat统一裁决显式-o参数 管道检测stdout 非 TTY 时自动降级为 JSONL26-L28 默认table。这解释了 README 中“管道给jq时无需显式-o json”的行为也意味着同一命令在终端与脚本中呈现不同形态属于设计行为而非缺陷。table模式对超过 60 字符的值做截断truncateValue列数超过 6 时优先保留_id、name、title、status、createdAt、updatedAt等常用列需要完整字段时使用-o wide或-o json。颜色输出可经NO_COLOR环境变量或--no-color全局选项关闭。相关实现与验证入口CLI/Commands/ResourceCommands.tsdiscoverResources与六个子命令的注册逻辑数据库/分析模型的差异化处理CLI/Core/ApiClient.tsApiOperation到 REST 路由与 HTTP 方法的完整映射get-list/get-item/count//id/后缀规则CLI/Utils/SelectFieldGenerator.ts按列级访问控制生成 select 集合CLI/Core/OutputFormatter.tstable/wide/json三种格式与 TTY 自动检测CLI/Commands/UtilityCommands.tsresources、whoami、version工具命令CLI/Tests/ResourceCommands.test.ts对资源发现含 Incident 资源的断言与各子命令行为的 Jest 测试mock 了executeApiRequest以隔离网络层CLI/README.md安装npm install -g oneuptime/cli或仓库内cd CLI npm install npm start -- --help、上下文管理与环境变量参考英文对照文档App/FeatureSet/Docs/Content/en/cli/resource-operations.md本丹麦语文档 App/FeatureSet/Docs/Content/da/cli/resource-operations.md 的原文。适用前提以上内容以当前仓库中 CLI 子项目oneuptime/cliversion由 CLI/package.json 运行时读取的实际代码为准--limit默认10、--skip默认0等取值来自 commander 注册时的默认参数若上游版本调整请以oneuptime resource list --help的实际输出为准。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考