HYC下载站 v2.3

模块化重构的Python镜像文件服务器，支持API版本化、实时通信、系统监控、数据库集成等高级功能。

项目结构

mirror_server/
├── main.py                      # 主入口文件
├── requirements.txt             # 依赖列表
├── settings.json                # 主配置文件
├── auth_token.txt              # 认证令牌文件
├── api/                         # API模块
│   ├── __init__.py
│   ├── router.py                # API路由器
│   ├── v1.py                    # API v1（基础功能）
│   ├── v2.py                    # API v2（增强功能）
│   ├── admin.py                 # 管理接口
│   ├── ws_handler.py            # WebSocket处理
│   ├── sse_handler.py           # SSE事件流
│   └── docs/                    # API文档
├── core/                        # 核心模块
│   ├── __init__.py
│   ├── config.py                # 配置管理
│   ├── config_hotreload.py      # 配置热重载
│   ├── utils.py                 # 工具函数
│   ├── server.py                # 服务器核心
│   ├── database.py              # 数据库管理
│   ├── mirror_sync.py           # 镜像同步管理
│   ├── sync_scheduler.py        # 同步调度器
│   ├── sync_engine.py           # 同步引擎
│   ├── cache_manager.py          # 缓存管理
│   ├── cache_prewarm.py         # 缓存预热
│   ├── monitor.py               # 系统监控
│   ├── health_check.py          # 健康检查
│   ├── alerts.py                # 告警系统
│   ├── security.py              # 安全模块
│   ├── api_auth.py              # API认证
│   ├── api_docs.py              # API文档
│   ├── optimization.py          # 性能优化
│   ├── scheduler.py             # 任务调度
│   ├── graceful_restart.py      # 优雅重启
│   └── prometheus.py            # Prometheus监控
├── handlers/                    # HTTP请求处理器
│   ├── __init__.py
│   └── http_handler.py          # HTTP请求处理
├── mirrors/                     # 镜像加速源模块
│   ├── __init__.py
│   ├── http.py                  # HTTP/HTTPS镜像
│   ├── docker.py                # Docker Hub镜像
│   ├── apt.py                  # APT镜像
│   ├── yum.py                  # YUM镜像
│   ├── pypi.py                 # PyPI镜像
│   ├── npm.py                  # npm镜像
│   └── go.py                   # Go镜像
├── scripts/                     # 辅助脚本
├── data/                        # 数据目录
├── docker/                      # Docker配置
└── k8s/                        # Kubernetes配置

安装

pip install -r requirements.txt

依赖

• psutil - 系统监控
• python-multipart - 多部分表单数据处理
• paramiko - SFTP支持（可选）

使用

基本使用

# 启动服务器（默认端口8080）
python main.py

# 指定端口和目录
python main.py -p 8080 -d ./downloads

# 启用HTTPS
python main.py --ssl-cert cert.pem --ssl-key key.pem

# 使用配置文件
python main.py --config config.json

# 指定API版本 (默认: v2)
python main.py --api-version v2

# 使用settings.json配置文件
python main.py --settings settings.json

# 检查系统兼容性
python main.py --check-compat

认证

# 无认证
python main.py --auth-type none

# 基本认证
python main.py --auth-type basic --auth-user admin --auth-pass password

# 令牌认证
python main.py --auth-type token --auth-token your_token_here

功能开关

# 禁用监控/同步/加速源
python main.py --enable-monitor --enable-sync --enable-mirrors

# 禁用WebSocket/SSE (适合低端设备)
python main.py --disable-ws --disable-sse

# 禁用文件哈希计算
python main.py --disable-hash

# 启用下载统计
python main.py --enable-stats --show-hash

# 启用目录浏览
python main.py --directory-listing true

镜像加速源

# 启用/禁用所有加速源功能
python main.py --enable-mirrors    # 启用
python main.py --enable-mirrors=false  # 禁用

# 各个镜像的启用/禁用通过 settings.json 配置
# 在 mirrors.xxx.enabled 中设置，例如:
# "docker": { "enabled": true, ... }
# "pypi": { "enabled": true, ... }

镜像同步配置

镜像同步支持多种同步类型，通过 settings.json 中的 sync_sources 配置：

