Uptime Kuma

核心用法

本 Skill 为 Uptime Kuma 监控服务器的 Python CLI 封装，基于 uptime-kuma-api 库通过 Socket.IO 与服务器交互。支持完整的监控生命周期管理：查看整体状态、列出/获取/添加/删除监控项、暂停/恢复检查、查看心跳历史及通知渠道管理。

典型工作流：

• 快速诊断：kuma.py status 查看整体健康度，kuma.py list 定位故障（🔴 标记）
• 灵活添加：支持 HTTP/HTTPS、ICMP Ping、TCP 端口、DNS、数据库（MySQL/PostgreSQL/MongoDB/Redis）、Docker 容器、MQTT、被动 Push 等 10+ 监控类型
• 维护操作：支持单个或批量暂停/恢复（配合 shell 循环实现全站维护模式）
• 历史追溯：kuma.py heartbeats <id> 查看指定时间窗口内的检测记录

显著优点

• 协议覆盖全面：从基础网络层（Ping、Port）到应用层（HTTP Keyword、数据库、Docker）全栈支持
• 被动监控支持：Push 类型允许内网服务主动上报，解决不可达场景
• 批量运维友好：JSON 输出配合 jq 可实现脚本化批量操作
• 自托管可控：对接开源 Uptime Kuma 项目，数据私有化

潜在缺点与局限性

• 依赖 Socket.IO 连接：网络不稳定时 API 调用可能失败
• 无内置高可用：Uptime Kuma 本身为单节点架构，Skill 无法规避该限制
• 权限粒度粗：仅支持用户名/密码认证，无 RBAC 或 API Token 机制
• 告警配置受限：仅能查看通知渠道，无法通过 CLI 创建或修改告警规则
• 无 SSL 证书过期专项监控：HTTP 类型不单独暴露证书有效期指标

适合人群

• 运维工程师/SRE：需要快速批量操作监控的日常值班场景
• 自托管用户：已部署 Uptime Kuma 且偏好命令行工作流的开发者
• 自动化集成：需将监控操作嵌入 CI/CD 或运维脚本的团队

常规风险

• 凭证泄露：UPTIME_KUMA_USERNAME/PASSWORD 环境变量需妥善保管，避免写入版本控制
• 误删风险：delete 操作无二次确认，脚本调用时需额外校验
• 维护误操作：批量 pause/resume 可能影响核心服务监控覆盖
• API 兼容性：Uptime Kuma 版本升级可能破坏 Socket.IO 接口契约，需锁定版本测试

核心用法

该 Skill 作为 Uptime Kuma 监控服务器的 CLI 封装层，通过 Python uptime-kuma-api 库与 Socket.IO API 交互，实现完整的监控生命周期管理：

状态监控

• status 命令输出整体运行摘要，快速识别故障节点
• list 命令以表格或 JSON 格式展示所有监控项，🔴 标记直观显示异常状态
• heartbeats <id> 查看指定监控项的历史心跳记录，支持 --hours 时间范围过滤

监控管理

• add 命令支持 10+ 监控类型：HTTP/HTTPS、ICMP Ping、TCP 端口、DNS 解析、数据库（MySQL/PostgreSQL/MongoDB/Redis）、Docker 容器、MQTT 代理、被动推送等
• pause/resume 实现维护模式切换，delete 清理废弃监控项
• get <id> 获取单监控项详细配置

典型工作流

# 快速故障排查
python scripts/kuma.py status
python scripts/kuma.py list | grep 🔴

# 带健康检查端点的 API 监控
python scripts/kuma.py add --name "API Health" --type http --url https://api.example.com/health --interval 30

# 批量维护模式（shell 循环暂停全部）
for id in $(python scripts/kuma.py list --json | jq -r '.[].id'); do python scripts/kuma.py pause $id; done

显著优点

| 维度 | 优势 |

|------|------|

| **安全架构** | S+ 顶级评分，无危险函数（eval/exec/system/subprocess），零硬编码凭据，100分静态/动态/依赖/网络/隐私全维度通过 |

| **协议兼容** | 覆盖 Uptime Kuma 原生支持的完整协议栈，从基础 Ping 到数据库、容器、消息队列等企业级场景 |

| **运维友好** | JSON 输出支持与 jq 等工具链集成，表格视图兼顾人工可读性，环境变量配置符合 12-Factor 原则 |

| **零外部依赖风险** | 仅连接用户自托管的 Uptime Kuma 实例，无第三方 SaaS 数据过境 |

潜在局限

• 单点连接：依赖单一 Uptime Kuma 服务器，无内置高可用或多实例聚合能力
• 功能边界：为管理端封装，不替代 Uptime Kuma 服务端本身的高可用部署
• 通知渠道只读：notifications 命令仅列出已配置渠道，无法通过 CLI 创建或修改通知规则
• 无内置调度：--interval 参数仅设置监控频率，Skill 本身不驻留后台，需配合 cron/systemd 实现定时任务

适合人群

• SRE/运维工程师：需要脚本化批量管理数十至数百监控项
• DevOps 平台开发者：将监控管理集成至 CI/CD 或内部运维平台
• Homelab 爱好者：自托管 Uptime Kuma 后追求命令行效率
• 多环境管理者：通过环境变量快速切换生产/测试/开发环境的监控实例

常规风险

| 场景 | 风险描述 | 缓解建议 |

|------|---------|---------|

| 凭据泄露 | `UPTIME_KUMA_PASSWORD` 环境变量若被 `ps`/`proc` 泄露 | 使用专用 secrets 管理工具（如 1Password CLI、Vault），避免在共享主机执行 |

| 误操作删除 | `delete` 命令无二次确认，脚本中误传 ID 导致监控丢失 | 生产环境操作前执行 `get <id>` 确认，或配合 `list --json` 做预校验 |

| 网络隔离 | 监控目标与 Uptime Kuma 服务端网络不通导致假阳性 | 合理设置超时与重试策略（Uptime Kuma 服务端配置） |

| API 变更 | `uptime-kuma-api` 库若滞后于 Uptime Kuma 服务端版本 | 锁定依赖版本，关注上游 changelog |

---
来源可信度：T3（个人开发者/社区项目） | 安全等级：S+（满分 100）