Lighttpd 1.4.85 常用 CLI 命令详解

Lighttpd 命令行工具链全实测：-h/-v/-V/-t/-tt/-p/-f/-m/-D/-i 全选项、TERM 与 USR1 信号、systemd 日常命令、lighty-enable-mod 与 lighttpd-angel 守护，含上线组合与排障 FAQ（2026-10-20）。

LighttpdLighttpd网络配置2026/10/21

Lighttpd 1.4.85 常用 CLI 命令详解

目标：把 lighttpd 命令行工具链——主程序 lighttpd 的全部选项、信号控制、systemd 场景命令与辅助工具 lighttpd-angel/lighty-enable-mod——逐一讲清并全部实测；所有回显逐行照抄自 Ubuntu 22.04.5 真实环境（1.4.85 编译版为主，apt 版 1.4.63 对照），覆盖从语法自检、调试到优雅重启的日常运维全流程。

一、环境信息

本文所有命令与回显的实测环境：

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • lighttpd 1.4.85：官方源码 meson 编译（前缀 /usr/local/lighttpd，二进制 /usr/local/lighttpd/sbin/lighttpd，测试配置 /usr/local/lighttpd/etc/lighttpd-min.conf，监听 80 端口，站点根 /srv/www）
  • lighttpd 1.4.63：Ubuntu apt 包（1.4.63-1ubuntu3.1，二进制 /usr/sbin/lighttpd，配置 /etc/lighttpd/lighttpd.conf，systemd 服务 lighttpd.service）
  • 实测日期：2026-10-20；两版 -h 帮助均已采集对照，差异处单独标注

二、命令行总览（lighttpd -h）

先看 1.4.85 的完整帮助（lighttpd -h，编译版实测）：

/usr/local/lighttpd/sbin/lighttpd -h

实测回显（全文）：

lighttpd/1.4.85 (ssl) - a light and fast webserver
usage:
 -f <name>  filename of the config-file ('-' for stdin)
 -m <name>  module directory (default: /usr/local/lighttpd/lib/lighttpd)
 -i <secs>  graceful shutdown after <secs> of inactivity
 -1         process single (one) request on stdin socket, then exit
 -p         print the parsed config-file in internal form, and exit
 -t         test config-file syntax, then exit
 -tt        test config-file syntax, load and init modules, then exit
 -D         don't go to background (default: go to background)
 -v         show version
 -V         show compile-time features
 -h         show this help

apt 版 1.4.63 的帮助与此几乎一致（首行版本为 lighttpd/1.4.63 (ssl)，-f 行无 '-' for stdin 说明），选项集合相同，下文命令两版通用。

选项作用典型场景
-f <file>指定配置文件一切操作的前提；-f - 表示从标准输入读配置
-m <dir>指定模块目录多实例/自定义构建时加载不同模块集
-i <secs>空闲 N 秒后优雅退出短生命周期任务、滚动替换
-1只处理一个 stdin 套接字请求后退出xinetd/inetd 按需拉起场景
-p打印解析后的配置并退出检查 include 展开与变量实际取值
-t只查配置语法快速校验
-tt语法检查 + 加载并初始化模块上线前完整自检（推荐）
-D前台运行（默认后台 daemon 化）systemd 托管必须
-v / -V版本 / 编译特性版本确认与能力盘点
-h帮助速查

三、版本与特性查询（-v / -V）

-v 一行给出版本与 TLS 后端：

/usr/local/lighttpd/sbin/lighttpd -v

实测回显：

lighttpd/1.4.85 (ssl) - a light and fast webserver

-V 输出编译期特性全集（事件机制、网络后端、压缩算法、TLS 后端、PCRE 等，+ 启用 - 未启用）：

/usr/local/lighttpd/sbin/lighttpd -V

实测回显（节选，全文含 27 行特性清单）：

Event Handlers:

        + poll (Unix)
        + epoll (Linux)
        - kqueue (FreeBSD)

Network handler:

        + linux-sendfile
        + writev
        + write

