# Mirgo / cloudflare-agent-proxy

公开、只读的开发资源代理。美国 VPS 主链路 + Cloudflare 免费回退；主链路是否已配置请读取 /healthz 的 primary_configured，不能仅根据此文档推断已启用。
主站：https://mirgo.iurl.ai
机器清单：https://mirgo.iurl.ai/.well-known/mirgo.json

统一入口仍经过 Cloudflare Workers Free：账号共享 100,000 动态请求/天，10 ms CPU/请求，128 MB 内存；北京时间每日 08:00 重置日请求额度。配置完成后优先通过美国 VPS 回源，VPS 故障时由 Cloudflare 回退。Cloudflare 回退时需要改写的元数据最多 256 KiB；此限制不适用于模型、镜像层等二进制文件。缓存仍消耗动态请求额度，缓存不是持久镜像。

X-Mirgo-Route: vps / cloudflare / edge-cache 表示本次实际链路。仅在发送响应前因网络错误、25 秒首响应超时或 502/503/504 切换；429/404 不切换。传输中断不能无缝切换，请使用客户端 Range 续传。

仅访问固定上游，禁止任意 URL、CONNECT、私有资源和凭据。仅修改当前任务需要的客户端配置；修改全局配置前先保留旧值，撤销时恢复旧值。下载后保留包管理器完整性验证，不关闭 TLS 和 Go sumdb。

## PyPI · pip / uv
端点：https://mirgo.iurl.ai/pypi/simple/

临时接入：
pip install --index-url https://mirgo.iurl.ai/pypi/simple/ requests

持久配置（由使用者决定是否应用）：
pip config set global.index-url https://mirgo.iurl.ai/pypi/simple/

撤销（已有自定义值时恢复原值）：
pip config unset global.index-url

限制：支持 HTML/JSON Simple API、wheel、sdist 和 .metadata；保留哈希和 Python 版本约束。使用 --index-url，不要用 extra-index-url 混合不可信源。uv：UV_INDEX_URL=https://mirgo.iurl.ai/pypi/simple/ uv sync

## npm · pnpm · Yarn
端点：https://mirgo.iurl.ai/npm/

临时接入：
npm install --registry=https://mirgo.iurl.ai/npm/ --no-audit --fund=false lodash

持久配置（由使用者决定是否应用）：
npm config set registry https://mirgo.iurl.ai/npm/

撤销（已有自定义值时恢复原值）：
npm config delete registry

限制：pnpm 使用同一 registry；Yarn Berry 设置 npmRegistryServer。支持 scoped 包。audit POST、发布、私有包不支持；安装脚本下载和 lockfile 固定的其他域名不会自动代理。需要时加 --ignore-scripts，但这可能影响包功能。

## Docker Hub
端点：https://mirgo.iurl.ai/v2/

临时接入：
docker pull mirgo.iurl.ai/library/alpine:latest

持久配置（由使用者决定是否应用）：
# 合并到 /etc/docker/daemon.json，保留原有键；由用户自行 reload Docker
{"registry-mirrors":["https://mirgo.iurl.ai"]}

撤销（已有自定义值时恢复原值）：
从 daemon.json 的 registry-mirrors 移除 https://mirgo.iurl.ai，再自行 reload Docker。

限制：显式地址最容易验证完整代理链路；官方镜像需要 library/ 前缀。仅支持 Docker Hub 公开镜像；匿名上游限流仍适用，daemon mirror 失败时可能尝试直连上游。无需 docker login。

## Hugging Face
端点：https://mirgo.iurl.ai/hf/

临时接入：
HF_ENDPOINT=https://mirgo.iurl.ai/hf HF_HUB_DISABLE_XET=1 HF_HUB_DISABLE_IMPLICIT_TOKEN=1 hf download gpt2 config.json

持久配置（由使用者决定是否应用）：
export HF_ENDPOINT=https://mirgo.iurl.ai/hf
export HF_HUB_DISABLE_XET=1
export HF_HUB_DISABLE_IMPLICIT_TOKEN=1

撤销（已有自定义值时恢复原值）：
unset HF_ENDPOINT HF_HUB_DISABLE_XET HF_HUB_DISABLE_IMPLICIT_TOKEN

限制：在导入 huggingface_hub/transformers 之前设置变量。只支持公开模型、数据集及文件；gated/private、推理、上传、Git LFS/Xet 原生客户端不支持。不要显式传入 HF token。大文件透传，不保证边缘缓存。

