Zoraxy 3.3.4 配置参数详解

目标：吃透 Zoraxy v3.3.4 的两套配置体系——启动参数（36 个，含默认值）与数据目录下的配置文件（反代规则 JSON 全字段、ACME、日志、可信代理），给出生产环境的推荐配置模板与改参后的验证方法。全部默认值与文件内容在本环境（Ubuntu 22.04.5 LTS，Zoraxy v3.3.4）实测核对。

一、环境信息

项目	内容
操作系统	Ubuntu 22.04.5 LTS（x86_64），systemd 249
Zoraxy 版本	v3.3.4（官方最新稳定版，查询日期 2026-10-20；sha256 `452b9bfd…97b298`）
安装形态	官方二进制 `/usr/bin/zoraxy` + systemd 托管（安装流程见《Ubuntu 22.04 安装 Zoraxy 指南》：https://www.quzuo.net/document/Nlod2Y9oF9CG ）
数据目录	`/opt/zoraxy/`（`-conf/-log/-tmp/-webroot/-plugin/-dbpath/-uuid` 全部指向该目录）
配置获取方式	`zoraxy --help`（启动参数）、`journalctl -u zoraxy`（运行时生效值）、`/opt/zoraxy/conf/`（落盘配置）

二、前置条件

已按《Ubuntu 22.04 安装 Zoraxy 指南》完成安装并确认服务运行：

systemctl is-active zoraxy && zoraxy -version

active
Zoraxy - Version 3.3.4

能查看服务日志（参数生效验证的主要依据）：

journalctl -u zoraxy --no-pager -n 5

理解 Zoraxy 的三层配置分工（下一章展开）。

三、配置方式总览（查看与修改）

Zoraxy 的配置分三条通道，优先级与生效方式不同，改配置前先分清你要改的东西在哪一层：

通道	内容	生效方式	手改风险
① 启动参数	36 个 `zoraxy` 命令行参数（端口、路径、数据库、超时、证书节奏等）	改 systemd 单元 → `daemon-reload` → `restart`	低（系统不会覆盖单元文件）
② conf 目录 JSON	`/opt/zoraxy/conf/` 下的静态配置（ACME、日志、可信代理、反代规则）	Web 界面保存时写入并即时生效	中：反代规则文件由系统全量重写，手改会被下次界面保存覆盖
③ 内嵌数据库	`sys.db`（BoltDB）里的动态数据（账号、会话、统计、设置项）	Web 界面操作实时写入	高：禁止直接编辑，备份时整库拷贝

判断口诀：改「怎么启动」走通道①；改「代理行为」走界面（落通道②③）；改「谁在跑、跑在哪」走 systemd。查看通道①的完整清单用 zoraxy --help；查看通道②的运行时生效值用 journalctl（Zoraxy 启动时会把关键参数落成日志行，例如超时参数）：

[internal] [system:info] Proxy timeout settings loaded. Read header: 30s, Write: 0s, Idle: 300s

四、启动参数详解

4.1 参数总览（36 个，v3.3.4 实测）

以下为 zoraxy --help 的完整参数清单（实测环境逐字转录，默认值来自帮助文本与首次启动日志核对）：

