配置说明 #

config.toml - 主配置文件 #

config.toml 是 ghproxy 的主配置文件. 您可以通过修改此文件来定制 ghproxy 的各项功能.

[server] - 服务器配置 #

此部分用于配置 ghproxy 监听的网络地址, 端口以及基础的请求限制.

[server]
host = "0.0.0.0"
port = 8080
sizeLimit = 125 
memLimit = 0 
cors = "*" 
debug = false

• host: ghproxy 监听的网络地址. 默认 "0.0.0.0" 表示监听所有可用的网络接口.
• port: ghproxy 监听的端口号. 默认 8080.
• sizeLimit: 允许接收的请求体最大大小, 单位为 MB. 默认 125.
• memLimit: 为 Go runtime 提供的内存限制指标 (MB), 用于优化垃圾回收 (GC) 行为. 默认 0 表示不设置.
• cors: 配置跨域资源共享 (CORS) 策略.
  • "*" 或 "" (默认): 允许所有来源.
  • "nil": 禁用 CORS.
  • "https://example.com": 只允许特定来源.
• debug: 启用调试模式, 会输出更详细的日志. 默认 false.

[httpc] - HTTP 客户端配置 #

此部分用于配置 ghproxy 向外部 (如 GitHub) 发送请求时所使用的 HTTP 客户端的行为.

[httpc]
mode = "auto"
maxIdleConns = 100
maxIdleConnsPerHost = 60
maxConnsPerHost = 0
useCustomRawHeaders = false

• mode: HTTP 客户端模式.
  • "auto" (默认): 使用默认配置, 适用于大多数场景.
  • "advanced": 允许自定义下方的连接池参数.
• maxIdleConns: (高级模式) 连接池中保持的最大空闲连接数. 默认 100.
• maxIdleConnsPerHost: (高级模式) 每个主机保持的最大空闲连接数. 默认 60.
• maxConnsPerHost: (高级模式) 每个主机的最大连接数. 0 (默认) 表示不限制.
• useCustomRawHeaders: 是否使用预定义的 Headers 访问 GitHub Raw 内容, 以避免潜在的封锁. 默认 false.

[gitclone] - Git 克隆配置 #

配置 git clone 命令通过代理时的加速行为.

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

• mode: Git 克隆模式.
  • "bypass" (默认): 直接转发 git clone 请求, 不进行加速.
  • "cache": 启用智能 Git 缓存加速, 需要配置 smartGitAddr.
• smartGitAddr: (缓存模式) 智能 Git 缓存服务的地址. 默认 "http://127.0.0.1:8080".
• ForceH2C: 是否强制使用 H2C (明文 HTTP/2) 连接到智能 Git 服务. 默认 false.

[shell] - Shell 脚本加速配置 #

用于在代理 .sh 脚本时, 动态修改其内容以实现嵌套加速.

[shell]
editor = false
rewriteAPI = false

• editor: 是否启用脚本编辑功能, 修改脚本内容以实现嵌套加速. 默认 false.
• rewriteAPI: 是否重写脚本内的 GitHub API 地址. 默认 false.

[pages] - Pages 服务配置 #

配置 ghproxy 内置的前端页面服务.

[pages]
mode = "internal"
theme = "bootstrap"
staticDir = "/data/www"

• mode: Pages 服务模式.
  • "internal" (默认): 使用 ghproxy 内置的 Pages 服务.
  • "external": 使用 staticDir 指定的外部静态文件目录.
• theme: (内置模式) 内置页面的主题. 参看 GHProxy-Frontend 获取可用主题.
• staticDir: (外部模式) 静态文件目录的路径.

[log] - 日志配置 #

配置日志的输出行为.

[log]
logFilePath = "/data/ghproxy/log/ghproxy.log"
maxLogSize = 5
level = "info"

• logFilePath: 日志文件的存储路径.
• maxLogSize: 单个日志文件的最大大小 (MB), 超出后会进行轮转. 默认 5.
• level: 日志输出级别. 可选值: "debug", "info" (默认), "warn", "error", "none".

[auth] - 认证配置 #

为 ghproxy 服务启用访问认证.

[auth]
enabled = false
method = "parameters"
token = "token"
key = ""
passThrough = false
ForceAllowApi = false
ForceAllowApiPassList = false

• enabled: 是否启用认证. 默认 false.
• method: 认证信息传递的方式.
  • "parameters" (默认): 通过 URL 参数 (auth_token 或 key 指定的参数).
  • "header": 通过请求头 (GH-Auth 或 key 指定的头).
• token: 认证所需的令牌 (Token) 值.
• key: 自定义认证参数名或请求头名. 为空则使用默认值.
• passThrough: 是否将认证参数透传到 GitHub. 默认 false.
• ForceAllowApi: 是否在未认证或认证失败时, 依然强制允许对 GitHub API 的访问. 默认 false.
• ForceAllowApiPassList: 在 ForceAllowApi 启用时, 是否跳过白名单检查. 默认 false.

