Ferron 2.8.1 配置参数详解

目标：系统梳理 Ferron 2.8.1（官方最新稳定版）的全部配置参数：配置文件组织结构、修改与热重载流程、按功能域分类的指令清单（作用域/默认值/用法）、三套生产配置模板与真实排障记录。指令默认值以官方 2.8.1 版文档为准，配置行为均经真实环境实测验证（查询/实测日期 2026-10-20）。

一、环境信息

二、前置条件

• 已按《Ubuntu 22.04 安装 Ferron 指南》完成 Ferron 2.8.1 安装，systemctl status ferron 显示 active (running)。
• 了解 KDL 语法三要素：节点（指令名 + 空格分隔的参数值）、属性（key=value 形式的具名参数，布尔值用 #true/#false，空值用 #null）、子块（节点名 { ... } 花括号嵌套）；// 为行注释。
• 理解 Ferron 的配置作用域三层模型：仅全局（只能写在 globals 或 * 块）、全局+虚拟主机（两处均可，主机级覆盖全局）、通用（几乎所有块内可用）。每条指令的实际允许作用域见下文分类清单。

三、配置查看与修改方式

3.1 配置文件与组织结构

Ferron 2.x 的配置文件（默认 /etc/ferron.kdl）由「顶层块」组成，块名即虚拟主机匹配器：

主机块内的 location 块、condition/if/if_not 条件块、snippet 片段与 include 拆分详见「十一、路由、URL 处理与访问控制参数」。

3.2 修改与热重载实测流程

标准修改流程：编辑 /etc/ferron.kdl → sudo systemctl reload ferron → journal 溯源确认 → curl 验证行为。实测（给 :80 块加一条响应头指令后重载）：

:80 {
  root "/var/www/ferron"
  header "X-Test-Header" "ferron-reload-ok"
}

sudo systemctl reload ferron

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.

验证生效（实测回显，新增头已出现）：

curl -sI http://localhost/ | grep -iE "HTTP/|x-test|server:"

HTTP/1.1 200 OK
x-test-header: ferron-reload-ok
server: Ferron

热重载机制：systemd 单元中 ExecReload=kill -HUP $MAINPID，进程收到 SIGHUP 后原地重读配置，监听端口与进程 PID 均不变，适合反代后端不中断场景。

3.3 临时配置与免文件运行

不落盘验证配置用 --config-string 直接内联传入（实测，在 80 端口被占用时换 8088 冒烟测试）：

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

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

两个易踩的语义差异（均实测确认）：

• 顶层未知指令：热重载时进程直接报 Invalid top-level directive 退出，进入 systemd 重启循环（见「十四、常见问题」）。
• 主机块内未知指令：Ferron 2.8.1 静默忽略并正常启动——指令拼写错误不会导致服务失败，但也不会生效，排障时先核对拼写。

3.4 配置拆分与复用

• include "/etc/ferron/sites/*.kdl"：把站点配置拆分到独立文件（2.1.0+），主文件保持干净。
• snippet / use：定义可复用配置片段（2.6.0+ 支持跨 include 文件复用），如全局安全响应头只写一次。

四、参数总览（速查表）

高频指令速查（完整语义见后续各章；默认值为官方 2.8.1 文档口径）：

💡 布尔语义约定：KDL 中开关型指令的裸写（如 directory_listing）等价于 #true；#null 多用于「恢复默认/禁用」。

五、HTTP 核心与网络参数

仅全局指令，写在 globals 或 * 块（官方《core directives》页口径）：

六、日志与可观测参数

访问日志实测样例（默认 Combined 格式，::ffff: 前缀为 IPv4-mapped IPv6 表示）：

::ffff:127.0.0.1 - - [20/Oct/2026:17:11:57 +0000] "GET / HTTP/1.1" 200 2411 "-" "curl/7.81.0"

可用占位符（官方 placeholders 参考页）：{client_ip}、{auth_user}、{timestamp}、{method}、{path_and_query}、{version}、{status_code}、{content_length}、{header:Referer}、{header:User-Agent} 等。

