# HYC下载站 v2.3 - API 文档

## 快速开始

```bash
# 测试健康检查
curl http://localhost:8080/api/v1/health

# 获取文件列表
curl http://localhost:8080/api/v1/files

# 下载文件
curl -O http://localhost:8080/downloads/ubuntu-22.04.iso
```

## 认证方式

项目支持可选的认证功能，通过 `settings.json` 配置。

### 公开访问模式（默认）

```json
{
  "auth_type": "none"
}
```

当 `auth_type: none` 时，所有接口无需认证即可访问，适合公开下载站点。

### 启用认证

如需启用认证：

```json
{
  "auth_type": "basic",
  "auth_user": "admin",
  "auth_pass": "yourpassword"
}
```

或使用 Token 认证：

```json
{
  "auth_type": "token",
  "auth_token": "your-secret-token"
}
```

**支持的认证方式：**

| 方式 | 请求头 |
|------|--------|
| Bearer Token | `Authorization: Bearer <token>` |
| Basic Auth | `Authorization: Basic <base64(username:password)>` |

---

## 文件管理

### 列出文件

**GET** `/api/v1/files`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| path | string | 否 | 目录路径 (默认根目录) |
| recursive | boolean | 否 | 是否递归列出子目录 |

**响应示例：**
```json
{
  "files": [
    {
      "name": "ubuntu-22.04.iso",
      "path": "ubuntu-22.04.iso",
      "size": 4588563456,
      "size_formatted": "4.3 GB",
      "type": "application/octet-stream",
      "modified": "2024-01-15T10:30:00",
      "sha256": "abc123...",
      "download_count": 1523
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1
  }
}
```

---

### 获取文件信息

**GET** `/api/v1/file/{path}`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| path | string | 是 | 文件路径 |

**响应示例：**
```json
{
  "name": "ubuntu-22.04.iso",
  "path": "ubuntu-22.04.iso",
  "size": 4588563456,
  "size_formatted": "4.3 GB",
  "type": "application/octet-stream",
  "modified": "2024-01-15T10:30:00",
  "sha256": "abc123def456...",
  "download_count": 1523
}
```

**错误响应 (404)：**
```json
{
  "error": "File not found",
  "path": "nonexistent.iso"
}
```

---

### 文件预览

**GET** `/api/v1/file/{path}/preview`

预览图片、JSON、Markdown、文本、PDF、音频等文件。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| path | string | 是 | 文件路径 |

**响应示例（图片）：**
```json
{
  "path": "images/logo.png",
  "name": "logo.png",
  "size": 24576,
  "type": "image/png",
  "preview_available": true,
  "preview_type": "image",
  "data_url": "data:image/png;base64,iVBORw0KGgo...",
  "truncated": false
}
```

**响应示例（JSON）：**
```json
{
  "path": "config.json",
  "name": "config.json",
  "size": 1024,
  "type": "application/json",
  "preview_available": true,
  "preview_type": "json",
  "content": {
    "server_name": "HYC Download",
    "port": 8080
  },
  "truncated": false
}
```

**支持的预览类型：** 图片、SVG、JSON、Markdown、XML、CSV、YAML、音频、PDF、文本文件

**错误响应 (413)：**
```json
{
  "error": "File too large for preview (max 10 MB)",
  "file_size": 15728640,
  "max_preview_size": 10485760
}
```

---

### 删除文件

**DELETE** `/api/v1/file/{path}` (需要认证)

**响应示例：**
```json
{
  "success": true,
  "message": "File deleted successfully",
  "path": "old-file.iso"
}
```

**错误响应 (403)：**
```json
{
  "error": "Permission denied",
  "code": "FORBIDDEN"
}
```

---

### 创建目录

**PUT** `/api/v1/mkdir` (需要认证)

**请求体：**
```json
{
  "path": "/downloads/new-folder"
}
```

**响应示例：**
```json
{
  "success": true,
  "message": "Directory created",
  "path": "/downloads/new-folder"
}
```

---

### 上传文件

**POST** `/api/v1/upload` (需要认证)

**表单参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| path | string | 目标目录 |
| file | binary | 要上传的文件 |

**响应示例：**
```json
{
  "success": true,
  "message": "File uploaded successfully",
  "name": "uploaded-file.iso",
  "size": 104857600,
  "path": "/downloads/uploaded-file.iso"
}
```

---

### 批量操作

**POST** `/api/v1/batch` (需要认证)

**请求体：**
```json
{
  "operation": "delete",
  "files": ["file1.iso", "file2.iso", "file3.iso"],
  "target_dir": ""
}
```

**响应示例：**
```json
{
  "success": true,
  "operation": "delete",
  "processed": 3,
  "failed": 0,
  "details": [
    {"path": "file1.iso", "status": "deleted"},
    {"path": "file2.iso", "status": "deleted"},
    {"path": "file3.iso", "status": "deleted"}
  ]
}
```