{
  "mirrors": {
    "my-http-mirror": {
      "type": "http",
      "url": "https://example.com/mirror/",
      "target": "downloads/mirror",
      "enabled": true,
      "auto_sync": true,
      "schedule": { "enabled": true, "type": "cron", "cron": "0 4 * * *" }
    },
    "my-ftp-mirror": {
      "type": "ftp",
      "host": "ftp.example.com",
      "port": 21,
      "username": "anonymous",
      "password": "[email protected]",
      "remote_path": "/pub",
      "target": "downloads/ftp",
      "enabled": true
    },
    "my-sftp-mirror": {
      "type": "sftp",
      "host": "sftp.example.com",
      "port": 22,
      "username": "syncuser",
      "password": "password",
      "private_key": "/path/to/id_rsa",
      "remote_path": "/mirror",
      "target": "downloads/sftp"
    },
    "my-git-repo": {
      "type": "git",
      "url": "https://github.com/example/repo.git",
      "branch": "main",
      "depth": 1,
      "target": "downloads/git"
    },
    "my-s3-mirror": {
      "type": "s3",
      "endpoint": "https://s3.amazonaws.com",
      "bucket": "my-bucket",
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "us-east-1",
      "prefix": "mirrors/",
      "target": "downloads/s3"
    },
    "my-oss-mirror": {
      "type": "oss",
      "bucket": "my-bucket",
      "access_key": "your-access-key",
      "secret_key": "your-secret-key",
      "region": "cn-hangzhou",
      "target": "downloads/oss"
    },
    "my-cos-mirror": {
      "type": "cos",
      "bucket": "my-bucket",
      "access_key": "your-access-key",
      "secret_key": "your-secret-key",
      "region": "ap-guangzhou",
      "target": "downloads/cos"
    },
    "my-rsync-mirror": {
      "type": "rsync",
      "source": "rsync://rsync.example.com/module/path",
      "target": "downloads/rsync",
      "exclude": ["*.tmp", "*.log"]
    },
    "my-local-mirror": {
      "type": "local",
      "path": "/mnt/external drive/mirrors",
      "target": "downloads/local"
    }
  }
}

支持的同步类型：

类型	说明	必需配置
http / https	HTTP/HTTPS同步	url, target
ftp	FTP同步	host, target
sftp	SFTP同步	host, username, target
rsync	Rsync同步	source, target
git	Git仓库克隆/更新	url, target
s3	AWS S3 / MinIO	bucket, access_key, secret_key, endpoint
oss	阿里云OSS	bucket, access_key, secret_key
cos	腾讯云COS	bucket, access_key, secret_key
webdav	WebDAV同步	url, username, password
local	本地目录同步	path, target

下载限速

# 全局限速 (字节/秒)
python main.py --rate-limit 10485760  # 10MB/s

低端设备优化

# 使用预设配置
python main.py --preset ultra_low   # 超低功耗
python main.py --preset low         # 低配置
python main.py --preset medium       # 中等
python main.py --preset high         # 高性能
python main.py --preset auto         # 自动检测

# 自定义参数
python main.py --memory-limit 256M \
  --workers 2 \
  --chunk-size 64K \
  --buffer-size 128K

调试选项

# 启用所有调试
python main.py --debug

# 启用特定调试
python main.py --debug-http
python main.py --debug-auth
python main.py --debug-api
python main.py --debug-v2
python main.py --debug-error
python main.py --debug-download

# 输出到调试文件
python main.py --debug-log /var/log/hyc-debug.log

# 指定调试类型
python main.py --debug-types http auth api v2 error

# 详细输出
python main.py -v
python main.py -vv
python main.py -q  # 静默模式

启动参数完整列表

服务器配置:
  --host HOST              监听地址 (默认: 0.0.0.0)
  -p, --port PORT          监听端口 (默认: 8080)
  -d, --base-dir DIR       文件存储目录 (默认: ./downloads)
  --server-name NAME       服务器名称 (默认: HYC下载站)

HTTPS配置:
  --ssl-cert FILE          SSL证书文件路径
  --ssl-key FILE           SSL私钥文件路径

认证配置:
  --auth-type TYPE         认证类型: none/basic/token (默认: none)
  --auth-user USER         基本认证用户名 (默认: admin)
  --auth-pass PASS         基本认证密码
  --auth-token TOKEN       令牌认证密钥

