API 文档

快速开始

# 健康检查 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 配置。 当 auth_type: none 时，所有接口无需认证即可访问（默认模式）。

Bearer Authorization: Bearer <token> JWT Token
Basic Authorization: Basic <base64> 用户名:密码 认证

文件管理

列出文件

GET/api/v1/files
参数类型说明
pathstring目录路径
recursivebool递归列出
{"files": [{"name": "ubuntu.iso", "size": 4588563456}], "page": 1}

获取文件信息

GET/api/v1/file/{path}

文件预览

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

支持文本、图片、JSON 预览，最大 10MB

{"path": "readme.txt", "preview_available": true, "preview_type": "text", "content": "..."}

删除文件

DELETE/api/v1/file/{path}

创建目录

PUT/api/v1/mkdir
{"path": "/downloads/new"}

上传文件

POST/api/v1/upload

multipart/form-data 表单，参数: path(目标目录), file(文件)

批量操作

POST/api/v1/batch
{"operation": "delete", "files": ["f1.iso", "f2.iso"], "target_dir": ""}

operation: delete, move, copy

压缩/解压

POST/api/v1/archive
{"operation": "compress", "files": ["file1", "file2"], "archive_name": "archive.zip"}
{"operation": "extract", "files": ["archive.zip"], "target_dir": "extracted/"}
GET/api/v1/search?q=关键词
参数类型说明
qstring搜索关键词
typestringall, file, dir
limitint结果数量限制

镜像同步

同步源管理

GET/api/v1/sync/sources

获取同步源列表

POST/api/v1/sync/sources
{"name": "ubuntu", "config": {"url": "https://...", "target": "ubuntu/"}}
DELETE/api/v1/sync/sources/{name}

删除同步源

同步状态

GET/api/v1/sync/status
{"running": true, "progress": 45.5, "synced": 1250, "total": 2748, "speed": "2.5 MB/s"}

控制同步

POST/api/v1/sync/start
{"name": "ubuntu"}
POST/api/v1/sync/stop
{"name": "ubuntu"}

加速源 (Mirror)

镜像列表

GET/api/v1/mirror/list

type: docker, apt, yum, pypi, npm, go

GET/api/v1/mirror/{type}/list
GET/api/v1/mirror/{type}/search?q=关键词

镜像操作

GET/api/v1/mirror/info
GET/api/v1/mirror/status
GET/api/v1/mirror/speed
GET/api/v1/mirror/bandwidth
POST/api/v1/mirror/refresh
{"speed": {"upload": 1024, "download": 2048, "unit": "KB/s"}}

Minecraft 服务

核心列表

GET/api/v1/mc/corelist
GET/api/v1/mc/corelist/{name}
{"corelist": [{"project": "Paper", "versions": ["1.21.1", "1.20.4"]}]}

版本列表

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

下载核心

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

下载指定版本的核心文件 (重定向到下载链接)

核心信息

GET/api/v1/mc/info/{name}/{version}
{"core_name": "Paper", "version": "1.21.1", "size": 52428800, "sha256": "abc123..."}

缓存管理

缓存统计

GET/api/v1/cache/stats
{"size": 10737418240, "count": 1520, "hit_rate": 85.5}

缓存统计 V2

GET/api/v2/cache/stats
{"size": 10737418240, "count": 1520, "hit_rate": 85.5, "miss_count": 256, "last_clean": "2024-01-15T10:30:00"}

缓存使用详情

GET/api/v2/cache/usage
{"entries": [{"key": "docker/ubuntu:latest", "size": 52428800, "access_count": 1250, "last_access": "2024-01-15T10:30:00"}], "page": 1, "total": 1520}

清理缓存

POST/api/v1/cache/clean

清空缓存

DELETE/api/v1/cache

V2 加速源 API

获取镜像列表

GET/api/v2/mirrors
{"mirrors": {"docker": {"enabled": true, "count": 156}, "apt": {"enabled": true, "count": 45820}, "custom-mirror": {"enabled": true, "type": "custom", "url": "https://mirror.example.com"}}}

添加镜像

POST/api/v2/mirrors
{"name": "custom-mirror", "type": "custom", "url": "https://mirror.example.com", "description": "自定义镜像", "enabled": true, "cache_enabled": true, "cache_ttl": 86400}

更新镜像

PUT/api/v2/mirrors/{name}

删除镜像

DELETE/api/v2/mirrors/{name}

启用/禁用镜像

PUT/api/v2/mirrors/{name}/enable?enabled=true

刷新镜像

POST/api/v2/mirrors/{name}/refresh

V2 监控 API

实时监控

GET/api/v2/monitor/realtime
{"cpu": {"percent": 35.5, "count": 8, "model": "Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz"}, "memory": {"percent": 37.5, "total": 17179869184, "used": 6442450944}, "disk": {"percent": 20.0, "total": 536870912000, "used": 53687091200}, "network": {"upload": 1024, "download": 2048}}

历史数据

GET/api/v2/monitor/history?metric=cpu&start=2024-01-01&end=2024-01-15
{"metric": "cpu", "data": [{"timestamp": "2024-01-15T10:00:00", "value": 35.5}, {"timestamp": "2024-01-15T10:05:00", "value": 38.2}], "avg": 36.8, "max": 45.2, "min": 28.5}

V2 健康检查 API

健康状态

