Ferron 2.8.1 常用 CLI 命令详解

Ferron 2.8.1 命令行工具全解：ferron 主程序（serve 子命令/config-string/module-config）、ferron-passwd 口令哈希、ferron-precompress 预压缩、ferron-yaml2kdl 迁移与 systemd 服务管理，全部回显实测，2026-10-20。

Ferron网络配置Web 服务器2026/10/21

Ferron 2.8.1 常用 CLI 命令详解

目标：讲清 Ferron 2.8.1（官方最新稳定版）随包交付的全部命令行工具——主程序 ferron（含 serve 子命令与全局选项）、口令工具 ferron-passwd、预压缩工具 ferron-precompress、配置转换工具 ferron-yaml2kdl，以及与 systemd 服务 ferron.service 的日常管理命令。所有命令输入与回显均为真实环境逐行实测（实测日期 2026-10-20）。

一、环境信息

项值
操作系统Ubuntu 22.04.5 LTS（jammy），x86_64
软件版本Ferron 2.8.1（APT 方式安装，/usr/sbin 下四个二进制）
服务单元ferron.service（systemd 托管）
实测方式服务运行态 + 前台运行态对照；全部输出为原样抄录
实测日期2026-10-20

二、工具概览与前置条件

2.1 工具清单

Ferron 的 deb/脚本/ZIP 三种安装形态均包含同一组命令行工具（路径以 deb 安装为准）：

命令用途
/usr/sbin/ferron主程序：以 KDL 配置启动 Web 服务器，含 serve 快速静态服务子命令
/usr/sbin/ferron-passwd交互式生成 HTTP Basic 认证口令哈希
/usr/sbin/ferron-precompress为静态站点批量生成预压缩文件
/usr/sbin/ferron-yaml2kdl将 Ferron 1.x 的 YAML 配置转换为 2.x KDL 配置

一键脚本安装额外提供 /usr/bin/ferron-updater（安装器版本的升级器）。

2.2 前置条件

  • 已按《Ubuntu 22.04 安装 Ferron 指南》完成安装；四个二进制在 PATH 内（/usr/sbin 对 root 默认可见，普通用户用绝对路径或 sudo）。
  • 主程序启动需要 80/443 端口未被占用（占用冲突的报错见「九、常见问题」）。
  • 非特权用户实验时注意：ferron 主程序绑定 80/443 需 CAP_NET_BIND_SERVICE 能力（deb 安装的 systemd 单元已配置；手动前台实验建议换高位端口如 8088）。

三、ferron 主程序命令详解

3.1 总览：ferron --help

ferron --help

实测回显：

A fast, modern, and easily configurable web server with automatic TLS.

Usage: ferron [OPTIONS] [COMMAND]
       ferron <COMMAND>

Commands:
  serve  Quickly serve static files
  help   Print this message or the help of the given subcommand(s)

Options:
  -c, --config <FILE>                          Sets a custom config file path [default: /etc/ferron.kdl]
      --config-string <CONFIG>                 Sets a config string to use, this overrides the config file
      --config-adapter <CONFIG_ADAPTER>        Sets a config file adapter to use [default: kdl] [possible values: kdl, yaml-legacy]
  -m, --module-config                          Prints compile-time module configuration
  -h, --help                                   Print help
  -V, --version                                Print version

💡 说明：主程序命令形态有两种——带配置文件直接启动（ferron -c <文件>），或使用 serve 子命令快速起一个静态服务。生产守护进程由 systemd 单元以 ExecStart=/usr/sbin/ferron -c /etc/ferron.kdl 拉起，日常无需手工前台运行。

3.2 查看版本：ferron --version（-V）

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

排障价值：核对二进制版本、构建三元组（GNU/musl）与发布日期是否与官方下载页一致。

3.3 打印编译期模块清单：ferron --module-config（-m）

ferron --module-config

实测回显（该二进制内置的模块加载器清单）：

module_loaders:
  - "Core"
  - "Blocklist"
  - "Limit"
  - "ForwardProxyAuth"
  - "ForwardProxy"
  - "Buffer"
  - "Rewrite"
  - "StatusCodes"
  - "ForwardedAuth"
  - "Cache"
  - "DynamicCompression"
  - "Replace"
  - "ReverseProxy"
  - "Fcgi"
  - "Scgi"
  - "Cgi"
  - "StaticFileServing"

用途：确认当前安装是否包含所需模块（官方源码支持按 cargo feature 裁剪模块重新编译）。

3.4 指定配置文件启动：ferron -c <FILE>（--config）

ferron -c /etc/ferron.kdl

实测回显（前台运行，配置合法、端口空闲）：

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

进程随 Ctrl+C 终止；生产环境交给 systemd 托管。配置非法时的报错形态见「九、常见问题」。

