Zoraxy 介绍与选型指南

Zoraxy（Go 编写的开源反向代理与边缘网关）的定位、核心架构、功能特性、快速上手与同类选型对比，信息溯源自官方仓库与文档站（查询日期 2026-10-20）

Zoraxy网络配置Ubuntu安全2026/10/21

Zoraxy 介绍与选型指南

目标：讲清 Zoraxy 是什么、能解决什么问题、核心架构与功能边界，并给出与 Nginx Proxy Manager、Caddy、Traefik 的量化选型对比，帮你在自托管入口网关选型时快速判断是否适合。本文全部信息溯源自官方仓库与官方渠道，查询日期为 2026-10-20。

一、环境信息

本文为认知与选型篇，内容以官方渠道联网溯源为准，不做本地实验断言。溯源环境清单如下：

项目内容
软件名称Zoraxy（GitHub：tobychui/zoraxy）
官方文档站https://zoraxy.aroz.org
代码仓库https://github.com/tobychui/zoraxy
发布通道GitHub Releases（https://github.com/tobychui/zoraxy/releases）
最新稳定版（查询日期 2026-10-20）v3.3.4，2026-08-22 发布（v3.3.5 尚处于 rc 预发布阶段）
开源协议AGPL-3.0（仓库 LICENSE 文件实查）
开发语言Go（仓库 go.mod 声明 go 1.25.0，官方 README 要求 Go 1.23 及以上源码编译）
维护方tobychui（imuslab.com），社区贡献者共同维护

💡 说明：本文版本与日期均标注来源与查询日期；后续篇目《Ubuntu 22.04 安装 Zoraxy 指南》《Zoraxy 3.3.4 配置参数详解》《Zoraxy 3.3.4 常用 CLI 命令详解》基于 v3.3.4 完成安装、配置与命令实测。

二、软件概述

Zoraxy 是一个用 Go 编写的通用 HTTP 反向代理与转发工具，官方对其定位的一句话描述是「A general purpose HTTP reverse proxy and forwarding tool. Now written in Go!」（来源：仓库 README，查询日期 2026-10-20）。它把「反向代理 + 自动 HTTPS + Web 管理界面」打包成一个静态编译的单文件可执行程序，启动后自带管理控制台，官方将其管理体验类比为「像管理一台家用路由器一样管理你的反向代理服务器」（README Standalone Mode 一节原意），面向的是 Homelab 玩家与需要把多个 Web 服务收敛到统一域名和统一证书下的中小团队。

与传统「改 Nginx 配置文件」的反向代理不同，Zoraxy 的所有代理规则、证书、黑白名单都通过 Web 界面操作并持久化到本地数据库与 JSON 配置文件，不需要手工维护 nginx.conf。同时它把边缘网关常用的一组配套能力（在线在线率监控、TCP/UDP 流量转发、Web-SSH、IP 扫描工具、mDNS 发现、插件系统）也内置在同一进程里，属于「一体化边缘网关」形态。

💡 技术拓展：与「反向代理」容易混淆的代理形态还有以下几类，选型时先分清你要的是哪一种——

形态工作位置典型用途
正向代理客户端一侧，代替客户端出网科学上网、内网统一出口审计
反向代理服务端一侧，代替服务端接客统一域名/证书、负载均衡、隐藏后端拓扑
透明代理网络链路中间，对双方不可见网关层流量劫持、行为管控
边缘网关服务端入口，反向代理的超集在反向代理之上叠加认证、限流、隧道组网等

本文主角 Zoraxy 属于「反向代理 + 边缘网关」形态：核心是反向代理，同时自带隧道转发（TCP/UDP Stream Proxy）、ZeroTier 虚拟网管理等边缘能力（官方 README 与管理界面 Global Area Network 功能区，查询日期 2026-10-20）。

三、核心架构

