Ubuntu 22.04 安装 Ferron 指南

目标：在 Ubuntu 22.04 LTS（x86_64）服务器上完成 Ferron 2.8.1（官方最新稳定版）的安装、systemd 托管与上线验证，覆盖官方 APT 仓库、官方一键脚本、官方 ZIP 二进制三种方案，并沉淀安装与启动阶段的真实排障记录。文中版本号、下载地址与命令回显均为官方渠道实查与真实环境实测结果（查询/实测日期 2026-10-20）。

一、环境信息

项	值
操作系统	Ubuntu 22.04.5 LTS（jammy），x86_64
内核 glibc	2.35（官方 GNU 构建要求 ≥ 2.31，满足）
目标软件	Ferron 2.8.1（Stable 通道，2026-06-17 发布）
官方文档	https://ferron.sh/docs/installation/debian（Debian/Ubuntu 包安装）
查询/实测日期	2026-10-20

二、前置条件

2.1 系统与依赖

方案一（APT 仓库）需要先安装添加软件源所用的基础工具：

sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring

2.2 端口占用检查

Ferron 默认绑定 80（HTTP）与 443（HTTPS）。安装前确认端口未被占用（Apache/Nginx/Caddy 等常驻服务会冲突）：

sudo ss -ltn | grep -E ':80\s|:443\s'

命令无输出即表示 80/443 空闲。若被占用，需先停止/卸载对应服务，或调整 Ferron 监听端口（见「八、常见问题」第 1 条的实测报错）。

2.3 版本选型说明

官方下载页（ferron.sh/download，2026-10-20 实查）并列三条版本通道：

通道	版本	发布日期	适用
Stable（推荐）	2.8.1	2026-06-17	最新稳定版，常规生产
LTS	2.6.4	2026-06-17	长期支持，变更敏感环境
Release Candidate	3.0.0-rc.9	2026-10-04	下一代大版本候选，仅供测试

APT 仓库（deb.ferron.sh）的 Candidate 即 Stable 通道版本，本文全部步骤以 2.8.1 为准：

curl -fsSL https://dl.ferron.sh/2.8.1/ferron-2.8.1-x86_64-unknown-linux-gnu.zip -o /tmp/ferron.zip   # 方案三用

官方对 GNU 构建的最低 glibc 要求为 2.31（安装脚本内置检查常量），Ubuntu 22.04 的 glibc 2.35 天然满足；musl 变体仅用于 Alpine 等 musl 发行版。

三、方案一：官方 APT 仓库安装（推荐）

3.1 添加官方仓库

# 安装依赖（见「二、前置条件」）
# 添加官方 PGP 公钥
curl https://deb.ferron.sh/signing.pgp | gpg --dearmor | sudo tee /usr/share/keyrings/ferron-keyring.gpg >/dev/null
# 写入仓库源（Ubuntu 22.04 代号 jammy）
echo "deb [signed-by=/usr/share/keyrings/ferron-keyring.gpg] https://deb.ferron.sh $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ferron.list

tee 命令的实测回显（即最终写入 /etc/apt/sources.list.d/ferron.list 的内容）：

deb [signed-by=/usr/share/keyrings/ferron-keyring.gpg] https://deb.ferron.sh jammy main

刷新软件源列表（节选 Ferron 相关行）：

sudo apt update

Get:4 https://deb.ferron.sh jammy InRelease [6,259 B]
Get:6 https://deb.ferron.sh jammy/main amd64 Packages [828 B]

3.2 安装 Ferron

sudo apt install ferron

实测回显（节选关键行，安装包约 8.4 MB）：

Need to get 8399 kB of archives.
Get:1 https://deb.ferron.sh jammy/main amd64 ferron amd64 2.8.1 [8399 kB]
Fetched 8399 kB in 2s (4115 kB/s)
(Reading database ... 7400 files and directories currently installed.)
Preparing to unpack .../ferron_2.8.1_amd64.deb ...
Unpacking ferron (2.8.1) ...
Setting up ferron (2.8.1) ...

安装完成后确认版本与仓库策略：

apt-cache policy ferron

ferron:
  Installed: 2.8.1
  Candidate: 2.8.1
  Version table:
 *** 2.8.1 500
        500 https://deb.ferron.sh jammy/main amd64 Packages

3.3 systemd 托管

