go-proxy

繁體中文文檔請看此

A lightweight, easy-to-use, and performant reverse proxy with a web UI.

Table of content

• go-proxy
  • Table of content
  • Key Points
  • Getting Started
    • Setup
    • Commands line arguments
    • Environment variables
    • Use JSON Schema in VSCode
    • Config File
    • Provider File
  • Known issues
  • Build it yourself

Key Points

• Easy to use
  • Effortless configuration
  • Error messages is clear and detailed, easy troubleshooting
• Auto certificate obtaining and renewal (See Supported DNS Challenge Providers)
• Auto configuration for docker containers
• Auto hot-reload on container state / config file changes
• Stop containers on idle, wake it up on traffic (optional)
• HTTP(s) reserve proxy
• TCP and UDP port forwarding
• Web UI for configuration and monitoring (See screenshots)
• Written in Go

🔼Back to top

Getting Started

Setup

1. Setup DNS Records, e.g.

   • A Record: *.y.z -> 10.0.10.1
   • AAAA Record: *.y.z -> ::ffff:a00:a01

2. Setup go-proxy See here

3. Setup docker-socket-proxy (see example other machine that is running docker (if any)

4. Configure go-proxy

   • with text editor (e.g. Visual Studio Code)
   • or with web config editor via http://gp.y.z

🔼Back to top

Commands line arguments

Argument	Description	Example
empty	start proxy server
validate	validate config and exit
reload	trigger a force reload of config
ls-config	list config and exit	go-proxy ls-config | jq
ls-route	list proxy entries and exit	go-proxy ls-route | jq

run with docker exec <container_name> /app/go-proxy <command>

Environment variables

Environment Variable	Description	Default	Values
GOPROXY_NO_SCHEMA_VALIDATION	disable schema validation	false	boolean
GOPROXY_DEBUG	enable debug behaviors	false	boolean
GOPROXY_HTTP_PORT	http server port	80	integer
GOPROXY_HTTPS_PORT	http server port (if enabled)	443	integer
GOPROXY_API_PORT	api server port	8888	integer

Use JSON Schema in VSCode

Copy .vscode/settings.example.json to .vscode/settings.json and modify it to fit your needs

🔼Back to top

Config File

See config.example.yml for more

# autocert configuration
autocert:
  email: # ACME Email
  domains: # a list of domains for cert registration
  provider: # DNS Challenge provider
  options: # provider specific options
    - ...
# reverse proxy providers configuration
providers:
  include:
    - providers.yml
    - other_file_1.yml
    - ...
  docker:
    local: $DOCKER_HOST
    remote-1: tcp://10.0.2.1:2375
    remote-2: ssh://root:1234@10.0.2.2

🔼Back to top

Provider File

See Fields

See providers.example.yml for examples

🔼Back to top

Known issues

• Cert "renewal" is actually obtaining a new cert instead of renewing the existing one

• autocert config is not hot-reloadable

🔼Back to top

Build it yourself

1. Clone the repository git clone https://github.com/yusing/go-proxy --depth=1

2. Install / Upgrade go (>=1.22) and make if not already

3. Clear cache if you have built this before (go < 1.22) with go clean -cache

4. get dependencies with make get

5. build binary with make build

🔼Back to top