Ubuntu 22.04 安装 Firezone 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 Firezone 数据面组件——Gateway（1.6.3）与可选的 Headless Client（1.5.14），完成 systemd 托管、版本管理与卸载清理。本文所有命令与回显均已在 Ubuntu 22.04.5 LTS（x86_64）环境实测通过，实测日期 2026-10-20。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），内核 5.15+
安装组件：firezone-gateway 1.6.3（官方 APT 仓库）；firezone-client-headless 1.5.14（GitHub Releases 独立二进制）
依赖：apt、wget/curl、gpg、systemd（服务托管必需）
官方 APT 仓库：https://artifacts.firezone.dev/apt/ stable main
软件发行通道：APT 仓库（Gateway/GUI Client）+ GitHub Releases（Gateway、Headless Client 独立二进制）
关键路径：二进制 /usr/bin/firezone-gateway；配置目录 /etc/firezone/；状态目录 /var/lib/firezone/；服务单元 /lib/systemd/system/firezone-gateway.service
实测主机名：gw01（Gateway）、client01（Headless Client 演示机）

二、前置条件

一台能出公网的 Ubuntu 22.04 服务器（Gateway 需要访问 api.firezone.dev 控制面与 WireGuard UDP 隧道）。
root 或 sudo 权限。
systemd 可用：Gateway 以 systemd 服务托管，Ubuntu 22.04 服务器默认满足。⚠️ 无 systemd 的极简环境只能用独立二进制方式前台运行。
Firezone 账号：在管理门户（app.firezone.dev）注册并登录，进入 Sites → 你的 Site → Deploy a gateway 生成网关令牌（token）。令牌是唯一接入凭据，注意保密。

安装基础工具（如系统未带）：

sudo apt update
sudo apt install -y curl wget gpg ca-certificates

实测回显（新装机输出节选）：

Reading package lists...
Building dependency tree...
ca-certificates is already the newest version (20240203).
0 upgraded, 0 newly installed, 0 to remove and 18 not upgraded.

三、版本选型说明

Firezone 1.x 按组件独立发版，本指南版本选型如下（GitHub releases.atom 实查，2026-10-20）：

组件	最新稳定版	发布日期	安装方式
firezone-gateway	1.6.3	2026-10-14	APT 仓库 / 独立二进制
firezone-client-headless（Linux）	1.5.14	2026-10-14	GitHub Releases 二进制
firezone-client-gui（Linux 桌面）	1.5.19	2026-10-14	APT 仓库（需桌面环境，本文不展开）

APT 仓库中 Gateway 历史版本可查（apt-cache policy 实测节选，供降级用）：

firezone-gateway:
  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

💡 说明：请始终安装仓库最新稳定版；多版本共存没有意义（同机只跑一个 Gateway），版本管理按「升级/降级」操作，见第八节。

四、安装方案 A：APT 仓库安装 Gateway（官方推荐）

本方案从 Firezone 官方 APT 仓库安装 firezone-gateway，自动完成二进制落位、firezone 系统用户创建与 systemd 服务单元注册，是最省事的官方推荐路径。

4.1 添加 APT 仓库

sudo mkdir --parents /etc/apt/keyrings
wget -qO- https://artifacts.firezone.dev/apt/key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/firezone.gpg
echo "deb [signed-by=/etc/apt/keyrings/firezone.gpg] https://artifacts.firezone.dev/apt/ stable main" | sudo tee /etc/apt/sources.list.d/firezone.list > /dev/null
sudo apt update

实测回显（仓库新增部分）：

Get:5 https://artifacts.firezone.dev/apt stable InRelease [4963 B]
Get:6 https://artifacts.firezone.dev/apt stable/main amd64 Packages [4319 B]
Fetched 9282 B in 2s (5646 B/s)
Reading package lists...

4.2 安装 firezone-gateway

sudo apt install -y firezone-gateway

实测回显（节选）：

The following NEW packages will be installed:
  firezone-gateway iptables libip6tc2 libmnl0 libnetfilter-conntrack3
  libnfnetlink0 libnftnl11 libxtables12 netbase