功能配置:
  --directory-listing BOOL 启用目录浏览 (默认: True)
  --enable-stats BOOL      启用下载统计 (默认: True)
  --show-hash             显示文件哈希值
  --ignore-hidden         忽略隐藏文件 (默认: True)
  --max-upload-size SIZE  最大上传文件大小 (默认: 1G)
  --api-version VERSION   API版本: v1/v2 (默认: v2)

实时通信:
  --enable-ws             启用WebSocket (默认: True)
  --enable-sse            启用SSE (默认: True)

系统监控:
  --enable-monitor        启用系统监控 (默认: True)
  --monitor-interval SEC  监控采集间隔(秒) (默认: 5)

同步配置:
  --enable-sync           启用镜像同步 (默认: True)
  --sync-config FILE      同步配置文件路径

镜像加速源:
  --enable-mirrors        启用下载加速源 (默认: True)
  # 各个镜像通过 settings.json 配置 (mirrors.xxx.enabled)

下载限速:
  --rate-limit BYTES      全局下载限速 (默认: 0=不限速)

低端设备优化:
  --preset PRESET         设备预设: ultra_low/low/medium/high/auto (默认: auto)
  --memory-limit SIZE     内存限制 (例如: 256M, 512M, 1G)
  --workers NUM           工作进程数 (0=自动)
  --chunk-size SIZE       文件传输块大小 (默认: 128K)
  --buffer-size SIZE      缓冲区大小 (默认: 256K)
  --disable-ws            禁用WebSocket
  --disable-sse           禁用SSE
  --disable-hash          禁用文件哈希计算
  --check-compat          检查系统兼容性后退出

日志配置:
  --access-log FILE       访问日志文件路径
  -v, --verbose          详细输出 (可叠加: -vvv)
  -q, --quiet            静默模式

调试选项:
  -D, --debug            启用所有调试输出
  --debug-log FILE       调试日志文件路径
  --debug-http           调试HTTP请求
  --debug-auth           调试认证检查
  --debug-api            调试API路由
  --debug-v2             调试V2 API
  --debug-error          调试错误堆栈
  --debug-download       调试下载记录
  --debug-types TYPES    指定调试类型列表

配置文件:
  --settings FILE         默认配置文件路径 (默认: settings.json)
  --config FILE           覆盖配置文件路径 (JSON格式)

API版本

API v1 - 基础功能

• 文件管理：上传、下载、删除、搜索
• 目录浏览
• 基础统计
• 同步管理（HTTP/HTTPS、FTP、SFTP、本地）

示例API端点

GET  /api/v1/files              # 列出文件
GET  /api/v1/file/{path}        # 获取文件信息
DELETE /api/v1/file/{path}      # 删除文件
POST /api/v1/upload             # 上传文件
GET  /api/v1/search?q={term}    # 搜索文件
GET  /api/v1/stats              # 获取统计
GET  /api/v1/health             # 健康检查
POST /api/v1/sync/start         # 开始同步

API v2 - 增强功能

继承v1所有功能，额外提供：

• 增强搜索（模糊匹配、正则表达式、内容搜索）
• 按标签和日期范围搜索
• 文件元数据管理
• 文件版本控制
• 缩略图生成
• 实时服务器监控
• Webhook支持
• 历史数据分析

示例API端点

GET  /api/v2/search/enhanced?q={term}           # 增强搜索
GET  /api/v2/search/by-tag?tag={tag}            # 按标签搜索
GET  /api/v2/search/by-date?start={date}        # 按日期搜索
GET  /api/v2/stats/detailed                     # 详细统计
GET  /api/v2/stats/trending                     # 热门文件
GET  /api/v2/file/{path}/metadata               # 获取文件元数据
PUT  /api/v2/file/{path}/metadata               # 更新文件元数据
GET  /api/v2/file/{path}/versions               # 获取文件版本
POST /api/v2/file/{path}/versions               # 创建文件版本
GET  /api/v2/file/{path}/thumbnail?w=200&h=200 # 获取缩略图
GET  /api/v2/monitor/realtime                  # 实时监控
GET  /api/v2/webhooks                          # 列出webhooks
POST /api/v2/webhooks                          # 创建webhook

配置

配置文件示例

参考 config.example.json

命令行参数