---

### 搜索文件

**GET** `/api/v1/search`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| q | string | 是 | 搜索关键词 |
| type | string | 否 | 搜索类型 (all, file, dir) |
| limit | integer | 否 | 返回结果数量限制 |

**响应示例：**
```json
{
  "query": "ubuntu",
  "total": 5,
  "results": [
    {
      "name": "ubuntu-22.04.iso",
      "path": "ubuntu-22.04.iso",
      "size": 4588563456,
      "size_formatted": "4.3 GB",
      "modified": "2024-01-15T10:30:00"
    }
  ]
}
```

---

## 镜像同步

### 获取同步源列表

**GET** `/api/v1/sync/sources`

**响应示例：**
```json
{
  "sources": [
    {
      "name": "ubuntu-releases",
      "type": "http",
      "url": "https://releases.ubuntu.com/",
      "target": "ubuntu/",
      "enabled": true,
      "auto_sync": true,
      "last_sync": "2024-01-15T02:00:00",
      "status": "idle"
    }
  ],
  "count": 2
}
```

---

### 添加同步源

**POST** `/api/v1/sync/sources` (需要认证)

**请求体：**
```json
{
  "name": "new-mirror",
  "type": "http",
  "url": "https://example.com/mirror/",
  "target": "custom/",
  "enabled": true,
  "auto_sync": true
}
```

---

### 删除同步源

**DELETE** `/api/v1/sync/sources/{name}` (需要认证)

**响应示例：**
```json
{
  "success": true,
  "message": "Sync source deleted",
  "name": "ubuntu-releases"
}
```

---

### 更新同步源配置

**PUT** `/api/v1/sync/sources/{name}` (需要认证)

**请求体：**
```json
{
  "config": {
    "enabled": true,
    "auto_sync": true,
    "schedule": "0 2 * * *"
  }
}
```

**响应示例：**
```json
{
  "success": true,
  "name": "ubuntu-releases"
}
```

---

### 开始同步

**POST** `/api/v1/sync/start` (需要认证)

**请求体：**
```json
{
  "sources": ["ubuntu-releases", "debian-cd"]
}
```

**响应示例：**
```json
{
  "success": true,
  "message": "Sync started",
  "sources": ["ubuntu-releases", "debian-cd"],
  "started_at": "2024-01-15T10:00:00"
}
```

---

### 停止同步

**POST** `/api/v1/sync/stop` (需要认证)

**响应示例：**
```json
{
  "success": true,
  "message": "Sync stopped",
  "stopped_at": "2024-01-15T10:30:00",
  "synced_files": 1250,
  "failed_files": 3
}
```

---

### 获取同步状态

**GET** `/api/v1/sync/status`

**响应示例：**
```json
{
  "running": true,
  "progress": 45.5,
  "synced": 1250,
  "total": 2748,
  "current_source": "ubuntu-releases",
  "speed": "2.5 MB/s",
  "eta": "5m 30s",
  "started_at": "2024-01-15T10:00:00"
}
```

---

## 加速源

### 列出可用包

**GET** `/api/v1/mirror/{type}/list`

**type 可选值：** `docker`, `apt`, `yum`, `pypi`, `npm`, `go`

**响应示例：**
```json
{
  "type": "docker",
  "total": 150,
  "page": 1,
  "per_page": 50,
  "packages": [
    {
      "name": "ubuntu",
      "description": "Ubuntu base image",
      "versions": ["latest", "22.04", "20.04", "18.04"],
      "size": "25 MB"
    }
  ]
}
```

---

### 搜索包

**GET** `/api/v1/mirror/{type}/search`

**响应示例：**
```json
{
  "type": "pypi",
  "query": "django",
  "total": 5,
  "results": [
    {
      "name": "Django",
      "version": "5.0.1",
      "summary": "The Web framework for perfectionists with deadlines.",
      "author": "Django Software Foundation",
      "size": "8.2 MB",
      "requires_python": ">=3.10"
    }
  ]
}
```

---

### 压缩/解压缩

**POST** `/api/v1/archive` (需要认证)

**请求体：**
```json
{
  "operation": "compress",  // 或 "extract"
  "files": ["file1.txt", "file2.txt"],
  "archive_name": "archive.zip",
  "target_dir": ""
}
```

**压缩响应示例：**
```json
{
  "operation": "compress",
  "archive_path": "archive.zip",
  "compressed_files": 2,
  "archive_size": 1048576
}
```

**解压缩响应示例：**
```json
{
  "operation": "extract",
  "extract_dir": "",
  "extracted_files": 5
}
```

**错误响应 (400)：**
```json
{
  "error": "Invalid operation"
}
```

---

### 获取服务器配置

**GET** `/api/v1/config`

