GHProxy: a Go reverse proxy for GitHub files and Docker images
基于Go的高性能,多功能,可扩展的Github代理加速项目
At a glance
- What is it?
- GHProxy is a self-hostable Go service that fetches GitHub resources and proxies OCI registries such as Docker Hub and GHCR through a rewritten URL. It gives teams in slow or restricted networks a single endpoint for clones, raw files, release assets and image pulls, with caching, auth and rate limits available.
- Who is it for?
- Adopt GHProxy when a team needs a controlled endpoint for GitHub downloads and container image pulls, and when you can operate a Go service with its configuration directory and volume mounts. Do not adopt it if your network already reaches GitHub reliably, or if you need audited upstream behaviour, since the service fetches and re-serves content itself.
- Can I use it commercially?
- Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 144 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
One endpoint for GitHub files, releases and OCI registries
GHProxy is a proxy program for GitHub resources written in Go. The README describes it as supporting git clone, raw file and release downloads, plus reverse proxying for Docker and other image registries such as GHCR. The practical goal is that a single base URL can stand in front of GitHub and a registry, so a script, a CI job or a developer machine only needs one reachable address.
The mechanics are URL rewriting rather than a new client. A GitHub address is placed after the proxy host, and the service resolves and streams it back. Both a bare path and a path that repeats the scheme work, which matters because people paste these URLs from many different places:
git clone https://ghproxy.1888866.xyz/github.com/WJQSERVER-STUDIO/ghproxy.git
git clone https://ghproxy.1888866.xyz/https://github.com/WJQSERVER-STUDIO/ghproxy.gitRegistry pulls follow the same idea with the registry host folded into the path, so Docker Hub and GHCR images can be pulled through the proxy as well:
docker pull gh.example.com/docker.io/wjqserver/ghproxy
docker pull gh.example.com/ghcr.io/openfaas/queue-workerRaw file downloads work the same way, with the full upstream URL appended. That is the mode people use to fetch a release script over HTTPS from a machine that cannot reach raw.githubusercontent.com directly.
The proxy is assembled from Touka, httpc and a row of small Go modules
The go.mod file names the module ghproxy and targets Go 1.26. Two dependencies carry most of the weight. The HTTP server side uses a project-owned framework, the Touka framework, and the HTTP client side uses Touka-HTTPC, both from the same maintainer group.
The rest of the dependency list is a good map of what the service actually does. There is a TOML parser, which matches the config file format the project ships in its config/ directory, and golang.org/x/net and golang.org/x/time for the networking and rate limiting work. A small set of purpose-built packages handle the rest: wanf for file uploads, bauth for authentication, ikumi for compression, ipfilter for address filtering, reco and record for request recording, limitreader for reading bodies under a limit, and a golang-lru cache. The presence of an LRU cache and a directory named weakcache/ tells you that caching is part of the design rather than an afterthought, which is also why the README points at a separate Smart-Git project for git clone caching.
The top-level layout follows the request path. proxy/ holds the upstream proxying logic, api/ the HTTP API surface, auth/ authentication, middleware/ the request filters, weakcache/ the caching layer, config/ the configuration, and deploy/ plus docker/ the deployment assets. main.go ties them together.
Because it is a static Go binary with a config file and no database, the operational footprint is small compared with a service written in a managed language.
Docker deployment with three volumes and one exposed port
The README gives a Docker CLI run command and recommends Docker Compose, pointing at the compose file under docker/compose/docker-compose.yml in the repository. The CLI form publishes one port and mounts three directories:
docker run -p 7210:8080 -v ./ghproxy/log/run:/data/ghproxy/log -v ./ghproxy/log/caddy:/data/caddy/log -v ./ghproxy/config:/data/ghproxy/config --restart always wjqserver/ghproxyTwo things are worth noting. The container listens on 8080 inside and the run command maps host port 7210 to it, so the proxy address your users type is the host port, not the container port. And the volume list shows that a Caddy log directory is mounted as well as the application log and the config directory, which means the deployment expects a reverse proxy in front of the service.
That expectation is worth thinking about before you adopt it. The proxy is designed to sit behind another proxy, with TLS and a public hostname handled outside the Go process. Anyone deploying it needs to supply that front layer themselves; the README does not describe a built-in certificate or domain configuration.
Binary installation is offered, but the README marks it not recommended
For people who do not want containers, the project ships a one-line install script that downloads and runs itself:
wget -O install.sh https://raw.githubusercontent.com/WJQSERVER-STUDIO/ghproxy/main/deploy/install.sh && chmod +x install.sh &&./install.shA separate script is provided for development builds, pulled from the dev branch rather than main:
wget -O install-dev.sh https://raw.githubusercontent.com/WJQSERVER-STUDIO/ghproxy/dev/deploy/install-dev.sh && chmod +x install-dev.sh && ./install-dev.shThe README labels the binary file deployment path as not recommended and points to Docker Compose as the preferred option, with a deployment write-up on the maintainer's blog as the reference. That is a reasonable default: the Docker path makes the config and log volumes explicit, while the binary path leaves more of the process supervision to you.
The distinction between the main and dev branches also matters for how you treat the script. Piping a remote script straight into a shell means the code on the remote branch executes with your privileges, and the dev variant is explicitly a development snapshot rather than a published release.
The licence is dual, and the front end is not covered by it
The licence story here is more complicated than a single file name, and it has changed several times. From version 3.5.2 onward the project is dual licensed: you may choose either the WJQserver Studio License 2.1 or the Mozilla Public License Version 2.0. Before version 2.3.0 it used the WJQserver Studio License 1.2, and before version 1.0.0 it inherited the Apache 2.0 licence from the earlier ghproxy-go project.
The gap that matters most for adoption is the front end. The README states that the front end lives in a separate repository, GHProxy-Frontend, and that each theme has its own licence, so the project licence does not cover the front end. If you deploy the official front end with your own instance, you are taking on a second set of terms for the parts users actually see. The theme repositories are the place to check.
None of this is legal advice, and the practical advice is narrower: read both licence texts before shipping the service, and decide deliberately which of the two you are complying with rather than assuming the MPL 2.0 label in the repository listing covers everything.
Feature surface is broad, and the configuration details live in a separate document
The feature list is long: multiple front end themes, custom blacklists and whitelists, git clone caching, self-hosted and containerized deployment, rate limiting, bandwidth rate limiting, user authentication, and multi-level acceleration for nested shell scripts.
What is missing from the repository itself is the substance behind most of those switches. The README does not show a configuration file. It points to a config document hosted on the project documentation site and to docs/config.md in the repository, and the configuration itself lives in the config/ directory that the Docker run command mounts as a volume. The top-level entries include config/, deploy/, docker/, api/, auth/, proxy/, middleware/, weakcache/, a VERSION file, a DEV-VERSION file, a CHANGELOG.md, a SECURITY.MD and a LICENSE-WSL file, which tells you the shape of the project but not the keys you need to set.
That gap matters for a proxy that handles authentication and rate limiting, because those are the settings most likely to affect how you deploy it. The rate limiting and bandwidth limit defaults are not stated in the README, and neither is the authentication flow. Read the configuration reference before you expose an instance publicly, since a proxy that forwards downloads is exactly the kind of service that attracts abuse if the limits are left too loose.
A public demo instance exists at ghproxy.1888866.xyz, and a Telegram discussion group is linked for support. Treat the demo as a reference for the URL forms, not as something to depend on for your own traffic.
Maintenance state: last push in June 2026, releases from September 2025
The repository is not archived and the last push was on 2026-06-01. Published releases are older than that: 4.3.5-rc.0 on 2025-09-14, 4.3.4 on 2025-09-13 and 4.3.3 on 2025-09-09. So there has been code movement on main since the last tagged build, and the most recent published artefact is a release candidate rather than a final version.
That gap between main and the last release is a practical upgrade consideration. If you pin a container image to a release tag, you pin code from September 2025. If you track main, you get later fixes without a version contract. The CHANGELOG.md and DEV-VERSION file in the repository are where to check what changed between the two.
The dependency set also constrains your rebuild options. The module requires Go 1.26 and pulls a Touka framework version tagged as a pseudo-version, which is the kind of dependency that has to be present when you build from source rather than pulled from a registry.
Editorial conclusion
Adopt GHProxy when a team needs a controlled endpoint for GitHub downloads and container image pulls, and when you can operate a Go service with its configuration directory and volume mounts. Do not adopt it if your network already reaches GitHub reliably, or if you need audited upstream behaviour, since the service fetches and re-serves content itself. Before deploying, read config/ and the referenced docs/config.md to set the auth and rate limit keys yourself, decide whether you need the Docker deployment over the binary one, and confirm that the separate GHProxy-Frontend repository, whose themes carry their own licences, matches the licence you intend to ship.
Frequently asked questions
What does GHProxy do and who needs it?
GHProxy is a Go service that fetches GitHub resources and proxies OCI registries such as Docker Hub and GHCR through a rewritten URL. It is aimed at users and teams on networks where GitHub downloads and image pulls are slow or blocked, and at operators who want to run their own endpoint.
How do I deploy GHProxy with Docker?
The README gives a docker run command that publishes port 7210 to container port 8080 and mounts log and config directories, and it recommends Docker Compose using the compose file under docker/compose/docker-compose.yml. The binary deployment path is offered through an install script but is marked not recommended.
Which licence applies to GHProxy and its front end?
From version 3.5.2 the project is dual licensed under the WJQserver Studio License 2.1 or the Mozilla Public License 2.0, and you pick one. The front end lives in a separate GHProxy-Frontend repository where each theme has its own licence, and it is not covered by the project licence.
Does GHProxy support authentication and rate limiting?
The feature list includes user authentication, rate limiting and bandwidth rate limiting, along with custom blacklists and whitelists. The configuration keys and defaults are documented in the project configuration document rather than in the README.
How is git clone caching handled in GHProxy?
The README lists support for Git clone caching and points at a separate Smart-Git project for that purpose. The repository also contains a weakcache/ directory and depends on an LRU cache, so caching is part of the service design.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/wjqserver-studio-ghproxy)Was this useful?