Firezone 1.6.3 常用 CLI 命令详解

Firezone 1.6.3 常用 CLI 命令详解：firezone-gateway 命令树、firezone-client-headless 子命令、systemd 服务管理与版本命令全量实测，含无效令牌等真实排障回显。

FirezoneVPN零信任安全2026/10/20

Firezone 1.6.3 常用 CLI 命令详解

目标：一册收齐 Firezone 数据面组件的日常命令——Gateway 主命令 firezone-gateway 的完整命令树与旗标、Headless 客户端 firezone-client-headless 子命令、systemd 托管命令与包版本命令，全部命令输入与回显逐行实测。实测环境 Ubuntu 22.04.5 LTS，实测日期 2026-10-20。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Gateway：firezone-gateway 1.6.3（官方 APT 仓库安装，二进制 /usr/bin/firezone-gateway）
  • Headless Client：firezone-client-headless 1.5.14（GitHub Releases 独立二进制，装于 /usr/local/bin）
  • 服务单元：firezone-gateway.service（官方包注册）
  • 安装与配置详见 《Ubuntu 22.04 安装 Firezone 指南》、《Firezone 1.6.3 配置参数详解》

二、工具概览

Firezone 1.x 是云控制架构，自托管侧的日常运维面由三组命令构成：

命令/工具归属用途
firezone-gatewayGateway 主命令令牌写入、服务启停注册、前台运行（含全部运行参数）
firezone-client-headlessHeadless 客户端主命令浏览器式登录/登出、证书查看、前台运行
systemctl / journalctlsystemd服务启停、状态、日志（Gateway 的日志统一走 journald）
apt / dpkg包管理Gateway 的安装、升级、降级、锁版本、卸载

命令定位（实测）：

which firezone-gateway firezone-client-headless

实测回显（两台主机分别执行后合并展示；Gateway 机）：

/usr/bin/firezone-gateway

（Headless 客户端机）

/usr/local/bin/firezone-client-headless

三、前置条件

  1. 已安装 firezone-gateway 1.6.3（APT 或独立二进制均可）并完成 firezone-gateway authenticate 写入令牌。
  2. systemd 可用（服务托管命令需要）；Ubuntu 22.04 服务器默认满足。
  3. 终端可交互：firezone-gateway authenticate 从 TTY 读入令牌（见 FAQ Q1）。
  4. 版本自检命令：
firezone-gateway --version

实测回显：

firezone-gateway 1.6.3

四、firezone-gateway 命令详解

4.1 命令总览（--help 全文实测）

firezone-gateway --help

实测回显（完整）：

Gateway for the Firezone zero-trust access product.

Usage: firezone-gateway [OPTIONS] [TOKEN] [COMMAND]

Commands:
  authenticate     Securely store the Gateway's token on disk
  enable-service   Enable the Gateway's systemd service
  disable-service  Disable the Gateway's systemd service
  help             Print this message or the help of the given subcommand(s)

Arguments:
  [TOKEN]
          Token generated by the portal to authorize websocket connection

          [env: FIREZONE_TOKEN=]