Features:

        + IPv6 support
        + zlib support
        + zstd support
        - bzip2 support
        + brotli support
        + OpenSSL support
        - Nettle support
        + PCRE support
        - MySQL support
        - PgSQL support
        - PAM support
        + inotify support
        - LUA support
        + Y2038 support

解读：排查「为什么某功能不生效」时先看 -V——比如实测编译版 - bzip2 support（meson 配置未启用 bzip2，需要时加 -Dwith_bzip2=enabled 重新构建）、- LUA support（未启用 mod_magnet 所需的 Lua）。注意 FastCGI/rewrite/alias 等 1.4.71+ 已并入主程序的模块不在 -V 特性清单也不生成独立 .so（本文构建的 19 个 .so 中没有 mod_fastcgi）。对照 apt 版 1.4.63（lighttpd -V 实测节选）则显示 + MySQL support、+ PgSQL support、+ DBI support 等发行版全量特性——同一命令快速分辨两套二进制的能力差异。

四、配置检查与调试（-t / -tt / -p / -f / -m）

本组是改配置后、重启前的标准动作，全部实测。

4.1 -t：语法快速检查

/usr/local/lighttpd/sbin/lighttpd -t -f /usr/local/lighttpd/etc/lighttpd-min.conf

实测回显：

Syntax OK

退出码 0；配置文件不存在时给出明确报错与退出码 255（实测 -tt -f /tmp/nonexist.conf）：

2026-10-20 17:06:44: (../src/configfile.c.2295) opening configfile /tmp/nonexist.conf failed: No such file or directory

4.2 -tt：语法 + 模块加载完整自检（推荐）

/usr/local/lighttpd/sbin/lighttpd -tt -f /usr/local/lighttpd/etc/lighttpd-min.conf && echo CONFIG-TEST-OK

实测回显：

CONFIG-TEST-OK

-tt 与 -t 的区别：-tt 会真正加载并初始化所有模块，能暴露「模块指令写错/模块未加载」类问题（实测：配置里写了 dir-listing.activate 但未加载 mod_dirlisting 时，-tt 打出 WARNING: unknown config-key: dir-listing.activate (ignored)，退出码仍为 0——告警要看输出而非只看返回码）。

4.3 -p：打印解析后的配置（调试 include 与变量）

/usr/local/lighttpd/sbin/lighttpd -p -f /usr/local/lighttpd/etc/lighttpd-min.conf

实测回显（头部，全文 61 行）：

