Mirror 存储配置
CloudPaste 支持将 HTTP 镜像站 作为只读存储后端，通过解析镜像站目录页实现文件浏览和下载。
常见场景：
- 需要通过 CloudPaste 统一访问多个开源镜像站；
- 希望对镜像站资源进行权限控制和访问管理；
- 需要为镜像站资源提供代理访问能力。
Mirror 存储驱动是 只读驱动，不支持上传、删除或修改文件。
支持的功能
Mirror 存储驱动支持以下能力：
- ✅ READER：读取文件和目录
- ✅ DIRECT_LINK：直接访问镜像站原始 URL
- ✅ PROXY：代理访问镜像站资源
- ❌ WRITER：不支持上传/删除/修改（只读驱动）
- ❌ MULTIPART：不支持分片上传
注意：
- 这是只读驱动，所有写入操作都会被拒绝
- 频繁请求可能触发上游镜像站风控（HTTP 403）
1. 准备工作
1.1 选择镜像站
目前支持三个预设模板：
| 预设 | 镜像站 | 说明 |
|---|---|---|
tuna | 清华大学开源软件镜像站 | 资源最全，更新最快 |
ustc | 中国科学技术大学开源软件镜像站 | 稳定性好，教育网访问快 |
aliyun | 阿里云开源镜像站 | 国内商业镜像站，速度稳定 |
1.2 确认镜像站可访问
在配置前，请确认目标镜像站可以正常访问：
- 清华 TUNA：https://mirrors.tuna.tsinghua.edu.cn/
- 中科大 USTC：https://mirrors.ustc.edu.cn/
- 阿里云：https://mirrors.aliyun.com/
无需 Token：Mirror 驱动不需要任何认证信息，直接访问公开的镜像站目录。
2. 新建 Mirror 存储配置
- 登录 CloudPaste 后台 → 存储配置
- 点击「新建存储配置」
- 在「存储类型」下拉中选择 Mirror
- 填写配置信息（见下文字段说明）
- 点击「测试连接」验证配置是否正确
- 保存后，在「挂载管理」中为这个存储创建挂载点
建议先测试连接，确认能正常列出根目录后再保存。
3. 字段说明
3.1 基本信息
配置名称 任意便于识别的名字，例如「清华镜像站」「USTC 镜像」。
存储容量限制（可选）
- 只影响 CloudPaste 自己的配额计算，不会真的限制镜像站访问。
- 镜像站本身是公开资源，没有存储限制概念。
3.2 Mirror 配置
这是 Mirror 存储的核心配置
预设模板（preset） 必填
- 选择目标镜像站的解析模板
- 可选值：
tuna（清华）、ustc（中科大）、aliyun（阿里云） - 不同镜像站的 HTML 结构不同，需要对应的解析策略
镜像站地址（endpoint_url） 必填
- 镜像站的根地址
- 必须以
http://或https://开头 - 示例：
https://mirrors.tuna.tsinghua.edu.cn/
3.3 高级配置
启用浏览器伪装（enable_masquerade）（可选）
- 默认：开启
- 开启后，请求会携带真实浏览器的请求头，降低被风控拦截的风险
- 包括：动态 User-Agent、Chromium Client Hints、随机 IP 头（X-Real-IP/X-Forwarded-For）
最大条目数（max_entries）（可选）
- 单次目录列表返回的最大条目数
- 默认：1000
- 超大目录可能导致解析缓慢，可适当调低
代理地址（url_proxy）（可选）
- 用于访问镜像站的 HTTP 代理
- 格式：
http://proxy:port
4. 工作原理
4.1 目录解析
Mirror 驱动将镜像站的目录页（HTML/JSON/XML）解析为文件列表：
CloudPaste 上游镜像站
┌─────────────────┐ ┌─────────────────┐
│ /ubuntu/ │ ──── GET ────→ │ HTML 目录页 │
│ ├── dists/ │ ←── 解析 ──── │ <a href="..."> │
│ └── pool/ │ │ ... │
└─────────────────┘ └─────────────────┘4.2 解析策略
根据 preset 配置，使用不同的 HTML 解析策略：
| 预设 | 解析特点 |
|---|---|
tuna | 解析 <tr> 表格行，提取 <a> 链接和 class="date" 时间 |
ustc | 解析 <tr> 表格行，提取 class="filetime" 时间和 title="bytes" 大小 |
aliyun | 解析门户页分页（自动抓取第 2 页），过滤 DNS/NTP 入口 |
4.3 浏览器伪装
当 enable_masquerade 开启时，每个请求会携带：
- 动态 User-Agent：从 19 个桌面 + 4 个移动 UA 池中随机选择
- Chromium Client Hints：
Sec-CH-UA、Sec-CH-UA-Platform等 - 随机 IP 头：
X-Real-IP、X-Forwarded-For（仅修改请求头，不是真实代理） - 完整浏览器头：
Accept、Accept-Language、Referer等
注意：IP 伪装仅修改 HTTP 请求头，上游服务器仍可通过 TCP 连接获取真实 IP。
4.4 性能保护
- 目录页大小限制：单个目录页最多抓取 2MB 数据
- 条目数限制：通过
max_entries参数控制（默认 1000） - HTTP Range 支持：文件下载支持断点续传
5. 挂载与权限配合
Mirror 存储配置保存后，需要在「挂载管理」中为其创建挂载点：
- 进入 挂载管理 → 新建挂载
- 选择存储类型为 Mirror 的那条存储配置
- 填写挂载路径（如
/mirror/tuna）、备注等 - 视情况开启：
- Web 代理：是否强制 Web 场景走 CloudPaste 代理
- 启用签名：是否对代理入口签名保护
同时，Mirror 存储配置中有一个 允许 API 密钥使用（is_public） 选项：
- 勾选后，API 密钥可以在其「挂载路径」范围内使用该存储
- 配合 API 密钥的 basic_path 和挂载路径，可以精确限制访问范围
详细的挂载与权限说明，可参考：
6. 常见问题
6.1 测试连接失败：HTTP 403
错误信息：
上游镜像站拒绝访问（HTTP 403）
可能原因：
- 镜像站检测到异常请求频率，触发风控
- 浏览器伪装未开启
解决方法：
- 确认
enable_masquerade已开启 - 降低请求频率，避免短时间内大量请求
- 使用
url_proxy配置代理服务器 - 等待几分钟后重试
6.2 目录列表为空
可能原因：
preset与实际镜像站不匹配- 镜像站更新了 HTML 结构
解决方法：
- 确认
preset选择正确（tuna/ustc/aliyun） - 确认
endpoint_url格式正确（包含协议和结尾斜杠） - 在浏览器中直接访问镜像站，确认页面正常
- 如果镜像站结构变化，请提交 Issue
6.3 下载速度慢
可能原因：
- 网络到镜像站的延迟较高
解决方法：
- 使用 DIRECT_LINK 直链策略，让客户端直接从镜像站下载
- 或在挂载配置中关闭「Web 代理」
6.4 能否添加其他镜像站？
回答：目前仅支持三个预设模板（tuna/ustc/aliyun）。如需支持其他镜像站：
- 提交 Issue 到 CloudPaste 项目
- 提供镜像站 URL 和目录页 HTML 示例
- 等待开发者添加新的解析策略
6.5 为什么只能只读？
说明：这是设计决定。镜像站是公开的只读资源，不提供上传接口。CloudPaste 仅作为"浏览器"角色，将目录页解析为文件列表。