3.5 内联配置启动：ferron --config-string <CONFIG>

免配置文件快速起服务（冒烟测试、临时静态服务）：

ferron --config-string ':8088 { root "/opt/servetest" }'

实测回显：

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

💡 说明：--config-string 会覆盖 -c 指定的配置文件；适合验证单块配置行为，正式配置仍应落盘到 ferron.kdl 并热重载。

3.6 serve 子命令：ferron serve

快速把一个目录变成静态站点，无需写配置文件。查看子命令帮助：

ferron serve --help

实测回显：

Quickly serve static files

Usage: ferron serve [OPTIONS]

Options:
  -p, --port <PORT>                              Sets the port to serve on [default: 3000]
  -l, --listen-ip <LISTEN_IP>                    Sets the IP address to serve on [default: 127.0.0.1]
  -r, --root <DIRECTORY>                         Sets the directory to serve static files from [default: .]
  -c, --credential <CREDENTIAL>                  Specifies a credential (like "username:password") for basic authentication
      --disable-brute-protection                 Disables brute-force protection for basic authentication
  -f, --forward-proxy                            Enables the forward proxy functionality
      --log <LOG_FILE_PATH>                      Specifies a file to log HTTP requests to
      --error-log <ERROR_LOG_FILE_PATH>          Specifies a file to log errors to
  -h, --help                                     Print help

实测运行（服务目录 /opt/servetest，内含 23 字节的 index.html）：

cd /opt/servetest && ferron serve -l 127.0.0.1 -p 3000 -r /opt/servetest

启动与访问的实测回显（访问日志随请求写入标准输出；带 --log 参数时写入文件，本例经重定向采集）：

HTTP server is listening on 127.0.0.1:3000...
127.0.0.1 - - [20/Oct/2026:17:16:16 +0000] "GET / HTTP/1.1" 200 23 "-" "curl/7.81.0"
127.0.0.1 - - [20/Oct/2026:17:16:16 +0000] "GET /nope HTTP/1.1" 404 1905 "-" "curl/7.81.0"

要点：

  • 默认只监听 127.0.0.1:3000（不对公网暴露，安全默认值），对外服务需显式 -l 0.0.0.0。
  • -c admin:q1w2e3r4 可为该目录加 Basic 认证（--disable-brute-protection 关闭防爆破）。
  • -f 将其变为正向代理（配合认证使用）。

3.7 help 子命令：ferron help [command]

ferron help serve

实测回显与 ferron serve --help 相同；ferron help 等价于 ferron --help。

四、ferron-passwd 命令详解

4.1 功能与用法

为 HTTP Basic 认证（配置文件中的 user 指令、serve 的 -c 凭据）生成口令哈希，支持 Argon2/PBKDF2/scrypt 三类哈希。纯交互式工具，不接受命令行明文口令参数：

ferron-passwd

实测回显（输入口令 q1w2e3r4）：

Password:
Confirm password:
The generated password hash: $argon2id$v=19$m=19456,t=2,p=1$KnOPoVFZIZsInafFvDLeAw$vHV8VXu1+EzeQKLHaGk7jr8he0jwk6/ub4Y7EcuUV5E

4.2 生成结果落入配置

将哈希写入 /etc/ferron.kdl 并热重载：

:80 {
  root "/var/www/ferron"
  status 401 realm="Restricted Area" users="admin"
  user "admin" "$argon2id$v=19$m=19456,t=2,p=1$KnOPoVFZIZsInafFvDLeAw$vHV8VXu1+EzeQKLHaGk7jr8he0jwk6/ub4Y7EcuUV5E"
}

实测三态验证：

请求方式结果
curl http://localhost/（无凭据）401
curl -u admin:q1w2e3r4 http://localhost/200
curl -u admin:wrongpass http://localhost/401（错误日志出现 Authorization failed for user "admin" and client "::ffff:127.0.0.1"）

五、ferron-precompress 命令详解

5.1 功能与用法

为静态站点目录批量预生成 .gz/.br/.zst/.deflate 四种压缩副本，配合配置指令 precompressed（默认关闭）让 Ferron 直接回源压缩文件，省去每次请求的实时压缩 CPU 开销：

ferron-precompress /var/www/ferron

实测回显（节选）：

Compressing "/var/www/ferron/assets/FunnelSans-Bold.woff2" into "/var/www/ferron/assets/FunnelSans-Bold.woff2.gz"...
Compressing "/var/www/ferron/assets/FunnelSans-Bold.woff2" into "/var/www/ferron/assets/FunnelSans-Bold.woff2.deflate"...
Compressing "/var/www/ferron/assets/FunnelSans-Bold.woff2" into "/var/www/ferron/assets/FunnelSans-Bold.woff2.zst"...

产物核对（实测目录清单节选）：

