Firezone 1.6.3 配置参数详解

目标：把 Firezone 1.6.3 Gateway 与 1.5.14 Headless Client 的全部可配置项（配置文件、环境变量、命令行旗标、systemd 覆盖、内核前置）讲清并逐项实测。本文所有命令与回显均已在 Ubuntu 22.04.5 LTS 环境实测通过，实测日期 2026-10-20。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Gateway：firezone-gateway 1.6.3（官方 APT 仓库安装），主机名 gw01
• Headless Client：firezone-client-headless 1.5.14（GitHub Releases 二进制，装于 /usr/local/bin），主机名 client01
• 配置路径：/etc/firezone/（Gateway）、/etc/dev.firezone.client/（Headless Client）
• 服务单元：/lib/systemd/system/firezone-gateway.service（官方包注册）
• 安装过程与验证见 《Ubuntu 22.04 安装 Firezone 指南》；命令行用法见 《Firezone 1.6.3 常用 CLI 命令详解》

二、前置条件

1. 已按安装指南完成 firezone-gateway 安装（或独立二进制 + 自建单元）。
2. 已在管理门户生成 Gateway 令牌并完成 sudo firezone-gateway authenticate（或手工写入 /etc/firezone/gateway-token）。
3. root/sudo 权限：改 /etc/firezone/ 与 systemctl edit 均需特权。
4. Headless Client 参数演示使用 firezone-client-headless 二进制（无桌面环境场景）。

确认组件版本（实测）：

firezone-gateway --version
firezone-client-headless --version

实测回显：

firezone-gateway 1.6.3

firezone-headless-client 1.5.14

三、参数查看与修改方式

Firezone 1.x 的配置入口有三层，按生效优先级从高到低：

1. 命令行旗标（如 --log-format json）：随进程启动传入，优先级最高，适合临时排障。
2. 环境变量（如 FIREZONE_LOG_FORMAT=json）：与旗标一一对应（官方帮助里每个旗标都标注了 [env: XXX=]），由 EnvironmentFile 注入，是持久化配置的推荐位置。
3. systemd 单元默认值：写在 /lib/systemd/system/firezone-gateway.service，不要直接改，用 systemctl edit 覆盖。

查看方法（实测）：

firezone-gateway --help            # 看全部旗标与对应环境变量
systemctl cat firezone-gateway     # 看官方单元的默认配置

修改方法分组件：

# Gateway：把环境变量写进 gateway-env，重启服务生效
echo 'FIREZONE_LOG_FORMAT=json' | sudo tee -a /etc/firezone/gateway-env
sudo systemctl restart firezone-gateway

# 临时验证：前台运行 + 环境变量（Ctrl+C 退出）
sudo FIREZONE_LOG_FORMAT=json firezone-gateway

四、参数总览

4.1 Gateway 配置文件总览（/etc/firezone/）

gateway-preset-env 实测内容：

# This file is managed by maintainer scripts. Do not touch!
# Use `etc/firezone/gateway-env` for custom configuration.
FIREZONE_ID=80b531b6c3074b7d87d573d7d5422594

4.2 Gateway 环境变量/旗标总览（firezone-gateway --help 实测整理）

4.3 Headless Client 环境变量总览（官方文档 + --help 实测整理）

五、核心参数分类详解

5.1 令牌与身份（Gateway）

Gateway 靠令牌向控制面证明身份，落盘路径与注入机制都由单元文件约定：

LoadCredential=FIREZONE_TOKEN:/etc/firezone/gateway-token
EnvironmentFile=/etc/firezone/gateway-preset-env
EnvironmentFile=/etc/firezone/gateway-env

• 令牌文件保持 0400 root，authenticate 命令负责写入；
• FIREZONE_ID 在 gateway-preset-env 由安装器随机生成（见 4.1），不要改——它绑定门户里的网关记录；
• 自建单元（非官方包）没有 LoadCredential，把令牌放进 gateway-env（FIREZONE_TOKEN=...）或前台运行时传环境变量。

5.2 日志格式与级别

Gateway 日志格式实测对比。human（默认）输出人类可读行：

2026-10-20T11:07:42.486Z  INFO telemetry: Started telemetry environment=production

FIREZONE_LOG_FORMAT=json 后输出结构化 JSON（实测）：

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

实测回显（无有效令牌时的启动段，JSON 格式）：

