141 lines
4.2 KiB
Markdown
141 lines
4.2 KiB
Markdown
# Hugs-Proxy
|
||
|
||
一个轻量的 GitHub 资源加速反向代理工具。当前版本在原有代理能力上新增了 SQLite 持久化鉴权和访问审计。
|
||
|
||
## 功能概览
|
||
|
||
- 支持 GitHub 资源代理（不匹配返回 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/...
|
||
- Bearer Token 鉴权（Authorization 头）
|
||
- SQLite 持久化：用户、token、访问明细、全站累计计数
|
||
- 白名单/黑名单（先白名单再黑名单）
|
||
- 大文件保护（>1GB 直接 302 回源）
|
||
- 上游重定向 Location 改写（可识别 GitHub URL 时继续经由代理）
|
||
|
||
## 快速开始
|
||
|
||
### 1. 启动服务
|
||
|
||
```bash
|
||
go run .
|
||
```
|
||
|
||
默认监听地址：127.0.0.1:2005
|
||
|
||
### 2. 初始化用户与 token
|
||
|
||
```bash
|
||
go run ./cmd/tokenctl create-user --name alice
|
||
go run ./cmd/tokenctl issue-token --user alice --expires 30d --uses 1
|
||
```
|
||
|
||
说明：
|
||
|
||
- --expires 支持 7d/30d 这类天数写法
|
||
- 也支持 RFC3339 绝对时间（例如 2026-12-31T23:59:59Z）
|
||
- 不传 --expires 时使用默认有效期（环境变量可配置）
|
||
- --uses 指定可用次数（例如 1 为一次性 token，5 为可用 5 次）
|
||
|
||
### 3. 携带 Bearer Token 请求
|
||
|
||
```bash
|
||
curl -L \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
"http://127.0.0.1:2005/https://github.com/OWNER/REPO/releases/download/v1.0.0/file.zip"
|
||
```
|
||
|
||
无 token：返回 401。
|
||
|
||
token 无效、已禁用、已过期或使用次数耗尽：返回 403。
|
||
|
||
## tokenctl 用法
|
||
|
||
```text
|
||
tokenctl create-user --name <username> [--db <path>]
|
||
tokenctl issue-token --user <username> [--expires <7d|30d|RFC3339>] [--uses <n>] [--db <path>]
|
||
tokenctl disable-token --token <token> [--db <path>]
|
||
tokenctl list-users [--db <path>]
|
||
tokenctl list-tokens [--db <path>]
|
||
```
|
||
|
||
示例：
|
||
|
||
```bash
|
||
go run ./cmd/tokenctl list-users
|
||
go run ./cmd/tokenctl list-tokens
|
||
go run ./cmd/tokenctl issue-token --user alice --uses 5
|
||
go run ./cmd/tokenctl disable-token --token <TOKEN>
|
||
```
|
||
|
||
## 环境变量配置
|
||
|
||
服务与 CLI 共用同一套配置：
|
||
|
||
- HUGS_PROXY_HOST：监听地址，默认 127.0.0.1
|
||
- HUGS_PROXY_PORT：监听端口，默认 2005
|
||
- HUGS_PROXY_DB_PATH：SQLite 文件路径，默认 ./hugs_proxy.db
|
||
- HUGS_PROXY_DEFAULT_TOKEN_TTL：默认 token 有效期，默认 30d
|
||
- HUGS_PROXY_DB_BUSY_TIMEOUT_MS：SQLite busy_timeout，默认 5000
|
||
|
||
说明：
|
||
|
||
- 代理大文件阈值 sizeLimit 仍在 main.go 内部常量（默认 1GB）。
|
||
- 白名单与黑名单规则仍在 main.go 的 whiteListStr 与 blackListStr。
|
||
|
||
## 数据库说明
|
||
|
||
程序启动会自动执行幂等建表迁移（CREATE TABLE IF NOT EXISTS），并设置：
|
||
|
||
- PRAGMA journal_mode = WAL
|
||
- PRAGMA busy_timeout = 5000（或你设置的环境变量值）
|
||
|
||
表结构语义：
|
||
|
||
- users：用户主体
|
||
- tokens：token 主体（含过期、禁用、可用次数上限与已使用次数）
|
||
- token_usage：访问审计明细（时间/IP/用户/token/原始 URL/HTTP 状态/成功标志/失败原因）
|
||
- site_stats：总体累计计数（total_accelerated_count）
|
||
|
||
## 白名单/黑名单规则
|
||
|
||
每行一条，支持：
|
||
|
||
- user1：匹配 user1 下所有仓库
|
||
- user1/repo1：匹配 user1/repo1
|
||
- \*/repo1：匹配所有 repo1
|
||
|
||
判定顺序：
|
||
|
||
1. 白名单优先（若白名单非空，必须命中）
|
||
2. 再匹配黑名单（命中即拒绝）
|
||
|
||
## 验证步骤
|
||
|
||
1. 构建：go build ./...
|
||
2. 无 token 请求：应返回 401
|
||
3. 签发 token 后请求合法 URL：应成功且代理行为与旧版本一致
|
||
4. 禁用或过期 token 请求：应返回 403，并记录失败 usage
|
||
5. 多次请求后检查 site_stats.total_accelerated_count 累计值
|
||
6. 检查 token_usage 记录字段完整性
|
||
|
||
## 排错
|
||
|
||
- 启动报数据库错误：
|
||
- 检查 HUGS_PROXY_DB_PATH 是否可写
|
||
- 检查目录权限
|
||
- 总是 401：
|
||
- 确认请求头格式为 Authorization: Bearer <TOKEN>
|
||
- 总是 403：
|
||
- 检查 token 是否过期或禁用
|
||
- 检查 URL 是否命中支持规则以及白黑名单规则
|
||
|
||
## License
|
||
|
||
详见仓库中的 LICENSE 文件。
|