**响应示例：**
```json
{
  "server_name": "HYC Download Station",
  "version": "2.3.0",
  "base_dir": "/downloads",
  "directory_listing": true,
  "max_upload_size": 1073741824,
  "enable_stats": true,
  "auth_type": "none",
  "sort_by": "name",
  "sort_reverse": false,
  "ignore_hidden": true,
  "enable_range": true,
  "show_hash": false,
  "calculate_hash": false,
  "max_search_results": 100,
  "api_version": "v1"
}
```

---

## 统计监控

### 获取系统统计

**GET** `/api/v1/stats`

**响应示例：**
```json
{
  "total_files": 1520,
  "total_dirs": 245,
  "total_size": 107374182400,
  "total_size_formatted": "100.0 GB",
  "downloads_total": 52340,
  "downloads_today": 1250,
  "downloads_week": 8750
}
```

---

### 获取监控数据

**GET** `/api/v1/monitor`

**响应示例：**
```json
{
  "cpu": {
    "percent": 35.5,
    "cores": 4
  },
  "memory": {
    "total": 8589934592,
    "used": 3221225472,
    "free": 5368709120,
    "percent": 37.5
  },
  "disk": {
    "total": 536870912000,
    "used": 107374182400,
    "free": 429496729600,
    "percent": 20.0
  },
  "network": {
    "rx_bytes": 1048576000,
    "tx_bytes": 524288000,
    "rx_speed": "1.2 MB/s",
    "tx_speed": "512 KB/s"
  },
  "uptime": 86400
}
```

---

### 健康检查

**GET** `/api/v1/health`