deb 包内置 systemd 单元并开机自启（is-enabled 实测回显为 enabled）。单元文件 /lib/systemd/system/ferron.service 实测内容：

[Unit]
Description=Ferron web server
After=network.target

[Service]
Type=simple
User=ferron
ExecStart=/usr/sbin/ferron -c /etc/ferron.kdl
ExecReload=kill -HUP $MAINPID
Restart=on-failure
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

要点解读：以非特权用户 ferron 运行（安装包会自动创建该系统用户，家目录 /var/lib/ferron，登录 shell 为 /usr/sbin/nologin）；通过 AmbientCapabilities=CAP_NET_BIND_SERVICE 获得 80/443 特权端口绑定能力；ExecReload 采用 kill -HUP 实现配置热重载。

若因特殊环境（如安装期间服务被策略拦截）服务未运行，手动启动一次：

sudo systemctl start ferron

查看服务状态：

sudo systemctl status ferron --no-pager

实测回显（CGroup 行为真实服务器标准输出）：

● ferron.service - Ferron web server
     Loaded: loaded (/lib/systemd/system/ferron.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-20 17:39:43 UTC; 2s ago
   Main PID: 4395 (ferron)
      Tasks: 21 (limit: 94371)
     Memory: 5.6M
        CPU: 9ms
     CGroup: /system.slice/ferron.service
             └─4395 /usr/sbin/ferron -c /etc/ferron.kdl

Oct 20 17:39:43 ferron-web systemd[1]: Started Ferron web server.
Oct 20 17:39:43 ferron-web ferron[4395]: HTTP server is listening on [::]:80...

内存常驻仅约 5.6 MB（实测值），日志行 HTTP server is listening on [::]:80... 表明监听已就绪。

3.4 安装验证

curl -sI http://localhost/

实测回显：

HTTP/1.1 200 OK
accept-ranges: bytes
etag: W/"90be009d3075f11c"
vary: Accept-Encoding, If-Match, If-None-Match, Range
content-type: text/html
content-length: 2411
server: Ferron
date: Tue, 20 Oct 2026 17:39:45 GMT

响应头 server: Ferron 与 200 状态码确认服务正常。浏览器打开 http://<服务器IP> 应看到「Ferron is installed successfully!」默认页（来源：官方安装文档验收标准）。

版本信息：

/usr/sbin/ferron --version

Ferron 2.8.1
  Compiled on: 2026-06-17 13:44:00 +00:00
  Git commit: 
  Build target: x86_64-unknown-linux-gnu
  Rust version: rustc 1.96.0 (ac68faa20 2026-05-25)
  Build host: linux-x86_64

四、方案二：官方一键脚本安装

官方为「不想手工加源」的用户提供一键脚本（来源：ferronweb.org 首页，2026-10-20）：

sudo bash -c "$(curl -fsSL https://get.ferron.sh/v2)"

脚本是交互式的，实测流程（节选关键交互与输出）：

选择安装通道（输入 stable）：

✅ Installation channel (`stable` for stable, `lts` for LTS, `manual` for manual installation from a ZIP archive): stable
Checking prerequisites...

选择安装方式（脚本检测到 Debian/Ubuntu 时会询问是否改用 deb 包安装；此处输入 n 走 ZIP 部署路径，输入 y 则等价于方案一的 apt 安装）。
随后脚本自动完成：下载 ZIP → 校验并安装 /usr/sbin/ferron 与配套工具 → 写入 /etc/ferron.kdl → 创建 ferron 系统用户 → 注册 /etc/systemd/system/ferron.service 并启动服务。
完成提示（实测回显，节选）：

✅ Installation completed! You can now start Ferron with `sudo systemctl start ferron` (if it isn't already running).

If Ferron is running now, you can view the website by visiting the URL: http://localhost
Enjoy! :)

脚本安装的验证与方案一相同（systemctl status ferron、curl -sI http://localhost/）。它额外提供版本更新器 /usr/bin/ferron-updater，并在 /etc/.ferron-installer.version 中记录安装版本（实测均为 2.8.1）。

五、方案三：官方 ZIP 二进制手动部署

适合无 root、需要多版本共存或完全掌控部署路径的场景。下载地址模式：https://dl.ferron.sh/<版本>/ferron-<版本>-<目标三元组>.zip，Ubuntu 22.04 x86_64 对应 x86_64-unknown-linux-gnu。

5.1 下载与完整性校验

cd /opt
sudo curl -fsSL -o ferron-2.8.1-x86_64-unknown-linux-gnu.zip https://dl.ferron.sh/2.8.1/ferron-2.8.1-x86_64-unknown-linux-gnu.zip
sudo curl -fsSL -o ferron-2.8.1.sha256sum https://dl.ferron.sh/2.8.1/ferron-2.8.1.sha256sum
sudo sha256sum -c ferron-2.8.1.sha256sum 2>/dev/null | grep x86_64-unknown-linux-gnu

实测回显（官方校验文件比对通过）：

ferron-2.8.1-x86_64-unknown-linux-gnu.zip: OK

5.2 解压与目录结构

sudo unzip ferron-2.8.1-x86_64-unknown-linux-gnu.zip -d /opt/ferron-zip

ZIP 包内容实测（unzip -l 节选）：

  Length      Date    Time    Name
---------  ---------- -----   ----
  1093712  2026-06-17 13:44   ferron-yaml2kdl
   778320  2026-06-17 13:44   ferron-passwd
       25  2026-06-17 13:39   ferron.kdl
 22768352  2026-06-17 13:46   ferron
  2510160  2026-06-17 13:44   ferron-precompress
        0  2026-06-17 13:39   wwwroot/

包内自带四个二进制（ferron 主程序与 ferron-passwd/ferron-precompress/ferron-yaml2kdl 伴生工具）、25 字节的极简默认配置与示例站点根 wwwroot/。默认 ferron.kdl 全文实测：

:80 {
  root "wwwroot"
}

先做独立运行冒烟测试（不与 80 端口冲突，用 --config-string 临时指定 8088）：

cd /opt/ferron-zip && ./ferron --config-string ":8088 { root \"wwwroot\" }"

HTTP server is listening on [::]:8088...

另开终端验证后 Ctrl+C 结束：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/
# 实测输出：200

5.3 手工 systemd 托管

将二进制部署为系统服务（注意：ZIP 部署默认以 root 运行，生产建议照方案一创建 ferron 用户并 User= 指定；下例保持简洁用 root 演示）：

sudo tee /etc/systemd/system/ferron-zip.service >/dev/null <<'EOF'
[Unit]
Description=Ferron web server (ZIP deployment)
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/ferron-zip
ExecStart=/opt/ferron-zip/ferron -c /opt/ferron-zip/ferron.kdl
ExecReload=kill -HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now ferron-zip

验证（实测回显）：

systemctl is-active ferron-zip && curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8089/

active
200

💡 说明：上例为演示环境实测——同一台机器上方案一的服务已占用 80 端口，故演示单元将 /opt/ferron-zip/ferron.kdl 的块名临时改为 :8089。独立服务器正式部署时直接使用默认 :80 块即可。若只想要轻量托管而不写单元，/opt/ferron-zip/ferron.kdl 配好后 sudo systemctl enable --now ferron-zip 一条命令即完成开机自启。

六、方案对比与选择建议

维度	方案一：APT 仓库	方案二：一键脚本	方案三：ZIP 手动
官方推荐度	官方文档标准路径	官网首页主推	官方下载页兜底路径
升级方式	`apt upgrade` 自动跟进 Stable	`ferron-updater` 或重跑脚本	手动下载新版本解压替换
systemd 托管	自动（单元内置）	自动（脚本写入）	需手写单元
非特权用户运行	自动（ferron 用户）	自动（ferron 用户）	需手动创建与配置
可定制安装路径	否（固定 /usr/sbin）	否	是（任意目录，可多版本共存）
适用人群	常规 Ubuntu 服务器	想一条命令搞定的新手	无 root/定制化/多版本场景

选择建议：生产服务器首选方案一（升级、依赖、单元管理全部走包管理器闭环）；新机器快速体验用方案二；无 root 环境、需要定制安装路径或 2.6.4 LTS 与 2.8.1 并行验证时用方案三。

七、安装后的基础配置说明

7.1 配置文件与默认站点

APT/脚本安装的文件结构（官方文档口径 + 实测核对）：

路径	用途
`/etc/ferron.kdl`	Ferron 配置文件（KDL 格式）
`/usr/sbin/ferron`	Ferron 主程序
`/usr/sbin/ferron-passwd`	口令哈希生成工具（HTTP Basic 认证用）
`/usr/sbin/ferron-precompress`	静态文件预压缩工具
`/usr/sbin/ferron-yaml2kdl`	Ferron 1.x YAML 配置转 2.x KDL 工具
`/var/www/ferron`	默认站点根（含 `index.html` 默认页与 `assets/`）
`/var/log/ferron/access.log`	访问日志（Combined Log Format）
`/var/log/ferron/error.log`	错误日志

默认配置 /etc/ferron.kdl 全文实测（含官方注释）：

// See https://ferron.sh/docs/configuration/fundamentals for the configuration reference

// Global configuration.
//
// Here you can put configuration that applies to all hosts,
// and even to the web server itself.
globals {
  // Log requests and errors into log files
  log "/var/log/ferron/access.log"
  error_log "/var/log/ferron/error.log"
}

// Host configuration.
//
// Here you can put configuration that applies to a specific host,
// by default a catch-all ":80" host that applies to all hostnames and port 80 (HTTP).
//
// Replace ":80" with your domain name (pointing to your server) to use HTTPS.
// If you don't specify the paths to the TLS certificate and private key manually,
// Ferron will obtain a TLS certificate automatically (via Let's Encrypt by default).
:80 {
  // Serve static files
  root "/var/www/ferron"

  // Reverse proxy to a backend server
  //proxy "http://localhost:3000/"

  // Serve a PHP site with PHP-FPM (you would need to specify the webroot also used for serving static files)
  // Replace "unix:///run/php/php-fpm.sock" with your Unix socket URL
  //fcgi_php "unix:///run/php/php-fpm.sock"
}

7.2 上线自己的站点（换域名自动 HTTPS）

将块名 :80 改为你的域名（该域名 DNS 需已指向本服务器，且 80/443 可从公网访问）：

example.com {
  root "/var/www/html"
}

热加载配置（不中断服务）：

sudo systemctl reload ferron

验证 HTTPS：curl -I https://example.com，Ferron 将自动向 Let's Encrypt 申请证书（默认 TLS-ALPN-01 质询）。

八、常见问题（FAQ）

以下均为本环境实测复现的排障记录。

8.1 端口被占用：`Cannot listen to HTTP port: Address already in use (os error 98)`

80 端口已有进程时前台运行 Ferron 的实测报错：

Error while running a server: Cannot listen to HTTP port: Address already in use (os error 98)

处理：sudo ss -ltnp | grep :80 找到占用进程（常见为 Apache/Nginx），先停用；或修改配置块名（如 :8080 { ... }）换端口监听。

8.2 配置热重载失败：`Invalid top-level directive`

在 ferron.kdl 顶层误加未知指令（如 not_a_real_directive "x"）后执行 sudo systemctl reload ferron，实测服务进程会退出并进入重启循环：

Error while running a server: Invalid top-level directive at "/etc/ferron.kdl"
systemd[1]: ferron.service: Main process exited, code=exited, status=1/FAILURE
systemd[1]: ferron.service: Scheduled restart job, restart counter is at 4.
systemd[1]: ferron.service: Start request repeated too quickly.
systemd[1]: Failed to start Ferron web server.

恢复步骤（先修正配置，再清失败计数重启）：

sudo systemctl reset-failed ferron
sudo systemctl start ferron

实测恢复后 systemctl is-active ferron 返回 active、curl -o /dev/null -w "%{http_code}" http://localhost/ 返回 200。

⚠️ 注意区别：写在虚拟主机块内部的未知指令（如 bad_directive "x"）Ferron 2.8.1 会静默忽略并正常启动（实测验证），顶层未知指令则直接判非法。排查「改了配置却没生效」时先检查指令是否拼错被忽略。

8.3 KDL 语法错误：花括号未闭合

配置缺少闭合 } 时前台运行实测报错（miette 诊断格式，标注出错位置）：

