minicron API接口参考：如何用API Key自动化管理定时任务与执行记录

minicron API接口参考：如何用API Key自动化管理定时任务与执行记录

【免费下载链接】minicron🕰️ Monitor your cron jobs项目地址: https://gitcode.com/gh_mirrors/mi/minicron

minicron 是一个轻量级的cron 定时任务监控工具，它通过 API 接口让你用API Key就能自动上报定时任务的执行过程，并在 Web 端保留完整的执行记录与历史数据。本文带你快速掌握 minicron 的全部 API 接口、统一响应格式以及最常见的认证方式，5 分钟即可把自己的定时任务接入监控。

1. minicron 是怎么工作的？

minicron 由两部分组成：

每次任务运行时，客户端会按「初始化 → 开始 → 上报输出 → 完成 → 退出」的固定顺序调用服务端 API，服务端据此生成一条可查询的执行记录。所有接口定义都集中在 server/lib/minicron/hub/controllers/api/executions.rb 中。

2. 准备工作：获取你的 API Key ⚙️

API Key 的获取非常简单：

1. 在 Web 端完成注册，系统会自动为你的账号生成一个 64 位的随机密钥（见 server/lib/minicron/hub/controllers/auth.rb 中SecureRandom.urlsafe_base64(48)的生成逻辑）；
2. 登录控制台，在个人资料页面即可查看并复制你的 API Key，该页面由 user/profile/index.erb 渲染；
3. 密钥在数据库中按用户唯一索引存储，定义见 server/db/schema.rb。

调用任意 API 时，只需在请求头中携带密钥即可：

curl -X POST http://你的服务端地址/api/1.0/execution/init \ -H "X-API-Key: 你的API密钥" \ -H "Content-Type: application/json" \ -d '{"hostname":"web-01","command":"mysqldump db > backup.sql","timestamp":1700000000}'

服务端会校验该请求头：认证逻辑位于 server/lib/minicron/hub/middleware/auth.rb。如果密钥缺失或错误，接口会直接返回401 状态码和{"error": "Invalid API credentials"}。

3. 五个核心接口一览 📋

所有接口均为POST方法，基础路径为/api/1.0/，且都返回统一的 JSON 结构。

4. 逐个接口详解 🔍

4.1 初始化执行：init

这是每次任务运行的第一步。服务端会做三件事：

• 自动识别主机：按hostname查找你的主机，不存在则自动创建；
• 自动识别任务：对命令做哈希，存在则复用，不存在则新建任务；
• 创建执行记录：自动递增执行编号（第 1 次、第 2 次……），并返回execution_id供后续接口使用。

注意：如果被监控的任务在 Web 端被禁用了，接口会返回 500 并附带Refusing to execute disabled job的提示信息（逻辑见 executions.rb 第 32-35 行）。

4.2 开始执行：start

传入execution_id和 Unix 时间戳，服务端将把任务的started_at字段更新为开始时间，用于后续统计任务时长。

4.3 上报输出：output

这是产生「执行记录」内容的接口。每产生一行输出就调用一次，参数包括：

• execution_id：所属执行记录；
• output：该行文本内容；
• seq：序号；
• timestamp：产生时间。

Web 端查看历史执行详情时展示的终端风格输出，正是来自这些记录，对应的数据模型为 server/lib/minicron/hub/models/job_execution_output.rb。

4.4 完成执行：finish

上报finished_at时间戳。start与finish两个时间戳之差，就是 Web 端展示的任务耗时。

4.5 退出判定：exit（关键接口）✅

最后一步。上报exit_status（退出码）：

• 退出码 = 0：任务成功，记录为绿色成功状态；
• 退出码 > 0：任务失败，服务端立即调用告警模块，按你在 Web 端配置的渠道（Email、SMS、Slack、PagerDuty、AWS SNS 等，实现见 server/lib/minicron/alert/）发出失败通知。

这就是 minicron「定时任务失败自动告警」能力在 API 层的入口（见 executions.rb 第 183-191 行）。

5. 统一响应格式 💬

所有接口返回结构一致，解析时先看success字段即可：

{ "body": { "execution_id": 123 }, "success": true, "error": { "message": null } }

• body：业务数据，仅init接口有值；
• success：布尔值，true表示调用成功；
• error.message：失败时给出具体的错误描述，成功时为null。

6. 更省事的方案：直接用 minicron 客户端 🚀

如果你不想自己写代码逐个调用接口，minicron 官方客户端已经封装好了完整流程（封装逻辑见 client/api/api.go），只需一条命令：

minicron --api-key 你的密钥 run 'mysqldump db > backup.sql'

常用全局参数（定义见 client/commands/root.go）：

客户端还会自动带上--dry-run干跑模式，方便在不回传服务端的情况下测试命令是否可用。

7. 常见问题 FAQ ❓

Q1：返回 401 Invalid API credentials 怎么办？检查请求头是否为X-API-Key（注意名称区分大小写），并确认密钥在个人资料页复制完整、未包含多余空格。

Q2：为什么 init 接口返回 500？最常见原因是该任务在 Web 端被禁用。到任务编辑页重新启用即可（编辑入口对应 server/lib/minicron/hub/controllers/jobs.rb）。

Q3：执行记录会保留多久？执行记录由服务端持久化存储，支持在 Web 端查看任意历史执行的状态、耗时与完整输出，这也是 minicron 相比原生 cron 的核心优势——原生 cron 的日志往往转瞬即逝。

Q4：时间戳格式是什么？所有timestamp字段均为Unix 秒级时间戳（如1700000000），服务端会将其转换为 UTC 时间存储。

写在最后

至此，minicron 的 API 接口已全部介绍完毕：init登记、start/finish计时、output留痕、exit判定成败并触发告警。配合 API Key 认证，你既可以调用官方客户端一行命令接入，也可以基于这 5 个接口为自己搭建任意语言（Python、Shell、Go 等）的自动化上报脚本，让每台机器上的定时任务都「有记录可查、有失败可警」。

【免费下载链接】minicron🕰️ Monitor your cron jobs项目地址: https://gitcode.com/gh_mirrors/mi/minicron