CasaOS API 接口详解与使用指南

概述

CasaOS 是一个轻量级的家庭云操作系统，提供了丰富的 API 接口供开发者和管理员使用。本文将对 CasaOS 的 OpenAPI 规范进行详细解析，帮助开发者更好地理解和使用这些接口。

API 基础信息

CasaOS API 遵循 OpenAPI 3.0.3 规范，当前版本为 v2。所有 API 请求都需要在请求头中包含 Authorization 字段进行身份验证。

主要功能模块

1. 健康检查方法

健康检查方法用于监控 CasaOS 系统及其相关服务的运行状态。

1.1 获取服务状态

接口路径: /v2/casaos/health/services

方法: GET

描述: 获取所有 casaos-* 服务的运行状态

响应示例:

{
  "message": "",
  "data": {
    "running": ["casaos-gateway.service"],
    "not_running": ["casaos.service"]
  }
}

1.2 获取端口使用情况

接口路径: /v2/casaos/health/ports

方法: GET

描述: 获取当前系统正在使用的 TCP 和 UDP 端口列表

响应示例:

{
  "message": "",
  "data": {
    "tcp": [80, 443],
    "udp": [53]
  }
}

1.3 获取系统日志

接口路径: /v2/casaos/health/logs

方法: GET

描述: 获取系统日志文件内容，返回二进制流

2. 文件操作方法

文件操作方法允许用户与 CasaOS 系统中的文件和目录进行交互。

2.1 文件上传检查

接口路径: /v2/casaos/file/upload

方法: GET

参数:

• path: 文件路径 (必需)
• relativePath: 相对路径 (必需)
• filename: 文件名 (必需)
• chunkNumber: 当前分块编号 (必需)
• totalChunks: 总分块数 (必需)

描述: 检查文件分块是否已上传

2.2 文件上传

接口路径: /v2/casaos/file/upload

方法: POST

请求体:

{
  "relativePath": "/DATA/test.log",
  "filename": "/DATA/test2.log",
  "totalChunks": "2",
  "chunkNumber": "20",
  "path": "/DATA",
  "file": "<binary data>",
  "chunkSize": "1024",
  "currentChunkSize": "1024",
  "totalSize": "1024",
  "identifier": "test.log"
}

描述: 上传文件分块

3. Zerotier 方法

Zerotier 方法用于管理 CasaOS 的 Zerotier 网络连接。

3.1 获取 Zerotier 信息

接口路径: /v2/casaos/zt/info

方法: GET

描述: 获取 Zerotier 网络的基本信息

响应示例:

{
  "id": "1234567890",
  "name": "CasaOS",
  "status": "online"
}

3.2 设置 Zerotier 网络状态

接口路径: /v2/casaos/zt/{network_id}/status

方法: PUT

参数:

• network_id: Zerotier 网络 ID (路径参数)

请求体:

{
  "status": "online"
}

描述: 设置 Zerotier 网络状态 (online/offline)

错误处理

所有 API 接口都遵循统一的错误响应格式:

• 200: 请求成功
• 400: 客户端错误
• 500: 服务器内部错误

错误响应示例:

{
  "message": "错误描述信息"
}

最佳实践

1. 身份验证: 确保在每个请求中都包含有效的 Authorization 头
2. 分块上传: 对于大文件上传，建议使用分块上传方式
3. 错误处理: 对所有 API 调用都要实现适当的错误处理逻辑
4. 状态监控: 定期调用健康检查接口监控系统状态

总结

CasaOS API 提供了系统监控、文件管理和网络配置等核心功能，开发者可以利用这些接口构建自定义的管理工具或集成 CasaOS 到现有系统中。通过本文的介绍，您应该已经对 CasaOS 的主要 API 有了全面的了解，可以开始开发自己的应用了。