[ipFilter] - IP 地址过滤 #

通过 IP 黑白名单限制对服务的访问.

[ipFilter]
enabled = false
enableAllowList = false
enableBlockList = false
ipFilterFile = "/data/ghproxy/config/ipfilter.json"

• enabled: 是否启用 IP 过滤功能. 默认 false.
• enableAllowList: 是否启用白名单.
• enableBlockList: 是否启用黑名单.
• ipFilterFile: 包含 IP/CIDR 列表的 JSON 文件路径.

[blacklist] & [whitelist] - 用户/仓库过滤 #

注意: 这两项是基于用户和仓库名的过滤, 与 [ipFilter] 的 IP 过滤不同.

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

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

• enabled: 是否启用黑/白名单.
• blacklistFile / whitelistFile: 指向包含规则的 JSON 文件路径. 详见下文.

[rateLimit] - 请求速率与带宽限制 #

防止服务被滥用.

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

• enabled: 是否启用请求速率限制. 默认 false.
• rateMethod: 限制方法.
  • "total" (默认): 对整个服务进行全局速率限制.
  • "ip": 对单个 IP 地址进行速率限制.
• ratePerMinute: 每分钟允许的请求数. 默认 180.
• burst: 允许的突发请求数. 默认 5.

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

• enabled: 是否启用带宽限制. 默认 false.
• totalLimit: 程序总带宽限制.
• totalBurst: 程序总突发带宽 (令牌桶大小).
• singleLimit: 单个连接的带宽限制.
• singleBurst: 单个连接的突发带宽 (令牌桶大小).
  • 单位支持 “kbps”, “mbps”, “gbps”.

[outbound] - 出站代理配置 #

让 ghproxy 通过另一个代理服务器访问外部网络.

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

• enabled: 是否启用出站代理. 默认 false.
• url: 代理服务器的 URL. 支持 http://... 和 socks5://....

[docker] - Docker 镜像代理 #

Version: 3.2.0+

配置对 Docker Hub, GHCR 等镜像仓库的代理.

[docker]
enabled = false
target = "ghcr"
auth = false

[docker.credentials]
user1 = "testpass"
test = "test123"

• enabled: 是否启用 Docker 镜像代理. 默认 false.
• target: 代理的目标镜像仓库.
  • "ghcr" (默认), "dockerhub", 或自定义地址如 "docker.example.com".
• auth: 是否对 Docker 代理启用 Basic Auth 鉴权.
• [docker.credentials]: 存储用于 Docker Basic Auth 的用户名和密码.

黑/白名单 JSON 文件说明 #

blacklist.json #

阻止对特定用户或仓库的访问.

{
  "blacklist": [
    "eviluser",
    "spamuser/bad-repo",
    "malwareuser/*"
  ]
}

• 规则:
  • 用户名 ("eviluser"): 阻止该用户的所有仓库.
  • 具体仓库 ("spamuser/bad-repo"): 阻止该特定仓库.
  • 通配符 ("malwareuser/*"): 阻止该用户下的所有仓库. (与只写用户名等效).

whitelist.json #

仅允许对特定用户或仓库的访问. 白名单优先级高于黑名单.

{
  "whitelist": [
    "my-org/project-a",
    "trusted-user/*",
    "another-trusted-user"
  ]
}

• 规则: 与黑名单类似, 支持具体仓库和通配符.

ipfilter.json - IP 地址过滤 #

当 [ipFilter].enabled = true 时, 此文件用于定义允许或拒绝访问的 IP 地址/范围.

{
  "allow": [
    "127.0.0.1",
    "192.168.1.0/24",
    "::1"
  ],
  "block": [
    "10.0.0.0/8"
  ]
}

• allow: 一个 JSON 数组, 定义了 IP 白名单.
  • 只有来源 IP 在此列表中的请求才会被考虑允许.
  • 此列表是否生效, 取决于 config.toml 中的 enableAllowList = true.
• block: 一个 JSON 数组, 定义了 IP 黑名单.
  • 来源 IP 在此列表中的请求将被直接拒绝.
  • 此列表是否生效, 取决于 config.toml 中的 enableBlockList = true.

规则说明:

• 列表中的每个字符串可以是一个单一的 IP 地址 (IPv4 或 IPv6) 或一个 CIDR 网段.
• 过滤优先级: 如果同时启用了白名单和黑名单, 请求的 IP 必须先通过白名单检查, 然后再通过黑名单检查, 才能被最终放行.

程序启动参数 (Flags) #

ghproxy 接受以下启动参数:

$ ghproxy -h
  -c string   config file path (default "/data/ghproxy/config/config.toml")
  -h          show help message and exit
  -v          show version and exit

• -c: 指定 config.toml 文件的路径.
• -h: 显示帮助信息.
• -v: 显示程序版本号.