# 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 文件。