参数	类型/默认值	说明
`-port`	string，`:8000`	管理 Web 界面监听端口
`-default_inbound_port`	int，`443`	反代入站默认端口
`-default_inbound_enabled`	bool，`true`	入站 Web 服务器默认开关
`-disablehttp2`	bool	关闭 TLS 监听上的 HTTP/2，仅 HTTP/1.1
`-h2_conn_buffer`	int，`0`	HTTP/2 每连接上传缓冲区字节数（最小 65536，0=Go 默认）
`-h2_stream_buffer`	int，`0`	HTTP/2 每流上传缓冲区字节数（最小 65536，0=Go 默认）
`-h2_max_concurrent_streams`	uint，`0`	HTTP/2 每连接最大并发流数（0=Go 默认）
`-readheadertimeout`	int，`30`	反代读请求头超时秒数（0=禁用）
`-writetimeout`	int，`0`	反代写超时秒数（0=禁用，长耗时请求推荐禁用）
`-idletimeout`	int，`300`	反代 keep-alive 空闲超时秒数（0=禁用）
`-conf`	string，`./conf`	配置目录路径
`-dbpath`	string，`./sys.db`	数据库文件路径
`-uuid`	string，`./sys.uuid`	节点 UUID 文件路径
`-log`	string，`./log`	日志目录路径
`-tmp`	string，`./tmp`	临时目录路径
`-webroot`	string，`./www`	内置静态 Web 服务器根目录（仅启动参数可改）
`-plugin`	string，`./plugins`	插件目录路径
`-db`	string，`auto`	数据库后端：`leveldb` / `boltdb` / `auto`（RISC-V 等不支持的平台自动用 fsdb）
`-earlyrenew`	int，`30`	证书提前续期天数
`-autorenew`	int，`86400`	证书自动续期检查间隔秒数
`-acmetestmode`	bool	ACME 走 staging 测试环境（验证 DNS Challenge 配置用，避免打爆配额）
`-acmekeymode`	string，`0600`	ACME 私钥文件权限（八进制）
`-acmepublicmode`	string，`0644`	ACME 证书与元数据文件权限（八进制）
`-fastgeoip`	bool，`true`	启用高速 GeoIP 查询；小内存设备可关
`-mdns`	bool，`true`	启用 mDNS 局域网扫描与应答
`-mdnsname`	string，空	mDNS 主机名，留空用默认 `zoraxy_{node-uuid}.local`
`-stats_max_entries`	int，`128`	统计维度条目软上限，超出按请求数最低先淘汰（0=不设限；官方建议启用时取 20000）
`-enablelog`	bool，`true`	系统级日志开关，false 时仅写 STDOUT
`-noauth`	bool	关闭管理界面鉴权（仅限受控网络调试）
`-sshlb`	bool	允许环回 Web-SSH 连接（官方标注 DANGER）
`-docker`	bool	Docker 兼容模式（容器发行形态专用参数，真实服务器无需设置）
`-dev`	bool	使用外部 web 目录做 UI 开发并开详细日志
`-cfgupgrade`	bool，`true`	检测到破坏性配置变更时自动升级配置格式
`-reset_ac`	bool	重置管理员账号并退出（命令用法见《Zoraxy 3.3.4 常用 CLI 命令详解》）
`-update_geoip`	bool	下载最新 GeoIP 数据并退出
`-version`	bool	显示版本号并退出

💡 说明：上表为 v3.3.4 --help 全量转录（36 个参数）。与 3.3.3 相比，本版新增了 HTTP/2 缓冲区三参数（-h2_conn_buffer、-h2_stream_buffer、-h2_max_concurrent_streams），高频吞吐场景可按需调大；默认 0 表示沿用 Go 标准库默认值。

4.2 核心参数逐项详解

端口三件套：-port、-default_inbound_port、-default_inbound_enabled

-port 只管管理界面（默认 :8000），不动反代入站。反代入站由 -default_inbound_port（默认 443）控制，首启日志可核对生效值：

[internal] [system:info] Inbound port not set. Using default (443)
[internal] [system:info] TLS mode enabled. Serving proxy request with TLS

-default_inbound_enabled 默认 true（首启即监听 443 入站）。端口实况核对（实测）：

netstat -ltnp | grep zoraxy

tcp6       0      0 :::443                  :::*                    LISTEN      2691/zoraxy
tcp6       0      0 :::80                   :::*                    LISTEN      2691/zoraxy
tcp6       0      0 :::5487                 :::*                    LISTEN      2691/zoraxy
tcp6       0      0 :::8000                 :::*                    LISTEN      2691/zoraxy

💡 说明：80 端口监听来自「HTTP→HTTPS 强制跳转」功能（界面默认开启），不受 -default_inbound_port 控制；5487 为内置静态 Web 服务器默认端口（源码内置常量，实测确认）。

路径七件套：-conf、-dbpath、-uuid、-log、-tmp、-webroot、-plugin

这七个参数共同决定 Zoraxy 的全部落盘位置，生产上建议统一钉到 /opt/zoraxy/ 下（本文 systemd 单元即如此，见第七章模板）。注意 -db 与 -dbpath 的语义区别：-db 是后端类型（leveldb/boltdb/auto），-dbpath 才是文件路径——两者写混是最常见的新手错误（真实报错与解法见第九章 Q1）。

超时三参数：-readheadertimeout、-writetimeout、-idletimeout

默认 30s / 0（禁用）/ 300s。官方对 -writetimeout 的注释明确写了「0 = disabled, recommended for long-running requests」——有长连接（WebSocket、大文件上传）时保持默认 0，别照搬通用反代的「全部设小」。生效值核对（首启日志实测）：