index.html  index.html.br  index.html.deflate  index.html.gz  index.html.zst
favicon.ico favicon.ico.br favicon.ico.deflate favicon.ico.gz favicon.ico.zst

5.2 帮助与参数

ferron-precompress --help

实测回显：

Precompresses assets

Usage: ferron-precompress [OPTIONS] <assets>...

Arguments:
  <assets>...  Paths to assets

Options:
  -t, --threads <threads>  Amount of threads [default: 64]
  -h, --help               Print help

默认 64 线程并发生成（低配机器可 -t 4 降载）；<assets> 支持一次传多个目录/文件。

六、ferron-yaml2kdl 命令详解

将 Ferron 1.x（YAML 配置世代）迁移到 2.x（KDL）的一键转换工具：

ferron-yaml2kdl <input> <output>

实测转换（输入一个最小 1.x YAML）：

printf 'hosts:\n  - domain: "example.com"\n    wwwroot: "/var/www/html"\n' > /tmp/ferron.yaml
ferron-yaml2kdl /tmp/ferron.yaml /tmp/ferron.kdl

实测输出文件 /tmp/ferron.kdl 内容：

// Converted by Ferron YAML to KDL converter

// Put global configurations here
globals {
    // Global configurations
}

// Put host configurations here
"example.com" {
    // Host configurations
    root "/var/www/html"
}

用途：1.x 升级 2.x 时批量迁移旧配置骨架，转换后需按 2.x 指令语义人工复核（日志指令、代理指令等写法已变化）。

七、systemd 服务管理命令

deb/脚本安装后由 ferron.service 托管（单元文件见安装指南），日常管理命令与实测回显：

sudo systemctl start ferron        # 启动
sudo systemctl stop ferron         # 停止
sudo systemctl restart ferron      # 重启
sudo systemctl reload ferron       # 热重载配置（kill -HUP，PID 不变）
sudo systemctl status ferron       # 状态
systemctl is-enabled ferron        # 开机自启（实测回显：enabled）

reload 的实测 journal（热重载全链路）：

Oct 20 17:44:43 ferron-web systemd[1]: Reloading Ferron web server...
Oct 20 17:44:43 ferron-web ferron[4395]: Reloading the server configuration...
Oct 20 17:44:43 ferron-web systemd[1]: Reloaded Ferron web server.

status 实测回显：

● 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...

日志溯源与跟进：

sudo journalctl -u ferron -f          # 跟踪服务日志
sudo tail -f /var/log/ferron/access.log   # 跟踪访问日志（配置了 log 指令时）

八、注意事项

  • ferron-passwd 只能交互输入：无 TTY 环境直接运行报 Error reading password: No such device or address (os error 6)（实测），不要试图用管道传口令；自动化场景需伪终端（如 script -c 或 pty 脚本）。
  • 哈希粘贴防污染：生成的哈希粘入 user 指令时混入换行/回车会导致 KDL 解析错误 Unexpected newline in single-line quoted string（实测）；粘贴后确认单行无尾随空白。
  • 未知指令静默忽略：主机块内写错的指令不会报错也不会生效（实测 bad_directive "x" 服务正常启动）；只有顶层未知指令在启动/热重载时报 Invalid top-level directive。
  • serve 的安全默认值：默认监听 127.0.0.1:3000 且带防爆破保护；对公网提供服务时显式指定 -l 0.0.0.0 并评估认证强度。
  • 前台运行即验证：改完配置先 ferron -c /etc/ferron.kdl 前台跑一次（端口冲突时临时换 --config-string 高位端口验证语法），确认无报错再 systemctl reload，可避免热重载失败引发的重启循环。

九、常见问题（FAQ）

9.1 端口被占用

前台启动实测报错：Error while running a server: Cannot listen to HTTP port: Address already in use (os error 98)。处理：sudo ss -ltnp | grep :80 定位占用进程；验证配置时改用 --config-string ':8088 { ... }' 换端口。

9.2 热重载失败后服务起不来

热重载时配置非法（如顶层未知指令）→ 进程退出 → Restart=on-failure 连续失败触发 systemd 限速（Start request repeated too quickly）。此时即使修好配置，systemctl start 仍会报 Job for ferron.service failed because the control process exited with error code（实测），正确恢复顺序：

sudo systemctl reset-failed ferron
sudo systemctl start ferron

9.3 reload 与 restart 如何选

reload（kill -HUP）原地重读配置，连接与 PID 保持，日常改配置用它；restart 用于二进制升级后或进程状态异常时。reload 不会重新加载二进制。

9.4 ZIP 部署没有 ferron-passwd 命令

ZIP 包自带四个二进制但不在 PATH，用相对/绝对路径调用（./ferron-passwd）或自行软链到 /usr/local/bin。

十、参考链接