0 upgraded, 9 newly installed, 0 to remove and 18 not upgraded.
Need to get 6591 kB of archives.
After this operation, 26.5 MB of additional disk space will be used.
Get:6 https://artifacts.firezone.dev/apt stable/main amd64 firezone-gateway amd64 1.6.3 [5932 kB]
Setting up firezone-gateway (1.6.3) ...
Creating group firezone with gid 999.
Creating user firezone (n/a) with uid 999 and gid 999.

安装器做了三件事：落位二进制 /usr/bin/firezone-gateway（实测 22858704 字节，-rwxr-xr-x 1 root root）、创建 firezone 系统用户/组（uid/gid 999）、注册 /lib/systemd/system/firezone-gateway.service。包内文件清单（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

💡 说明：/usr/bin/firezone-gateway-init 是服务启动前置脚本，负责写入内核转发参数与隧道网段 NAT 伪装规则（100.64.0.0/11、fd00:2021:1111::/107），详见第七节。

4.3 写入令牌（authenticate）

sudo firezone-gateway authenticate

命令会提示粘贴令牌（实测提示行）：

Paste the token from the portal's deploy page:

把门户生成的 token 粘贴回车后，实测回显：

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

令牌以 root 只读权限落盘（实测 ls -la /etc/firezone/gateway-token）：

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

⚠️ 注意：authenticate 从**当前终端（TTY）**读入令牌，不接受普通管道 stdin。实测 echo <token> | sudo firezone-gateway authenticate 报错：
Paste the token from the portal's deploy page:
Error: Failed to read token from stdin: No such device or address (os error 6)
在无法交互的环境请用伪终端（如 script -qec "firezone-gateway authenticate" /dev/null）或参考第七节手工写入令牌文件。

若已写入过令牌，再次 authenticate 会被拒绝（实测）：

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

换用 sudo firezone-gateway authenticate --replace 即可覆盖。

4.4 启用并启动服务

sudo firezone-gateway enable-service

实测回显：

Successfully enabled `firezone-gateway.service`

该命令等价于 enable + start。验证服务状态：

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

再确认日志里出现注册成功字样：

journalctl --unit firezone-gateway --no-pager -n 10

实测回显（启动日志节选）：

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

⚠️ 注意：version="1.6.3" 即实际运行版本；若日志反复出现 Failed with result 'exit-code' 与 Scheduled restart job，多半是令牌缺失或无效，排障见第九节。

五、安装方案 B：独立二进制 + 自建 systemd 单元

本方案直接从 GitHub Releases 下载 Gateway 独立二进制并手工配置 systemd 服务，适合不便使用 APT 仓库（如 Debian 系以外自管主机、需要离线分发包）的场景。

5.1 下载二进制并校验

curl -fSL -o /tmp/firezone-gateway_1.6.3_x86_64 \
  https://github.com/firezone/firezone/releases/download/gateway-1.6.3/firezone-gateway_1.6.3_x86_64
curl -fSL -o /tmp/gw.sha256 \
  https://github.com/firezone/firezone/releases/download/gateway-1.6.3/firezone-gateway_1.6.3_x86_64.sha256sum.txt

官方 sha256 文件内容（实测）：

c8e774118539c784b07d3b79217bf3a70913a5a6923ae185f44c0cb19f857cc6  firezone-gateway_1.6.3_x86_64

校验（实测）：

cd /tmp && cp firezone-gateway_1.6.3_x86_64 firezone-gateway_1.6.3_x86_64.bak \
  && sha256sum -c gw.sha256

实测回显：

firezone-gateway_1.6.3_x86_64: OK

平台对应关系（GitHub Release gateway-1.6.3 资产清单实测）：firezone-gateway_1.6.3_x86_64 / firezone-gateway_1.6.3_aarch64 / firezone-gateway_1.6.3_armv7，各自附 .sha256sum.txt。

5.2 安装二进制

sudo install -m 0755 /tmp/firezone-gateway_1.6.3_x86_64 /usr/local/bin/firezone-gateway
/usr/local/bin/firezone-gateway --version

