初步实现鉴权

Co-authored-by: Copilot <copilot@github.com>
2026-04-23 20:21:35 +08:00
parent 847ce0c6a8
commit 62e076111f
10 changed files with 1212 additions and 87 deletions
@@ -1,110 +1,140 @@
-
 # Hugs-Proxy

-> 本项目目前支持Github,后面可能会增加HuggingFace......
+一个轻量的 GitHub 资源加速反向代理工具。当前版本在原有代理能力上新增了 SQLite 持久化鉴权和访问审计。

-一个**轻量的 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`，让跳转继续走本代理
+- 支持 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) 运行
-
-在仓库根目录执行：
+### 1. 启动服务

 ```bash
 go run .
 ```

-默认监听：`127.0.0.1:2005`
+默认监听地址：127.0.0.1:2005

-### 2) 使用方式
+### 2. 初始化用户与 token

-访问路径就是你要代理的目标 URL（去掉前面的 `/`）：
-
-```text
-http://127.0.0.1:2005/<目标URL>
+```bash
+go run ./cmd/tokenctl create-user --name alice
+go run ./cmd/tokenctl issue-token --user alice --expires 30d --uses 1
 ```

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

- Release 文件：
+- --expires 支持 7d/30d 这类天数写法
+- 也支持 RFC3339 绝对时间（例如 2026-12-31T23:59:59Z）
+- 不传 --expires 时使用默认有效期（环境变量可配置）
+- --uses 指定可用次数（例如 1 为一次性 token，5 为可用 5 次）

-```text
-http://127.0.0.1:2005/https://github.com/OWNER/REPO/releases/download/v1.0.0/app-darwin-amd64.zip
+### 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"
 ```

- 仓库归档（archive）：
+无 token：返回 401。
+
+token 无效、已禁用、已过期或使用次数耗尽：返回 403。
+
+## tokenctl 用法

 ```text
-http://127.0.0.1:2005/https://github.com/OWNER/REPO/archive/refs/heads/main.zip
+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>]
 ```

- Raw 文件（也可以给 `blob`，服务端会自动替换为 `raw`）：
+示例：

-```text
-http://127.0.0.1:2005/https://github.com/OWNER/REPO/blob/main/README.md
+```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>
 ```

- raw.githubusercontent.com：
+## 环境变量配置

-```text
-http://127.0.0.1:2005/https://raw.githubusercontent.com/OWNER/REPO/main/README.md
-```
+服务与 CLI 共用同一套配置：

-如果你传入的链接不属于上面支持的 GitHub 资源格式，会返回：`403 Invalid input.`
+- 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

-## 配置
+说明：

-目前所有配置都在 [main.go](main.go) 顶部的“配置区域”，修改后重新运行即可：
+- 代理大文件阈值 sizeLimit 仍在 main.go 内部常量（默认 1GB）。
+- 白名单与黑名单规则仍在 main.go 的 whiteListStr 与 blackListStr。

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

-### 白名单/黑名单规则
+程序启动会自动执行幂等建表迁移（CREATE TABLE IF NOT EXISTS），并设置：

-每行一条，支持三种写法：
+- PRAGMA journal_mode = WAL
+- PRAGMA busy_timeout = 5000（或你设置的环境变量值）

- `user1`：匹配/封禁 `user1` 下的所有仓库
- `user1/repo1`：匹配/封禁 `user1/repo1`
- `*/repo1`：匹配/封禁所有名为 `repo1` 的仓库
+表结构语义：
+
+- users：用户主体
+- tokens：token 主体（含过期、禁用、可用次数上限与已使用次数）
+- token_usage：访问审计明细（时间/IP/用户/token/原始 URL/HTTP 状态/成功标志/失败原因）
+- site_stats：总体累计计数（total_accelerated_count）
+
+## 白名单/黑名单规则
+
+每行一条，支持：
+
+- user1：匹配 user1 下所有仓库
+- user1/repo1：匹配 user1/repo1
+- \*/repo1：匹配所有 repo1

 判定顺序：

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

+## 验证步骤

+1. 构建：go build ./...
+2. 无 token 请求：应返回 401
+3. 签发 token 后请求合法 URL：应成功且代理行为与旧版本一致
+4. 禁用或过期 token 请求：应返回 403，并记录失败 usage
+5. 多次请求后检查 site_stats.total_accelerated_count 累计值
+6. 检查 token_usage 记录字段完整性

-## 常见问题
+## 排错

-### 为什么有时会直接跳转到 GitHub？
-
-当上游响应 `Content-Length` 大于 `sizeLimit`（默认 1GB）时，程序会返回 302 重定向到目标 URL，而不是继续转发大文件内容。
-
-### 支持 Git Clone / Git LFS 吗？
-
-本项目主要面向“下载/获取资源”。它只放行并代理部分与 GitHub 资源下载相关的 URL 形态；不保证覆盖完整的 Git 协议或 Git LFS 场景。
+- 启动报数据库错误：
+  - 检查 HUGS_PROXY_DB_PATH 是否可写
+  - 检查目录权限
+- 总是 401：
+  - 确认请求头格式为 Authorization: Bearer <TOKEN>
+- 总是 403：
+  - 检查 token 是否过期或禁用
+  - 检查 URL 是否命中支持规则以及白黑名单规则

 ## License

-详见 License 文件
-
+详见仓库中的 LICENSE 文件。