Error while running a server: Failed to parse the server configuration file:
  × Failed to parse KDL document
   ╭─[/etc/ferron.kdl:3:1]
 1 │ globals {
 2 │   log "/tmp/x.log"
 3 │
   ╰────
  help: No closing '}' for child block

8.4 HTTP Basic 认证哈希粘贴错误：`Unexpected newline in single-line quoted string`

用 ferron-passwd 生成的哈希粘贴进 user 指令时若夹带了换行/回车（例如从终端复制到带 \r 尾字符），实测解析报错：

Error while running a server: Failed to parse the server configuration file:
  × Failed to parse KDL document
   ╭─[/etc/ferron.kdl:9:16]
 8 │   status 401 realm="Restricted Area" users="admin"
 9 │   user "admin" "$argon2id$v=19$m=19456,t=2,p=1$...<trailing-newline>"
   ╰────
  help: Unexpected newline in single-line quoted string

处理：确保哈希单行无尾随空白后重试。认证配置生效后实测三态：无凭据 401、正确凭据（curl -u admin:***）200、错误凭据 401，错误日志出现 Authorization failed for user "admin" and client "::ffff:127.0.0.1"。

8.5 服务反复崩溃后无法直接重启

触发条件见 8.2（Restart=on-failure 连续失败触发 Start request repeated too quickly 限速）。关键点是 systemctl reset-failed：systemd 的失败计数不清除时，配置修好后 systemctl start ferron 仍会报 Job for ferron.service failed because the control process exited with error code（实测复现），reset-failed 后再 start 即可恢复。

九、升级、降级与多版本管理

APT 方案：跟随 Stable 通道，sudo apt update && sudo apt upgrade ferron 即升级到最新稳定版；回退需在 deb.ferron.sh 的文件浏览器（https://dl.ferron.sh/ ）获取旧版 deb 后 sudo apt install ./ferron_<旧版>_amd64.deb。
一键脚本方案：重跑 sudo bash -c "$(curl -fsSL https://get.ferron.sh/v2)" 或使用安装器附带的 sudo ferron-updater。
ZIP 方案：新版本解压到新目录（如 /opt/ferron-2.9.0），改单元 ExecStart 路径后 daemon-reload && restart，旧目录保留即可随时回退。

十、卸载与清理

APT 方案：

sudo systemctl stop ferron
sudo apt purge ferron
sudo rm -rf /var/log/ferron /var/www/ferron /var/lib/ferron /etc/ferron.kdl /etc/apt/sources.list.d/ferron.list /usr/share/keyrings/ferron-keyring.gpg

一键脚本方案额外清理（文件结构与 APT 相同，另含更新器）：

sudo rm -f /usr/bin/ferron-updater /etc/.ferron-installer.version /etc/systemd/system/ferron.service
sudo userdel ferron
sudo systemctl daemon-reload

ZIP 方案：

sudo systemctl disable --now ferron-zip
sudo rm /etc/systemd/system/ferron-zip.service && sudo systemctl daemon-reload
sudo rm -rf /opt/ferron-zip

十一、参考链接

官方 Debian/Ubuntu 安装文档：https://ferron.sh/docs/installation/debian
官方下载页（版本与校验和）：https://ferron.sh/download
官方一键脚本：https://get.ferron.sh/v2
APT 仓库与签名密钥：https://deb.ferron.sh
全版本文件浏览器：https://dl.ferron.sh/
本平台关联文档：《Ferron 介绍与选型指南》、《Ferron 2.8.1 配置参数详解》、《Ferron 2.8.1 常用 CLI 命令详解》

Ubuntu 22.04 安装 Ferron 指南

Ubuntu 22.04 安装 Ferron 指南

一、环境信息

二、前置条件

2.1 系统与依赖

2.2 端口占用检查

2.3 版本选型说明

三、方案一：官方 APT 仓库安装（推荐）

3.1 添加官方仓库

3.2 安装 Ferron

3.3 systemd 托管

3.4 安装验证

四、方案二：官方一键脚本安装

五、方案三：官方 ZIP 二进制手动部署

5.1 下载与完整性校验

5.2 解压与目录结构

5.3 手工 systemd 托管

六、方案对比与选择建议

七、安装后的基础配置说明

7.1 配置文件与默认站点

7.2 上线自己的站点（换域名自动 HTTPS）

八、常见问题（FAQ）

8.1 端口被占用：Cannot listen to HTTP port: Address already in use (os error 98)

8.2 配置热重载失败：Invalid top-level directive

8.3 KDL 语法错误：花括号未闭合

8.4 HTTP Basic 认证哈希粘贴错误：Unexpected newline in single-line quoted string

8.5 服务反复崩溃后无法直接重启

九、升级、降级与多版本管理

十、卸载与清理

十一、参考链接

8.1 端口被占用：`Cannot listen to HTTP port: Address already in use (os error 98)`

8.2 配置热重载失败：`Invalid top-level directive`

8.4 HTTP Basic 认证哈希粘贴错误：`Unexpected newline in single-line quoted string`