[internal] [system:info] Proxy timeout settings loaded. Read header: 30s, Write: 0s, Idle: 300s

证书四参数：-earlyrenew、-autorenew、-acmetestmode、-acmekeymode/-acmepublicmode

默认提前 30 天续期、每 86400 秒（一天）检查一次，与首启日志一致（实测）：

[cert-renew] [system:info] ACME early renew set to 30 days and check interval set to 86400 seconds

调试 DNS Challenge 时加 -acmetestmode（走 Let's Encrypt staging），配置验证通过后再去掉——避免重复申请触发放牌配额。密钥与证书文件权限默认 0600/0644，多用户共享配置目录时按需收紧。

数据库三参数：-db、-dbpath、-cfgupgrade

-db auto 在 x86-64 上实际选择 BoltDB（首启日志实测）：

[database] [system:info] Using BoltDB as the database backend

切换 -db leveldb 后重启即用 LevelDB（实测日志行变为 Using LevelDB as the database backend）。同一 -dbpath 下混用两种后端或来回切换，可能读到不兼容的旧数据文件，切换前先备份。 -cfgupgrade 默认 true，跨大版本升级时自动迁移配置格式（conf/version 文件记录当前格式版本，本环境实测值为 334）。

GeoIP 与 mDNS：-fastgeoip、-mdns、-mdnsname

-fastgeoip 默认开（访问统计里的国家分布靠它），内存紧张的树莓派级设备可关闭。-mdns 默认开，会让 Zoraxy 在局域网里广播自己的存在（同网段的另一台 Zoraxy 能在界面里互相发现）；公网服务器或不希望暴露节点信息时可 -mdns=false 关掉，-mdnsname 可自定义广播名（留空为 zoraxy_{节点UUID}.local）。

统计与安全：-stats_max_entries、-noauth、-sshlb、-enablelog

-stats_max_entries 默认 128，即每个统计维度（如按 URL、按 UA）最多记 128 条，超出按请求数最低先淘汰——大流量站点想看完整 Top 域名/URL 时调到官方建议的 20000。-noauth 关掉管理界面登录（内网调试用，暴露公网绝对禁止）；-sshlb 放开 Web-SSH 的环回连接（官方标注 DANGER，默认关）；-enablelog 关闭后日志只走 STDOUT（systemd 场景下仍会进 journal）。

4.3 修改启动参数的标准流程

以「管理端口改到 8443」为例，标准流程是：改单元 → 重载 → 重启 → 验证，任何一步缺了都不生效：

sed -i 's|-port :8000|-port :8443|' /etc/systemd/system/zoraxy.service 2>/dev/null
systemctl daemon-reload && systemctl restart zoraxy
systemctl is-active zoraxy

active

⚠️ 注意：改完单元文件必须 daemon-reload，否则 systemd 仍按旧单元运行；只 restart 不重载会让人误以为「参数不生效」。-default_inbound_port 等入站参数同样走此流程。不建议用命令行 sed 直接手拼，本环境实测时单元文件中未显式写 -port（用默认值），上例的 sed 仅作流程示意，直接编辑 /etc/systemd/system/zoraxy.service 的 ExecStart 行更稳妥。

五、数据目录与配置文件详解

5.1 目录结构总览

/opt/zoraxy/ 首启后的完整实测结构：

ls -la /opt/zoraxy/

total 60
drwxr-xr-x 8 zoraxy zoraxy  4096 Oct 20 17:26 .
drwxr-xr-x 1 root   root    4096 Oct 20 17:24 ..
drwxr-xr-x 8 zoraxy zoraxy  4096 Oct 20 17:24 conf
drwxr-xr-x 2 zoraxy zoraxy  4096 Oct 20 17:24 log
drwxr-xr-x 2 zoraxy zoraxy  4096 Oct 20 17:24 plugins
-rw------- 1 zoraxy zoraxy 32768 Oct 20 17:31 sys.db
-rwxr-xr-x 1 zoraxy zoraxy    36 Oct 20 17:24 sys.uuid
drwxr-xr-x 2 zoraxy zoraxy  4096 Oct 20 17:26 tmp
drwxr-xr-x 2 zoraxy zoraxy  4096 Oct 20 17:24 www

ls -la /opt/zoraxy/conf/