七、静态文件与内容参数

预压缩实测：ferron-precompress /var/www/ferron 后站点目录出现成套压缩产物（实测清单节选）：

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
FunnelSans-Bold.woff2  FunnelSans-Bold.woff2.br  FunnelSans-Bold.woff2.gz  ...

八、缓存参数

HTTP 缓存模块（cache）参数（反代场景常用，静态文件本身有 file_cache_control 控制客户端缓存）：

九、反向代理与负载均衡参数

核心是 proxy 指令，可写多条实现上游池：

:80 {
  proxy "http://localhost:3000"
  proxy "http://localhost:3001"
  lb_algorithm "round_robin"
  lb_health_check
}

💡 技术拓展：lb_algorithm 四种负载均衡算法对比——

算法	调度策略	适用场景
random	纯随机选取	后端性能同质、请求量均匀
round_robin	依次轮转	后端性能同质、需要确定性分布
least_conn	当前并发请求数最少者	请求处理耗时不均（长连接/WebSocket 混布）
two_random（默认）	随机取两个、选并发更少者（power of two choices）	通用默认，兼顾随机性与负载感知

默认 two_random 是「随机 + 最少连接」的折中：无全局锁开销，负载倾斜概率远低于纯随机。

十、TLS 与安全参数

10.1 手工证书与协议级参数

10.2 自动 TLS（ACME）参数

💡 技术拓展：三种 ACME 质询方式对比——

质询	验证途径	前置条件	典型场景
http-01	80 端口回读令牌	80 可从公网访问	常规网站
tls-alpn-01（默认）	443 端口 TLS ALPN 握手	443 可从公网访问	只开 443 的站点
dns-01	DNS TXT 记录	DNS API 凭据	通配符证书、内网源站、CDN 后源站

dns-01 需以 provider=<服务商> 属性指定 DNS 服务商并配凭据（内置 Cloudflare、Route 53、bunny.net、deSEC、DigitalOcean、OVH、Porkbun 等 10+ 家）。

10.3 访问控制与限流参数

Basic 认证实测配置（生成哈希与生效验证）：

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

实测三态：无凭据 401；curl -u admin:<密码> 200；错误凭据 401，错误日志出现 Authorization failed for user "admin" and client "::ffff:127.0.0.1"。

十一、路由、URL 处理与访问控制参数

结构块（组合指令实现精细化路由）：

example.com {
  location "/api" {
    proxy "http://localhost:3000"
  }
  location "/static" {
    root "/var/www/assets"
  }
  condition "is_admin_ip" {
    is_remote_ip "10.0.0.0/8"
  }
  if_not "is_admin_ip" {
    status 403 body="Forbidden"
  }
}

• condition "<名>" { ... }：命名条件块，内部放 is_remote_ip/is_forwarded_for/is_equal/is_regex/is_not_*/is_rego（OpenPolicyAgent Rego 策略）/is_language 等判定指令。
• if "<名>" { ... } / if_not "<名>" { ... }：条件通过/不通过时生效的指令组。
• set_constant <k> <v>：定义配置内常量（2.1.0+）。

十二、应用后端参数（CGI/SCGI/FastCGI）

十三、生产配置模板

13.1 模板一：静态站点（资源需求：内存 ~6 MB / 磁盘 <100 MB）

globals {
  log "/var/log/ferron/access.log"
  error_log "/var/log/ferron/error.log"
  log_rotate_size 10485760
  log_rotate_keep 7
}

example.com {
  root "/var/www/site"
  precompressed
  file_cache_control "public, max-age=3600"
  header "X-Content-Type-Options" "nosniff"
  header "X-Frame-Options" "DENY"
  header "Referrer-Policy" "strict-origin-when-cross-origin"
  error_page 404 "/404.html"
}

适用：文档站、博客、下载站。precompressed 配合 ferron-precompress 预生成 .zst/.br/.gz 省运行时 CPU。