服务器配置:
  --host                  监听地址 (默认: 0.0.0.0)
  -p, --port              监听端口 (默认: 8080)
  -d, --base-dir          文件存储目录 (默认: ./downloads)
  --server-name           服务器名称

HTTPS配置:
  --ssl-cert              SSL证书文件路径
  --ssl-key               SSL私钥文件路径

认证配置:
  --auth-type             认证类型: none, basic, token
  --auth-user             基本认证用户名
  --auth-pass             基本认证密码
  --auth-token            令牌认证密钥

功能配置:
  --no-directory-listing  禁用目录浏览
  --no-stats              禁用下载统计
  --show-hash             显示文件哈希值
  --max-upload-size       最大上传文件大小 (默认: 1G)
  --sync-config           同步配置文件路径
  --api-version           API版本: v1, v2 (默认: v1)

日志配置:
  --access-log            访问日志文件路径
  -v, --verbose           详细输出
  -q, --quiet             静默模式

配置:
  --config                配置文件路径 (JSON格式)

模块说明

core/ - 核心模块

• config.py: 配置管理和验证，支持多级配置合并
• config_hotreload.py: 配置文件热重载，无需重启生效
• utils.py: 通用工具函数（文件大小格式化、哈希计算等）
• server.py: 服务器核心类（基于标准库 http.server 的线程池服务器）
• database.py: 数据库管理，支持SQLite/MySQL/PostgreSQL
• mirror_sync.py: 镜像同步管理器（支持HTTP/HTTPS、FTP、SFTP、本地、Rsync、Git、S3/OSS/COS、WebDAV）
• sync_scheduler.py: 同步调度器，定时执行同步任务
• sync_engine.py: 同步引擎，核心同步逻辑
• cache_manager.py: 缓存管理，智能缓存策略
• cache_prewarm.py: 缓存预热，启动时预加载热门资源
• monitor.py: 系统监控，CPU/内存/磁盘/网络实时监控
• health_check.py: 健康检查，系统组件状态检测
• alerts.py: 告警系统，异常情况自动告警
• security.py: 安全模块，防护和审计
• api_auth.py: API认证，Token/Basic认证
• api_docs.py: API文档自动生成
• optimization.py: 性能优化，自动检测设备配置
• scheduler.py: 通用任务调度器
• graceful_restart.py: 优雅重启，服务无缝更新
• prometheus.py: Prometheus监控指标导出

api/ - API模块

• router.py: API路由器，支持版本化
• v1.py: API v1实现（基础功能）
• v2.py: API v2实现（增强功能，继承v1）
• admin.py: 管理接口，Webhooks管理
• ws_handler.py: WebSocket处理，实时双向通信
• sse_handler.py: SSE事件流，单向实时推送
• docs/: API文档 (index.html, api.md)

handlers/ - HTTP请求处理器

• http_handler.py: HTTP请求处理，包括文件服务、目录浏览等

特性

• ✅ 模块化设计，易于扩展
• ✅ API版本化支持（v1/v2）
• ✅ 镜像同步（HTTP/HTTPS、FTP、SFTP、Rsync、Git、S3/OSS/COS、WebDAV、本地目录）
• ✅ 文件上传下载（支持断点续传）
• ✅ 目录浏览（镜像站风格）
• ✅ 认证支持（无、基本认证、令牌认证）
• ✅ HTTPS支持
• ✅ 下载统计
• ✅ 文件搜索（基础/增强/正则）
• ✅ 批量操作
• ✅ 压缩/解压缩
• ✅ 增强搜索（v2）
• ✅ 文件元数据管理（v2）
• ✅ 服务器监控（v2）
• ✅ Webhook支持（v2）
• ✅ 实时通信（WebSocket + SSE）
• ✅ 数据库支持（SQLite/MySQL/PostgreSQL）
• ✅ 缓存系统（智能/手动/全同步）
• ✅ 配置热重载
• ✅ 优雅重启
• ✅ Prometheus监控
• ✅ 告警系统
• ✅ 设备自动优化
• ✅ 多镜像加速源（Docker/APT/YUM/PyPI/npm/Go）
• ✅ Web管理界面

开发

添加新的API版本

1. 在 api/ 目录下创建 v3.py
2. 继承 APIv2 或 APIv1
3. 实现所需方法
4. 在 api/router.py 中注册新版本

添加新的同步类型

在 core/mirror_sync.py 的 MirrorSyncManager 类中：