**成功响应 (200)：**
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00",
  "version": "2.2.0",
  "uptime": 86400,
  "components": {
    "api": "ok",
    "database": "ok",
    "cache": "ok",
    "storage": "ok"
  }
}
```

**异常响应 (503)：**
```json
{
  "status": "unhealthy",
  "timestamp": "2024-01-15T10:30:00",
  "error": "Database connection failed",
  "components": {
    "api": "ok",
    "database": "error",
    "cache": "ok",
    "storage": "ok"
  }
}
```

---

## Webhooks

### 列出 Webhooks

**GET** `/api/v2/webhooks` (需要 admin 权限)

**响应示例：**
```json
{
  "webhooks": [
    {
      "id": "wh_abc123",
      "name": "Download Notification",
      "url": "https://example.com/webhook",
      "events": ["download", "sync.complete"],
      "enabled": true,
      "created_at": "2024-01-10T10:00:00",
      "last_triggered": "2024-01-15T10:25:00",
      "trigger_count": 1250
    }
  ],
  "count": 1
}
```

---

### 创建 Webhook

**POST** `/api/v2/webhooks` (需要 admin 权限)

**请求体：**
```json
{
  "name": "New Download",
  "url": "https://example.com/webhook",
  "events": ["download"],
  "secret": "webhook-secret-key"
}
```

---

### 删除 Webhook

**DELETE** `/api/v2/webhooks/{webhook_id}` (需要 admin 权限)

---

### 测试 Webhook

**POST** `/api/v2/webhooks/{webhook_id}/test` (需要 admin 权限)

**响应示例：**
```json
{
  "success": true,
  "webhook_id": "wh_abc123",
  "status_code": 200,
  "response_time": 150,
  "response_body": "{\"status\":\"ok\"}"
}
```

---

## Minecraft 服务器核心 API

### 获取核心列表

**GET** `/api/v1/mc/corelist`

**响应示例：**
```json
{
  "corelist": [
    {
      "project": "paper",
      "metadata": {
        "current": "1.21.1"
      },
      "versions": ["1.21.1", "1.21", "1.20.6", "1.20.4"]
    },
    {
      "project": "spigot",
      "metadata": {
        "current": "1.20.4"
      },
      "versions": ["1.20.4", "1.20.1", "1.19.4"]
    }
  ]
}
```

---

### 获取特定核心版本列表

**GET** `/api/v1/mc/corelist/{name}`

**响应示例：**
```json
{
  "project": "paper",
  "metadata": {
    "current": "1.21.1"
  },
  "versions": ["1.21.1", "1.21", "1.20.6"]
}
```

---

### 获取所有版本

**GET** `/api/v1/mc/versions`

**GET** `/api/v1/mc/versions/{name}`

**响应示例：**
```json
{
  "core": "paper",
  "versions": {
    "paper": {
      "1.21.1": [
        {
          "version": "1.21.1",
          "file_name": "paper-1.21.1.jar",
          "size": 47185920,
          "modified": "2024-01-15T10:30:00"
        }
      ],
      "1.21": [
        {
          "version": "1.21",
          "file_name": "paper-1.21.jar",
          "size": 46000000,
          "modified": "2024-01-10T08:00:00"
        }
      ]
    }
  }
}
```

---

### 获取核心信息

**GET** `/api/v1/mc/info/{name}/{version}`

**响应示例：**
```json
{
  "core_name": "paper",
  "version": "1.21.1",
  "major_version": "1.21",
  "file_name": "paper-1.21.1.jar",
  "size": 47185920,
  "size_formatted": "45.0 MB",
  "modified": "2024-01-15T10:30:00",
  "sha256": "abc123...",
  "download_url": "/api/v1/mc/download/paper/1.21.1"
}
```

---

### 下载核心

**GET** `/api/v1/mc/download/{name}/{version}`

返回文件下载响应（302 重定向或直接文件流）

---

## JDK API

### 获取 JDK 下载链接（最新版本）

**GET** `/api/v2/jdk/retrieve/{arch}/{vendor}/{major}`

**参数说明：**
- `arch`: 架构，可选 `arm64`、`aarch64`、`amd64`、`x64`、`amd`
- `vendor`: 供应商，可选 `corretto`、`openjdk`
- `major`: 主版本号，如 `8`、`11`、`17`、`21`

**响应示例：**
```json
{
  "vendor": "corretto",
  "architecture": "arm64",
  "major_version": "21",
  "full_version": "21.0.10.7.1",
  "file_name": "amazon-corretto-21.0.10.7.1-linux-aarch64.tar.gz",
  "size": 207193683,
  "size_formatted": "197.60 MB",
  "modified": "2026-03-03T22:45:30.573436",
  "download_url": "/jdk/corretto/arm64/21/21.0.10.7.1/amazon-corretto-21.0.10.7.1-linux-aarch64.tar.gz",
  "direct_url": "http://download.hycexit.xyz/jdk/corretto/arm64/21/21.0.10.7.1/amazon-corretto-21.0.10.7.1-linux-aarch64.tar.gz"
}
```

---

### 获取 JDK 下载链接（指定版本）

**GET** `/api/v2/jdk/retrieve/{arch}/{vendor}/{major}/{full_version}`

**参数说明：**
- `arch`: 架构
- `vendor`: 供应商
- `major`: 主版本号
- `full_version`: 完整版本号，如 `17.0.18`、`21.0.10.7.1`

**响应示例：**
```json
{
  "vendor": "openjdk",
  "architecture": "arm64",
  "major_version": "17",
  "full_version": "17.0.18",
  "file_name": "jdk-17.0.18_linux-aarch64_bin.tar.gz",
  "size": 181262708,
  "size_formatted": "172.87 MB",
  "modified": "2026-03-03T21:22:35.848593",
  "download_url": "/jdk/openjdk/arm64/17/17.0.18/jdk-17.0.18_linux-aarch64_bin.tar.gz",
  "direct_url": "http://download.hycexit.xyz/jdk/openjdk/arm64/17/17.0.18/jdk-17.0.18_linux-aarch64_bin.tar.gz"
}
```

---

### 获取所有 JDK 版本列表

**GET** `/api/v2/jdk/list`

**响应示例：**
```json
{
  "vendors": [
    {
      "name": "corretto",
      "architectures": [
        {
          "name": "arm64",
          "major_versions": [
            {
              "major": "21",
              "versions": ["21.0.10.7.1"]
            },
            {
              "major": "17",
              "versions": ["17.0.12.7.1", "17.0.11.9.1"]
            }
          ]
        }
      ]
    }
  ]
}
```

---

### 获取特定供应商的 JDK 版本列表

**GET** `/api/v2/jdk/list/{vendor}`

**示例：** `/api/v2/jdk/list/corretto`

---

### 支持的文件格式

JDK API 支持以下文件格式：
- `.tar.gz` - Linux/macOS 常见
- `.tar.xz` - 高压缩比 tarball
- `.tar.bz2` - bzip2 压缩
- `.zip` - Windows/Linux 通用
- `.bin` - 老版本 JDK 安装脚本
- `.msi` - Windows 安装程序
- `.dmg` - macOS 镜像
- `.pkg` - macOS 安装包

---

## 镜像站管理 API

### 获取镜像站信息

**GET** `/api/v1/mirror/info`

**响应示例：**
```json
{
  "server_name": "HYC Download Station",
  "version": "2.3.0",
  "uptime": 86400,
  "total_files": 1520,
  "total_size": 107374182400,
  "api_version": "v1"
}
```

---

### 刷新镜像源

**POST** `/api/v1/mirror/refresh` (需要认证)

**响应示例：**
```json
{
  "success": true,
  "message": "Mirror refresh initiated"
}
```

---

### 获取镜像状态

**GET** `/api/v1/mirror/status`

**响应示例：**
```json
{
  "running": true,
  "active_syncs": 2,
  "completed_syncs": 1250,
  "failed_syncs": 3,
  "last_sync": "2024-01-15T02:00:00"
}
```

---

### 获取同步速度

**GET** `/api/v1/mirror/speed`

**响应示例：**
```json
{
  "upload": 1024,
  "download": 5120,
  "unit": "KB/s"
}
```

---

### 获取带宽使用

**GET** `/api/v1/mirror/bandwidth`

**响应示例：**
```json
{
  "total": 10737418240,
  "used": 2147483648,
  "percentage": 20.0
}
```

---

## API v2 - 增强版 API

API v2 是 v1 的超集，添加了更多增强功能。

### 认证 API

#### 验证认证状态

**POST** `/api/v2/admin/auth/verify`

**成功响应 (200)：**
```json
{
  "valid": true,
  "level": "admin",
  "user_id": "admin",
  "permissions": ["admin:*", "files:*", "sync:*"],
  "expires_at": null
}
```

**未认证响应 (401)：**
```json
{
  "valid": false,
  "error": "Invalid or expired credentials"
}
```

---

### 增强搜索 API

#### 增强搜索

**GET** `/api/v2/search/enhanced`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| q | string | 是 | 搜索关键词 |
| type | string | 否 | 搜索类型 (all, file, dir) |
| mode | string | 否 | 搜索模式 (fuzzy, exact, regex) |
| limit | integer | 否 | 返回结果数量限制 |
| offset | integer | 否 | 偏移量 |

**响应示例：**
```json
{
  "query": "ubuntu",
  "total": 25,
  "results": [
    {
      "name": "ubuntu-22.04.iso",
      "path": "ubuntu/ubuntu-22.04.iso",
      "type": "file",
      "size": 4588563456,
      "size_formatted": "4.3 GB",
      "modified": "2024-01-15T10:30:00"
    }
  ],
  "search_mode": "fuzzy",
  "took_ms": 15
}
```

#### 按标签搜索

**GET** `/api/v2/search/by-tag`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| tag | string | 是 | 标签名称 |
| limit | integer | 否 | 返回结果数量限制 |

#### 按日期搜索

**GET** `/api/v2/search/by-date`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| from | string | 否 | 开始日期 (ISO格式) |
| to | string | 否 | 结束日期 (ISO格式) |
| order | string | 否 | 排序 (asc, desc) |

---

### 增强统计 API

#### 详细统计

**GET** `/api/v2/stats/detailed`

**响应示例：**
```json
{
  "total_files": 1520,
  "total_dirs": 245,
  "total_size": 107374182400,
  "total_size_formatted": "100.0 GB",
  "downloads_total": 52340,
  "downloads_today": 1250,
  "downloads_week": 8750,
  "file_types": {
    "application/octet-stream": 850,
    "text/plain": 320,
    "image/png": 150
  },
  "top_downloads": [
    {"path": "ubuntu-22.04.iso", "count": 1523}
  ]
}
```

#### 热门文件

**GET** `/api/v2/stats/trending`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| period | string | 否 | 时间周期 (day, week, month) |
| limit | integer | 否 | 返回数量限制 |

#### 下载趋势

**GET** `/api/v2/stats/download-trend`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| from | string | 否 | 开始日期 |
| to | string | 否 | 结束日期 |
| period | string | 否 | 聚合周期 (hour, day, week) |

#### 按周期下载统计

**GET** `/api/v2/stats/download-by-period`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| period | string | 否 | 周期 (hour, day, week, month) |
| limit | integer | 否 | 返回数量限制 |

#### 下载排行

**GET** `/api/v2/stats/rank`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | string | 否 | 排行类型 (downloads, size, recent) |
| limit | integer | 否 | 返回数量限制 |

---

### 文件操作 API

#### 文件元数据

**GET** `/api/v2/file/{path}/metadata`

**PUT** `/api/v2/file/{path}/metadata` (需要认证)

**请求体：**
```json
{
  "tags": ["linux", "os", "lts"],
  "description": "Ubuntu 22.04 LTS Server",
  "custom_fields": {
    "version": "22.04",
    "architecture": "amd64"
  }
}
```

**响应示例：**
```json
{
  "path": "ubuntu-22.04.iso",
  "name": "ubuntu-22.04.iso",
  "size": 4588563456,
  "modified": "2024-01-15T10:30:00",
  "tags": ["linux", "os", "lts"],
  "description": "Ubuntu 22.04 LTS Server",
  "custom_fields": {
    "version": "22.04",
    "architecture": "amd64"
  },
  "created_at": "2024-01-10T08:00:00",
  "last_accessed": "2024-01-15T10:30:00"
}
```

#### 文件版本

**GET** `/api/v2/file/{path}/versions`

**POST** `/api/v2/file/{path}/versions` (需要认证)

**响应示例：**
```json
{
  "path": "config.json",
  "current_version": 3,
  "versions": [
    {
      "version": 3,
      "modified": "2024-01-15T10:30:00",
      "modified_by": "admin",
      "size": 2048,
      "changes": "Updated timeout settings"
    },
    {
      "version": 2,
      "modified": "2024-01-10T08:00:00",
      "modified_by": "admin",
      "size": 1920,
      "changes": "Added new endpoints"
    }
  ]
}
```

#### 缩略图

**GET** `/api/v2/file/{path}/thumbnail`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| size | string | 否 | 尺寸 (small, medium, large) |

**响应：** 图片文件或 404

#### 批量元数据操作

**GET** `/api/v2/metadata/batch`

**PUT** `/api/v2/metadata/batch` (需要认证)

**请求体：**
```json
{
  "files": ["file1.txt", "file2.txt"],
  "action": "add_tags",
  "tags": ["batch", "uploaded"]
}
```

---

### 监控 API

#### 实时监控

**GET** `/api/v2/monitor/realtime`

**响应示例：**
```json
{
  "cpu": {
    "percent": 35.5,
    "cores": 4,
    "freq_mhz": 2400
  },
  "memory": {
    "total": 8589934592,
    "used": 3221225472,
    "percent": 37.5,
    "available": 5368709120
  },
  "disk": {
    "total": 536870912000,
    "used": 107374182400,
    "percent": 20.0,
    "read_bytes": 10485760,
    "write_bytes": 5242880
  },
  "network": {
    "rx_bytes": 1048576000,
    "tx_bytes": 524288000,
    "rx_speed": "1.2 MB/s",
    "tx_speed": "512 KB/s",
    "connections": 45
  },
  "uptime": 86400,
  "timestamp": "2024-01-15T10:30:00"
}
```

#### 监控历史

**GET** `/api/v2/monitor/history`

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| metric | string | 否 | 指标类型 (cpu, memory, disk, network) |
| from | string | 否 | 开始时间 |
| to | string | 否 | 结束时间 |
| interval | string | 否 | 采样间隔 |

#### 详细监控

**GET** `/api/v2/monitor/detailed`

---

### 健康检查 API

#### 镜像源健康检查

**GET** `/api/v2/health/sources`

**响应示例：**
```json
{
  "sources": [
    {
      "name": "ubuntu-releases",
      "status": "healthy",
      "latency_ms": 45,
      "last_check": "2024-01-15T10:25:00",
      "success_rate": 99.5
    },
    {
      "name": "debian-cd",
      "status": "degraded",
      "latency_ms": 120,
      "last_check": "2024-01-15T10:25:00",
      "success_rate": 95.0,
      "message": "High latency detected"
    }
  ],
  "total": 5,
  "healthy": 4,
  "degraded": 1,
  "unhealthy": 0
}
```

#### 检查特定镜像源

**GET** `/api/v2/health/check/{name}

