[开源自荐] MirrorProxy 一套服务，接管你的所有软件源加速需求

还在为 GitHub 下载慢、Docker 拉取失败、Cargo 超时、npm/pip 源配置混乱而反复折腾？ 部署一个 MirrorProxy ，把常用开发生态和操作系统软件源统一加速。

## 项目简介

MirrorProxy 是一个使用 Rust 开发的高性能、自托管、多生态镜像代理平台。

它将 GitHub 、Docker/OCI 、npm 、PyPI 、Cargo 、Go Modules 、Composer 、Maven 、NuGet 、RubyGems ，以及 Linux/BSD 操作系统软件仓库统一到同一套代理核心中，并提供 Web 管理后台、流量统计、缓存、配额和跨平台改源客户端。

简单来说：

以前每种包管理器都要寻找不同镜像站，现在只需要部署一个 MirrorProxy 。

## 它解决了哪些痛点？

### 1. 软件源又多又乱

开发环境往往同时依赖：

• GitHub Release 和源码仓库
• Docker Hub 、GHCR 、Quay
• npm 、Yarn 、pnpm
• pip 、PyPI
• Cargo 、Crates.io
• Go Modules
• Composer 、Packagist
• Maven 、NuGet 、RubyGems
• Linux 发行版软件仓库

每个生态都有不同的配置格式、镜像地址和回滚方式。换一台电脑、重装一次系统，就要重新配置一遍。

MirrorProxy 用一套服务统一处理这些协议。

### 2. 公共镜像不可控

第三方镜像站可能随时出现：

• 同步延迟
• 服务限流
• 地址变更
• 镜像下线
• 缺少特定生态
• 无法查看真实流量
• 无法配置自己的上游和访问策略

MirrorProxy 可以部署在自己的服务器上，节点、带宽、缓存、上游和配额全部由自己控制。

### 3. GitHub 下载和 Git 依赖经常超时

MirrorProxy 不仅能代理 GitHub Release 、Raw 文件和源码压缩包，还支持 Git Smart HTTP Clone 。

独立客户端可以自动配置 GitHub HTTPS URL 重写：

mirrorproxy set github –base-url https://mirror.example.com

之后使用：

https://github.com/owner/repository.git

的 Git Clone 和包管理器 Git 依赖，会自动改走 MirrorProxy ，无需手动修改每个项目的依赖地址。

### 4. 改源容易，恢复困难

很多改源脚本只负责写入配置，却不关心用户原来的内容。一旦配置出错，恢复只能靠手工处理。

MirrorProxy 客户端提供带保护的操作：

mirrorproxy set cargo –base-url https://mirror.example.com mirrorproxy reset cargo

写入前记录原始配置，重置时精确恢复；如果文件在改源后被其他程序修改，还会拒绝静默覆盖。

### 5. 自建代理最怕失控

一个没有边界的下载代理很容易变成：

• 开放代理
• SSRF 入口
• 带宽黑洞
• 凭据泄漏点
• 磁盘无限增长器

MirrorProxy 从设计上限制代理目标：

• GitHub Host 白名单
• 软件仓库固定路由
• 路径穿越检查
• Hop-by-hop Header 过滤
• 私有凭据隔离
• 全局请求限流
• 月度流量配额
• 有容量上限的磁盘缓存
• 请求统计和审计日志

它不是简单的 URL 转发器，而是一套面向软件分发场景设计的受控代理平台。

## 核心功能

### 多生态统一代理

当前已经覆盖：

• GitHub 仓库、Raw 、Release 、Archive 和 Git Clone
• Docker Hub 、GHCR 、Quay 、Kubernetes Registry
• Composer / Packagist
• npm / Yarn / pnpm
• pip / PyPI
• Cargo / Crates.io
• Go Modules
• Maven Central
• RubyGems
• NuGet v3
• CPAN 、CRAN 、Hackage
• Rustup 、Julia 、LuaRocks
• NVM / Node.js 、opam
• Clojars 、CocoaPods
• Pub / Flutter 、Anaconda / Conda
• TeX Live 、WinGet 、GNU ELPA
• Nix 、Guix 、Flatpak 、Homebrew
• Debian 、Ubuntu 、Fedora 、Arch Linux 、Alpine 、openSUSE 、Void 、Gentoo 、OpenWrt 、ROS 等操作系统软件仓库

一套 MirrorProxy ，基本覆盖现代开发环境最常用的软件分发链路。

### 独立跨平台客户端

服务端和改源客户端完全分离：

• mirrorproxy-server：代理服务和 Web 管理后台
• mirrorproxy：轻量级改源客户端

