青龙面板API完全指南：从入门到精通RESTful接口开发

你还在为定时任务管理平台的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调用流程

sequenceDiagram
    participant 客户端
    participant 认证中间件
    participant API服务
    participant 数据库

    客户端->>认证中间件: 发送API请求(带token)
    认证中间件->>认证中间件: 验证token有效性
    alt 验证失败
        认证中间件->>客户端: 返回401 Unauthorized
    else 验证成功
        认证中间件->>API服务: 转发请求
        API服务->>数据库: 数据操作
        数据库->>API服务: 返回结果
        API服务->>客户端: 返回200 OK及数据
    end

快速开始：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

获取访问令牌

1. 登录青龙面板Web界面
2. 进入【系统设置】->【安全设置】
3. 生成或复制已有的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调用最佳实践

1. 超时处理：设置合理的请求超时时间（建议5-10秒）
2. 重试机制：对幂等操作（GET、PUT、DELETE）实现失败重试
3. 批量操作：大量任务操作使用批量API而非循环单个调用
4. 日志记录：记录API调用日志，便于问题排查
5. 权限控制：根据功能需求创建不同权限的API令牌

API接口扩展

青龙面板的API接口设计支持灵活扩展，如果你需要添加自定义API，可以按照以下步骤进行：

1. 在back/api目录下创建新的API路由文件
2. 在back/protos目录中定义新的API协议
3. 实现对应的Service层逻辑
4. 在back/api/index.ts中注册新的API路由

总结

青龙面板提供了全面的RESTful API接口，覆盖了定时任务管理、环境变量配置、脚本订阅等核心功能。通过这些API，开发者可以轻松实现青龙面板的自动化管理和二次开发。

掌握青龙API不仅能提高运维效率，还能实现许多高级功能，如：

• 与第三方系统集成（如智能家居、消息通知）
• 开发自定义管理界面
• 实现复杂的任务调度逻辑

建议结合官方文档和源代码中的API定义文件深入学习，探索更多高级用法。