**响应示例：**
```json
{
  "name": "ubuntu-releases",
  "status": "healthy",
  "latency_ms": 45,
  "http_code": 200,
  "last_check": "2024-01-15T10:30:00",
  "message": "Connection successful"
}
```

#### 故障切换

**GET** `/api/v2/health/failover`

**响应示例：**
```json
{
  "enabled": true,
  "auto_failover": true,
  "current_primary": "ubuntu-releases",
  "fallback": "ubuntu-alternate",
  "failover_count": 2,
  "last_failover": "2024-01-14T02:00:00"
}
```

**POST** `/api/v2/health/failover/{type}` (需要认证)

触发手动故障切换

#### 健康检查统计

**GET** `/api/v2/health/stats`

---

### Webhooks API

#### 列出 Webhooks

**GET** `/api/v2/webhooks` (需要 admin 权限)

**响应示例：**
```json
{
  "webhooks": [
    {
      "id": "wh_abc123",
      "name": "Download Notification",
      "url": "https://example.com/webhook",
      "events": ["download", "sync.complete"],
      "enabled": true,
      "created_at": "2024-01-10T10:00:00",
      "last_triggered": "2024-01-15T10:25:00",
      "trigger_count": 1250,
      "success_rate": 99.8
    }
  ],
  "count": 1
}
```