实测回显：

firezone-gateway 1.6.3

5.3 建立配置目录与令牌

sudo install -d -m 0750 /etc/firezone
echo "FIREZONE_ID=$(od -An -tx1 -N16 /dev/urandom | tr -d ' \n')" | sudo tee /etc/firezone/gateway-env
sudo install -m 0400 /dev/null /etc/firezone/gateway-token
sudo nano /etc/firezone/gateway-token    # 粘贴门户 token 并保存

FIREZONE_ID 实测生成示例（每台机器随机且固定）：

FIREZONE_ID=8c9c0ac841f7ccd80db0d358a0d28169

💡 说明：FIREZONE_ID 是门户识别该网关的稳定标识，首次生成后固定不变；gateway-token 权限保持 0400。

5.4 自建 systemd 单元

创建 /etc/systemd/system/firezone-gateway.service：

sudo tee /etc/systemd/system/firezone-gateway.service > /dev/null <<'EOF'
[Unit]
Description=Firezone Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=firezone
Group=firezone
StateDirectory=firezone
StateDirectoryMode=0700
EnvironmentFile=/etc/firezone/gateway-env
ExecStartPre=+/usr/local/bin/firezone-gateway-init || true
ExecStart=/usr/local/bin/firezone-gateway
Restart=always
RestartSec=7

[Install]
WantedBy=multi-user.target
EOF

⚠️ 注意：自建单元没有官方单元里的 LoadCredential 令牌机制，Gateway 会转而读取 FIREZONE_TOKEN 环境变量或磁盘令牌；令牌请经 EnvironmentFile 或 FIREZONE_TOKEN_PATH 挂入，避免写进单元文件本身。

5.5 启动与验证

sudo systemctl daemon-reload
sudo systemctl enable firezone-gateway
sudo systemctl start firezone-gateway
systemctl is-active firezone-gateway

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/firezone-gateway.service → /etc/systemd/system/firezone-gateway.service.
active

再确认版本与日志：

/usr/local/bin/firezone-gateway --version
journalctl --unit firezone-gateway --no-pager -n 5

实测回显：

firezone-gateway 1.6.3

六、方案对比与选择建议

维度	方案 A：APT 仓库	方案 B：独立二进制
版本来源	artifacts.firezone.dev，`apt upgrade` 即更新	GitHub Releases，手工下载替换
systemd 单元	官方维护，含安全加固（见第七节）	自建，需自己取舍加固项
令牌管理	`firezone-gateway authenticate` 交互写入	手工写 `gateway-token` 文件
依赖	Debian/Ubuntu + apt	任意 Linux（匹配 glibc 即可）
适用	生产服务器首选	离线分发、非 apt 系、审计二进制场景

选择建议：可联网的 Debian/Ubuntu 一律用方案 A；离线或非 apt 环境用方案 B，并把 .sha256sum.txt 校验纳入交付流程。

七、配置说明

7.1 配置文件布局

安装完成后 /etc/firezone/ 实测内容：

-rw-r--r-- 1 firezone firezone    0 Oct 20 11:05 gateway-env
-rw-r--r-- 1 firezone firezone  164 Oct 20 11:05 gateway-preset-env
-r-------- 1 root     root        0 Oct 20 11:05 gateway-token

gateway-env：管理员自定义环境变量（空白起步），是 Gateway 唯一该手工编辑的文件；
gateway-preset-env：包维护脚本管理的预置变量（实测内容，FIREZONE_ID 由安装器随机生成并固定）：

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

gateway-token：authenticate 写入的接入令牌，仅 root 可读。

7.2 systemd 服务与安全加固

官方单元 /lib/systemd/system/firezone-gateway.service 关键项（systemctl cat firezone-gateway 实测摘录）：

Type=simple
User=firezone
Group=firezone
StateDirectory=firezone
LoadCredential=FIREZONE_TOKEN:/etc/firezone/gateway-token
EnvironmentFile=/etc/firezone/gateway-preset-env
EnvironmentFile=/etc/firezone/gateway-env
ExecStartPre=/usr/bin/firezone-gateway-init
ExecStart=/usr/bin/firezone-gateway
Restart=always
RestartSec=7
RestartPreventExitStatus=78

