Hugs-Proxy/README.md

Hugs-Proxy

一个轻量的 GitHub 资源加速反向代理工具。当前版本在原有代理能力上新增了 SQLite 持久化鉴权和访问审计。

功能概览

• 支持 GitHub 资源代理（不匹配返回 403）：
  • github.com///releases/...
  • github.com///archive/...
  • github.com///blob/...（自动改写为 /raw/）
  • github.com///raw/...
  • github.com///info/... 与 github.com///git-...
  • raw.githubusercontent.com///...
  • gist.github.com/... 与 gist.githubusercontent.com/...
• Bearer Token 鉴权（Authorization 头）
• SQLite 持久化：用户、token、访问明细、全站累计计数
• 白名单/黑名单（先白名单再黑名单）
• 大文件保护（>1GB 直接 302 回源）
• 上游重定向 Location 改写（可识别 GitHub URL 时继续经由代理）

快速开始

1. 启动服务

go run .

默认监听地址：127.0.0.1:2005

2. 初始化用户与 token

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 请求

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 用法

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>]

示例：

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
• 总是 403：
  • 检查 token 是否过期或禁用
  • 检查 URL 是否命中支持规则以及白黑名单规则

License

详见仓库中的 LICENSE 文件。