青龙面板API完全指南：从入门到精通RESTful接口开发
项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong 你还在为定时任务管理平台的API调用烦恼吗？是否想通过编程方式轻松控制青龙面板的定时任务、环境变量和订阅管理？本文将系统解析青龙面板（Qinglong）的内置API接口，通过实际示例教会你如何利用这些接口实现自动化运维。读完本文后，你将能够：
- 掌握青龙API的认证与请求规范
- 熟练使用任务管理、环境变量、订阅管理等核心接口
- 实现API调用的错误处理与最佳实践
- 了解API接口的扩展与二次开发方法
API架构概览
青龙面板采用RESTful API设计风格，所有接口均通过HTTP/HTTPS协议提供服务。API服务由后端服务模块实现，主要定义在back/api目录下，包含任务管理、环境变量、系统配置等多个功能模块。
核心API模块
| 模块路径 | 功能描述 | 主要接口 |
|---|---|---|
| back/api/cron.ts | 定时任务管理 | 创建、查询、更新、删除定时任务 |
| back/api/env.ts | 环境变量管理 | 获取、添加、修改、删除环境变量 |
| back/api/subscription.ts | 订阅管理 | 订阅脚本、更新订阅、查看订阅日志 |
| back/api/script.ts | 脚本管理 | 脚本列表、执行、停止、日志查看 |
API调用流程
快速开始：API调用准备
认证方式
青龙API使用Bearer Token认证机制，所有需要权限的接口都需要在HTTP请求头中包含认证信息：
GET /api/crons HTTP/1.1
Host: your-qinglong-server.com
Authorization: Bearer your_token_here
Content-Type: application/json
获取访问令牌
- 登录青龙面板Web界面
- 进入【系统设置】->【安全设置】
- 生成或复制已有的API访问令牌
API请求格式
所有API请求和响应均使用JSON格式，标准响应格式如下：
{
"code": 200,
"data": { /* 响应数据 */ },
"message": "success"
}
code: 状态码，200表示成功，非200表示失败data: 业务数据，不同接口返回不同结构message: 状态描述，错误时返回具体错误信息
核心API使用示例
1. 定时任务管理API
获取任务列表
请求
GET /api/crons?searchValue=jd_&status=1
响应
{
"code": 200,
"data": [
{
"id": 1,
"name": "京东签到",
"command": "node jd_sign.js",
"schedule": "0 0 0 * * *",
"status": 1,
"labels": ["jd", "sign"],
"last_execution_time": 1620000000000
}
],
"message": "success"
}
创建定时任务
请求
POST /api/crons
Content-Type: application/json
{
"name": "淘宝签到",
"command": "python3 tb_sign.py",
"schedule": "0 30 7 * * *",
"labels": ["taobao", "sign"],
"status": 1
}
响应
{
"code": 200,
"data": {
"id": 2,
"name": "淘宝签到",
"command": "python3 tb_sign.py",
"schedule": "0 30 7 * * *",
"status": 1
},
"message": "success"
}
相关接口实现代码可参考 back/api/cron.ts 中的路由定义。
2. 环境变量管理API
环境变量API允许你管理青龙面板中所有脚本共享的环境变量，常用于存储账号信息、API密钥等敏感数据。
添加环境变量
请求
POST /api/envs
Content-Type: application/json
{
"envs": [
{
"name": "JD_COOKIE",
"value": "pt_key=xxx;pt_pin=xxx;",
"remarks": "京东账号1",
"status": 1
}
]
}
响应
{
"code": 200,
"data": [
{
"id": 1,
"name": "JD_COOKIE",
"value": "pt_key=xxx;pt_pin=xxx;",
"remarks": "京东账号1",
"status": 1
}
],
"message": "success"
}
环境变量的数据结构定义在 back/protos/api.proto 文件的 EnvItem 消息类型中。
3. 订阅管理API
订阅功能允许青龙面板定期拉取远程脚本仓库，保持本地脚本最新。
创建订阅
请求
POST /api/subscriptions
Content-Type: application/json
{
"name": "京东脚本合集",
"url": "https://gitcode.com/xxx/jd_scripts.git",
"branch": "main",
"schedule": "0 0 */1 * * *",
"whiteList": "jd_",
"blackList": "test_",
"autoAddCron": true
}
响应
{
"code": 200,
"data": {
"id": 1,
"name": "京东脚本合集",
"url": "https://gitcode.com/xxx/jd_scripts.git",
"status": 1
},
"message": "success"
}
订阅管理的API实现逻辑位于 back/api/subscription.ts 文件中。
高级应用：API批量操作
批量启用定时任务
PUT /api/crons/enable
Content-Type: application/json
[1, 2, 3, 4]
批量更新环境变量
PUT /api/envs
Content-Type: application/json
{
"id": 1,
"name": "JD_COOKIE",
"value": "new_cookie_value",
"remarks": "更新后的京东账号1",
"status": 1
}
错误处理与最佳实践
常见错误码
| 错误码 | 含义 | 解决方法 |
|---|---|---|
| 400 | 请求参数错误 | 检查请求参数格式和必填项 |
| 401 | 未授权 | 检查token是否有效或已过期 |
| 403 | 权限不足 | 使用管理员账号生成的token |
| 404 | 资源不存在 | 检查请求的ID是否正确 |
| 500 | 服务器内部错误 | 查看服务器日志获取详细信息 |
API调用最佳实践
- 超时处理：设置合理的请求超时时间（建议5-10秒）
- 重试机制：对幂等操作（GET、PUT、DELETE）实现失败重试
- 批量操作：大量任务操作使用批量API而非循环单个调用
- 日志记录：记录API调用日志，便于问题排查
- 权限控制：根据功能需求创建不同权限的API令牌
API接口扩展
青龙面板的API接口设计支持灵活扩展，如果你需要添加自定义API，可以按照以下步骤进行：
- 在
back/api目录下创建新的API路由文件 - 在
back/protos目录中定义新的API协议 - 实现对应的Service层逻辑
- 在
back/api/index.ts中注册新的API路由
总结
青龙面板提供了全面的RESTful API接口，覆盖了定时任务管理、环境变量配置、脚本订阅等核心功能。通过这些API，开发者可以轻松实现青龙面板的自动化管理和二次开发。
掌握青龙API不仅能提高运维效率，还能实现许多高级功能，如：
- 与第三方系统集成（如智能家居、消息通知）
- 开发自定义管理界面
- 实现复杂的任务调度逻辑
建议结合官方文档和源代码中的API定义文件深入学习，探索更多高级用法。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
