111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
|
||
# 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) 运行
|
||
|
||
在仓库根目录执行：
|
||
|
||
```bash
|
||
go run .
|
||
```
|
||
|
||
默认监听：`127.0.0.1:2005`
|
||
|
||
### 2) 使用方式
|
||
|
||
访问路径就是你要代理的目标 URL（去掉前面的 `/`）：
|
||
|
||
```text
|
||
http://127.0.0.1:2005/<目标URL>
|
||
```
|
||
|
||
目标 URL 可以写全（推荐），也可以省略 scheme（会自动补 `https://`）。示例：
|
||
|
||
- Release 文件：
|
||
|
||
```text
|
||
http://127.0.0.1:2005/https://github.com/OWNER/REPO/releases/download/v1.0.0/app-darwin-amd64.zip
|
||
```
|
||
|
||
- 仓库归档（archive）：
|
||
|
||
```text
|
||
http://127.0.0.1:2005/https://github.com/OWNER/REPO/archive/refs/heads/main.zip
|
||
```
|
||
|
||
- Raw 文件（也可以给 `blob`，服务端会自动替换为 `raw`）：
|
||
|
||
```text
|
||
http://127.0.0.1:2005/https://github.com/OWNER/REPO/blob/main/README.md
|
||
```
|
||
|
||
- raw.githubusercontent.com：
|
||
|
||
```text
|
||
http://127.0.0.1:2005/https://raw.githubusercontent.com/OWNER/REPO/main/README.md
|
||
```
|
||
|
||
如果你传入的链接不属于上面支持的 GitHub 资源格式，会返回：`403 Invalid input.`
|
||
|
||
## 配置
|
||
|
||
目前所有配置都在 [main.go](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 文件
|
||
|