GET/api/v1/health
{"status": "healthy", "timestamp": "2024-01-15T10:30:00", "version": "2.2.0", "uptime": 86400, "system": {"cpu_percent": 35.5, "memory_percent": 37.5, "disk_percent": 20.0}}

镜像源健康

GET/api/v2/health/sources
{"sources": [{"name": "docker", "status": "healthy", "latency_ms": 125, "last_check": "2024-01-15T10:30:00"}, {"name": "apt", "status": "healthy", "latency_ms": 89}], "overall": "healthy"}

故障切换状态

GET/api/v2/health/failover
{"enabled": true, "active": false, "failover_count": 0, "last_failover": null}

V2 告警管理 API

获取告警

GET/api/v2/alerts
{"alerts": [{"id": "alert-001", "type": "disk", "severity": "warning", "message": "Disk usage above 80%", "timestamp": "2024-01-15T10:30:00", "acknowledged": false}], "total": 1}

确认告警

POST/api/v2/alerts/{id}/acknowledge

告警配置

GET/api/v2/alerts/config
{"enabled": true, "disk_warning": 80, "disk_critical": 90, "email_enabled": true, "smtp_server": "smtp.example.com", "alert_email": "admin@example.com"}

更新告警配置

PUT/api/v2/alerts/config

V2 Webhooks API

列出 Webhooks

GET/api/v2/webhooks (admin)
{"webhooks": [{"id": "wh-001", "name": "Download Notify", "url": "https://example.com/webhook", "events": ["download", "upload"], "enabled": true}], "total": 1}

创建 Webhook

POST/api/v2/webhooks (admin)
{"name": "Download Notify", "url": "https://example.com/webhook", "events": ["download", "sync_complete"], "headers": {"Authorization": "Bearer token"}, "enabled": true}

获取 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)
{"success": true, "status_code": 200, "response_time_ms": 150, "response_body": "OK"}

V2 服务器管理 API

服务器信息

GET/api/v2/server/info
{"version": "2.2.0", "uptime": 86400, "platform": "Linux x86_64", "python_version": "3.10.12", "pid": 1234, "config_path": "/etc/hyc/settings.json"}

重启服务器

POST/api/v2/server/restart
{"message": "Server restart initiated", "delay_seconds": 5}

关闭服务器

POST/api/v2/server/shutdown

服务器日志

GET/api/v2/server/logs?lines=100
{"logs": ["2024-01-15 10:30:00 INFO: Server started", "2024-01-15 10:30:01 INFO: Health check passed"], "total_lines": 100}

V2 配置管理 API

获取配置

GET/api/v1/config

获取配置 V2

GET/api/v2/config
{"success": true, "config": "{\"port\": 8080, \"base_dir\": \"./downloads\"...}, "path": "/etc/hyc/settings.json"}

保存配置

PUT/api/v2/config
{"success": true, "message": "Configuration saved"}

重新加载配置

POST/api/v2/config/reload

V2 增强统计 API

基础统计

GET/api/v1/stats
{"total_files": 1520, "total_size": 107374182400, "total_downloads": 52340, "downloads_today": 1250, "downloads_week": 8920}

详细统计

GET/api/v2/stats/detailed
{"total_files": 1520, "total_size": 107374182400, "file_types": {"application/octet-stream": 850, "text/plain": 320, "application/json": 150}, "top_downloads": [{"file": "ubuntu-22.04.iso", "count": 5234}], "daily_stats": [{"date": "2024-01-15", "downloads": 1250, "size": 5368709120}]}

监控统计

基础统计

GET/api/v1/stats
{"total_files": 1520, "total_size": 107374182400, "total_downloads": 52340}

实时监控

GET/api/v2/monitor/realtime
{"cpu": {"percent": 35.5, "count": 8}, "memory": {"percent": 37.5, "total": 17179869184}, "disk": {"percent": 20.0, "used": 53687091200}}

健康检查

GET/api/v1/health
{"status": "healthy", "timestamp": "2024-01-15T10:30:00", "version": "2.2.0", "uptime": 86400, "system": {"cpu_percent": 35.5, "memory_percent": 37.5}}

认证管理

POST/api/v2/admin/auth/verify
{"valid": true, "level": "admin", "user_id": "admin", "permissions": [...]}
{"valid": false, "error": "Invalid credentials"}

Webhooks

GET/api/v2/webhooks (admin)
POST/api/v2/webhooks (admin)
{"name": "Download Notify", "url": "https://...", "events": ["download"]}

Webhook 操作

GET/api/v2/webhooks/{id} (admin)
DELETE/api/v2/webhooks/{id} (admin)
POST/api/v2/webhooks/{id}/test (admin)
{"success": true, "status_code": 200, "response_time": 150}

WebSocket

GET/ws

建立 WebSocket 连接接收实时更新

# 连接示例 wss://your-server/ws # 接收消息 {"type": "download", "file": "ubuntu.iso", "size": 4588563456}

SSE 事件流

GET/sse/stream

订阅 Server-Sent Events 实时更新

# 请求头 Accept: text/event-stream # 接收消息 event: download data: {"file": "ubuntu.iso", "size": 4588563456}

错误码

200
成功
201
已创建
400
请求错误
401
未认证
403
无权限
404
不存在
405
方法不允许
413
文件过大
500
服务器错误
503
服务不可用

HYC下载站 API v2.3.0 · 最后更新 2026-02-19