Zoraxy 采用「单进程单体架构」：一个静态编译的 Go 二进制内嵌全部 Web 管理界面资源，启动即用，没有外部依赖组件（不需要额外的数据库服务或消息队列）。按官方仓库与发布件结构（查询日期 2026-10-20），其运行时结构可以概括为四层：

  1. 接入层（网络监听）：默认监听四类端口——:8000 管理界面（Web UI 与管理 API）、:443 反向代理入站（TLS 模式）、:80 HTTP 到 HTTPS 的跳转监听、:5487 内置静态 Web 服务器（另含 :5488 WebDAV 端口）。以上端口分工来自官方发布件默认值与启动参数（-port、-default_inbound_port 等，详见《Zoraxy 3.3.4 配置参数详解》）。
  2. 路由层（动态反代路由器）：以「代理规则（Proxy Rule）」为基本单位管理转发：每条规则包含匹配域名（含别名主机）、上游（Upstream，可多个并带权重）、虚拟目录、WebSocket 开关、请求头改写、访问控制等，规则以 JSON 文件持久化在配置目录的 proxy/ 子目录中（每个域名一个 .config 文件）。
  3. 数据层（存储与配置）：内嵌键值数据库（默认 auto 模式在 x86-64 上选用 BoltDB，可切换 LevelDB），存放统计、账号、会话等动态数据（sys.db）；静态配置以 JSON 文件存放在 -conf 配置目录（如 acme_conf.json、log_conf.json、trusted_proxies.json）。
  4. 扩展层（可选子系统）：ACME 证书自动化（基于 lego 库，支持 Let's Encrypt 等 CA 与大量 DNS 提供商的 DNS Challenge）、在线率监控（Uptime Monitor）、TCP/UDP 流量代理（Stream Proxy）、mDNS 局域网发现、ZeroTier 虚拟网管理入口、插件系统（v3.2 起引入，官方插件仓库独立于主仓库发布）。

💡 技术拓展：Zoraxy 的存储后端 -db 参数支持三种取值，选型取舍如下——

后端特点适用场景
auto（默认）平台自动探测，x86-64 上选 BoltDB通用服务器，绝大多数场景
boltdb单文件 B+Tree 键值库，读写稳定常规部署、备份简单（拷一个 sys.db）
leveldbLSM 日志结构键值库，目录形态高频写入统计、官方为特定平台提供的备选

单节点网关写入压力小，实际部署保留默认 auto 即可；-dbpath 指定数据库文件路径，-conf 指定配置目录，两者共同决定持久化位置（参数说明见《Zoraxy 3.3.4 配置参数详解》）。

四、功能特性

以下功能清单溯源自官方仓库 README 的 Features 一节与 CHANGELOG.md（查询日期 2026-10-20）：

  • 反向代理（HTTP/2）：虚拟目录（Virtual Directory）、WebSocket 自动代理（无需配置）、Basic Auth、别名主机名（Alias Hostnames）、自定义请求头、上游负载均衡（多上游加权）；v3.3.1 起支持每条规则独立的 WebSocket 超时与多端口监听。
  • TLS/SSL 全自动：ACME 证书自动申请与自动续期、SNI 与 SAN 证书支持、DNS Challenge（支持 lego 库的各 DNS 提供商，可对接 Let's Encrypt；v3.3.1 起启动参数可开 ACME staging 测试模式）。
  • 访问控制：按国家或 IP 的黑/白名单（支持单 IP、CIDR、通配符三种写法）；v3.3.0 起可一键阻断常见漏洞利用特征（Block common exploits）与 AI 爬虫（Block AI Crawlers）；v3.3.1 起 CAPTCHA 人机验证可挂到代理规则上。
  • 流量转发：TCP/UDP Stream Proxy（非 HTTP 协议的四层转发）。
  • 可观测与运维：内置在线率监控（Uptime Monitor，支持每个规则独立健康检查 URI）、流量统计与地理分布、日志查看与轮转配置、Web-SSH 终端。
  • 组网与工具集：mDNS 局域网扫描、Wake-On-Lan 网络唤醒、CIDR 转换器、IP/端口扫描器、调试用转发代理；对 ZeroTier 虚拟网络提供管理入口（Global Area Network）。
  • 认证扩展（社区贡献）：Forward-Auth 对接（Authelia、Authentik 等）、OAuth2、reCAPTCHA；v3.3.2 起内置 Zoraxy Auth 单点登录（SSO）。
  • 其他：单管理员管理模型、外部权限管理系统对接、SMTP 密码重置、暗色主题。

