静态文件服务器

相关源文件

• .gitignore
• caddytest/integration/caddyfile_adapt/file_server_sort.caddyfiletest
• cmd/caddy/setcap.sh
• modules/caddyhttp/fileserver/browse.go
• modules/caddyhttp/fileserver/browse.html
• modules/caddyhttp/fileserver/browsetplcontext.go
• modules/caddyhttp/fileserver/browsetplcontext_test.go
• modules/caddyhttp/fileserver/caddyfile.go
• modules/caddyhttp/fileserver/staticfiles.go
• modules/caddyhttp/staticresp.go

静态文件服务器是 Caddy 的核心 HTTP 处理程序，用于从文件系统提供静态文件和目录。它提供全面的文件服务功能，包括目录浏览、安全控制、预压缩文件支持以及与各种文件系统后端的集成。

有关与文件服务结合使用的 URL 重写功能，请参阅重写。有关所提供文件的模板处理，请参阅模板。有关内容编码和压缩，请参阅内容编码。

核心架构

静态文件服务器实现为FileServer结构体，在 Caddy 的请求处理管道中充当 HTTP 中间件处理程序。

FileServer 组件结构

来源：modules/caddyhttp/fileserver/staticfiles.go97-175 modules/caddyhttp/fileserver/staticfiles.go186-259

请求处理流程

文件服务器通过定义良好的管道处理请求，该管道负责路径清理、文件系统访问、安全检查和响应生成。

文件服务管道

来源：modules/caddyhttp/fileserver/staticfiles.go261-571 modules/caddyhttp/fileserver/browse.go78-213

配置选项

FileServer可以通过 JSON 配置或 Caddyfile 指令进行配置。主要的配置字段控制文件系统行为、安全性以及功能的启用。

核心配置字段

字段	类型	目的
根目录	字符串	站点根目录路径
文件系统 (FileSystem)	字符串	文件系统后端标识符
隐藏	[]string	隐藏文件的全局模式
IndexNames	[]string	尝试的索引文件名
CanonicalURIs	*bool	启用/禁用 URI 规范化
StatusCode	WeakString	覆盖响应状态码
PassThru	bool	将 404 错误传递给下一个处理程序

Caddyfile 语法

文件服务器指令支持以下 Caddyfile 语法

file_server [<matcher>] [browse] {
    fs            <filesystem>
    root          <path>
    hide          <files...>
    index         <files...>
    browse        [<template_file>]
    precompressed <formats...>
    status        <status>
    disable_canonical_uris
    pass_thru
    etag_file_extensions <extensions...>
}

来源：modules/caddyhttp/fileserver/caddyfile.go51-67 modules/caddyhttp/fileserver/staticfiles.go97-175

目录浏览

当通过Browse配置启用目录浏览时，文件服务器会生成具有多种输出格式和自定义选项的目录列表。

浏览配置

排序和过滤

浏览功能支持由applySortAndLimit()方法控制的多种排序选项

• 排序依据：name、namedirfirst、size、time
• 顺序：asc（升序）、desc（降序）
• 过滤：用于limit、offset、layout的查询参数

来源：modules/caddyhttp/fileserver/browse.go52-72 modules/caddyhttp/fileserver/browsetplcontext.go143-189 modules/caddyhttp/fileserver/browsetplcontext.go220-264

安全特性

文件服务器实施了多项安全机制，以防止未经授权的访问和目录遍历攻击。

路径清理和文件隐藏

Windows 特定的安全性

在 Windows 平台上，文件服务器执行额外的安全检查

• 替代数据流 (ADS)：拒绝包含:字符的路径
• 8.3 短文件名：阻止包含~可能绕过隐藏规则的路径

来源：modules/caddyhttp/fileserver/staticfiles.go264-275 modules/caddyhttp/fileserver/staticfiles.go659-704

高级特性

预压缩文件支持

文件服务器可以在客户端支持的情况下自动提供预压缩版本的文件

支持的预压缩格式通过PrecompressedRaw字段配置，包括

• Brotli (.br 后缀)
• Zstandard (.zst 后缀)
• Gzip (.gz 后缀)

自定义文件系统

文件服务器通过FileSystem字段支持可插拔的文件系统后端，允许与以下各项集成

• 本地磁盘文件系统（默认）
• 自定义文件系统实现
• 云存储后端
• 虚拟文件系统

ETag 管理

文件服务器使用文件修改时间和大小生成强 ETags，或者在配置了EtagFileExtensions时从附带文件读取 ETags。

来源：modules/caddyhttp/fileserver/staticfiles.go428-476 modules/caddyhttp/fileserver/staticfiles.go214-238 modules/caddyhttp/fileserver/staticfiles.go730-741 modules/caddyhttp/fileserver/staticfiles.go744-761