简而言之, 我们在3.0.x进一步优化了资源消耗与效率, 在3.1.x中我们加入了各个错误码的美观界面, 同时大幅优化了路径匹配器的效率, 在3.2.x中我们加入了Docker,GHCR的反代加速支持, 在3.3.x中我们优化了资源管理与断开感知

项目简介

pullDocker Image Size (tag)Go Report Card

基于Go的高性能,多功能,可扩展的Github代理

  • 基于 Go 语言实现,跨平台的同时提供高并发性能
  • 🌐 使用字节旗下的 HertZ 作为 Web 框架
  • 📡 使用 Touka-HTTPC 作为 HTTP 客户端
  • 📥 支持 Git clone、raw、releases 等文件拉取
  • 🐳 支持反代Docker, GHCR等镜像仓库
  • 🎨 支持多个前端主题
  • 🚫 支持自定义黑名单/白名单
  • 🗄️ 支持 Git Clone 缓存(配合 Smart-Git
  • 🐳 支持自托管与Docker容器化部署
  • 支持速率限制
  • 支持带宽速率限制
  • 🔒 支持用户鉴权
  • 🐚 支持 shell 脚本多层嵌套加速

DEMO

TG讨论群组

相关文章

项目文档

GHProxy项目文档Next(仍在建设中)

CHANGLOG (更新日志)

3.3.2 - 2025-05-18

  • CHANGE: 默认主题改为design

3.3.1 - 2025-05-16

  • CHANGE: 为target放宽限制, 支持自定义
  • CHANGE: 更新hertz, 0.9.7=>0.10.0

3.3.0 - 2025-05-15

  • CHANGE: 为httpc加入request builderwithcontext选项
  • ADD: 加入带宽限制功能
  • ADD: 为netpoll模式开启探测客户端是否断开功能

3.2.4 - 2025-05-13

  • CHANGE: 移除未使用的变量与相关计算

3.2.3 - 2025-05-07

  • CHANGE: 迁移logger库到新的仓库, 开启异步日志记录
  • CHANGE: 更新Go版本到go1.24.3
  • CHANGE: 迁移httpc到新的仓库

3.2.2 - 2025-04-29

  • ADD: 实验性的raw Header处置, 用于应对Github对zh-CN的限制
  • FIX: 修正Header部分的一些处理问题
  • REVERT: 为git clone部分回滚 3.1.0中的 “使用bodystream进行req方向的body复制, 而不是使用额外的buffer reader” 修改

3.2.1 - 2025-04-29

  • FIX: 修复在HertZ路由匹配器下matcher键值不一致的问题

3.2.0 - 2025-04-27

  • CHANGE: 加入ghcrdockerhub反代功能
  • FIX: 修复在HertZ路由匹配器下与用户名相关功能异常的问题

3.1.0 - 2025-04-24

  • CHANGE: 对标准url使用HertZ路由匹配器, 而不是自制匹配器, 以提升效率
  • CHANGE: 使用bodystream进行req方向的body复制, 而不是使用额外的buffer reader
  • CHANGE: 使用HertZrequestContext传递matcher参数, 而不是25w30a中的ctx
  • CHANGE: 改进rate模块, 避免并发竞争问题
  • CHANGE: 将大部分状态码返回改为新的html/tmpl方式处理
  • CHANGE: 修改部分log等级
  • FIX: 修正默认配置的填充错误
  • CHANGE: 使用go html/tmpl处理状态码页面, 同时实现错误信息显示
  • CHANGE: 改进handle, 复用共同部分
  • CHANGE: 细化url匹配的返回码处理
  • CHANGE: 增加404界面

3.0.3 - 2025-04-19

  • CHANGE: 增加移除部分header的处置, 避免向服务端/客户端透露过多信息
  • FIX: 修正非预期的header操作行为
  • CHANGE: 合并header相关逻辑, 避免多次操作
  • CHANGE: 对editor模式下的input进行处置, 增加隐式关闭处理
  • CHANGE: 增加netlib配置项

3.0.2 - 2025-04-15

  • CHANGE: 避免重复的re编译操作
  • CHANGE: 去除不必要的请求
  • CHANGE: 改进httpc相关配置
  • CHANGE: 更新httpc 0.4.0
  • CHANGE: 为不遵守RFC 2616, RFC 9112的客户端带来兼容性改进

3.0.1 - 2025-04-08

  • CHANGE: 加入memLimit指示gc
  • CHANGE: 加入hlog输出路径配置
  • CHANGE: 修正H2C配置问题

3.0.0 - 2025-04-04

  • RELEASE: Next Gen; 下一个起点;
  • CHANGE: 使用HertZ框架重构, 提升性能
  • CHANGE: 前端在构建时加入, 新增Design,Metro,Classic主题
  • CHANGE: 加入Mino主题对接选项
  • FIX: 修正部分日志输出问题
  • CHANGE: 移除gin残留
  • CHANGE: 移除无用传入参数, 调整代码结构
  • CHANGE: 改进cli
  • CHANGE: 改进脚本嵌套加速处理器
  • CHANGE&FIX: 使用c.SetBodyStream方式, 修正此前chunked传输中存在的诸多问题, 参看HertZ Issues #1309
  • PORT: 从v2移植matcher相关改进
  • CHANGE: 增加默认配置生成
  • CHANGE: 优化前端资源加载
  • CHANGE: 将cfgflag改为c以符合POSIX规范
  • CHANGE: 为smart-git添加no-cache标头

主要更新

Docker GHCR等镜像代理支持

于3.2.0中引入, 支持反代DockerHub等镜像仓库

反代DockerHub

1
2
3
[docker]
enabled = true
target = "dockerhub" # ghcr/dockerhub or "xx.example.com"

反代ghcr.io

1
2
3
[docker]
enabled = true
target = "ghcr" # ghcr/dockerhub or "xx.example.com"

反代自定义地址(以docker.example.com为例子)

1
2
3
[docker]
enabled = true
target = "docker.example.com" # ghcr/dockerhub or "xx.example.com"

带宽速率限制

允许限制单个请求的带宽与程序总体的带宽

1
2
3
4
5
6
[rateLimit.bandwidthLimit]
	enabled = true
	totalLimit = "100mbps" # 程序总带宽限制
	totalBurst = "100mbps" # 令牌桶大小 (参看go rate标准库令牌桶原理)
	singleLimit = "10mbps" # 单个请求带宽限制
	singleBurst = "10mbps" # 令牌桶大小 (参看go rate标准库令牌桶原理)

错误返回页面

在3.1.0我们引入了错误页面支持, 基于go强大的html/tmpl, 我们可以在返回错误页面时返回具体的错误, 而不是固定的错误页面与内容

以下是部分页面效果演示, 此功能支持更多状态码(几乎所有内部错误), 若生成页面失败, 也会回退逻辑, 保证错误返回

404 Not Match

则代表内部匹配器未匹配路径, 路径可能不是正确的, 可以看到页面中明确的提示

404-not-match

404 By Github

这个404的来源是Github, 这代表路径经过了内部匹配并向Github发出了请求, 但Github返回了404

404-by-github

403 Black List

这代表请求被黑名单功能屏蔽了

403-blacklist

非显式功能与性能改进

还有诸多非显式的改进, 无法简单说明, 后续会另起文章说明

例如 客户端断联主动探测 以避免客户端断开攻击

配置文件

config.tomlghproxy 的主配置文件,采用 TOML 格式。您可以通过修改此文件来定制 ghproxy 的各项功能,例如服务器端口、连接设置、Git 克隆模式、日志级别、认证方式、黑白名单以及限速策略等。

以下是 config.toml 文件的详细配置项说明:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
[server]
host = "0.0.0.0"
port = 8080
netlib = "netpoll" # "netpoll" / "std" "standard" "net/http" "net"
sizeLimit = 125 # MB
memLimit = 0 # MB
H2C = true
cors = "*" # "*"/"" -> "*" ; "nil" -> "" ;
debug = false

[httpc]
mode = "auto" # "auto" or "advanced"
maxIdleConns = 100 # only for advanced mode
maxIdleConnsPerHost = 60 # only for advanced mode
maxConnsPerHost = 0 # only for advanced mode
useCustomRawHeaders = false

[gitclone]
mode = "bypass" # bypass / cache
smartGitAddr = "http://127.0.0.1:8080"
ForceH2C = false

[shell]
editor = false
rewriteAPI = false

[pages]
mode = "internal" # "internal" or "external"
theme = "bootstrap" # "bootstrap" or "nebula"
staticDir = "/data/www"

[log]
logFilePath = "/data/ghproxy/log/ghproxy.log"
maxLogSize = 5 # MB
level = "info" # dump, debug, info, warn, error, none
hertzLogPath = "/data/ghproxy/log/hertz.log"

[auth]
method = "parameters" # "header" or "parameters"
token = "token"
key = ""
enabled = false
passThrough = false
ForceAllowApi = false

[blacklist]
blacklistFile = "/data/ghproxy/config/blacklist.json"
enabled = false

[whitelist]
enabled = false
whitelistFile = "/data/ghproxy/config/whitelist.json"

[rateLimit]
enabled = false
rateMethod = "total" # "ip" or "total"
ratePerMinute = 180
burst = 5

[rateLimit.bandwidthLimit]
	enabled = false
	totalLimit = "100mbps"
	totalBurst = "100mbps"
	singleLimit = "10mbps"
	singleBurst = "10mbps"

[outbound]
enabled = false
url = "socks5://127.0.0.1:1080" # "http://127.0.0.1:7890"

[docker]
enabled = false
target = "ghcr" # ghcr/dockerhub or "xx.example.com"

配置项详细说明

  • [server] - 服务器配置

    • host: 监听地址。
      • 类型: 字符串 (string)
      • 默认值: "0.0.0.0" (监听所有)
      • 说明: 设置 ghproxy 监听的网络地址。通常设置为 "0.0.0.0" 以监听所有可用的网络接口。
    • port: 监听端口。
      • 类型: 整数 (int)
      • 默认值: 8080
      • 说明: 设置 ghproxy 监听的端口号。
    • netlib: 底层网络库。
      • 类型: 字符串 (string)
      • 默认值: "" (HertZ默认处置)
      • 说明: "std" "standard" "net/http" "net" 均会被设置为go标准库net/http, 设置为"netpoll"""会由HertZ默认逻辑处理
    • sizeLimit: 请求体大小限制。
      • 类型: 整数 (int)
      • 默认值: 125 (MB)
      • 说明: 限制允许接收的请求体最大大小,单位为 MB。用于防止过大的请求导致服务压力过大。
    • memLimit: runtime内存限制
      • 类型: 整数 (int64)
      • 默认值: 0 (不传入)
      • 说明: 给runtime的指标, 让gc行为更高效
    • H2C: 是否启用 H2C (HTTP/2 Cleartext) 传输。
      • 类型: 布尔值 (bool)
      • 默认值: true (启用)
      • 说明: 启用后,允许客户端使用 HTTP/2 协议进行无加密传输,提升性能。
    • cors: CORS (跨域资源共享) 设置。
      • 类型: 字符串 (string)
      • 默认值: "*" (允许所有来源)
      • 可选值:
        • """*": 允许所有来源跨域访问。
        • "nil": 禁用 CORS。
        • 具体的域名: 例如 "https://example.com",只允许来自指定域名的跨域请求。
      • 说明: 配置 CORS 策略,用于控制哪些域名可以跨域访问 ghproxy 服务。
    • debug: 是否启用调试模式。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后,ghproxy 会输出更详细的日志信息,用于开发和调试。
  • [httpc] - HTTP 客户端配置

    • mode: HTTP 客户端模式。
      • 类型: 字符串 (string)
      • 默认值: "auto" (自动模式)
      • 可选值:
        • "auto": 自动模式,使用默认的 HTTP 客户端配置,适用于大多数场景。
        • "advanced": 高级模式,允许自定义连接池参数,可以更精细地控制 HTTP 客户端的行为。
      • 说明: 选择 HTTP 客户端的运行模式。
    • maxIdleConns: 最大空闲连接数 (仅在高级模式下生效)。
      • 类型: 整数 (int)
      • 默认值: 100
      • 说明: 设置 HTTP 客户端连接池中保持的最大空闲连接数。
    • maxIdleConnsPerHost: 每个主机最大空闲连接数 (仅在高级模式下生效)。
      • 类型: 整数 (int)
      • 默认值: 60
      • 说明: 设置 HTTP 客户端连接池中,每个主机允许保持的最大空闲连接数。
    • maxConnsPerHost: 每个主机最大连接数 (仅在高级模式下生效)。
      • 类型: 整数 (int)
      • 默认值: 0 (不限制)
      • 说明: 设置 HTTP 客户端连接池中,每个主机允许建立的最大连接数。设置为 0 表示不限制。
    • useCustomRawHeaders: 使用预定义header避免github waf对应zh-CN的封锁
      • 类型: 布尔值(bool)
      • 默认值: false(停用)
      • 说明: 启用后, 拉取raw文件会使用程序预定义的固定headers, 而不是原先的复制行为
  • [gitclone] - Git 克隆配置

    • mode: Git 克隆模式。
      • 类型: 字符串 (string)
      • 默认值: "bypass" (绕过模式)
      • 可选值:
        • "bypass": 绕过模式,直接克隆 GitHub 仓库,不使用任何缓存加速。
        • "cache": 缓存模式,使用智能 Git 服务加速克隆,需要配置 smartGitAddr
      • 说明: 选择 Git 克隆的模式。
    • smartGitAddr: 智能 Git 服务地址 (仅在缓存模式下生效)。
      • 类型: 字符串 (string)
      • 默认值: "http://127.0.0.1:8080"
      • 说明: 当 mode 设置为 "cache" 时,需要配置智能 Git 服务的地址,用于加速 Git 克隆。
    • ForceH2C: 是否强制使用 H2C 连接到智能 Git 服务。
      • 类型: 布尔值 (bool)
      • 默认值: false (不强制)
      • 说明: 如果智能 Git 服务支持 H2C,可以设置为 true 以强制使用 H2C 连接,提升性能。
  • [shell] - Shell 嵌套加速功能配置

    • editor: 是否启用编辑(嵌套加速)功能。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后, 会修改.sh文件内容以实现嵌套加速
    • rewriteAPI: 是否重写 API 地址。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后,ghproxy 会重写脚本内的Github API地址。
  • [pages] - Pages 服务配置

    • mode: Pages 服务模式。
      • 类型: 字符串 (string)
      • 默认值: "internal" (内置 Pages 服务)
      • 可选值:
        • "internal": 使用 ghproxy 内置的 Pages 服务。
        • "external": 使用外部 Pages 位置。
      • 说明: 选择 Pages 服务的运行模式。
    • theme: Pages 主题。
      • 类型: 字符串 (string)
      • 默认值: "bootstrap"
      • 可选值: 参看GHProxy项目前端仓库
      • 说明: 设置内置 Pages 服务使用的主题。
    • staticDir: 静态文件目录。
      • 类型: 字符串 (string)
      • 默认值: "/data/www"
      • 说明: 指定外置 Pages 服务使用的静态文件目录。
  • [log] - 日志配置

    • logFilePath: 日志文件路径。
      • 类型: 字符串 (string)
      • 默认值: "/data/ghproxy/log/ghproxy.log"
      • 说明: 设置 ghproxy 日志文件的存储路径。
    • maxLogSize: 最大日志文件大小。
      • 类型: 整数 (int)
      • 默认值: 5 (MB)
      • 说明: 设置单个日志文件的最大大小,单位为 MB。当日志文件大小超过此限制时,会进行日志轮转。
    • level: 日志级别。
      • 类型: 字符串 (string)
      • 默认值: "info"
      • 可选值: "dump", "debug", "info", "warn", "error", "none"
      • 说明: 设置日志输出的级别。级别越高,输出的日志信息越少。
        • "dump": 输出所有日志,包括最详细的调试信息。
        • "debug": 输出调试信息、信息、警告和错误日志。
        • "info": 输出信息、警告和错误日志。
        • "warn": 输出警告和错误日志。
        • "error": 仅输出错误日志。
        • "none": 禁用所有日志输出。
    • hertzLogPath: HertZ日志文件路径。
      • 类型: 字符串 (string)
      • 默认值: "/data/ghproxy/log/hertz.log"
      • 说明: 设置 HertZ 日志文件的存储路径。
  • [auth] - 认证配置

    • enabled: 是否启用认证。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后,需要提供正确的认证信息才能访问 ghproxy 服务。
    • method: 认证方法。
      • 类型: 字符串 (string)
      • 默认值: "parameters" (URL 参数)
      • 可选值: "header""parameters"
        • "header": 通过请求头 GH-Auth 或自定义请求头 (通过 key 配置) 传递认证 Token。
        • "parameters": 通过 URL 参数 auth_token 或自定义 URL 参数名 (通过 Key 配置) 传递认证 Token。
      • 说明: 选择认证信息传递的方式。
    • key: 自定义认证 Key。
      • 类型: 字符串 (string)
      • 默认值: "" (空字符串,使用默认的 GH-Auth 请求头或 auth_token URL 参数名)
      • 说明: 可以自定义认证时使用的请求头名称或 URL 参数名。如果为空,则使用默认的 GH-Auth 请求头或 auth_token URL 参数名。
    • token: 认证 Token。
      • 类型: 字符串 (string)
      • 默认值: "token"
      • 说明: 设置认证时需要提供的 Token 值。
    • passThrough: 是否认证参数透穿到Github。
      • 类型: 布尔值 (bool)
      • 默认值: false (不允许)
      • 说明: 如果设置为 true,相关参数会被透穿到Github。
    • ForceAllowApi: 是否强制允许 API 访问。
      • 类型: 布尔值 (bool)
      • 默认值: false (不强制允许)
      • 说明: 如果设置为 true,则强制允许对 GitHub API 的访问,即使未启用认证或认证失败。
  • [blacklist] - 黑名单配置

    • enabled: 是否启用黑名单。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后,ghproxy 将根据 blacklist.json 文件中的规则阻止对特定用户或仓库的访问。
    • blacklistFile: 黑名单文件路径。
      • 类型: 字符串 (string)
      • 默认值: "/data/ghproxy/config/blacklist.json"
      • 说明: 指定黑名单配置文件的路径。
  • [whitelist] - 白名单配置

    • enabled: 是否启用白名单。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后,ghproxy 将只允许访问 whitelist.json 文件中规则指定的用户或仓库。白名单的优先级高于黑名单。
    • whitelistFile: 白名单文件路径。
      • 类型: 字符串 (string)
      • 默认值: "/data/ghproxy/config/whitelist.json"
      • 说明: 指定白名单配置文件的路径。
  • [rateLimit] - 限速配置

    • enabled: 是否启用限速。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后,ghproxy 将根据配置的策略限制请求速率,防止服务被滥用。
    • rateMethod: 限速方法。
      • 类型: 字符串 (string)
      • 默认值: "total" (全局限速)
      • 可选值: "ip""total"
        • "ip": 基于客户端 IP 地址进行限速,每个 IP 地址都有独立的速率限制。
        • "total": 全局限速,所有客户端共享同一个速率限制。
      • 说明: 选择限速的策略。
    • ratePerMinute: 每分钟允许的请求数。
      • 类型: 整数 (int)
      • 默认值: 180
      • 说明: 设置每分钟允许通过的最大请求数。
    • burst: 突发请求数。
      • 类型: 整数 (int)
      • 默认值: 5
      • 说明: 允许在短时间内超过 ratePerMinute 的突发请求数。
    • [rateLimit.bandwidthLimit] 带宽速率限制
      • enabled: 是否启用带宽速率限制。
        • 类型: 布尔值 (bool)
        • 默认值: false (禁用)
        • 说明: 启用后,ghproxy 将根据配置的策略限制带宽使用,防止服务被滥用。
      • totalLimit: 全局带宽限制。
        • 类型: 字符串 (string)
        • 默认值: "100mbps"
        • 说明: 设置全局最大带宽使用量。支持的单位有 “kbps”, “mbps”, “gbps”。
      • totalBurst: 全局突发带宽。
        • 类型: 字符串 (string)
        • 默认值: "100mbps"
        • 说明: 设置全局突发带宽使用量。支持的单位有 “kbps”, “mbps”, “gbps”。
      • singleLimit: 单个连接带宽限制。
        • 类型: 字符串 (string)
        • 默认值: "10mbps"
        • 说明: 设置单个连接的最大带宽使用量。支持的单位有 “kbps”, “mbps”, “gbps”。
      • singleBurst: 单个连接突发带宽。
        • 类型: 字符串 (string)
        • 默认值: "10mbps"
        • 说明: 设置单个连接的突发带宽使用量。支持的单位有 “kbps”, “mbps”, “gbps”。
  • [outbound] - 出站代理配置

    • enabled: 是否启用出站代理。
      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 启用后,ghproxy 将通过配置的代理服务器转发所有出站请求。
    • url: 出站代理 URL。
      • 类型: 字符串 (string)
      • 默认值: "socks5://127.0.0.1:1080"
      • 支持协议: socks5://http://
      • 说明: 设置出站代理服务器的 URL。支持 SOCKS5 和 HTTP 代理协议。
  • [docker] - Docker 镜像代理配置

    • enabled: 是否启用 Docker 镜像代理功能。

      • 类型: 布尔值 (bool)
      • 默认值: false (禁用)
      • 说明: 当设置为 true 时,ghproxy 将尝试代理 Docker 镜像的下载请求,以加速从 GitHub Container Registry (GHCR) 或 Docker Hub 下载镜像。
    • target: 代理的目标 Docker 注册表。

      • 类型: 字符串 (string)
      • 默认值: "ghcr" (代理 GHCR)
      • 可选值: "ghcr""dockerhub"
      • 说明: 指定要代理的 Docker 注册表。
        • "ghcr": 代理 GitHub Container Registry (ghcr.io)。
        • "dockerhub": 代理 Docker Hub (docker.io)。
        • 自定义, 支持传入自定义target, 例如"docker.example.com"

前端主题一览

Bootstrap

使用Bootstrap框架制作的前端页面, v2默认主题

light.png dark.png

许可证: WJQserver Studio License v2.0

Nebula

https://github.com/WJQSERVER-STUDIO/ghproxy/pull/49 加入的主题, 作者为 @liangshengmoran

light.png dark.png

许可证: MIT License

mino

作者为 @admin8800

light.png

许可证: MIT License Copyright (c) admin8800

Design

在v3加入的新主题, 3.3.2开始作为默认主题

light.png dark.png

许可证: WJQserver Studio License v2.0

Classic

来自GHProxy v1阶段的前端页面, 回味项目起点

light.png dark.png

许可证: WJQserver Studio License v2.0

Metro

磁贴风格

light.png dark.png

许可证: WJQserver Studio License v2.0

结语

我们感谢所有用户的支持与反馈,并期待 GhProxy 3.3.2 能为您带来更大的便利和效率!若此项目对您有所帮助,请不要忘记 star 本项目,您的支持是我们前进的动力!