Lighttpd 配置选项介绍

根据提供的 Lighttpd 配置选项文档（https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_ConfigurationOptions ），以下是所有配置选项的详细解释、作用及适用场景，按模块分组说明：

---

以下是对 Lighttpd 配置选项 的完整详解，依据官方文档结构逐模块、逐选项解释其作用及使用场景：

---

一、Lighttpd Core (核心配置)

基本服务设置

1. server.name
   • 作用：定义服务器或虚拟主机的名称（Hostname）。
   • 场景：多虚拟主机时区分不同站点，影响 Host 头匹配。
2. server.document-root
   • 作用：网站文件的根目录路径。
   • 场景：必需项，例如 server.document-root = "/var/www/html"。
3. server.error-handler (>=1.4.40)
   • 作用：非动态请求（非CGI/代理）返回 HTTP 状态码 ≥400 时，调用指定 URI 处理。
   • 场景：自定义错误页面，如 server.error-handler = "/error-handler.php"。
4. server.error-handler-404
   • 作用：针对 403/404 错误调用指定 URI。
   • 场景：单独处理资源不存在或权限错误。
5. server.errorfile-prefix
   • 作用：预定义错误页面路径前缀（如 /error-404.html）。
   • 场景：快速部署静态错误页。
6. server.error-intercept (>=1.4.46)
   • 作用：是否允许 server.error* 覆盖动态处理器的错误页。
   • 场景：统一管理所有错误响应。

网络与端口

7. server.bind
   • 作用：绑定 IP、主机名或 Unix 套接字路径（默认 "*"）。
   • 场景：多IP服务器限制监听特定地址。
8. server.port
   • 作用：监听端口（默认 80）。
   • 场景：HTTP 服务端口配置。
9. server.network-backend
   • 作用：选择系统网络 I/O 模型（如 linux-sendfile）。
   • 场景：高性能场景调优（需测试兼容性）。
10. server.listen-backlog
    • 作用：监听队列大小（默认受系统限制）。
    • 场景：高并发时防止连接丢弃（需调内核参数）。
11. server.use-ipv6
    • 作用：启用 IPv6 监听。
    • 场景：支持 IPv6 网络环境。
12. server.v4mapped (>=1.4.56)
    • 作用：允许 IPv6 套接字接收 IPv4 连接（禁用 IPV6_V6ONLY）。
    • 场景：双栈服务器简化配置。

日志管理

13. server.errorlog
    • 作用：错误日志文件路径。
    • 场景：记录服务器错误和警告。
14. server.errorlog-use-syslog
    • 作用：错误日志发送至 Syslog。
    • 场景：集中式日志管理。
15. server.syslog-facility (>=1.4.46)
    • 作用：指定 Syslog 设施（如 "local0"）。
    • 场景：分类日志到不同设施。
16. server.breakagelog
    • 作用：重定向 stderr（包括 CGI 错误）。
    • 场景：捕获子进程错误信息。

性能与安全

17. server.username / server.groupname
    • 作用：降权运行的用户/组。
    • 场景：提升安全性（避免 root 运行）。
18. server.chroot
    • 作用：设置服务根目录（隔离环境）。
    • 场景：高安全环境限制文件访问。
19. server.max-connections
    • 作用：最大并发连接数。
    • 场景：防资源耗尽（需配合系统限制）。
20. server.max-fds
    • 作用：最大文件描述符数。
    • 场景：高并发服务器调优（需调 ulimit）。
21. server.stream-request-body
    • 作用：流式传输请求体到后端。
    • 场景：大文件上传节省内存。

其他核心选项

22. server.pid-file
    • 作用：PID 文件路径。
    • 场景：服务管理工具定位进程。
23. mimetype.assign
    • 作用：MIME 类型映射表。
    • 场景：定义文件扩展名对应的 Content-Type。
24. etag.use-*
    • 作用：控制 ETag 生成方式（inode/mtime/size）。
    • 场景：缓存验证优化（集群环境需禁用 inode）。

---

二、Core Debug Info (调试选项)

