gh-proxy

用 Rust 编写的高性能、高并发、跨平台 GitHub 反向代理。

gh-proxy 把客户端的请求透明地转发到 GitHub（网页、API、raw 文件或 release 下载）， 请求与响应均以流式方式端到端传递，全程不在内存中缓冲整个 payload-- 因此无论是 git clone 几个 G 的仓库，还是下载大体积 release，内存占用都保持平坦。

---

✨ 特性

• 端到端流式转发：请求体与响应体均以 async stream 透传，零全量缓冲。
• 高并发：基于 tokio + axum（hyper），单机可承载数万并发连接；上游连接池复用、HTTP/2、TCP_NODELAY。
• 跨平台：TLS 使用 rustls，不依赖系统 OpenSSL，开箱即编译运行于 Linux / macOS / Windows。
• 透明代理：正确转发请求头与响应头，按 RFC 7230 §6.1 剥离 hop-by-hop 头与 Connection 中列出的头。
• 可选 Token 注入：配置 GitHub Token 后自动以 Authorization: Bearer <token> 转发，突破 API 速率限制。
• 配置分层：默认值 -> TOML 文件 -> 环境变量 -> 命令行参数，逐层覆盖。
• 优雅停机：收到 Ctrl-C / SIGTERM 后停止接收新连接，等待在途请求完成。
• 结构化日志：pretty（本地开发）或 json（日志收集）。
• 内置探针：GET /health、GET /version。

---

🚀 快速开始

1. 编译

cargo build --release
# 产物：target/release/gh-proxy

2. 运行

# 最简：使用默认配置（监听 0.0.0.0:8080，上游 https://github.com）
./target/release/gh-proxy

3. 验证

curl http://localhost:8080/health        # -> ok
curl http://localhost:8080/version       # -> {"name":"gh-proxy","version":"0.1.0"}
curl http://localhost:8080/             # 透传 https://github.com/ 首页

代理 GitHub API（示例）

./target/release/gh-proxy --upstream https://api.github.com
curl http://localhost:8080/rate_limit    # 透传 GitHub API

配合 git 使用

# 让 git 走代理克隆仓库
git -c http.proxy=http://localhost:8080 clone https://github.com/torvalds/linux.git

注：http.proxy 走 HTTP 代理协议；更通用的做法是把 https://github.com 的请求直接指向本代理 （例如在反代域名上部署本程序）。本程序同时也可作为 git 的 HTTP 透传反代使用。

---

⚙️ 配置

配置按优先级从低到高叠加，后者覆盖前者：

1. 默认值（见 src/config.rs）
2. TOML 文件：--config <path> 指定，或在程序工作目录存在 config.toml 时自动加载（参考 config.toml.example）
3. 环境变量（GH_PROXY_*，下表列出）
4. 命令行参数（优先级最高）

配置项一览

字段	环境变量 / CLI	默认值	说明
host	GH_PROXY_HOST / --host	0.0.0.0	监听地址
port	GH_PROXY_PORT / --port	8080	监听端口
upstream	GH_PROXY_UPSTREAM / --upstream	https://github.com	上游地址（无尾斜杠）
token	GH_PROXY_TOKEN / --token	（无）	可选 GitHub Bearer Token
request_timeout_secs	GH_PROXY_REQUEST_TIMEOUT / --request-timeout	0	总超时秒数，0 表示不限时（推荐，避免切断大下载）
connect_timeout_secs	仅文件	10	上游连接建立超时
pool_idle_timeout_secs	仅文件	90	空闲连接保留时长
pool_max_idle_per_host	仅文件	64	每个 host 的最大空闲连接数
cors_enabled	仅文件	true	是否开启宽松 CORS（浏览器可用）
log_format	GH_PROXY_LOG_FORMAT / --log-format	pretty	日志格式：pretty / json

日志级别由标准 RUST_LOG 控制，默认 gh_proxy=info,tower_http=info。

配置文件示例

# config.toml
host = "0.0.0.0"
port = 8080
upstream = "https://github.com"
# token = "ghp_xxxxxxxxxxxx"
request_timeout_secs = 0
connect_timeout_secs = 10
pool_idle_timeout_secs = 90
pool_max_idle_per_host = 64
cors_enabled = true
log_format = "pretty"

常用上游

用途	upstream
GitHub 网页 / git	https://github.com
REST / GraphQL API	https://api.github.com
原始文件	https://raw.githubusercontent.com

---

🐳 Docker 部署

docker build -t gh-proxy .
docker run -d -p 8080:8080 -e RUST_LOG=gh_proxy=info -e GH_PROXY_UPSTREAM=https://github.com gh-proxy

镜像基于多阶段构建，最终镜像只含编译好的二进制，体积小、无工具链。

---

📦 跨平台构建

得益于 rustls，无需安装系统 OpenSSL：

# macOS Apple Silicon
cargo build --release

# Linux (交叉编译)
rustup target add x86_64-unknown-linux-gnu
cargo build --release --target x86_64-unknown-linux-gnu

# Windows
rustup target add x86_64-pc-windows-msvc
cargo build --release --target x86_64-pc-windows-msvc

---

🛠️ 开发

开发流程、架构、如何扩展功能、交叉编译与发布等，详见 DEVELOPMENT.md。

cargo test          # 运行单元测试
cargo clippy --all-targets -- -D warnings   # 严格 lint
cargo fmt           # 格式化

---

🧱 技术栈

组件	用途
tokio	异步运行时
axum	HTTP 服务端与路由（基于 hyper / tower）
reqwest	上游 HTTP 客户端（rustls + HTTP/2 + 连接池）
tower-http	中间件：tracing、CORS、timeout
tracing	结构化日志
clap	命令行参数（同时支持环境变量）
serde + toml	配置反序列化

---

📄 License

MIT，见 LICENSE。