#### 创建 Webhook

**POST** `/api/v2/webhooks` (需要 admin 权限)

**请求体：**
```json
{
  "name": "New Webhook",
  "url": "https://example.com/webhook",
  "events": ["download", "sync.complete"],
  "secret": "webhook-secret-key",
  "headers": {
    "X-Custom-Header": "value"
  }
}
```

#### 获取 Webhook

**GET** `/api/v2/webhooks/{id}` (需要 admin 权限)

#### 更新 Webhook

**PUT** `/api/v2/webhooks/{id}` (需要 admin 权限)

#### 删除 Webhook

**DELETE** `/api/v2/webhooks/{id}` (需要 admin 权限)

#### 测试 Webhook

**POST** `/api/v2/webhooks/{id}/test` (需要 admin 权限)

**响应示例：**
```json
{
  "success": true,
  "webhook_id": "wh_abc123",
  "status_code": 200,
  "response_time": 150,
  "response_body": "{\"status\":\"ok\"}"
}
```

#### Webhook 交付历史

**GET** `/api/v2/webhooks/{id}/deliveries` (需要 admin 权限)

#### Webhook 统计

**GET** `/api/v2/webhooks/{id}/stats` (需要 admin 权限)

---

### 同步管理 API

#### 获取同步源

**GET** `/api/v2/sync/sources` (需要认证)