total 52
drwxr-xr-x 8 zoraxy zoraxy 4096 Oct 20 17:24 .
drwxr-xr-x 8 zoraxy zoraxy 4096 Oct 20 17:26 ..
drwxr-xr-x 2 zoraxy zoraxy 4096 Oct 20 17:24 access
-rwxr-xr-x 1 zoraxy zoraxy   94 Oct 20 17:24 acme_conf.json
drwxr-xr-x 2 zoraxy zoraxy 4096 Oct 20 17:24 certs
-rw-r--r-- 1 zoraxy zoraxy   81 Oct 20 17:24 log_conf.json
-rw-r--r-- 1 zoraxy zoraxy    2 Oct 20 17:24 plugin_groups.json
drwxr-xr-x 2 zoraxy zoraxy 4096 Oct 20 17:25 proxy
drwxr-xr-x 2 zoraxy zoraxy 4096 Oct 20 17:24 redirect
drwxr-xr-x 3 zoraxy zoraxy 4096 Oct 20 17:24 sso
drwxr-xr-x 2 zoraxy zoraxy 4096 Oct 20 17:24 streamproxy
-rwxr-xr-x 1 zoraxy zoraxy 1372 Oct 20 17:24 trusted_proxies.json
-rwxr-xr-x 1 zoraxy zoraxy    3 Oct 20 17:24 version

路径	内容与说明
`sys.db`	BoltDB 主数据库（账号/会话/统计/界面设置项），权限 `0600`，备份必含
`sys.uuid`	节点 UUID（36 字节），mDNS 与实例识别用
`conf/proxy/`	反代规则目录，每条规则一个 `<域名>.config` JSON 文件
`conf/access/`	访问控制（黑白名单）规则文件目录
`conf/certs/`	ACME 证书存储目录
`conf/redirect/`	跳转规则目录
`conf/sso/`	Zoraxy Auth 单点登录（v3.3.2+）相关文件
`conf/streamproxy/`	TCP/UDP 流量代理规则
`conf/acme_conf.json`	ACME 自动证书配置（见 5.3）
`conf/log_conf.json`	日志轮转配置（见 5.4）
`conf/trusted_proxies.json`	可信代理 CIDR 列表（见 5.5）
`conf/plugin_groups.json`	插件分组（首启为空对象 `{}`）
`conf/version`	配置格式版本号，实测值 `334`（对应 v3.3.x 配置结构）
`log/zr_2026-10.log`	系统日志文件，按月滚动命名（月份为实测样例）
`tmp/`	临时文件（实测存放了自签的 `localhost.key/localhost.pem`）
`www/`	内置静态 Web 服务器根目录（默认空）
`plugins/`	插件目录（默认空）

