Hugs-Proxy/README.md

Hugs-Proxy

本项目目前支持Github,后面可能会增加HuggingFace......

一个轻量的 GitHub 资源加速/反代下载小工具：把 GitHub 的下载链接（Release、Archive、Raw、Gist、部分 git/info 相关请求）通过本地 HTTP 服务转发，从而在某些网络环境下提升可用性。

本项目默认只监听 127.0.0.1，更改为对外监听前请务必阅读“安全提示”。

特性

• 支持代理的链接类型（不匹配会返回 403）：
  • github.com/<owner>/<repo>/releases/...
  • github.com/<owner>/<repo>/archive/...
  • github.com/<owner>/<repo>/blob/...（会自动改写为 .../raw/... 进行下载）
  • github.com/<owner>/<repo>/raw/...
  • github.com/<owner>/<repo>/info/...、github.com/<owner>/<repo>/git-...
  • raw.githubusercontent.com/<owner>/<repo>/...
  • gist.github.com/...、gist.githubusercontent.com/...
• 白名单/黑名单（先白名单，后黑名单）
• 大文件保护：响应体 Content-Length 超过 1GB 时直接 302 重定向到源站，避免本机带宽/内存压力
• 处理上游重定向：对可识别的 GitHub 下载链接会改写 Location，让跳转继续走本代理

快速开始

1) 运行

在仓库根目录执行：

go run .

默认监听：127.0.0.1:2005

2) 使用方式

访问路径就是你要代理的目标 URL（去掉前面的 /）：

http://127.0.0.1:2005/<目标URL>

目标 URL 可以写全（推荐），也可以省略 scheme（会自动补 https://）。示例：

• Release 文件：

http://127.0.0.1:2005/https://github.com/OWNER/REPO/releases/download/v1.0.0/app-darwin-amd64.zip

• 仓库归档（archive）：

http://127.0.0.1:2005/https://github.com/OWNER/REPO/archive/refs/heads/main.zip

• Raw 文件（也可以给 blob，服务端会自动替换为 raw）：

http://127.0.0.1:2005/https://github.com/OWNER/REPO/blob/main/README.md

• raw.githubusercontent.com：

http://127.0.0.1:2005/https://raw.githubusercontent.com/OWNER/REPO/main/README.md

如果你传入的链接不属于上面支持的 GitHub 资源格式，会返回：403 Invalid input.

配置

目前所有配置都在 main.go 顶部的“配置区域”，修改后重新运行即可：

• host：监听地址（默认 127.0.0.1）
• port：监听端口（默认 2005）
• sizeLimit：大文件阈值（默认 1GB）
• whiteListStr：白名单（多行字符串，每行一条规则）
• blackListStr：黑名单（多行字符串，每行一条规则）

白名单/黑名单规则

每行一条，支持三种写法：

• user1：匹配/封禁 user1 下的所有仓库
• user1/repo1：匹配/封禁 user1/repo1
• */repo1：匹配/封禁所有名为 repo1 的仓库

判定顺序：

1. 白名单优先生效：如果白名单非空，则必须至少命中一条白名单规则，否则直接拒绝（403）。
2. 再匹配黑名单：命中任意黑名单规则则拒绝（403）。

常见问题

为什么有时会直接跳转到 GitHub？

当上游响应 Content-Length 大于 sizeLimit（默认 1GB）时，程序会返回 302 重定向到目标 URL，而不是继续转发大文件内容。

支持 Git Clone / Git LFS 吗？

本项目主要面向“下载/获取资源”。它只放行并代理部分与 GitHub 资源下载相关的 URL 形态；不保证覆盖完整的 Git 协议或 Git LFS 场景。

License

详见 License 文件