{"timestamp":"2026-10-20T11:08:58.710087Z","level":"INFO","message":"`gateway` started logging","arch":"x86_64","os":"linux","version":"1.6.3","system_uptime":"69697s","target":"firezone_gateway"}
{"timestamp":"2026-10-20T11:08:58.710588Z","level":"INFO","message":"Started telemetry","environment":"production","target":"telemetry"}

💡 说明：接入日志采集（Loki/ELK）时把 FIREZONE_LOG_FORMAT=json 写进 /etc/firezone/gateway-env 是第一件事；Gateway 文件日志不走 LOG_DIR，统一由 journald 收口（journalctl --unit firezone-gateway）。

Headless Client 则支持文件日志（实测 LOG_DIR=/var/log/firezone-client）：

sudo mkdir -p /var/log/firezone-client
sudo FIREZONE_DNS_CONTROL=disabled LOG_DIR=/var/log/firezone-client firezone-client-headless
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

文件按启动时间戳命名，firezone-headless-client.latest 软链始终指向最新一份，便于日志轮转采集。

5.3 DNS 接管模式（Headless Client）

FIREZONE_DNS_CONTROL（或 --dns-control）三种取值的取舍（官方帮助实测原文）：

实测确认旗标枚举与默认值（firezone-client-headless --help 节选）：

--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]

5.4 内核与网络前置参数

firezone-gateway-init（ExecStartPre）在服务每次启动前写入的内核参数（脚本实测）：

iptables 前置（同脚本实测）：

iptables -I FORWARD 1 -i tun-firezone -j ACCEPT
iptables -I FORWARD 1 -o tun-firezone -j ACCEPT
iptables -t nat -A POSTROUTING -s 100.64.0.0/11 -o e+ -j MASQUERADE
iptables -t nat -A POSTROUTING -s 100.64.0.0/11 -o w+ -j MASQUERADE
ip6tables ...（同构，网段 fd00:2021:1111::/107）

💡 说明：100.64.0.0/11 是 Firezone 隧道内网（CGNAT 段），MASQUERADE 让 Gateway 后面的真实资源看到的是网关地址而非隧道地址；tun-firezone 是隧道接口名。自建防火墙（ufw/firewalld）的服务器要为 tun-firezone 放行转发，否则出现「客户端能认证、资源不通」。

另有两个与内核缓冲相关的旗标：Gateway 默认尝试调大 core.rmem_max/core.wmem_max（WireGuard 大包缓冲），--no-inc-buf 可关闭该行为；--no-check 跳过启动前权限预检，一般保持默认。

5.5 systemd 覆盖与重载

官方单元禁止直接编辑，正确做法是 drop-in 覆盖：

sudo systemctl edit firezone-gateway

例如临时加调试日志级别（RUST_LOG 是 Client 侧变量，Gateway 用 firezone 日志指令，这里示例加资源限制覆盖）：

[Service]
LimitNOFILE=8192

保存后 sudo systemctl restart firezone-gateway 生效。核对最终生效配置：

systemctl show firezone-gateway -p LimitNOFILE -p RestartSec

实测回显（默认值状态）：

LimitNOFILE=4096
RestartSec=7s

💡 说明：官方单元已设 LimitNOFILE=4096、LimitNPROC=512、LimitCORE=0，以及 SystemCallFilter=@system-service、ProtectSystem=full 等加固项；覆盖时只写要改的键。

5.6 参数校验行为（实测）

非法取值直接拒绝启动，这是确认参数拼写/格式的快速手段（实测）：

sudo env FIREZONE_TOKEN="$FIREZONE_TOKEN" firezone-gateway -m abc

实测回显：

error: invalid value 'abc' for '--max-partition-time <MAX_PARTITION_TIME>': expected number at 0
For more information, try '--help'.

合法取值样例：5m、1h、30d。

六、生产配置模板

适用场景：8GB 内存 / SSD 云主机上的生产 Site Gateway（官方建议每 Site ≥3 个做高可用），日志接 JSON 采集、关闭遥测、锁定断连上限。

/etc/firezone/gateway-env 模板：

# /etc/firezone/gateway-env —— 管理员自定义项（重启 firezone-gateway 生效）
FIREZONE_LOG_FORMAT=json
FIREZONE_MAX_PARTITION_TIME=1h
FIREZONE_NO_TELEMETRY=1