5.2 反代规则文件（proxy/*.config）全字段

每条反代规则以域名命名落盘，例如 demo.example.com.config（本环境实测文件，字段完整转录）：

cat /opt/zoraxy/conf/proxy/demo.example.com.config | python3 -m json.tool

{
    "ProxyType": 1,
    "RootOrMatchingDomain": "demo.example.com",
    "MatchingDomainAlias": [],
    "ActiveOrigins": [
        {
            "OriginIpOrDomain": "127.0.0.1:3000",
            "RequireTLS": false,
            "SkipCertValidations": false,
            "SkipWebSocketOriginCheck": false,
            "Weight": 1,
            "MaxConn": 0,
            "RespTimeout": 0
        }
    ],
    "InactiveOrigins": [],
    "UseStickySession": false,
    "UseActiveLoadBalance": false,
    "Disabled": false,
    "ListeningPorts": null,
    "BypassGlobalTLS": true,
    "EnableConnectSupport": false,
    "TlsOptions": {
        "DisableSNI": false,
        "DisableLegacyCertificateMatching": false,
        "EnableAutoHTTPS": false,
        "PreferredCertificate": {}
    },
    "VirtualDirectories": [],
    "DisableWebSocket": false,
    "WebsocketTimeout": 0,
    "EnableTimeoutRefreshOnActivity": false,
    "HeaderRewriteRules": {
        "UserDefinedHeaders": [],
        "RequestHostOverwrite": "",
        "HSTSMaxAge": 0,
        "EnablePermissionPolicyHeader": false,
        "PermissionPolicy": null,
        "DisableHopByHopHeaderRemoval": false,
        "DisableUserAgentHeaderRemoval": false
    },
    "EnableWebsocketCustomHeaders": false,
    "AuthenticationProvider": {
        "AuthMethod": 0,
        "BasicAuthCredentials": [],
        "BasicAuthExceptionRules": [],
        "BasicAuthGroupIDs": null,
        "ForwardAuthURL": "",
        "ForwardAuthResponseHeaders": null,
        "ForwardAuthResponseClientHeaders": null,
        "ForwardAuthRequestHeaders": null,
        "ForwardAuthRequestExcludedCookies": null,
        "ZorxAuthExceptionRules": null
    },
    "RequireRateLimit": false,
    "RateLimit": 1000,
    "RequireCaptcha": false,
    "CaptchaConfig": null,
    "DisableUptimeMonitor": false,
    "UptimeMonitorURI": ""
}

核心字段说明（其余为对应功能开关的默认值）：

字段	说明
`ProxyType`	规则类型，`1` = 子域名（host）规则
`RootOrMatchingDomain`	匹配域名（路由主键），即界面上填的「Matching Domain」
`MatchingDomainAlias`	别名域名数组，同一规则可绑多个域名
`ActiveOrigins[].OriginIpOrDomain`	上游地址（可带端口），多上游即多元素
`ActiveOrigins[].RequireTLS`	上游是否要求 HTTPS（对应界面「Require TLS」）
`ActiveOrigins[].SkipCertValidations`	跳过上游证书校验（上游自签时勾选）
`ActiveOrigins[].Weight`	负载均衡权重（默认 1）
`ActiveOrigins[].MaxConn / RespTimeout`	上游最大连接数 / 响应超时（0 = 不限制）
`UseStickySession` / `UseActiveLoadBalance`	会话粘滞 / 主动健康检查负载均衡开关
`BypassGlobalTLS`	允许该域名绕过「强制 HTTPS」直接走 80（本例实测为 true，所以 80 直连返回 200）
`EnableConnectSupport`	是否代理 CONNECT 请求（HTTP 隧道）
`VirtualDirectories`	虚拟目录规则数组（子路径分流到不同上游）
`DisableWebSocket` / `WebsocketTimeout`	WebSocket 代理开关与独立超时（0=沿用全局）
`HeaderRewriteRules.RequestHostOverwrite`	改写转发给上游的 Host 头（后端按域名路由时常用）
`HeaderRewriteRules.HSTSMaxAge`	HSTS 头最大年龄（0=不发）
`AuthenticationProvider.AuthMethod`	0=无认证；其余值对应 BasicAuth/ForwardAuth/ZorxAuth
`RequireRateLimit` / `RateLimit`	该规则级速率限制（默认 1000 req/s 阈值，默认不启用）
`RequireCaptcha` / `CaptchaConfig`	人机验证开关与配置
`DisableUptimeMonitor` / `UptimeMonitorURI`	在线率监控开关与自定义探活 URI

⚠️ 注意：规则文件由 Web 界面保存时全量重写，直接手改 JSON 后又在界面上点保存会丢掉手改内容；批量调整规则的推荐做法是逐条在界面操作，或改完文件后不要动界面里对应规则。

5.3 ACME 配置（acme_conf.json）

首启生成的默认内容（实测）：

cat /opt/zoraxy/conf/acme_conf.json

{"RenewCheckInterval":86400,"EarlyCertificateRenewal":30,"ACMEEmail":"","acmeDirectoryURL":"","InstituteMode":false,"DNS":{},"LegacyDNSProvider":"","LegacyDNSTimeout":10}

字段	说明	对应启动参数
`RenewCheckInterval`	续期检查间隔秒数（默认一天）	`-autorenew`
`EarlyCertificateRenewal`	提前续期天数（默认 30）	`-earlyrenew`
`ACMEEmail`	证书账号邮箱（界面「TLS/SSL Certificates」里填）	—
`acmeDirectoryURL`	自定义 ACME Directory URL（对接其他 CA）	—
`InstituteMode`	机构模式开关	—
`DNS`	DNS Challenge 提供商凭据（界面填入后落盘）	—
`LegacyDNSProvider` / `LegacyDNSTimeout`	旧版 DNS 提供商配置兼容字段（默认超时 10 秒）	—

5.4 日志轮转配置（log_conf.json）

cat /opt/zoraxy/conf/log_conf.json

{"AutoCleanLogFiles":false,"LogMaxFilePoolSize":100,"LogAutoScanDays":30,"LogMaxFileSizeAccumulateInMB":4096}

字段	说明
`AutoCleanLogFiles`	自动清理过期日志（默认关；首启日志显示 `Log rotation is disabled` 与此对应）
`LogMaxFilePoolSize`	日志文件池上限（最多保留 100 个文件）
`LogAutoScanDays`	自动扫描清理的过期天数（30 天）
`LogMaxFileSizeAccumulateInMB`	日志累计体积上限 4096MB

系统日志文件按月落盘在 log/ 下（实测 zr_2026-10.log）；systemd 托管时 journal 里同样有全量日志（journalctl -u zoraxy）。

5.5 可信代理列表（trusted_proxies.json）

该文件决定「谁是反代前面的可信代理」——Zoraxy 据此从 X-Forwarded-For 链里判定真实客户端 IP。首启默认预置了 Cloudflare 全部 IP 段（实测 22 条 CIDR，节选）：

[
  {
    "IP": "103.21.244.0/22",
    "Desc": "Cloudflare"
  },
  {
    "IP": "104.16.0.0/13",
    "Desc": "Cloudflare"
  },
  {
    "IP": "2606:4700::/32",
    "Desc": "Cloudflare"
  }
]

💡 说明：网站前面有 CDN/负载均衡时（哪怕不是 Cloudflare），必须把对应出口 IP 段加进该文件，否则访问统计里的客户端 IP 全是 CDN 节点 IP；反之，把不可信的 IP 加进来会让攻击者伪造真实 IP 绕过基于 IP 的黑白名单。修改走界面「Global Settings → Trusted Proxies」或直接编辑该文件。

六、Web 界面设置项与落盘位置对照

界面里改的设置项最终都落到「conf 文件或 sys.db」，下表给出常用设置组的核对方法（本环境逐项实测）：

界面设置组	关键项与默认值	落盘/核对方式
Web Server（内置静态站）	端口 5487、WebDAV 端口 5488、目录列表关、Webroot `/opt/zoraxy/www`	`GET /api/webserv/status` 实测返回 `{"ListeningPort":5487,"PortWebDav":5488,"EnableDirectoryList":false,"Webroot":"/opt/zoraxy/www"}`
TLS/SSL	强制 HTTPS 默认开、入站 443	首启日志 `Force HTTPS mode enabled`、`Inbound port not set. Using default (443)`
超时设置	读头 30s / 写 0（禁用）/ 空闲 300s	日志 `Proxy timeout settings loaded. Read header: 30s, Write: 0s, Idle: 300s`
ACME 证书	提前续期 30 天、检查间隔 86400s	日志 `ACME early renew set to 30 days and check interval set to 86400 seconds` + `acme_conf.json`
可信代理	预置 Cloudflare 22 段 CIDR	`trusted_proxies.json`
访问统计	维度条目软上限 128	`-stats_max_entries` 参数 + `sys.db`
单点登录 SSO	浏览器会话与网关会话（首启 0 条）	日志 `Loaded 0 browser sessions from database (0 expired sessions removed)`

七、生产环境推荐配置模板

以下 systemd 单元为本环境实测可用的完整模板（对应安装流程见《Ubuntu 22.04 安装 Zoraxy 指南》4.5 节）：

[Unit]
Description=Zoraxy Reverse Proxy and Edge Gateway
Documentation=https://zoraxy.aroz.org
After=network.target

[Service]
Type=simple
User=zoraxy
Group=zoraxy
WorkingDirectory=/opt/zoraxy
ExecStart=/usr/bin/zoraxy -conf /opt/zoraxy/conf -log /opt/zoraxy/log -dbpath /opt/zoraxy/sys.db -uuid /opt/zoraxy/sys.uuid -webroot /opt/zoraxy/www -plugin /opt/zoraxy/plugins -tmp /opt/zoraxy/tmp
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

参数取舍理由：

决策	理由
路径七参数全部显式指定	避免依赖 WorkingDirectory 的隐式相对路径，迁移/备份只看一个目录
`-dbpath` 与 `-uuid` 钉死	防止误在工作目录生成第二个数据库造成「配置丢失」假象
不加 `-acmetestmode`	生产签发真实证书；仅调试 DNS Challenge 时临时加
不加 `-mdns=false`（内网）	保留同网段 Zoraxy 互相发现的便利；公网服务器建议关闭
不加 `-fastgeoip=false`	除非内存 <512MB 的小设备
`Restart=on-failure` + `RestartSec=5`	崩溃自愈且避免快速重启风暴
`LimitNOFILE=65535`	反代长连接与证书文件句柄余量

再叠三条运行建议：其一，证书申请前先把 DNS 指到服务器并放行 80/443；其二，暴露公网前在界面里改掉默认 8000 管理端口或用防火墙限制管理界面来源；其三，/opt/zoraxy/ 整目录纳入每日备份（含 sys.db，建议停服务后冷备或用界面自带备份导出）。

八、参数验证方法

改完任何参数，用三层证据链验证生效：

启动层——journalctl 里的参数落载行（每类参数启动时都会打印生效值）：

journalctl -u zoraxy --no-pager | grep -E "timeout settings|Inbound port|early renew|database backend"

[database] [system:info] Using BoltDB as the database backend
[cert-renew] [system:info] ACME early renew set to 30 days and check interval set to 86400 seconds
[internal] [system:info] Inbound port not set. Using default (443)
[internal] [system:info] Proxy timeout settings loaded. Read header: 30s, Write: 0s, Idle: 300s

网络层——监听端口与接口探活（实测）：

netstat -ltnp | grep zoraxy
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8000/login.html

tcp6       0      0 :::443                  :::*                    LISTEN      2691/zoraxy
tcp6       0      0 :::80                   :::*                    LISTEN      2691/zoraxy
tcp6       0      0 :::5487                 :::*                    LISTEN      2691/zoraxy
tcp6       0      0 :::8000                 :::*                    LISTEN      2691/zoraxy
200

数据层——conf 文件时间戳与内容（界面保存后 mtime 应刷新）：

ls -la /opt/zoraxy/conf/proxy/

total 12
drwxr-xr-x 2 zoraxy zoraxy 4096 Oct 20 17:25 .
drwxr-xr-x 8 zoraxy zoraxy 4096 Oct 20 17:24 ..
-rwxr-xr-x 1 zoraxy zoraxy 1921 Oct 20 17:25 demo.example.com.config

九、常见问题（FAQ）

Q1：zoraxy -reset_ac 提示 Unknown database backend，账号没被重置？

-db 与 -dbpath 语义混淆——-db 是后端类型，路径参数是 -dbpath。本环境实测错误写法与回显：

Resetting admin account...
Unknown database backend: /opt/zoraxy/sys.db
Using auto detected backend
No auth table found. Nothing to reset.

把路径参数改为 -dbpath /opt/zoraxy/sys.db 后正确执行：

Resetting admin account...
Successfully reset admin account. All users have been removed from the system.
Please restart and create a new admin account.

Q2：手改了 conf/proxy/*.config，为什么改动有时又消失了？

规则文件是 Web 界面的落盘产物：你在界面里对任何规则点保存时，系统会全量重写对应 JSON。手改生效的正确姿势：改文件 → 重启服务（或不动界面里那条规则）；批量维护建议走界面操作。

Q3：改了 systemd 单元里的参数，重启后没生效？

漏了 daemon-reload——systemd 缓存了旧单元。顺序必须是：改文件 → systemctl daemon-reload → systemctl restart zoraxy，再按第八章方法验证。

Q4：内存占用偏高，哪个参数可以减负？

实测 v3.3.4 启动后常驻内存约 150MB（systemctl status 的 Memory 字段），大头是 GeoIP 数据与 HTTP/2 组件。内存紧张设备依次尝试：-fastgeoip=false（关闭高速 GeoIP，统计的国家维度变粗）、-stats_max_entries=64（压缩统计内存）、仍不够再 -disablehttp2（极端兼容场景才用）。

Q5：conf/version 里的 334 是什么？

配置格式版本号（33x 对应 v3.3.x 的配置结构）。升级 Zoraxy 后首启时，-cfgupgrade（默认开）会按需迁移旧格式；跨大版本升级前先备份 /opt/zoraxy/ 整目录。

十、参考链接

官方 README（Start Parameters 一节）：https://github.com/tobychui/zoraxy
官方 Wiki：https://github.com/tobychui/zoraxy/wiki
官方站点：https://zoraxy.aroz.org
站内配套阅读：《Zoraxy 介绍与选型指南》、《Ubuntu 22.04 安装 Zoraxy 指南》