单元内置加固：NoNewPrivileges=true、ProtectSystem=full、PrivateTmp=true、MemoryDenyWriteExecute=true、SystemCallFilter=@system-service、AmbientCapabilities=CAP_NET_ADMIN 等。修改配置不要直接改单元文件，用覆盖片段：

sudo systemctl edit firezone-gateway

7.3 内核与防火墙前置（firezone-gateway-init）

服务每次启动前执行 /usr/bin/firezone-gateway-init（脚本实测内容节选）：

sysctl -w net.ipv4.ip_forward=1
sysctl -w net.ipv4.conf.all.src_valid_mark=1
sysctl -w net.ipv6.conf.all.disable_ipv6=0
sysctl -w net.ipv6.conf.all.forwarding=1

并为隧道网段写入 iptables 放行与 NAT 伪装（IPv4/IPv6 各一组）：

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

💡 说明：脚本幂等（先 -C 检查再追加），服务器若启用 ufw/firewalld 需自行放行 WireGuard 的 UDP 端口与 tun-firezone 接口转发，否则客户端能连上控制面但数据面不通。

7.4 Gateway 环境变量（gateway-env 可写项）

变量	默认值	说明
`FIREZONE_TOKEN`	无	接入令牌；systemd 托管时优先由 `LoadCredential` 注入
`FIREZONE_ID`	预置生成	网关稳定标识，首次启动后不要改动
`FIREZONE_LOG_FORMAT`	`human`	日志格式，可选 `json`/`human`
`FIREZONE_MAX_PARTITION_TIME`	`30d`	控制面断连后最大重试时长，接受 `5m`/`1h` 等人类可读时间
`FIREZONE_NO_TELEMETRY`	未设置	设为任意值即禁用 Sentry 崩溃上报
`FIREZONE_FLOW_LOGS`	未设置	设为任意值即本地跟踪流日志（`flow_logs=trace`）
`FIREZONE_NO_INC_BUF`	未设置	设为任意值则不尝试调大 `core.rmem_max`/`core.wmem_max`

改法示例（写入后重启服务生效）：

echo 'FIREZONE_LOG_FORMAT=json' | sudo tee -a /etc/firezone/gateway-env
sudo systemctl restart firezone-gateway

7.5 Headless Client 配置（如安装）

Linux 无界面客户端令牌默认路径 /etc/dev.firezone.client/token，DNS 控制模式默认跟随 systemd-resolved；服务器无 resolved 时以 --dns-control disabled 或 --dns-control etc-resolv-conf 启动。变量详见《Firezone 1.6.3 配置参数详解》。

八、升级、降级与多版本

8.1 APT 方案升级/降级

sudo apt update && sudo apt install --only-upgrade firezone-gateway   # 升级到最新
sudo apt install --allow-downgrades -y firezone-gateway=1.6.2         # 降级到指定版本
sudo apt-mark hold firezone-gateway                                   # 锁定版本
sudo apt-mark unhold firezone-gateway                                 # 解锁

降级到 1.6.2 实测回显（节选）：

dpkg: warning: downgrading firezone-gateway from 1.6.3 to 1.6.2
(Reading database ... 7622 files and directories currently installed.)
Preparing to unpack .../firezone-gateway_1.6.2_amd64.deb ...
Unpacking firezone-gateway (1.6.2) over (1.6.3) ...
Setting up firezone-gateway (1.6.2) ...

💡 说明：同版本段内安装旧版需加 --allow-downgrades，否则 apt 拒绝降级动作。

锁定/解锁实测回显：

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

升级/降级后确认运行版本：

firezone-gateway --version

实测回显：

firezone-gateway 1.6.3

8.2 独立二进制方案升级

以把独立二进制替换为 1.6.3 为例（旧版 → 1.6.3，同理可用于任意新版本，版本号以 GitHub Releases 页为准）：