**POST** `/api/v2/sync/sources` (需要认证)

#### 控制同步

**POST** `/api/v2/sync/{name}/start` (需要认证)

**POST** `/api/v2/sync/{name}/stop` (需要认证)

**GET** `/api/v2/sync/{name}/status` (需要认证)

#### 同步历史

**GET** `/api/v2/sync/history` (需要认证)

#### 同步软件包

**POST** `/api/v2/sync/packages` (需要认证)

**GET** `/api/v2/sync/packages/{name}/status` (需要认证)

---

### 缓存管理 API

#### 缓存统计

**GET** `/api/v2/cache/stats` (需要认证)

#### 清理缓存

**POST** `/api/v2/cache/clean` (需要认证)

**请求体：**
```json
{
  "pattern": "*.tmp",
  "older_than": 86400
}
```

#### 缓存使用

**GET** `/api/v2/cache/usage` (需要认证)

**响应示例：**
```json
{
  "total_size": 10737418240,
  "total_size_formatted": "10.0 GB",
  "file_count": 1520,
  "by_type": {
    "pypi": 5368709120,
    "npm": 2684354560,
    "docker": 2147483648
  }
}
```

#### 热门缓存

**GET** `/api/v2/cache/popular` (需要认证)

---

### 缓存预热 API

#### 预热状态

**GET** `/api/v2/cache/prewarm` (需要认证)

**POST** `/api/v2/cache/prewarm` (需要认证)

**请求体：**
```json
{
  "urls": [
    "https://pypi.org/packages/source/d/django/Django-5.0.tar.gz",
    "https://registry.npmjs.org/react/-/react-18.2.0.tgz"
  ],
  "priority": "high"
}
```

#### 预热统计

**GET** `/api/v2/cache/prewarm/stats` (需要认证)

#### 预热项目

**GET** `/api/v2/cache/prewarm/items` (需要认证)

**POST** `/api/v2/cache/prewarm/items` (需要认证)

#### 预热历史

**GET** `/api/v2/cache/prewarm/history` (需要认证)

#### 清空预热队列

**POST** `/api/v2/cache/prewarm/clear` (需要认证)

#### 热门预热

**GET** `/api/v2/cache/prewarm/popular` (需要认证)

**POST** `/api/v2/cache/prewarm/popular` (需要认证)

#### 预热配置

**GET** `/api/v2/cache/prewarm/config` (需要认证)

**PUT** `/api/v2/cache/prewarm/config` (需要认证)

---

### 镜像加速 API

#### 列出镜像

**GET** `/api/v2/mirrors` (需要认证)

**POST** `/api/v2/mirrors` (需要认证)

**请求体：**
```json
{
  "name": "pypi-cn",
  "type": "pypi",
  "url": "https://pypi.cn",
  "enabled": true
}
```

#### 管理镜像

**PUT** `/api/v2/mirrors/{name}` (需要认证)

**DELETE** `/api/v2/mirrors/{name}` (需要认证)

#### 启用/禁用镜像

**PUT** `/api/v2/mirrors/{name}/enable` (需要认证)

**请求体：**
```json
{
  "enabled": true
}
```

#### 刷新镜像

**POST** `/api/v2/mirrors/{name}/refresh` (需要认证)

#### PyPI 镜像

**GET** `/api/v2/mirrors/pypi/{path}`

#### NPM 镜像

**GET** `/api/v2/mirrors/npm/{path}`

#### Go 镜像

**GET** `/api/v2/mirrors/go/{path}`

#### Docker 镜像

**GET** `/api/v2/mirrors/docker/{path}`

---

### 用户管理 API

#### 用户登录

**POST** `/api/v2/user/login`

**请求体：**
```json
{
  "username": "admin",
  "password": "password123"
}
```