Options:
      --no-telemetry
          Disable sentry.io crash-reporting agent

          [env: FIREZONE_NO_TELEMETRY=]

      --no-check
          Don't preemtively check permissions

  -i, --firezone-id <FIREZONE_ID>
          Identifier generated by the portal to identify and display the device

          [env: FIREZONE_ID=]

      --log-format <LOG_FORMAT>
          [env: FIREZONE_LOG_FORMAT=]
          [default: human]
          [possible values: json, human]

      --flow-logs
          Track flow logs even when the portal has them disabled, and emit them to the log output by adding the `flow_logs=trace` log directive.

          Flows tracked only because of this flag stay on the log output; spooling and uploading them is always controlled by the portal.

          [env: FIREZONE_FLOW_LOGS=]

      --no-inc-buf
          Do not try to increase the `core.rmem_max` and `core.wmem_max` kernel parameters

          [env: FIREZONE_NO_INC_BUF=]

  -m, --max-partition-time <MAX_PARTITION_TIME>
          Maximum length of time to retry connecting to the portal if we're having internet issues or it's down. Accepts human times. e.g. "5m" or "1h" or "30d"

          [env: FIREZONE_MAX_PARTITION_TIME=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

💡 说明：四个子命令（authenticate / enable-service / disable-service / help）+ 一组运行旗标。旗标与环境变量一一对应（[env: ...] 标注），持久化配置写环境变量，临时排障用旗标。前台运行直接 sudo firezone-gateway（可带 [TOKEN] 位置参数，经环境变量 FIREZONE_TOKEN 注入更安全）。

4.2 authenticate——写入门户令牌

sudo firezone-gateway authenticate

实测回显（粘贴 token 回车后）：

Paste the token from the portal's deploy page:
Successfully installed token
Tip: You can now start the Gateway with `firezone-gateway enable-service`

令牌落盘（实测 ls -la /etc/firezone/gateway-token）：

-r-------- 1 root root 41 Oct 20 11:06 /etc/firezone/gateway-token

子命令参数（firezone-gateway authenticate --help 实测全文）：

Securely store the Gateway's token on disk

Usage: firezone-gateway authenticate [OPTIONS]

Options:
      --replace  If an existing token is found, replace it
  -h, --help     Print help

覆盖旧令牌（实测）：

sudo firezone-gateway authenticate --replace

Successfully installed token
Tip: You can now start the Gateway with `firezone-gateway enable-service`

不带 --replace 时重复写入被拒（实测）：

Error: Found existing token at /etc/firezone/gateway-token, use --replace to overwrite

4.3 enable-service / disable-service——注册与停用服务

sudo firezone-gateway enable-service

实测回显（enable + start 一次完成）：

Successfully enabled `firezone-gateway.service`

随后 systemctl status firezone-gateway 可见 Active: active (running)（令牌有效时）。停用：

sudo firezone-gateway disable-service

实测回显：

Successfully disabled `firezone-gateway.service`

💡 说明：这两个子命令是官方封装的 systemctl enable --now / disable --now，等效手工 systemd 命令见第六节。

4.4 前台运行与运行旗标

排障时前台运行最能看清问题（实测）：

export FIREZONE_TOKEN=$(sudo cat /etc/firezone/gateway-token)   # 注入方式：从令牌文件读入；也可直接粘贴门户令牌
sudo env FIREZONE_TOKEN="$FIREZONE_TOKEN" firezone-gateway

实测回显（启动段，Ctrl+C 结束）：

2026-10-20T11:07:42.485Z  INFO firezone_gateway: `gateway` started logging arch="x86_64" os="linux" version="1.6.3" system_uptime=69621s
2026-10-20T11:07:42.486Z  INFO telemetry: Started telemetry environment=production
2026-10-20T11:07:42.488Z  INFO flow_log_upload: Flow-log uploader started

常用旗标组合（均取自 4.1 帮助原文，值为真实默认）：

旗标默认值说明
--log-format jsonhumanJSON 日志，接采集器用
-m, --max-partition-time 1h未显式设置断连最大重试，接受 5m/1h/30d
--no-telemetry关禁用 Sentry 上报
--flow-logs关本地跟踪流日志（flow_logs=trace）
--no-inc-buf关不调大 core.rmem_max/core.wmem_max
--no-check关跳过权限预检

非法时长值直接被参数解析拒绝（实测）：

error: invalid value 'abc' for '--max-partition-time <MAX_PARTITION_TIME>': expected number at 0

For more information, try '--help'.

五、firezone-client-headless 命令详解

5.1 命令总览（--help 全文实测）

firezone-client-headless --help

实测回显（完整）：

Command-line args for the headless Client

Usage: firezone-client-headless [OPTIONS] [COMMAND]

Commands:
  sign-in   Sign in via browser-based authentication
  sign-out  Sign out by removing the stored token
  x509      Show the X.509 client certificate the platform keystore holds
  help      Print this message or the help of the given subcommand(s)

Options:
      --dns-control <DNS_CONTROL>
          Possible values:
          - disabled:         Explicitly disable DNS control
          - etc-resolv-conf:  Back up `/etc/resolv.conf` and replace it with our own
          - systemd-resolved: Cooperate with `systemd-resolved`

          [env: FIREZONE_DNS_CONTROL=]
          [default: systemd-resolved]

  -l, --log-dir <LOG_DIR>
          File logging directory. Should be a path that's writeable by the current user

          [env: LOG_DIR=]

  -m, --max-partition-time <MAX_PARTITION_TIME>
          Maximum length of time to retry connecting to the portal if we're having internet issues or it's down. Accepts human times. e.g. "5m" or "1h" or "30d"

          [env: MAX_PARTITION_TIME=]

      --firezone-name <FIREZONE_NAME>
          Friendly name for this client to display in the UI

          [env: FIREZONE_NAME=]

  -i, --firezone-id <FIREZONE_ID>
          Identifier used by the portal to identify and display the device

          [env: FIREZONE_ID=]

      --activate-internet-resource
          Activate the Internet Resource.

          To actually use the Internet Resource, the user must also have a policy granting access to the Internet Resource.

          [env: FIREZONE_ACTIVATE_INTERNET_RESOURCE=]

      --no-telemetry
          Disable sentry.io crash-reporting agent

          [env: FIREZONE_NO_TELEMETRY=]

      --token-path <TOKEN_PATH>
          A filesystem path where the token can be found

          [env: FIREZONE_TOKEN_PATH=]
          [default: /etc/dev.firezone.client/token]

      --flow-logs
          Track flow logs even when the portal has them disabled, and emit them to the log output by adding the `flow_logs=trace` log directive.

          Flows tracked only because of this flag stay on the log output; spooling and uploading them is always controlled by the portal.

          [env: FIREZONE_FLOW_LOGS=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

💡 说明：与 Gateway 相比，客户端多了 DNS 接管、令牌路径、设备命名等参数；x509 子命令用于设备证书（PKCS#11）场景。版本号实测：firezone-client-headless --version → firezone-headless-client 1.5.14。

5.2 sign-in / sign-out——浏览器式登录与登出

sign-in --help 实测全文：

Sign in via browser-based authentication

Usage: firezone-client-headless sign-in [OPTIONS]

Options:
      --auth-base-url <AUTH_BASE_URL>  Auth base URL [env: FIREZONE_AUTH_BASE_URL=] [default: https://app.firezone.dev]
      --account-slug <ACCOUNT_SLUG>    Account slug [env: FIREZONE_ACCOUNT_SLUG=]
  -h, --help                           Print help

用法（官方文档原文流程）：

sudo firezone-client-headless sign-in --account-slug <门户账号slug>
# 终端打印一个 URL，浏览器打开完成登录后，把门户显示的 token 粘贴回终端
# 令牌落盘 /etc/dev.firezone.client/token，此后运行主命令无需再传 FIREZONE_TOKEN

sign-out --help 实测全文：

Sign out by removing the stored token

Usage: firezone-client-headless sign-out [OPTIONS]

Options:
  -f, --force  Skip confirmation prompt
  -h, --help   Print help

无令牌时登出（实测）：

firezone-client-headless sign-out -f

No token file found at: /etc/dev.firezone.client/token

5.3 x509——查看设备证书

firezone-client-headless x509

实测回显（未配置 PKCS#11 的典型主机）：

No PKCS#11 module is registered, or p11-kit is not installed, so no X.509 client identity certificate can be found. Firezone reads certificates through PKCS#11 modules registered with p11-kit. See https://www.firezone.dev/kb/install/linux for what to install.

💡 说明：该命令配合设备可信（Device Trust）PKI 使用；普通账号密码/OIDC 登录场景用不到它。

5.4 前台运行与日志目录

sudo firezone-client-headless --dns-control disabled

实测回显（无效令牌演示，进程在门户拒绝后退出）：

2026-10-20T11:08:39.825Z  INFO firezone_headless_client: `headless-client` started logging arch="x86_64" os="linux" version="1.5.14" system_uptime=69678s
2026-10-20T11:08:40.853Z  INFO tunnel_proto::client: Initiating graceful shutdown
Firezone disconnected: Connection to portal failed: Your Firezone sign-in has expired. Sign in again to reconnect.

落文件日志（实测）：

sudo mkdir -p /var/log/firezone-client
sudo env LOG_DIR=/var/log/firezone-client firezone-client-headless --dns-control disabled
ls -la /var/log/firezone-client/

-rw-r----- 1 root root  740 Oct 20 11:09 firezone-headless-client.2026-10-20-11-08-59.log
lrwxrwxrwx 1 root root   73 Oct 20 11:08 firezone-headless-client.latest -> /var/log/firezone-client/firezone-headless-client.2026-10-20-11-08-59.log

六、systemd 服务管理命令

Gateway 与（自建单元的）Headless Client 都由 systemd 托管，日常命令逐条实测：

systemctl status firezone-gateway --no-pager

实测回显（运行中）：

● firezone-gateway.service - Firezone Gateway
     Loaded: loaded (/lib/systemd/system/firezone-gateway.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-20 11:06:18 UTC; 6ms ago
       Docs: https://www.firezone.dev/kb
    Process: 3206 ExecStartPre=/usr/bin/firezone-gateway-init (code=exited, status=0/SUCCESS)
   Main PID: 3228 ((-gateway))
      Tasks: 1 (limit: 5753)
     Memory: 424.0K

令牌缺失/无效时的典型状态（实测）：

     Active: activating (auto-restart) (Result: exit-code) since Tue 2026-10-20 11:07:22 UTC; 4s ago
Result=exit-code
ExecMainStatus=1

启停与开机自启（等效 4.3 子命令，逐条执行）：

sudo systemctl start firezone-gateway      # 启动
sudo systemctl stop firezone-gateway       # 停止
sudo systemctl restart firezone-gateway    # 重启（改配置后必做）
systemctl is-active firezone-gateway       # 健康检查
sudo systemctl enable firezone-gateway     # 开机自启
sudo systemctl disable firezone-gateway    # 取消自启

is-active 实测回显：

active

disable 实测回显：

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

日志查看（Gateway 日志统一进 journald）：

journalctl --unit firezone-gateway --no-pager -n 10       # 最近 10 行
journalctl --unit firezone-gateway --follow               # 实时跟踪

实测回显（启动段节选）：

firezone-gateway[3252]: 2026-10-20T11:06:26.164Z  INFO firezone_gateway: `gateway` started logging arch="x86_64" os="linux" version="1.6.3" system_uptime=69544s
firezone-gateway[3252]: 2026-10-20T11:06:26.164Z  INFO telemetry: Started telemetry environment=production

单元内容与覆盖：

systemctl cat firezone-gateway     # 查看官方单元全文（含安全加固项）
sudo systemctl edit firezone-gateway   # drop-in 覆盖（如 LimitNOFILE）

重启策略要点（systemctl cat 实测摘录）：Restart=always + RestartSec=7（失败每 7 秒重试），RestartPreventExitStatus=78（门户拒绝令牌时不再自动重启）。

七、包管理与版本命令

APT 方案安装的 Gateway 用包管理命令维护版本（全部实测）：

apt-cache policy firezone-gateway       # 看候选版本与版本表
apt list 2>/dev/null | grep -i firezone # 看仓库内全部 firezone 包
dpkg -L firezone-gateway                # 看包内文件清单
dpkg -l | grep firezone                 # 看已装版本

apt-cache policy 实测回显（节选）：

firezone-gateway:
  Installed: (none)
  Candidate: 1.6.3
  Version table:
     1.6.3 500
        500 https://artifacts.firezone.dev/apt stable/main amd64 Packages
     1.6.2 500
     1.6.1 500
     1.6.0 500
     1.5.2 500
     1.4.19 500

apt list 实测回显：

firezone-client-gui/stable 1.5.19 amd64
firezone-gateway/stable 1.6.3 amd64

dpkg -L firezone-gateway 实测回显：

/usr/bin/firezone
/usr/bin/firezone-gateway
/usr/bin/firezone-gateway-init
/usr/lib/systemd/system/firezone-gateway.service
/usr/lib/sysusers.d/firezone-gateway.conf
/usr/lib/tmpfiles.d/firezone-gateway.conf
/usr/share/doc/firezone-gateway/copyright

版本切换与锁定：

sudo apt install --allow-downgrades -y firezone-gateway=1.6.2   # 降级
sudo apt-mark hold firezone-gateway                             # 锁定
sudo apt-mark unhold firezone-gateway                           # 解锁

实测回显：

dpkg: warning: downgrading firezone-gateway from 1.6.3 to 1.6.2

firezone-gateway set on hold.
Canceled hold on firezone-gateway.

卸载：

sudo apt remove --purge -y firezone-gateway
dpkg -l | grep firezone || echo "no firezone packages"
which firezone-gateway || echo "binary removed"

实测回显：

no firezone packages
binary removed

💡 说明：purge 不删除运行期生成的 /etc/firezone/gateway-env 等文件，彻底清理需 sudo rm -rf /etc/firezone。

八、注意事项

  1. 令牌是最高敏感凭据：gateway-token 保持 0400 root；泄露后回门户吊销再 authenticate --replace 换新。
  2. authenticate 必须交互终端：管道 stdin 会报 Failed to read token from stdin: No such device or address (os error 6)（实测，见 4.2）。
  3. 服务托管优先用子命令：enable-service/disable-service 是官方封装，与手工 systemctl 等效且语义清晰。
  4. 前台运行仅限排障：前台进程随会话退出；生产一律 systemd 托管。
  5. 退出码 78 不重启：见 FAQ Q3，别把它当「服务起不来」盲目重启。
  6. 客户端与网关版本解耦：两端各自升级即可，控制面按组件版本管理兼容性（官方 changelog 为准）。

九、常见问题（FAQ）

Q1：authenticate 报读不到 stdin？ 该子命令从 TTY 读令牌，不支持普通管道。实测报错：

Error: Failed to read token from stdin: No such device or address (os error 6)

处理：交互终端执行；自动化场景改写 /etc/firezone/gateway-token 文件（0400）。

Q2：服务一直 activating (auto-restart)？ Gateway 启动失败退、systemd 每 7 秒重试。先看日志定位：journalctl --unit firezone-gateway -n 20。令牌文件缺失/不可读时的实测日志：

firezone-gateway[3252]: 2026-10-20T11:06:26.164Z  INFO firezone_gateway: Failed to read `FIREZONE_TOKEN` systemd credential: Permission denied (os error 13)
systemd[1]: firezone-gateway.service: Failed with result 'exit-code'.

确认 /etc/firezone/gateway-token 存在且写入有效令牌后 sudo systemctl restart firezone-gateway。

Q3：日志出现 Failed to login to portal？ 门户拒绝令牌（无效/过期/吊销）。实测回显：

ERROR firezone_gateway: Eventloop failed: Failed to login to portal: Your Firezone sign-in has expired. Sign in again to reconnect.

该路径退出码 78，systemd 不再自动重启：回门户重新生成令牌 → sudo firezone-gateway authenticate --replace → sudo systemctl restart firezone-gateway。

Q4：客户端登录后令牌存哪、怎么删？ 默认 /etc/dev.firezone.client/token（--token-path 可改）。删除令牌用 sudo firezone-client-headless sign-out -f（实测无令牌时提示 No token file found at: /etc/dev.firezone.client/token）。

Q5：怎么确认线上跑的是哪个版本？ 三处对账：firezone-gateway --version（firezone-gateway 1.6.3）、dpkg -l | grep firezone（包版本）、启动日志 version="1.6.3" 字段（见 4.4 节实测）。

十、参考链接

  1. Gateway CLI 官方参考：https://www.firezone.dev/kb/reference/cli/gateway
  2. Headless Client CLI 官方参考：https://www.firezone.dev/kb/reference/cli/headless-linux
  3. Gateway 令牌与部署：https://www.firezone.dev/kb/deploy/tokens 、https://www.firezone.dev/kb/deploy/debian
  4. APT 仓库与 Releases：https://artifacts.firezone.dev/apt/ 、https://github.com/firezone/firezone/releases
  5. 本专栏姊妹篇：《Firezone 1.6.3 介绍与选型指南》、《Ubuntu 22.04 安装 Firezone 指南》、《Firezone 1.6.3 配置参数详解》