从 CHANGELOG 的迭代重点看，v3.3.x 系列集中在认证（SSO、CAPTCHA、Forward-Auth 修正）、证书（lego 版本跟进、DNS Challenge 修复）与代理细节（超时、重定向、虚拟目录修复）三个方向，属于功能稳定后的打磨期（来源：仓库 CHANGELOG.md，查询日期 2026-10-20）。

五、快速开始（最小可用示例）

按官方 README 的 Getting Started 一节（查询日期 2026-10-20），最快路径是直接下载官方 release 二进制运行。以下命令均出自官方 README/Releases 页面：

# 下载 Linux amd64 官方二进制（官方 README 的 Releases 下载链接）
wget -O zoraxy "https://github.com/tobychui/zoraxy/releases/latest/download/zoraxy_linux_amd64"
chmod +x zoraxy

# 以默认参数启动（官方 README 的 Linux 启动命令）
sudo ./zoraxy -port=:8000

启动后用浏览器访问 http://<服务器IP>:8000，首次访问登录页会自动进入 Account Setup 模式，创建管理员账号后即进入控制台，在「HTTP Proxy」页添加一条「域名 → 上游地址」的代理规则即可完成最小反代链路。官方二进制为静态编译，无任何运行时依赖，放进任意主流 Linux 发行版即可运行。

⚠️ 注意：直接前台运行适合快速体验，生产环境应使用 systemd 托管并配置数据目录持久化——完整的 0→1 安装流程（含 systemd 服务单元、目录规划、验证与排障）见《Ubuntu 22.04 安装 Zoraxy 指南》。

Zoraxy 官方同时提供 Docker 镜像形态（README 的 Docker 一节指向仓库 docker/ 目录），本文后续篇目按「真实服务器二进制 + systemd」形态撰写；了解官方全部发行形态属于选型常识，本文如实说明。

版本确认命令与输出（官方二进制自带）：

zoraxy -version

Zoraxy - Version 3.3.4

即本文撰写时官方最新稳定版 v3.3.4 的实际版本号（发布信息来源：GitHub Releases，查询日期 2026-10-20）。

六、适用场景与限制

适用场景（结合官方定位与功能清单归纳）：

  • Homelab / 自托管多服务统一入口：一台服务器上跑了多个 Web 服务（相册、NAS 面板、下载器、家庭助手），需要统一域名 + 各自子域名 + 自动 HTTPS，Zoraxy 的 Web 界面操作路径最短。
  • 中小团队内网服务的对外发布：需要 Basic Auth、IP/国家黑白名单、CAPTCHA 等轻量访问控制，而不想引入完整的 API 网关。
  • 非 HTTP 服务的端口转发：游戏服、数据库、IoT 设备等 TCP/UDP 服务用 Stream Proxy 统一收敛到一台入口机。
  • 从 Nginx/NPM 迁移的轻量化替代：官方提供了实验性的 nginx 配置转换器（README「Switching from Nginx / NPM?」一节，https://zoraxy.aroz.org/nginx2zoraxy.html ）。

已知限制（来源：官方 README、仓库设计说明，查询日期 2026-10-20）：

  • 单管理员模型：官方明确定位为「Basic single-admin management mode」，只有一个管理账号体系，没有多租户、多管理员分级授权（可通过外部权限管理系统对接缓解）。
  • 无原生集群/高可用形态：单进程单体架构，配置与状态在本机数据库与文件中，官方未提供多节点配置同步或主备方案；高可用需借助外部手段（如 keepalived/VIP 或 DNS 层）。
  • 协议 AGPL-3.0：对二次开发后对外提供网络服务的行为有开源义务要求，商用二开集成前需评估合规。
  • 社区规模小于 Caddy/Traefik：迭代以作者主导 + 社区 PR，遇到边界问题的可检索资料相对少。

七、同类选型对比

选取三个最常见的同类开源方案做量化对比：Nginx Proxy Manager（带 Web 界面的 Nginx 反代管理器）、Caddy（自动 HTTPS 的现代 Web 服务器/反代）、Traefik（云原生边缘路由器）。数据溯源自各官方仓库（查询日期 2026-10-20）。

7.1 量化对比总表