**响应示例：**
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1736841600
}
```

#### 修改密码

**POST** `/api/v2/user/password` (需要认证)

**请求体：**
```json
{
  "old_password": "oldpassword",
  "new_password": "newpassword123"
}
```

#### 登录日志

**GET** `/api/v2/user/login-logs` (需要认证)

---

### 配置管理 API

#### 获取配置

**GET** `/api/v2/config` (需要 admin 权限)

**PUT** `/api/v2/config` (需要 admin 权限)

#### 重载配置

**POST** `/api/v2/config/reload` (需要 admin 权限)

**响应示例：**
```json
{
  "success": true,
  "message": "Configuration reloaded",
  "changes": 3
}
```

#### 配置变更历史

**GET** `/api/v2/config/changes` (需要 admin 权限)

---

### 告警管理 API

#### 获取告警

**GET** `/api/v2/alerts` (需要认证)

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| severity | string | 否 | 严重程度 (info, warning, error, critical) |
| acknowledged | boolean | 否 | 是否已确认 |
| limit | integer | 否 | 返回数量限制 |

**响应示例：**
```json
{
  "alerts": [
    {
      "id": "alert_001",
      "severity": "warning",
      "title": "High CPU Usage",
      "message": "CPU usage above 80% for 5 minutes",
      "timestamp": "2024-01-15T10:30:00",
      "acknowledged": false,
      "source": "monitor"
    }
  ],
  "count": 1,
  "unacknowledged": 1
}
```

#### 确认告警

**POST** `/api/v2/alerts/{id}/acknowledge` (需要认证)

#### 清空告警

**POST** `/api/v2/alerts/clear` (需要 admin 权限)

**请求体：**
```json
{
  "severity": "info",
  "older_than": 86400
}
```

#### 测试告警

**POST** `/api/v2/alerts/test` (需要 admin 权限)

**请求体：**
```json
{
  "type": "email",
  "recipients": ["admin@example.com"]
}
```

#### 告警配置

**GET** `/api/v2/alerts/config` (需要 admin 权限)

**PUT** `/api/v2/alerts/config` (需要 admin 权限)

**请求体：**
```json
{
  "email": {
    "enabled": true,
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "recipients": ["admin@example.com"]
  },
  "webhook": {
    "enabled": true,
    "url": "https://example.com/alerts"
  },
  "rules": [
    {
      "name": "High CPU",
      "condition": "cpu.percent > 80",
      "severity": "warning",
      "actions": ["email", "webhook"]
    }
  ]
}
```

---

### Prometheus 指标

**GET** `/api/v2/metrics`

返回 Prometheus 格式的指标数据。

---

### 活动日志 API

**GET** `/api/v2/activity` (需要认证)

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | string | 否 | 活动类型 |
| limit | integer | 否 | 返回数量限制 |
| offset | integer | 否 | 偏移量 |

**响应示例：**
```json
{
  "activities": [
    {
      "id": 1001,
      "type": "file.download",
      "user": "admin",
      "path": "ubuntu-22.04.iso",
      "ip": "192.168.1.100",
      "timestamp": "2024-01-15T10:30:00",
      "details": {
        "size": "4.3 GB"
      }
    }
  ],
  "count": 1,
  "total": 52340
}
```

---

### 服务器管理 API

#### 重启管理

**GET** `/api/v2/server/restart` (需要认证)

**POST** `/api/v2/server/restart` (需要 admin 权限)

**请求体：**
```json
{
  "schedule": "2024-01-15T23:00:00",
  "notify_users": true
}
```

**响应示例：**
```json
{
  "success": true,
  "scheduled": true,
  "restart_time": "2024-01-15T23:00:00",
  "pending_requests": 15
}
```

#### 确认重启

**POST** `/api/v2/server/restart/confirm` (需要认证)

#### 立即重启

**POST** `/api/v2/server/restart/immediate` (需要 admin 权限)

#### 待处理请求

**GET** `/api/v2/server/restart/pending` (需要 admin 权限)

#### 重启历史

**GET** `/api/v2/server/restart/history` (需要 admin 权限)

#### 重启配置

**GET** `/api/v2/server/restart/config` (需要 admin 权限)

**PUT** `/api/v2/server/restart/config` (需要 admin 权限)

**请求体：**
```json
{
  "require_confirmation": true,
  "confirmation_timeout": 300,
  "notify_before_restart": true,
  "notify_seconds_before": 60,
  "allowed_users": ["admin"]
}
```

#### 服务器信息

**GET** `/api/v2/server/info`

**响应示例：**
```json
{
  "version": "2.3.0",
  "uptime": 86400,
  "hostname": "hyc-server",
  "platform": "Linux",
  "platform_version": "Ubuntu 22.04",
  "python_version": "3.11.0",
  "arch": "x86_64",
  "cpu_count": 4,
  "memory_total": 8589934592,
  "disk_total": 536870912000,
  "started_at": "2024-01-14T10:30:00"
}
```

---

### API 文档 API

#### 获取 API 文档

**GET** `/api/v2/api-docs.json`

**GET** `/api/v2/api-docs.yaml`

#### 生成 API 文档

**POST** `/api/v2/api-docs/generate` (需要 admin 权限)

---

## WebSocket

### 连接

**GET** `/ws`

建立 WebSocket 连接以接收实时更新。

**响应：** 101 Switching Protocols

---

## SSE 事件流

### 订阅

**GET** `/sse/stream`

订阅 Server-Sent Events 实时更新。

**响应：** 200 OK (流连接)

---

## 错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 405 | 方法不允许 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用 |

---

## 状态码说明

| 状态码 | 说明 |
|--------|------|
| 101 | 连接升级成功 (WebSocket) |
| 200 | 成功 |
| 206 | 部分内容 (断点续传) |
| 301 | 永久重定向 |
| 304 | 未修改 |
| 416 | 请求范围不符合 |

---

> 最后更新: 2026-02-19
> 版本: 2.3.0