13.2 模板二：反向代理 + 缓存 + 限流（资源需求：内存 ~10-20 MB / 磁盘视缓存条目而定）

globals {
  log "/var/log/ferron/access.log"
  error_log "/var/log/ferron/error.log"
  buffer_request 65536
}

app.example.com {
  proxy "http://10.0.0.11:3000"
  proxy "http://10.0.0.12:3000"
  lb_algorithm "least_conn"
  lb_health_check
  cache
  cache_max_entries 4096
  cache_max_response_size 1048576
  limit rate=100 burst=400
  proxy_request_header_replace "X-Real-IP" "{client_ip}"
}

适用：为多个内网服务做统一 TLS 网关与流量防护。

13.3 模板三：PHP 站点（资源需求：内存 ~6 MB + PHP-FPM 自身开销 / 磁盘 <100 MB）

blog.example.com {
  root "/var/www/wordpress"
  fcgi_php "unix:///run/php/php-fpm.sock"
  index "index.php" "index.html"
}

适用：WordPress 等 PHP 应用。前置条件：PHP-FPM 池监听套接字的属主需改为 ferron 用户（listen.owner = ferron、listen.group = ferron），否则报 503（官方默认配置内注释亦提示此点）。

十四、常见问题（FAQ）

14.1 改了配置不生效或重载失败

先分层排查（均实测复现）：

1. sudo systemctl reload ferron 后 journal 出现 Reloading the server configuration... 即重载已触发；未出现则服务本体已挂，systemctl status ferron 看真相。
2. 顶层未知指令重载时报 Error while running a server: Invalid top-level directive at "/etc/ferron.kdl"，进程退出并触发 Restart=on-failure 重启循环；修复配置后需 sudo systemctl reset-failed ferron && sudo systemctl start ferron（失败计数不清除时直接 start 会报 Job for ferron.service failed）。
3. KDL 语法错误（如缺闭合花括号）前台运行会给出带行号的 miette 诊断：Failed to parse KDL document ... No closing '}' for child block。
4. 主机块内未知指令被静默忽略（如误写 bad_directive "x" 服务照常启动）——「改了没生效」先查拼写。

14.2 Basic 认证哈希导致解析错误

ferron-passwd 生成的哈希粘入 user 指令时夹带换行/回车，实测报 Unexpected newline in single-line quoted string（miette 定位到行:列）。确保哈希单行粘贴且无尾随空白。认证生效判据：无凭据/错误凭据 401、正确凭据 200，错误日志含 Authorization failed for user。

14.3 端口冲突

Error while running a server: Cannot listen to HTTP port: Address already in use (os error 98)：80/443 被占用。sudo ss -ltnp | grep :80 定位占用者；或用 :8080 形式块名换端口（注意：块名显式写端口后，auto_tls 默认逻辑关闭，需手工 tls 指令或 default_https_port 调整）。

14.4 域名块开了但 443 不通/证书没签下来

• 域名 DNS 未指向本机或 80/443 未对公网开放（云安全组/防火墙）；
• auto_tls_challenge 与可达端口不匹配（只开 80 用 http-01，只开 443 用默认 tls-alpn-01，内网/通配符用 dns-01）；
• 调试期可 auto_tls_letsencrypt_production #false 切 staging 环境规避限频。

十五、参考链接

• 官方配置文档（2.x 世代）：https://ferron.sh/docs（配置语法与指令参考）
• 配置基础页：https://www.ferronweb.org/docs/configuration/fundamentals/syntax
• Ferron 2.8.1 源码内配置文档（与二进制同源）：https://github.com/ferronweb/ferron/tree/2.8.1/docs
• DNS-01 服务商对接与凭据：官方文档 Automatic TLS 章节
• 本平台关联文档：《Ubuntu 22.04 安装 Ferron 指南》、《Ferron 介绍与选型指南》、《Ferron 2.8.1 常用 CLI 命令详解》