1. 添加 _sync_{type} 方法
2. 实现同步逻辑
3. 在 _sync_worker 中添加路由

构建和部署

使用 PyInstaller 打包成二进制文件

构建当前平台

项目提供 PyInstaller 打包配置，可以将项目打包成当前平台的二进制可执行文件。

# 安装 PyInstaller
pip install pyinstaller

# 构建当前平台（使用仓库内的打包配置）
pyinstaller hyc-download.spec

# 使用旧的打包配置（含 aiohttp 隐藏依赖，已弃用）
# pyinstaller pyinstaller.spec

支持的平台（仅当前平台）：

• Linux: amd64, arm64, 386
• Windows: amd64, 386
• macOS: amd64, arm64

构建完成后，二进制文件和发布包会输出到 dist/ 目录。

跨平台构建（GitHub Actions）

使用 GitHub Actions 可以方便地构建多平台版本（Linux ARM、AMD64 等）：

# 1. 初始化 git 仓库
git init
git add .
git commit -m "Add build workflow"

# 2. 添加远程仓库（替换为你的仓库地址）
git remote add origin https://github.com/your-username/your-repo.git
git branch -M main
git push -u origin main

推送完成后：

1. 访问 GitHub 仓库
2. 点击 Actions 标签
3. 选择 "Build Linux ARM Binaries"
4. 点击 "Run workflow"
5. 等待 5-10 分钟后下载构建产物

优势：

• ✅ 完全免费
• ✅ 无需本地配置
• ✅ 支持多平台构建
• ✅ 自动化持续集成

详细说明请参考 BUILD.md

快速开始

Linux/macOS:

# 给脚本添加执行权限
chmod +x docker-deploy.sh

# 构建并运行
./docker-deploy.sh build
./docker-deploy.sh run

# 使用 docker-compose
./docker-deploy.sh compose

Windows:

docker-deploy.bat build
docker-deploy.bat run

HTTPS 支持

使用 Nginx 反向代理

1. 创建 SSL 证书目录并放置证书

mkdir -p ssl
# 将 cert.pem 和 key.pem 放入 ssl/ 目录

2. 使用带 Nginx 的 docker-compose 启动

docker-compose --profile with-nginx up -d

直接启用 HTTPS

python main.py --ssl-cert cert.pem --ssl-key key.pem

详细说明请参考 DOCKER.md

CI/CD 自动构建

项目使用 GitHub Actions 自动构建 Docker 镜像和可执行文件。

GitHub Actions 工作流

工作流文件	触发条件	功能
.github/workflows/releases.yml	打 Tag (v*)	构建并发布二进制可执行文件到 GitHub Releases
.github/workflows/docker-multiarch.yml	打 Tag (v*)	构建并推送多架构 Docker 镜像到 Docker Hub
.github/workflows/ci-cd.yml	push main / PR	运行测试

发布新版本

# 1. 推送所有代码
git push origin main

# 2. 创建版本标签
git tag v1.0.0

# 3. 推送到远程
git push origin v1.0.0

推送 Tag 后，GitHub Actions 会自动：

• ✅ 构建 4 个架构的二进制文件（Linux AMD64/ARM64/ARMv7 + Windows AMD64）
• ✅ 构建 3 个架构的 Docker 镜像（AMD64/ARM64/ARMv7）
• ✅ 上传到 GitHub Releases
• ✅ 推送到 Docker Hub 和 GitHub Container Registry

GitHub Secrets 配置

需要配置以下 Secrets 才能正常工作：

Secret 名称	值	说明
DOCKERHUB_USERNAME	Docker Hub 用户名
DOCKERHUB_TOKEN	Docker Hub Access Token

Docker Hub 镜像

构建完成后，镜像会自动推送到：

• Docker Hub: hx100cv/hyc-download:latest
• GitHub Container Registry: ghcr.io/hexikx/mirror_server:latest

GitHub Releases

每个版本会生成以下文件：

文件名	说明
hyc-download-linux-amd64	Linux x64 可执行文件
hyc-download-linux-arm64	Linux ARM64 可执行文件
hyc-download-linux-armv7	Linux ARMv7 可执行文件
hyc-download-windows-amd64.exe	Windows x64 可执行文件

Stargazers over time

Contributors

License

The MIT License (MIT)