客户端支持：

• Windows
• macOS
• Linux

并提供类似 chsrc 的简洁命令：

mirrorproxy list mirrorproxy get npm mirrorproxy set npm –base-url https://mirror.example.com mirrorproxy reset npm

### Web 管理后台

服务端内嵌 React Web 控制台，无需单独部署前端。

可以管理和查看：

• 已启用代理
• 上游地址
• 流量统计
• 月度配额
• 请求限流
• 磁盘缓存
• 管理员密码
• 配置审计
• CLI 命令生成
• 镜像源目录

首次启动会生成随机管理员密码，密码仅以 Argon2 哈希形式保存。

### 流式传输，适合大文件

MirrorProxy 默认采用流式转发：

• 不把大型软件包完整读入内存
• 支持 Range 请求
• 保留必要的 ETag 和缓存头
• 下载流量按实际发送字节统计
• Docker Blob 、GitHub Release 和系统软件包均可持续流式传输

即使面对大型镜像和安装包，也不需要用服务器内存硬扛。

### 可控磁盘缓存

缓存默认关闭，启用后具备明确边界：

• 只缓存成功的公开 GET 响应
• 可限制单对象大小
• 可限制缓存总容量
• 自动执行 LRU 淘汰
• Authorization 、Cookie 、Range 请求自动绕过缓存
• 大文件和未知长度响应保持流式转发

不用担心代理运行几天后把磁盘悄悄塞满。

### 流量统计与月度配额

MirrorProxy 使用 SQLite 保存：

• 每日请求量
• 每个代理目标的流量
• 错误数量
• 月度总流量
• 配额剩余量
• 请求诊断事件

可以配置月度上限：

[quota] enabled = true monthly_gb = 500 timezone = “Asia/Taipei” on_exceeded = “stop_proxy”

达到上限后只停止代理请求，Web 后台、健康检查和管理接口仍然可以访问。

## 部署非常简单

使用 Docker Compose：

MIRRORPROXY_PUBLIC_BASE_URL=https://mirror.example.com docker compose up -d

或者直接运行容器：

docker run -d

--name mirrorproxy \
--restart unless-stopped \
-p 3000:3000 \
-e MIRRORPROXY_PUBLIC_BASE_URL=https://mirror.example.com \
-v mirrorproxy-data:/data \
kudang/mirrorproxy:latest

检查服务：

curl http://127.0.0.1:3000/healthz

生产环境建议放在 Nginx 、Caddy 或 Traefik 后，通过 HTTPS 对外提供服务。

## 为什么值得推荐？

MirrorProxy 最吸引人的地方，不只是“支持的软件源多”，而是它把原本碎片化的镜像加速问题变成了一套完整产品：

• 一个服务统一多个软件生态
• 一个客户端完成跨平台改源
• 配置可以安全回滚
• Web 后台集中管理
• 流量和缓存都有明确边界
• 默认防止开放代理和凭据泄漏
• Rust 单体服务，部署成本低
• SQLite 默认持久化，无需额外数据库
• 提供真实包管理器和操作系统仓库验证矩阵

它非常适合：

• 网络访问不稳定的开发者
• 家庭实验室和自托管用户
• 中小团队内部软件源
• CI/CD 构建节点
• 教育网和企业内网
• 多服务器统一下载出口
• 希望掌控带宽和缓存成本的运维团队

## Roadmap：星火志愿镜像网络

MirrorProxy 还规划了一个更有野心的方向——星火计划。

未来，社区运营者可以自愿贡献公网 MirrorProxy 节点：

• 通过 spark-mirrors.sina.dev DNS TXT 获取核心 Bootstrap Peer
• 使用 libp2p Kademlia 发现志愿者节点
• 根据延迟、健康状态、容量和成功率自动选择节点
• 节点故障时自动切换
• 使用签名身份和短期公告防止伪造节点
• 保留 MirrorProxy 的白名单、安全策略和流量限制

为了保证网络质量，志愿者节点必须具备：

• 稳定的公网域名
• 公共可信的 HTTPS 证书
• 可从公网访问的开放端口
• 可配置的带宽和流量配额

星火计划明确不考虑 NAT 、CGNAT 、Relay 或打洞节点，把精力集中在可靠、可验证、真正能够承担软件分发流量的公网服务器上。

## 一句话总结

MirrorProxy 把 GitHub 、容器镜像、语言包管理器和操作系统软件仓库，统一成了一套可以自己掌控的高速软件分发入口。

如果你受够了下载超时、改源脚本、镜像失效和重复配置，MirrorProxy 很可能就是那个“部署一次，长期省心”的开源项目。