Zoraxy 3.3.4 常用 CLI 命令详解

目标：整理 Zoraxy v3.3.4 日常运维的全部命令行入口——主程序命令（版本/帮助/账号重置/GeoIP 更新）、systemd 服务管理、journalctl 日志检索、配置备份恢复与版本升级，每条命令都附本环境实测回显，拿来即可执行。

一、环境信息

项目	内容
操作系统	Ubuntu 22.04.5 LTS（x86_64），systemd 249
Zoraxy 版本	v3.3.4（官方最新稳定版，查询日期 2026-10-20）
安装形态	官方二进制 `/usr/bin/zoraxy` + systemd 服务 `zoraxy.service`（安装过程见《Ubuntu 22.04 安装 Zoraxy 指南》）
数据目录	`/opt/zoraxy/`（conf/log/tmp/www/plugins/sys.db/sys.uuid）
命令环境	root shell；普通用户请自行加 `sudo`

二、工具概览

Zoraxy 没有传统的子命令体系，命令面由三层组成，日常运维按需取用：

层	命令	用途
主程序	`zoraxy -version` / `-help` / `-reset_ac` / `-update_geoip`	版本查询、参数清单、账号重置、GeoIP 更新（后两者为「执行完即退出」型维护命令）
主程序启动参数	`zoraxy -port/-conf/-db/...`（共 36 个）	定义服务怎么跑，统一写进 systemd 单元（参数含义见《Zoraxy 3.3.4 配置参数详解》）
systemd/journalctl	`systemctl start	stop

💡 说明：-reset_ac、-update_geoip、-version 是 Zoraxy 仅有的三个「带动作、会退出」的参数；其余 33 个都是「设置后常驻运行」的启动参数。日常改配置不需要反复重启服务——代理规则、证书、黑白名单等都在管理界面改（界面操作实时生效）。

三、前置条件

已按《Ubuntu 22.04 安装 Zoraxy 指南》完成安装，服务处于 systemd 托管状态：

systemctl is-active zoraxy && systemctl is-enabled zoraxy

active
enabled

二进制在 /usr/bin/zoraxy（命令可在任意目录直接调用）：

which zoraxy

/usr/bin/zoraxy

四、zoraxy 主程序命令详解

4.1 查看版本

升级前后必用，确认当前二进制版本：

zoraxy -version

Zoraxy - Version 3.3.4

4.2 查看帮助（参数全清单）

zoraxy --help

Usage of zoraxy:
  -acmekeymode string
        File mode for ACME private key files (octal) (default "0600")
  -acmepublicmode string
        File mode for ACME certificate and metadata files (octal) (default "0644")
  -acmetestmode
        Run ACME in test/staging mode
  -autorenew int
        ACME auto TLS/SSL certificate renew check interval (seconds) (default 86400)
  -cfgupgrade
        Enable auto config upgrade if breaking change is detected (default true)
  -conf string
        Configuration folder path (default "./conf")
  -db string
        Database backend to use (leveldb, boltdb, auto) Note that fsdb will be used on unsupported platforms like RISCV (default "auto")
  -dbpath string
        Database path (default "./sys.db")
  -default_inbound_enabled
        If web server is enabled by default (default true)
  -default_inbound_port int
        Default web server listening port (default 443)
  -dev
        Use external web folder for UI development and enable verbose logging
  -disablehttp2
        Disable HTTP/2 on the TLS listener and serve HTTP/1.1 only
  -docker
        Run Zoraxy in docker compatibility mode
  -earlyrenew int
        Number of days to early renew a soon expiring certificate (days) (default 30)
  -enablelog
        Enable system wide logging, set to false for writing log to STDOUT only (default true)
  -fastgeoip
        Enable high speed geoip lookup, disable this if you are using a very small memory footprint device (default true)
  -h2_conn_buffer int
        HTTP/2 max upload buffer per connection in bytes, min 65536 (0 = Go default)
  -h2_max_concurrent_streams uint
        HTTP/2 max concurrent streams per connection (0 = Go default)
  -h2_stream_buffer int
        HTTP/2 max upload buffer per stream in bytes, min 65536 (0 = Go default)
  -idletimeout int
        Proxy server idle keep-alive connection timeout in seconds (0 = disabled) (default 300)
  -log string
        Log folder path (default "./log")
  -mdns
        Enable mDNS scanner and transponder (default true)
  -mdnsname string
        mDNS name, leave empty to use default (zoraxy_{node-uuid}.local)
  -noauth
        Disable authentication for management interface
  -plugin string
        Plugin folder path (default "./plugins")
  -port string
        Management web interface listening port (default ":8000")
  -readheadertimeout int
        Proxy server read header timeout in seconds (0 = disabled) (default 30)
  -reset_ac
        Reset admin account username and password to default and exit
  -sshlb
        Allow loopback web ssh connection (DANGER)
  -stats_max_entries int
        Soft-cap per-dimension statistics maps at N entries; when exceeded the entries with the lowest request counts are dropped first (0 = unbounded; recommended value when enabled: 20000)
  -tmp string
        Temporary folder path (default "./tmp")
  -update_geoip
        Download the latest GeoIP data and exit
  -uuid string
        sys.uuid file path (default "./sys.uuid")
  -version
        Show version of this server
  -webroot string
        Static web server root folder. Only allow change in start paramters (default "./www")
  -writetimeout int
        Proxy server write timeout in seconds (0 = disabled, recommended for long-running requests)

💡 说明：每个参数的类型与默认值都直接印在帮助里（int/string/bool 与 (default ...)）。各参数的语义、调优建议与生产取舍逐项拆解见《Zoraxy 3.3.4 配置参数详解》，此处不重复。

4.3 重置管理员账号（-reset_ac）

忘记管理员密码或需要重新初始化账号时使用。执行即清空全部用户并退出程序（不启动服务），随后重启服务回到「首次建号」状态：

systemctl stop zoraxy
zoraxy -reset_ac -conf /opt/zoraxy/conf -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.

systemctl start zoraxy

重启后访问 http://<服务器IP>:8000 会重新进入 Account Setup 建号页（实测用户数接口返回 0，与首启一致）：

curl -s http://localhost:8000/api/auth/userCount; echo " <- userCount"

0 <- userCount

⚠️ 注意：-reset_ac 必须在服务停止后执行——运行中执行会与正在运行的实例争抢 sys.db（BoltDB 独占锁），且重置结果可能不落盘。另外注意参数是 -dbpath（路径）而不是 -db（后端类型），写混会得到 No auth table found. Nothing to reset. 的无效重置（真实报错与对比见《Zoraxy 3.3.4 配置参数详解》FAQ Q1）。

4.4 更新 GeoIP 数据（-update_geoip）

访问统计里的「访客国家分布」依赖内置 GeoIP 数据库，该命令手动拉取最新数据并下载完即退出：

systemctl stop zoraxy
zoraxy -update_geoip -conf /opt/zoraxy/conf -dbpath /opt/zoraxy/sys.db

2026/10/20 17:13:20 Downloading IPv4 database update...
2026/10/20 17:13:25 Downloading IPv6 database update...
2026/10/20 17:13:34 GeoDB update stored at: /opt/zoraxy/conf/geodb
2026/10/20 17:13:34 Exiting...

systemctl start zoraxy

💡 说明：与 -reset_ac 相同，维护命令在停服状态执行更稳妥；更新后的数据落在 conf/geodb，重启服务后生效。

4.5 前台试运行（排障用）

排查「systemd 起不来但手动能跑」类问题时，可用前台模式直接观察输出。务必带上与单元一致的路径参数，避免在错误位置生成新配置：

zoraxy -conf /opt/zoraxy/conf -log /opt/zoraxy/log -dbpath /opt/zoraxy/sys.db

前台运行会把启动日志直接打到终端（与服务首启日志内容一致，含 Zoraxy started. Visit control panel at ... 行），Ctrl+C 结束。确认无异常后立即回到 systemd 托管：systemctl start zoraxy。

五、systemd 服务管理命令详解

5.1 启动 / 停止 / 重启 / 自启

四个日常命令（stop 与 restart 执行后无回显，用 is-active 确认状态）：

systemctl start zoraxy     # 启动
systemctl stop zoraxy      # 停止
systemctl restart zoraxy   # 重启（改完 systemd 单元或系统配置后用）
systemctl enable zoraxy    # 设开机自启

enable 成功的回显（实测）：

Created symlink /etc/systemd/system/multi-user.target.wants/zoraxy.service → /etc/systemd/system/zoraxy.service.

关闭自启用 systemctl disable zoraxy，回显（实测）：

Removed /etc/systemd/system/multi-user.target.wants/zoraxy.service.

停止后查询状态，实测 inactive 与退出码 3（非 0，可用于脚本判断）：

systemctl is-active zoraxy

inactive

5.2 状态查看（status / is-active / is-enabled）

排障第一命令 systemctl status（实测）：

systemctl status zoraxy --no-pager -l

● zoraxy.service - Zoraxy Reverse Proxy and Edge Gateway
     Loaded: loaded (/etc/systemd/system/zoraxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-20 17:35:51 UTC; 2min 39s ago
       Docs: https://zoraxy.aroz.org
   Main PID: 15749 (zoraxy)
      Tasks: 17 (limit: 94371)
     Memory: 168.7M
        CPU: 1.345s
     CGroup: /system.slice/zoraxy.service
             └─15749 /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

读法要点：Loaded 行末尾的 enabled = 自启已开；Active 行是运行状态与启动时刻；Memory 约 150~170MB 为 v3.3.4 典型常驻内存（含 GeoIP 数据，随运行时间小幅波动）；CGroup 归属 /system.slice/zoraxy.service（系统服务切片）。

5.3 修改单元后的重载流程

改过 /etc/systemd/system/zoraxy.service（如调整启动参数）后，标准三步——重载 → 重启 → 验证：

systemctl daemon-reload
systemctl restart zoraxy
systemctl is-active zoraxy

active

⚠️ 注意：漏掉 daemon-reload 是「改了参数不生效」的最常见原因——systemd 会继续按内存里的旧单元运行。

六、日志命令详解（journalctl）

systemd 托管下 Zoraxy 的日志双写：journal（journalctl -u zoraxy）与数据目录日志文件（/opt/zoraxy/log/zr_2026-10.log，按月滚动）。常用检索命令与实测输出：

看最近的实时日志（排障首选）：

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

Oct 20 17:35:52 web-gw-01 zoraxy[15749]: [2026-10-20 17:35:52.483151] [dprouter] [system:info] Starting HTTP-to-HTTPS redirector (port 80)
Oct 20 17:36:02 web-gw-01 zoraxy[15749]: [2026-10-20 17:36:02.384821] [plugin-manager] [system:error] Failed to sync plugin list from plugin store: failed to get plugin list from https://raw.githubusercontent.com/aroz-online/zoraxy-official-plugins/refs/heads/main/directories/index2.json: Get "https://raw.githubusercontent.com/aroz-online/zoraxy-official-plugins/refs/heads/main/directories/index2.json": net/http: TLS handshake timeout
Oct 20 17:36:02 web-gw-01 zoraxy[15749]: [2026-10-20 17:36:02.384867] [plugin-manager] [system:error] Failed to sync plugin list from https://raw.githubusercontent.com/aroz-online/zoraxy-official-plugins/refs/heads/main/directories/index2.json: Get "https://raw.githubusercontent.com/aroz-online/zoraxy-official-plugins/refs/heads/main/directories/index2.json": net/http: TLS handshake timeout
Oct 20 17:36:15 web-gw-01 zoraxy[15749]: [2026-10-20 17:36:15.294747] [auth] [system:info] admin logged in.
Oct 20 17:36:22 web-gw-01 zoraxy[15749]: [2026-10-20 17:36:22.181511] [internal] [system:info] mDNS Startup scan completed

按关键词过滤（参数生效值 / 登录 / 代理规则加载）：

journalctl -u zoraxy --no-pager | grep -E "logged in|routing rule loaded|database backend" | tail -3

Oct 20 17:35:52 web-gw-01 zoraxy[15749]: [2026-10-20 17:35:52.001160] [database] [system:info] Using BoltDB as the database backend
Oct 20 17:35:52 web-gw-01 zoraxy[15749]: [2026-10-20 17:35:52.182108] [proxy-config] [system:info] demo.example.com -> 127.0.0.1:3000 routing rule loaded
Oct 20 17:36:15 web-gw-01 zoraxy[15749]: [2026-10-20 17:36:15.294747] [auth] [system:info] admin logged in.

看本次启动的日志：

journalctl -u zoraxy -b --no-pager | tail -5

实时跟随（等价 tail -f）：

journalctl -u zoraxy -f

💡 说明：Zoraxy 日志行格式为 [模块名] [system:info|error] 正文，按模块 grep（如 grep "cert-renew" 看证书、grep "Access" 看访问相关）比全文翻页高效。日志行前缀是 主机名 zoraxy[PID]，多实例环境按服务名过滤即可。

七、配置备份与恢复命令

Zoraxy 的全部状态集中在 /opt/zoraxy/，备份 = 打包这个目录。两种方式：

方式一：tar 冷备份（最稳，停服执行）

systemctl stop zoraxy
cd /opt/zoraxy
tar -czf /opt/zoraxy-backup-$(date +%Y%m%d).tar.gz sys.db sys.uuid conf log
systemctl start zoraxy
ls -la /opt/zoraxy-backup-*.tar.gz

-rw-r--r-- 1 root root 4943 Oct 20 17:35 /opt/zoraxy-backup-20261020.tar.gz

校验备份内容（实测列表节选，sys.db/sys.uuid/conf/ 全部在内）：

tar -tzf /opt/zoraxy-backup-20261020.tar.gz | head -8

sys.db
sys.uuid
conf/
conf/redirect/
conf/sso/
conf/sso/zorxauth/group_policies/
conf/streamproxy/

恢复：停服 → 清空或移走 /opt/zoraxy/ → tar -xzf 解包回原位置 → chown -R zoraxy:zoraxy /opt/zoraxy → systemctl start zoraxy。

方式二：管理界面导出 zip（适合迁移到新机）

界面右上角账户菜单里有配置导出入口，接口形式（登录态下）实测：

curl -s -b cookies.txt http://localhost:8000/api/conf/export -o zoraxy-conf.zip -w "http=%{http_code} bytes=%{size_download}\n"

http=200 bytes=2528

file zoraxy-conf.zip

zoraxy-conf.zip: Zip archive data, at least v2.0 to extract, compression method=deflate

💡 说明：接口导出的 zip 是配置快照（反代规则、设置项等），不含 sys.db 里的账号与统计；整机迁移推荐方式一的全目录打包。-b cookies.txt 指向登录时保存的会话 cookie 文件（获取方式见《Zoraxy 3.3.4 配置参数详解》第八章的登录验证步骤）。

八、版本升级命令

Zoraxy 升级 = 换二进制，配置与数据不动。标准五步（本环境实测通过）：

# 1. 备份（必做，跨版本防回退）
tar -czf /opt/zoraxy-backup-$(date +%Y%m%d).tar.gz -C /opt/zoraxy sys.db sys.uuid conf

# 2. 下载新版本二进制（以官方最新 release 为准）
curl -x http://192.168.1.62:7897 -LO "https://github.com/tobychui/zoraxy/releases/download/v3.3.4/zoraxy_linux_amd64" -o /tmp/zoraxy_new

# 3. 校验（与官方 Release 页公布的 sha256 一致才继续）
sha256sum /tmp/zoraxy_new

452b9bfd3e54e24853b6ad27555b1727be0e85f356f5c8487da9d2f28497b298  /tmp/zoraxy_new

# 4. 停服 → 替换 → 启动
systemctl stop zoraxy
install -m 755 /tmp/zoraxy_new /usr/bin/zoraxy
systemctl start zoraxy

# 5. 验证版本与服务状态
zoraxy -version
systemctl is-active zoraxy

Zoraxy - Version 3.3.4
active

⚠️ 注意：若升级跨大版本（如 v3.2.x → v3.3.x），首启时 -cfgupgrade（默认开）会自动迁移配置格式；迁移失败导致服务起不来时，用第七章备份回滚再分析 journal 报错。同版本号「重装」升级（如本例 v3.3.4 → v3.3.4）是平滑无感的。

九、注意事项

维护三命令（-reset_ac/-update_geoip/-version）与常驻服务的端口与数据库互斥：前两者会在停服状态执行；-version 随时可执行（只读）。
-db 与 -dbpath 是两个参数：-db 选后端类型（leveldb/boltdb/auto），-dbpath 指路径；写混是新手高频错误（FAQ 与报错实录见《Zoraxy 3.3.4 配置参数详解》）。
改 systemd 单元必须 daemon-reload，否则参数不生效且排障方向会被带偏。
journal 与文件日志双写：systemd 环境下 journal 全量、文件按月滚动；-enablelog=false 可关掉文件侧只留 journal。
升级/迁移先备份：sys.db 是独占锁的 BoltDB，热拷贝可能拿到不一致快照，备份前 systemctl stop zoraxy 最稳。

十、常见问题（FAQ）

Q1：systemctl status 显示 status=203/EXEC，服务起不来？

systemd 找不到 ExecStart 指定的二进制（路径写错或文件缺失）。实测日志：

zoraxy.service: Failed to locate executable /usr/bin/zoraxy: No such file or directory
zoraxy.service: Failed at step EXEC spawning /usr/bin/zoraxy: No such file or directory
zoraxy.service: Main process exited, code=exited, status=203/EXEC

处理：ls -la /usr/bin/zoraxy 确认存在且可执行，缺失则重装（install -m 755 <下载的二进制> /usr/bin/zoraxy），再 systemctl restart zoraxy。

Q2：zoraxy -reset_ac 提示 No auth table found. Nothing to reset.？

参数写错（-db 传了路径）或没带 -dbpath 指向正确的库文件，导致它打开了一个空库。正确姿势见 4.3 节；对比实录见《Zoraxy 3.3.4 配置参数详解》FAQ Q1。

Q3：重启服务后管理界面 8000 打不开？

按顺序排查：systemctl is-active zoraxy（active 才继续）→ ss -ltn | grep 8000（确认监听）→ journalctl -u zoraxy -n 20（看启动是否报端口占用）。端口被占时改 -port 参数走 5.3 节流程。

Q4：journal 里出现 [plugin-manager] [system:error] Failed to sync plugin list from plugin store ... TLS handshake timeout？

插件商店同步失败（访问 GitHub 不顺畅的网络常见，实测日志见第六章示例输出中两条 plugin-manager error 行），不影响反代与证书核心功能，可忽略；确需插件商店时改善网络后重启。

十一、参考链接

官方 README（Start Parameters / Wiki 入口）：https://github.com/tobychui/zoraxy
官方 Wiki：https://github.com/tobychui/zoraxy/wiki
官方 Releases（升级包下载与 sha256 公布处）：https://github.com/tobychui/zoraxy/releases
官方站点：https://zoraxy.aroz.org
站内配套阅读：《Zoraxy 介绍与选型指南》、《Ubuntu 22.04 安装 Zoraxy 指南》、《Zoraxy 3.3.4 配置参数详解》