config {
    var.CWD                     = "/"
    var.PID                     = 7184
    server.modules              = (
        "mod_accesslog",
        "mod_dirlisting",
        "mod_access",
        "mod_alias",
        "mod_auth",
        "mod_authn_file",
        "mod_deflate",
        "mod_redirect",
        "mod_rewrite",
        "mod_openssl",
        "mod_h2",
    )
    server.document-root        = "/srv/www"
    server.bind                 = "0.0.0.0"
    server.port                 = 80
    server.pid-file             = "/usr/local/lighttpd/var/run/lighttpd.pid"
    server.errorlog             = "/usr/local/lighttpd/var/log/error.log"
    accesslog.filename          = "/usr/local/lighttpd/var/log/access.log"
...

解读：-p 输出的是 include 展开变量代入后的最终生效配置，排查「改了配置却像没生效」「软链片段顺序问题」时最有用（Ubuntu apt 版配置含多个 include_shell，用它能看到展开后的真实结果）。

4.4 -f 与 -m：配置与模块路径

-f 指定配置（前文所有命令已反复使用）；-m 覆盖模块目录，默认值即 -h 中显示的 /usr/local/lighttpd/lib/lighttpd（编译版）或 /usr/lib/lighttpd（apt 版，ls /usr/lib/lighttpd/ 可见全部官方 .so）。多套构建并存时用它显式指定，避免加载错版本模块。

五、启动与前台运行（默认 daemonize / -D / -i）

5.1 默认后台运行

不带 -D 时 lighttpd 解析配置后 fork 到后台（父进程立即返回）：

/usr/local/lighttpd/sbin/lighttpd -f /usr/local/lighttpd/etc/lighttpd-min.conf
echo rc=$?

实测回显：

rc=0

随后进程常驻、监听配置端口（curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/ 实测输出 200）；主进程号写入 server.pid-file 指定的文件（实测 /usr/local/lighttpd/var/run/lighttpd.pid）。

5.2 -D：前台运行

-D 让进程驻留前台不 fork，这是 systemd 托管的推荐形态（apt 版单元文件 ExecStart=/usr/sbin/lighttpd -D -f /etc/lighttpd/lighttpd.conf 即此用法，见 B1 4.2）。实测前台运行期间服务正常响应、进程随终端信号退出（timeout 3 包住 -D 运行，期间 curl 实测返回 200）。

5.3 -i：空闲 N 秒后优雅退出

/usr/local/lighttpd/sbin/lighttpd -f /usr/local/lighttpd/etc/lighttpd-min.conf -i 3
echo rc=$?
sleep 4
ps -eo pid,args | grep "[l]ighttpd/sbin/lighttpd -f" || echo IDLE-GONE

实测回显：

rc=0
IDLE-GONE

解读：-i 3 表示「连续 3 秒无活动即优雅退出」，实测进程在无请求窗口期自动消失；适合配合按需拉起机制，常规常驻服务不用它。

六、信号控制（TERM / USR1）

lighttpd 主进程响应两个常用信号，均实测验证：

6.1 SIGTERM：停止服务

kill -TERM $(cat /usr/local/lighttpd/var/run/lighttpd.pid)
sleep 1
tail -1 /usr/local/lighttpd/var/log/error.log

实测回显：

2026-10-20 17:05:22: (../src/server.c.2384) server stopped by UID = 0 PID = 7133

进程随即退出（ps 确认无该 PID）。

6.2 SIGUSR1：优雅重启（不停机加载新配置）

kill -USR1 $(cat /usr/local/lighttpd/var/run/lighttpd.pid)

实测行为链：错误日志先记录 server stopped by UID = 0 PID = 6936，随即记录 server started (lighttpd/1.4.85)；主进程 PID 保持不变（实测重载前后 cat pid 均为 7158），期间 curl 实测返回 200——即「老连接处理完、新配置生效、服务不断」。这正是 apt 版 systemd 单元 ExecReload=/bin/kill -USR1 $MAINPID 的原理（B1 4.2 有单元文件全文），生产改配置后的标准动作：lighttpd -tt 自检 → systemctl reload lighttpd。

💡 技术拓展：systemctl restart（stop+start）与 systemctl reload（USR1 优雅重启）的差别在连接处理——restart 会直接终止既有连接，reload 等待活跃请求结束再换配置；对线上静态/代理服务优先用 reload，只有进程异常时才 restart。

七、systemd 场景常用命令（apt 版实测）

Ubuntu 安装后的日常操作都走 systemd，以下为实测命令与回显（完整安装流程见 B1）：

systemctl is-active lighttpd && systemctl is-enabled lighttpd

实测回显：

active
enabled

systemctl status lighttpd --no-pager

实测回显（节选）：

● lighttpd.service - Lighttpd Daemon
     Loaded: loaded (/lib/systemd/system/lighttpd.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-10-20 16:25:39 UTC; 1min 12s ago
    Process: 1659 ExecStartPre=/usr/sbin/lighttpd -tt -f /etc/lighttpd/lighttpd.conf (code=exited, status=0/SUCCESS)
   Main PID: 1661 (lighttpd)
     Memory: 2.4M

失败排障两连（端口被占用场景的完整实录见 B1 FAQ Q1）：

journalctl -u lighttpd --no-pager -n 4

实测回显（端口占用时）：

Oct 20 16:26:35 ubuntu systemd[1]: Starting Lighttpd Daemon...
Oct 20 16:26:35 ubuntu lighttpd[2050]: 2026-10-20 16:26:35: (server.c.1494) can't bind to socket: 0.0.0.0:80: Address already in use
Oct 20 16:26:35 ubuntu systemd[1]: lighttpd.service: Main process exited, code=exited, status=255/EXCEPTION
Oct 20 16:26:37 ubuntu systemd[1]: lighttpd.service: Failed with result 'exit-code'.

模块片段启用器（Ubuntu 专属，非 lighttpd 本体命令；同目录有 lighttpd-enable-mod/lighttpd-disable-mod 等价别名）：

lighty-enable-mod cgi

实测回显：

Enabling cgi: ok
Run "service lighttpd force-reload" to enable changes

lighty-disable-mod cgi

实测回显：

Disabling cgi
Run "service lighttpd force-reload" to enable changes

实测说明：enable/disable 只增删 conf-enabled/ 软链；service lighttpd force-reload 成功时静默返回 0（用 && echo OK 验证），等价于 systemctl reload lighttpd。

八、辅助工具：lighttpd-angel（守护拉起）

编译安装时同时产出 /usr/local/lighttpd/sbin/lighttpd-angel。其手册页（源码包随附 man8/lighttpd-angel.8）明确：它监视并守护 lighttpd 守护进程——作为父进程拉起 lighttpd，除自己发出的信号外，子进程因任何原因退出都会被重新拉起；SIGTERM 触发立即关闭、SIGINT 触发优雅关闭、SIGHUP 触发优雅重启。实测运行记录：

lighttpd-angel.c.107: child (pid=6975) exited normally with exitcode: 0

解读：lighttpd-angel -f <config> 会以与 lighttpd 相同的参数启动被守护进程；在有 systemd 的现代系统上，生产环境优先用 Restart=on-failure 的服务单元（B1 5.6），lighttpd-angel 更适合无 systemd 的嵌入式/脚本化管理场景。

九、常见问题（FAQ）

Q1：-t 通过了，启动却失败？

-t 只查语法；绑定端口、权限、日志路径等运行期问题要到启动时才暴露。实测案例：配置指向被占用的 80 端口时，-t/-tt 均通过，启动日志报 can't bind to socket: 0.0.0.0:80: Address already in use（完整排障见 B1 FAQ Q1）。习惯动作：-tt 自检 → 启动 → tail 错误日志确认 server started。

Q2：-p 和 -t 应该先用哪个？

改配置后先 -tt（含模块加载的完整自检），行为不符合预期时再 -p 看展开后的最终配置（include、变量代入是否如你所想，见 4.3 实测样例）。

Q3：怎么确认线上跑的到底是哪个版本/哪套二进制？

lighttpd -v 配合 systemctl status 里的 ExecStart 路径一起看：apt 版为 /usr/sbin/lighttpd（1.4.63），编译版为 /usr/local/lighttpd/sbin/lighttpd（1.4.85）；版本号直接写在 -v 首行。

Q4：pid 文件里的 PID 和实际进程对不上？

server.pid-file 必须与 systemd 单元/启动脚本一致，且 lighttpd 以该文件为准做优雅重启定位主进程；多实例并存时（如本文 lighttpd.service 与 lighttpd-local.service）确保各自配置的 pid 文件不同，否则 USR1 会发错进程。

Q5：如何一行命令完成「改配置 → 自检 → 生效」？

lighttpd -tt -f /etc/lighttpd/lighttpd.conf && systemctl reload lighttpd

实测要点：-tt 失败（退出码非 0）时 && 短路，reload 不会执行——这是最安全的上线组合。

十、参考链接

  1. lighttpd 手册页（编译版随附 /usr/local/lighttpd/share/man/man8/lighttpd.8；apt 版 man lighttpd）
  2. lighttpd-angel 手册页：man8/lighttpd-angel.8（源码包随附，守护行为见第八节）
  3. 官方 Wiki：https://redmine.lighttpd.net/projects/lighttpd/wiki
  4. 同专栏文档：《Lighttpd 介绍与选型指南》、《Ubuntu 22.04 安装 Lighttpd 指南》、《Lighttpd 1.4.85 配置参数详解》
  5. 本文实测：lighttpd 1.4.85（meson 编译）/ 1.4.63（apt），Ubuntu 22.04.5，实测日期 2026-10-20