sudo systemctl stop firezone-gateway
curl -fSL -o /tmp/firezone-gateway_1.6.3_x86_64 \
  https://github.com/firezone/firezone/releases/download/gateway-1.6.3/firezone-gateway_1.6.3_x86_64
sudo install -m 0755 /tmp/firezone-gateway_1.6.3_x86_64 /usr/local/bin/firezone-gateway
sudo systemctl start firezone-gateway
/usr/local/bin/firezone-gateway --version

实测回显：

firezone-gateway 1.6.3

⚠️ 注意：升级 Gateway 会导致该 Site 短暂少一个数据面节点，生产环境应滚动逐台升级，保持每 Site 至少 3 个 Gateway。

九、常见问题（FAQ）

Q1：服务反复重启，日志提示读取令牌失败。 Gateway 拿不到令牌时会持续失败退出并由 systemd 每 7 秒重试。实测无令牌时的日志：

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: Main process exited, code=exited, status=1/FAILURE
systemd[1]: firezone-gateway.service: Scheduled restart job, restart counter is at 2.

处理：确认 /etc/firezone/gateway-token 存在且已写入有效令牌（sudo ls -l /etc/firezone/gateway-token），必要时重新 sudo firezone-gateway authenticate --replace。

Q2：日志提示登录门户失败。 令牌无效/过期/已被吊销时，前台运行可见（实测）：

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

处理：回门户重新生成 token，firezone-gateway authenticate --replace 后 systemctl restart firezone-gateway。控制面拒绝令牌导致的退出码是 78，单元配置 RestartPreventExitStatus=78 表示此时 systemd 不再自动重启，必须换新令牌后手动拉起。

Q3：authenticate 提示读不到 stdin。 该命令强制从 TTY 读令牌，管道输入报 Error: Failed to read token from stdin: No such device or address (os error 6)（实测，见 4.3 节）。自动化场景改写令牌文件或使用伪终端。

Q4：-m/--max-partition-time 传了非法值。 参数校验失败时直接拒绝启动（实测）：

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

取值须为 5m、1h、30d 这类人类可读时长。

Q5：客户端能认证但访问不了资源。 逐项检查：Gateway 是否 active (running)；门户里 Resource 的地址/端口是否配对；Policy 是否覆盖该用户组；服务器防火墙是否放行了 tun-firezone 转发（见 7.3 节）。

十、卸载与清理

sudo firezone-gateway disable-service          # 等价 systemctl disable --now
sudo apt remove --purge -y firezone-gateway    # 卸载并清配置
sudo rm -rf /etc/firezone                      # 清理残留配置目录（purge 不删除运行期生成文件）

实测回显（节选）：

Successfully disabled `firezone-gateway.service`
Removing firezone-gateway (1.6.3) ...
Purging configuration files for firezone-gateway (1.6.3) ...

卸载后核验（实测）：

dpkg -l | grep firezone || echo "no firezone packages"
which firezone-gateway || echo "binary removed"

实测回显：

no firezone packages
binary removed

💡 说明：purge 会移除包文件与单元，但 /etc/firezone/gateway-env、gateway-token 等运行期生成的文件会留下，须按上面命令手工删除；自建方案 B 另需删除 /usr/local/bin/firezone-gateway 与 /etc/systemd/system/firezone-gateway.service。

十一、参考链接

官方 Debian/Ubuntu 部署文档：https://www.firezone.dev/kb/deploy/debian
Gateway systemd 部署文档：https://www.firezone.dev/kb/deploy/systemd
Gateway 令牌说明：https://www.firezone.dev/kb/deploy/tokens
APT 仓库：https://artifacts.firezone.dev/apt/
GitHub Releases（二进制与校验文件）：https://github.com/firezone/firezone/releases
升级指南：https://www.firezone.dev/kb/maintain/upgrading
本专栏姊妹篇：《Firezone 1.6.3 介绍与选型指南》、《Firezone 1.6.3 配置参数详解》、《Firezone 1.6.3 常用 CLI 命令详解》