维度ZoraxyNginx Proxy ManagerCaddyTraefik
技术栈/形态Go 单二进制，Web UI 内嵌Node.js + Nginx，容器化部署为主Go 单二进制Go 单二进制
开源协议AGPL-3.0GPL-3.0Apache-2.0MIT
管理界面内置全功能控制台（规则/证书/统计/工具）内置 Web 界面（规则/证书/ACL）无官方 UI（第三方项目补足）有 Dashboard（偏状态观测，规则主要靠配置文件/标签）
自动 HTTPS内置 ACME + DNS Challenge，界面管理内置 ACME，界面管理语言级原生 ACME（申请/续期零配置）ACME + Ingress/标签声明式管理
配置载体Web 界面 + 本地 JSON/内嵌 KV 库Web 界面 + 数据库（下发 Nginx 配置）Caddyfile / JSON API标签/文件/K8s CRD，声明式
TCP/UDP 四层转发内置 Stream Proxy（界面管理）依赖底层 Nginx stream 模块手工配支持（layer4 插件/配置）原生支持（entryPoint/Router）
认证生态Basic Auth、SSO、Forward-Auth、CAPTCHABasic Auth、访问控制列表第三方中间件/插件中间件体系（forwardAuth 等）
社区活跃度（GitHub Stars）
典型部署形态裸机二进制/systemd/容器皆可以 Docker/Compose 为主二进制/系统包/容器皆可二进制/容器/Kubernetes

表格解读：星数为查询日期 2026-10-20 的 shields.io 动态徽章（实时反映仓库数据，未硬编码数字）。关键差异在于管理界面与配置载体的取舍——Zoraxy 与 NPM 走「界面点选」路线，Caddy 与 Traefik 走「声明式配置」路线；Zoraxy 相比 NPM 的优势是单二进制无容器依赖且内置统计/监控/工具集，相比 Caddy/Traefik 的优势是零配置文件门槛，劣势是自动化集成（IaC/CI 里声明式下发）能力弱。

7.2 版本节奏对比（Zoraxy 实查数据）

Zoraxy 近五个稳定版发布时间（来源：仓库 CHANGELOG.md 与 Releases，查询日期 2026-10-20）：

版本发布日期
v3.3.42026-08-22
v3.3.32026-06-09
v3.3.22026-03-21
v3.3.12026-01-28
v3.3.02025-12-06

即稳定版约 2~3 个月一版，介于 NPM（更新较慢）与 Caddy/Traefik（持续小步发布）之间，迭代节奏健康。

7.3 兼容矩阵（Zoraxy 官方发布件，查询日期 2026-10-20）

官方 v3.3.4 Release 附件覆盖以下平台：linux/386、linux/amd64、linux/arm、linux/arm64、linux/mipsle、linux/riscv64、windows/amd64、darwin/amd64、freebsd/amd64，另有源码构建（Makefile 支持 linux/386~riscv64、windows、darwin、freebsd 共 9 个目标）。树莓派 4 及以上选 arm64，旧款树莓派选 arm 版（README Raspberry Pi 一节）。

7.4 选型建议

  • 要「点界面就能用」、机器上不想跑容器 → Zoraxy：单二进制 + 全功能界面 + 内置监控/工具，Homelab 与中小团队自托管的最短路径。
  • 已经在用 Docker/Compose 且只管 Web 站点 → Nginx Proxy Manager：生态熟悉、教程多；注意它是容器形态为主，且底层是传统 Nginx。
  • 喜欢声明式配置、追求极致简洁的自动 HTTPS → Caddy：Caddyfile 几行顶几十行 Nginx 配置；没有官方 UI 是主要取舍。
  • Kubernetes/多集群云原生入口 → Traefik：Ingress/CRD 原生集成，中间件体系完整；非 K8s 场景用它反而是杀鸡用牛刀。
  • 一句话结论：Zoraxy 的差异化 = Web 界面体验 + 单二进制零依赖 + 边缘工具全家桶；如果你的入口网关需要被基础设施即代码管理，选 Caddy/Traefik，如果需要被人点点鼠标管理，Zoraxy 与 NPM 二选一（前者轻、后者生态大）。

八、参考链接