From b7802f4e3e8395f43d77cd5a648da15841c5bec2 Mon Sep 17 00:00:00 2001 From: yusing Date: Sun, 5 Jan 2025 03:58:56 +0800 Subject: [PATCH] docs and makefile changes --- Makefile | 3 +- README.md | 13 ++-- README_CHT.md | 187 ++++++++++++++++++++++++++++-------------------- next-release.md | 1 + 4 files changed, 119 insertions(+), 85 deletions(-) diff --git a/Makefile b/Makefile index 235dd85..94d0ce9 100755 --- a/Makefile +++ b/Makefile @@ -62,8 +62,9 @@ cloc: push-docker-io: BUILDER=build docker buildx build \ --platform linux/arm64,linux/amd64 \ - -f Dockerfile.dev \ + -f Dockerfile \ -t docker.io/yusing/godoxy-nightly \ + -t docker.io/yusing/godoxy-nightly:${VERSION}-${BUILD_DATE} \ --build-arg VERSION="${VERSION}-nightly-${BUILD_DATE}" \ --push . diff --git a/README.md b/README.md index 9bca386..ad4f742 100755 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ _Join our [Discord](https://discord.gg/umReR62nRd) for help and discussions_ - [HTTP middleware support](https://github.com/yusing/go-proxy/wiki/Middlewares) - [Custom error pages support](https://github.com/yusing/go-proxy/wiki/Middlewares#custom-error-pages) - TCP and UDP port forwarding -- **Web UI with App dashboard** +- **Web UI with App dashboard and config editor** - Supports linux/amd64, linux/arm64 - Written in **[Go](https://go.dev)** @@ -54,6 +54,8 @@ _Join our [Discord](https://discord.gg/umReR62nRd) for help and discussions_ ## Getting Started +For full documentation, **[See Wiki](https://github.com/yusing/go-proxy/wiki)** + ### Prerequisites Setup DNS Records point to machine which runs `GoDoxy`, e.g. @@ -95,8 +97,7 @@ Setup DNS Records point to machine which runs `GoDoxy`, e.g. 6. You may now do some extra configuration - With text editor (e.g. Visual Studio Code) - - With Web UI via `http://localhost:3000` or `https://gp.y.z` - - For more info, [See Wiki](<[wiki](https://github.com/yusing/go-proxy/wiki)>) + - With Web UI via `https://gp.y.z` [🔼Back to top](#table-of-content) @@ -104,15 +105,15 @@ Setup DNS Records point to machine which runs `GoDoxy`, e.g. 1. Make `config` directory then grab `config.example.yml` into `config/config.yml` - `mkdir -p config && wget https://raw.githubusercontent.com/yusing/go-proxy/v0.7/config.example.yml -O config/config.yml` + `mkdir -p config && wget https://raw.githubusercontent.com/yusing/go-proxy/v0.8/config.example.yml -O config/config.yml` 2. Grab `.env.example` into `.env` - `wget https://raw.githubusercontent.com/yusing/go-proxy/v0.7/.env.example -O .env` + `wget https://raw.githubusercontent.com/yusing/go-proxy/v0.8/.env.example -O .env` 3. Grab `compose.example.yml` into `compose.yml` - `wget https://raw.githubusercontent.com/yusing/go-proxy/v0.7/compose.example.yml -O compose.yml` + `wget https://raw.githubusercontent.com/yusing/go-proxy/v0.8/compose.example.yml -O compose.yml` ### Folder structrue diff --git a/README_CHT.md b/README_CHT.md index 3bebe4d..9673dd5 100644 --- a/README_CHT.md +++ b/README_CHT.md @@ -1,4 +1,4 @@ -# go-proxy +# GoDoxy [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=yusing_go-proxy&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=yusing_go-proxy) [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=yusing_go-proxy&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=yusing_go-proxy) @@ -7,124 +7,155 @@ [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=yusing_go-proxy&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=yusing_go-proxy) [![](https://dcbadge.limes.pink/api/server/umReR62nRd)](https://discord.gg/umReR62nRd) -一個輕量化、易用且[高效]([docs/benchmark_result.md](https://github.com/yusing/go-proxy/wiki/Benchmarks)))的反向代理和端口轉發工具 +[English Documentation](README.md) + +一個輕量級、易於使用且[高效能](https://github.com/yusing/go-proxy/wiki/Benchmarks)的反向代理，具有網頁介面和儀表板。 + +![截圖](screenshots/webui.png) + +_加入我們的 [Discord](https://discord.gg/umReR62nRd) 獲取幫助和討論_ ## 目錄 -- [go-proxy](#go-proxy) +- [GoDoxy](#godoxy) - [目錄](#目錄) - - [重點](#重點) + - [主要特點](#主要特點) - [入門指南](#入門指南) + - [前置需求](#前置需求) - [安裝](#安裝) - - [命令行參數](#命令行參數) - - [環境變量](#環境變量) - - [VSCode 中使用 JSON Schema](#vscode-中使用-json-schema) - - [展示](#展示) - - [idlesleeper](#idlesleeper) - - [源碼編譯](#源碼編譯) - -## 重點 - -- 易用 - - 不需花費太多時間就能輕鬆配置 - - 支持多個docker節點 - - 除錯簡單 -- 自動配置 SSL 證書（參見[可用的 DNS 供應商](https://github.com/yusing/go-proxy/wiki/Supported-DNS%E2%80%9001-Providers)） -- 透過 Docker 容器自動配置 -- 容器狀態變更時自動熱重載 -- **idlesleeper** 容器閒置時自動暫停/停止，入站時自動喚醒 (可選, 參見 [展示](#idlesleeper)) -- HTTP(s) 反向代理 -- [HTTP middleware](https://github.com/yusing/go-proxy/wiki/Middlewares) -- [自訂 error pages](https://github.com/yusing/go-proxy/wiki/Middlewares#custom-error-pages) -- TCP/UDP 端口轉發 -- Web 面板 (內置App dashboard) -- 支持 linux/amd64、linux/arm64 平台 -- 使用 **[Go](https://go.dev)** 編寫 - -[🔼 返回頂部](#目錄) + - [手動安裝](#手動安裝) + - [資料夾結構](#資料夾結構) + - [在 VSCode 中使用 JSON Schema](#在-vscode-中使用-json-schema) + - [截圖](#截圖) + - [閒置休眠](#閒置休眠) + - [自行編譯](#自行編譯) + +## 主要特點 + +- 容易使用 + - 輕鬆配置 + - 簡單的多節點設置 + - 錯誤訊息清晰詳細，易於排除故障 +- 自動 SSL 憑證管理（參見 [支援的 DNS-01 驗證提供商](https://github.com/yusing/go-proxy/wiki/Supported-DNS%E2%80%9001-Providers)） +- 自動配置 Docker 容器 +- 容器狀態/配置文件變更時自動熱重載 +- **閒置休眠**：在閒置時停止容器，有流量時喚醒（_可選，參見[截圖](#閒置休眠)_） +- HTTP(s) 反向代理 +- [HTTP 中介軟體支援](https://github.com/yusing/go-proxy/wiki/Middlewares) +- [自訂錯誤頁面支援](https://github.com/yusing/go-proxy/wiki/Middlewares#custom-error-pages) +- TCP 和 UDP 埠轉發 +- **網頁介面，具有應用儀表板和配置編輯器** +- 支援 linux/amd64、linux/arm64 +- 使用 **[Go](https://go.dev)** 編寫 + +[🔼回到頂部](#目錄) ## 入門指南 +完整文檔請參見 **[Wiki](https://github.com/yusing/go-proxy/wiki)** + +### 前置需求 + +設置 DNS 記錄指向運行 `GoDoxy` 的機器，例如： + +- A 記錄：`*.y.z` -> `10.0.10.1` +- AAAA 記錄：`*.y.z` -> `::ffff:a00:a01` + ### 安裝 -1. 抓取Docker鏡像 +1. 拉取最新的 Docker 映像 ```shell docker pull ghcr.io/yusing/go-proxy:latest ``` -2. 建立新的目錄，並切換到該目錄，並執行 - - ```shell - docker run --rm -v .:/setup ghcr.io/yusing/go-proxy /app/go-proxy setup +2. 建立新目錄，`cd` 進入後運行安裝，或[手動安裝](#手動安裝) + + ```shell + docker run --rm -v .:/setup ghcr.io/yusing/go-proxy /app/godoxy setup ``` -3. 設置 DNS 記錄，例如： +3. _（可選）_ 設置網頁介面登入 + + - 設置隨機 JWT 密鑰 + + ```shell + sed -i "s|API_JWT_SECRET=.*|API_JWT_SECRET=$(openssl rand -base64 32)|g" .env + ``` + + - 更改網頁介面認證的使用者名稱和密碼 + ```shell + sed -i "s|API_USERNAME=.*|API_USERNAME=admin|g" .env + sed -i "s|API_PASSWORD=.*|API_PASSWORD=some-strong-password|g" .env + ``` + +4. _（可選）_ 設置其他 Docker 節點的 `docker-socket-proxy`（參見 [多 Docker 節點設置](https://github.com/yusing/go-proxy/wiki/Configurations#multi-docker-nodes-setup)），然後在 `config.yml` 中添加它們 + +5. 啟動容器 `docker compose up -d` + +6. 現在您可以進行額外的配置 + - 使用文字編輯器（如 Visual Studio Code） + - 通過網頁介面 `https://gp.y.z` - - A 記錄: `*.y.z` -> `10.0.10.1` - - AAAA 記錄: `*.y.z` -> `::ffff:a00:a01` +[🔼回到頂部](#目錄) -4. 配置 `docker-socket-proxy` 其他 Docker 節點（如有） (參見 [範例](docs/docker_socket_proxy.md)) 然後加到 `config.yml` 中 +### 手動安裝 -5. 大功告成，你可以做一些額外的配置 - - 使用文本編輯器 (推薦 Visual Studio Code [參見 VSCode 使用 schema](#vscode-中使用-json-schema)) - - 或通過 `http://localhost:3000` 使用網頁配置編輯器 - - 詳情請參閱 [docker.md](docs/docker.md) +1. 建立 `config` 目錄，然後將 `config.example.yml` 下載到 `config/config.yml` -[🔼 返回頂部](#目錄) + `mkdir -p config && wget https://raw.githubusercontent.com/yusing/go-proxy/v0.8/config.example.yml -O config/config.yml` -### 命令行參數 +2. 將 `.env.example` 下載到 `.env` -| 參數 | 描述 | 示例 | -| ------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- | -| 空 | 啟動代理服務器 | | -| `validate` | 驗證配置並退出 | | -| `reload` | 強制刷新配置 | | -| `ls-config` | 列出配置並退出 | `go-proxy ls-config \| jq` | -| `ls-route` | 列出路由並退出 | `go-proxy ls-route \| jq` | -| `go-proxy ls-route \| jq` | -| `ls-icons` | 列出 [dashboard-icons](https://github.com/walkxcode/dashboard-icons/tree/main) 並退出 | `go-proxy ls-icons \| grep adguard` | -| `debug-ls-mtrace` | 列出middleware追蹤 **(僅限於 debug 模式)** | `go-proxy debug-ls-mtrace \| jq` | + `wget https://raw.githubusercontent.com/yusing/go-proxy/v0.8/.env.example -O .env` -**使用 `docker exec go-proxy /app/go-proxy <參數>` 運行** +3. 將 `compose.example.yml` 下載到 `compose.yml` -### 環境變量 + `wget https://raw.githubusercontent.com/yusing/go-proxy/v0.8/compose.example.yml -O compose.yml` -| 環境變量 | 描述 | 默認 | 格式 | -| ------------------------------ | ---------------- | ---------------- | ------------- | -| `GOPROXY_NO_SCHEMA_VALIDATION` | 禁用 schema 驗證 | `false` | boolean | -| `GOPROXY_DEBUG` | 啟用調試輸出 | `false` | boolean | -| `GOPROXY_HTTP_ADDR` | http 收聽地址 | `:80` | `[host]:port` | -| `GOPROXY_HTTPS_ADDR` | https 收聽地址 | `:443` | `[host]:port` | -| `GOPROXY_API_ADDR` | api 收聽地址 | `127.0.0.1:8888` | `[host]:port` | +### 資料夾結構 -### VSCode 中使用 JSON Schema +```shell +├── certs +│ ├── cert.crt +│ └── priv.key +├── compose.yml +├── config +│ ├── config.yml +│ ├── middlewares +│ │ ├── middleware1.yml +│ │ ├── middleware2.yml +│ ├── provider1.yml +│ └── provider2.yml +└── .env +``` -複製 [`.vscode/settings.example.json`](.vscode/settings.example.json) 到 `.vscode/settings.json` 並根據需求修改 +### 在 VSCode 中使用 JSON Schema -[🔼 返回頂部](#目錄) +複製 [`.vscode/settings.example.json`](.vscode/settings.example.json) 到 `.vscode/settings.json` 並根據需要修改 +[🔼回到頂部](#目錄) -## 展示 +## 截圖 -### idlesleeper +### 閒置休眠 -![idlesleeper](screenshots/idlesleeper.webp) +![閒置休眠](screenshots/idlesleeper.webp) -[🔼 返回頂部](#目錄) +[🔼回到頂部](#目錄) -## 源碼編譯 +## 自行編譯 -1. 獲取源碼 `git clone https://github.com/yusing/go-proxy --depth=1` +1. 克隆儲存庫 `git clone https://github.com/yusing/go-proxy --depth=1` -2. 安裝/升級 [go 版本 (>=1.22)](https://go.dev/doc/install) 和 `make`（如果尚未安裝） +2. 如果尚未安裝，請安裝/升級 [go (>=1.22)](https://go.dev/doc/install) 和 `make` -3. 如果之前編譯過（go 版本 < 1.22），請使用 `go clean -cache` 清除緩存 +3. 如果之前編譯過（go < 1.22），請使用 `go clean -cache` 清除快取 -4. 使用 `make get` 獲取依賴項 +4. 使用 `make get` 獲取依賴 -5. 使用 `make build` 編譯 +5. 使用 `make build` 編譯二進制檔案 -[🔼 返回頂部](#目錄) +[🔼回到頂部](#目錄) diff --git a/next-release.md b/next-release.md index 7420fb2..e751a89 100644 --- a/next-release.md +++ b/next-release.md @@ -76,6 +76,7 @@ - `proxy..path_patterns` fully support http.ServeMux patterns `[METHOD ][HOST]/[PATH]` (See https://pkg.go.dev/net/http#hdr-Patterns-ServeMux) - caching ACME private key in order to reuse ACME account, to prevent from ACME rate limit +- WebUI config editor now validates for middleware compose files - **New:** fully support string as inline YAML for docker labels