25. debug.log-request-header
    • 作用：记录所有请求头。
    • 场景：排查客户端请求问题。
26. debug.log-file-not-found
    • 作用：记录未找到文件事件。
    • 场景：检查错误资源路径。
27. debug.log-ssl-noise
    • 作用：记录隐藏的 SSL 警告（如握手失败）。
    • 场景：TLS 连接问题诊断。
28. debug.log-response-header
    • 作用：记录响应头。
    • 场景：验证服务器返回的头部信息。

注：调试选项仅临时启用，避免生产环境长期使用。

---

三、模块配置 (按功能分类)

访问控制

• mod_access
  29. url.access-deny：禁止访问指定后缀文件（如 .htaccess）。
  30. url.access-allow (>=1.4.40)：仅允许访问指定后缀文件。

日志记录

• mod_accesslog
  31. accesslog.format：定义日志格式（类似 Apache 的 %h %l %u %t）。
  32. accesslog.filename：访问日志路径（如 /var/log/lighttpd/access.log）。

路径处理

• mod_alias
  33. alias.url：路径别名（如 "/img" => "/var/images"）。
• mod_evhost
  34. evhost.path-pattern：基于域名动态生成文档根目录（如 "/sites/%0"）。

认证与授权

• mod_auth
  35. auth.backend：认证后端（如 "plain"/"htpasswd"）。
  36. auth.require：限制访问策略（如 require user="admin"）。

压缩与缓存

• mod_deflate
  37. deflate.mimetypes：启用压缩的 MIME 类型（如 "text/"）。
  38. deflate.max-compress-size：压缩文件大小上限（默认 1MB）。
• mod_expire
  39. expire.url：为路径设置缓存过期时间（如 "/images" => "access 30 days"）。

目录与索引

• mod_dirlisting
  40. dir-listing.activate：启用目录列表（替代 server.dir-listing）。
  41. dir-listing.exclude：隐藏匹配正则的文件（如 "~$" 隐藏临时文件）。
• mod_indexfile
  42. index-file.names：默认索引文件（如 ("index.html", "index.php")）。

代理与网关

• mod_proxy / mod_fastcgi / mod_scgi
  43. *.server：定义后端服务器（如 ("host" => "127.0.0.1", "port" => 9000)）。
  44. *.balance：负载均衡算法（如 "round-robin"）。
  45. proxy.replace-http-host：替换代理请求的 Host 头。

高级处理

• mod_magnet
  46. magnet.attract-raw-url-to：用 Lua 脚本处理请求（如重写 URL）。
• mod_setenv
  47. setenv.add-response-header：添加响应头（如 "X-Custom-Header: value"）。

---

四、TLS/SSL 配置

mod_openssl (推荐)

48. ssl.engine：启用 SSL/TLS。
49. ssl.pemfile：证书链文件（PEM 格式）。
50. ssl.cipher-list：加密套件（如 "HIGH:!aNULL"）。
51. ssl.verifyclient.activate：启用客户端证书验证。

其他后端

• mod_gnutls / mod_mbedtls / mod_nss / mod_wolfssl：
  功能类似 mod_openssl，按需选择加密库。

---

五、废弃模块 (Deprecated)

• mod_compress → 由 mod_deflate 替代。
• mod_geoip → 由 mod_maxminddb 替代（支持 MMDB 格式）。
• mod_mysql_vhost → 由 mod_vhostdb 替代。

关键替代关系：

• compress.* → deflate.*
• geoip.db-filename → maxminddb.db
• mysql-vhost.* → vhostdb.mysql.*

---

总结

• 必选项：server.document-root、server.port、index-file.names。
• 安全建议：server.username/groupname、server.chroot、TLS 配置。
• 性能调优：server.max-connections、deflate.* 压缩、*.balance 负载均衡。
• 废弃模块：避免使用，优先替代方案。

此列表覆盖 所有文档提及选项，共 50+ 核心配置项及模块参数。实际配置时，需结合版本（如 ≥1.4.46 的新特性）和场景灵活选择。