💡 说明：令牌与 FIREZONE_ID 不写入此文件——令牌由 firezone-gateway authenticate 写入 gateway-token，FIREZONE_ID 在 gateway-preset-env 由安装器维护。改完执行 sudo systemctl restart firezone-gateway，并用 journalctl --unit firezone-gateway -n 5 确认日志已变 JSON。

适用场景：无桌面服务器上的 Headless Client（CI 或堡垒机），IP 型资源、DNS 自管、日志落盘。

systemd 单元 /etc/systemd/system/firezone-headless-client.service 模板（实测可启动）：

[Unit]
Description=Firezone Headless Client
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
Environment=FIREZONE_TOKEN_PATH=/etc/dev.firezone.client/token
Environment=LOG_DIR=/var/log/firezone-client
ExecStart=/usr/local/bin/firezone-client-headless --dns-control disabled
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启用与验证（实测回显）：

sudo systemctl daemon-reload
sudo systemctl enable firezone-headless-client
sudo systemctl start firezone-headless-client
systemctl status firezone-headless-client --no-pager

Created symlink /etc/systemd/system/multi-user.target.wants/firezone-headless-client.service → /etc/systemd/system/firezone-headless-client.service.
● firezone-headless-client.service - Firezone Headless Client
     Loaded: loaded (/etc/systemd/system/firezone-headless-client.service; enabled; vendor preset: enabled)
     Active: activating (auto-restart) (Result: exit-code) since Tue 2026-10-20 11:10:51 UTC; 2s ago
    Process: 2789 ExecStart=/usr/local/bin/firezone-client-headless --dns-control disabled (code=exited, status=1/FAILURE)
   Main PID: 2789 (code=exited, status=1/FAILURE)

💡 说明：上面实测截图里的 FAILURE 是因为演示机令牌为无效占位值（code=exited, status=1/FAILURE）——令牌有效时该单元应为 active (running)；Restart=always + RestartSec=5 保证断网后自动重试。

七、常见问题（FAQ）

Q1：改了 gateway-env 不生效？ EnvironmentFile 只在服务启动时读取，改完必须 sudo systemctl restart firezone-gateway。验证注入结果：systemctl show firezone-gateway -p EnvironmentFiles 确认两个 env 文件都被加载。

Q2：gateway-preset-env 里的 FIREZONE_ID 能改成好记的值吗？ 不要。该值首次生成后与门户侧网关记录绑定；确需重置应删掉门户里的网关记录重新注册，而不是单方面改本机文件。

Q3：authenticate 报 Found existing token ... use --replace to overwrite？ 令牌文件已存在（实测报错原文）。换新令牌用 sudo firezone-gateway authenticate --replace。

Q4：控制面拒绝令牌后服务会一直重启吗？ 不会。令牌被门户拒绝时 Gateway 以退出码 78 退出，单元设了 RestartPreventExitStatus=78，systemd 不再自动重启，避免无效重试。换新令牌后需手动 sudo systemctl restart firezone-gateway。

Q5：Headless Client 报 Your Firezone sign-in has expired？ 用户令牌过期（有效期由门户里身份源的会话时长决定）。实测回显：

Firezone disconnected: Connection to portal failed: Your Firezone sign-in has expired. Sign in again to reconnect.

无人值守场景改用服务账号令牌（Service Account）写入 FIREZONE_TOKEN，长效不过期。

Q6：客户端把系统 DNS 改坏了？ etc-resolv-conf 模式会备份原文件并直接接管 /etc/resolv.conf；崩溃后未恢复时，把备份文件还原即可。/etc/resolv.conf 是 stub-resolv.conf 软链的系统一律用默认 systemd-resolved 模式（官方帮助明确警告，见 5.3 节）。

八、参考链接

1. Gateway 环境变量与旗标：firezone-gateway --help（本文 4.2 节实测）与官方 Gateway CLI 参考 https://www.firezone.dev/kb/reference/cli/gateway
2. Headless Client 环境变量参考：https://www.firezone.dev/kb/reference/cli/headless-linux
3. 官方单元文件：/lib/systemd/system/firezone-gateway.service（本文 5.5 节实测摘录）
4. 网关部署与令牌：https://www.firezone.dev/kb/deploy/debian 、https://www.firezone.dev/kb/deploy/tokens
5. DNS 配置维护：https://www.firezone.dev/kb/maintain/dns
6. 本专栏姊妹篇：《Ubuntu 22.04 安装 Firezone 指南》、《Firezone 1.6.3 常用 CLI 命令详解》