## GitHub downloads
端点：https://mirgo.iurl.ai/github/

临时接入：
curl -fL https://mirgo.iurl.ai/raw/psf/requests/main/README.md -o README.md

持久配置（由使用者决定是否应用）：
# 替换下载地址前缀
https://github.com/OWNER/REPO/releases/download/TAG/FILE
→ https://mirgo.iurl.ai/github/OWNER/REPO/releases/download/TAG/FILE
https://github.com/OWNER/REPO/archive/refs/tags/TAG.tar.gz
→ https://mirgo.iurl.ai/github/OWNER/REPO/archive/refs/tags/TAG.tar.gz
https://raw.githubusercontent.com/OWNER/REPO/REF/PATH
→ https://mirgo.iurl.ai/raw/OWNER/REPO/REF/PATH

撤销（已有自定义值时恢复原值）：
恢复原始 URL，无全局配置。

限制：支持 releases/latest/download/FILE。只支持公开资源下载，不提供 Git clone、GitHub API、任意网页或任意 URL 转发。上游 HTML 内容在代理域名受到 CSP sandbox 限制。

## Go Modules + sumdb
端点：https://mirgo.iurl.ai/go/

临时接入：
GOPROXY=https://mirgo.iurl.ai/go GOSUMDB=sum.golang.org go mod download

持久配置（由使用者决定是否应用）：
go env -w GOPROXY=https://mirgo.iurl.ai/go
go env -w GOSUMDB=sum.golang.org

撤销（已有自定义值时恢复原值）：
go env -u GOPROXY
go env -u GOSUMDB

限制：同时代理 sum.golang.org 校验数据，保留官方签名，禁止 GOSUMDB=off。私有模块依赖 GOPRIVATE 的直连行为不在覆盖范围；Go toolchain 自动下载不承诺兼容。

## Rust · crates.io
端点：https://mirgo.iurl.ai/cargo/index/

临时接入：
# 临时使用，无需改全局配置
cargo --config 'source.crates-io.replace-with="mirgo"' --config 'source.mirgo.registry="sparse+https://mirgo.iurl.ai/cargo/index/"' fetch

持久配置（由使用者决定是否应用）：
# 项目 .cargo/config.toml，合并已有配置
[source.crates-io]
replace-with = "mirgo"
[source.mirgo]
registry = "sparse+https://mirgo.iurl.ai/cargo/index/"

撤销（已有自定义值时恢复原值）：
移除新增的 source replacement 配置，保留原配置。

限制：支持 sparse index 和 crate 文件，保留原 checksum。仅设置 CARGO_REGISTRIES_CRATES_IO_INDEX 不能完整替代 source replacement。Git 依赖和 rustup 工具链不支持。

## 排错与验收
- GET /healthz 检查 Worker 存活，不代表上游都可达。
- 400 public_resources_only：移除 Authorization/Cookie，HF 设置 HF_HUB_DISABLE_IMPLICIT_TOKEN=1。
- 404 unsupported_*：路径不在支持范围。不要退化成任意 URL 代理。
- 429：遵守 Retry-After，降低并发；可能来自代理或官方上游。
- 502 upstream_redirect_not_allowed：官方新增下载域名，需要维护者核实后添加白名单；不要关闭校验。
- 504：上游首响应超时；传输中断可使用 curl -C - 或客户端续传。
- Cloudflare 1027：免费动态请求日额度耗尽，北京时间 08:00 重置。主站静态文档独立提供。
- X-Mirgo-Cache: HIT/MISS/BYPASS 表示边缘缓存决策；不超过 100 MiB 且已知大小的完整文件才尝试缓存，大型元数据（超过 2 MiB）不缓存。缓存节点之间不保证共享。
- 不保证国内所有网络的速度；请比较直连和代理的耗时、状态与 SHA256。
- 核心客户端范围：pip/uv、npm/pnpm/Yarn、Docker、huggingface_hub、Go、Cargo；脚本二次下载、私有包、Git clone 和工具链不在承诺范围。

## 官方依据
https://developers.cloudflare.com/workers/platform/limits/
https://packaging.python.org/en/latest/specifications/simple-repository-api/
https://docs.npmjs.com/cli/using-npm/config/
https://docs.docker.com/reference/api/registry/auth/
https://huggingface.co/docs/huggingface_hub/en/package_reference/file_download
https://go.dev/ref/mod
https://doc.rust-lang.org/cargo/reference/registry-index.html