虚拟世界的懒猫

FileHunter 实战：5 个场景配置详解

· · 约 13 分钟阅读 · 技术分享

本文通过 5 个真实场景演示 FileHunter 的配置方法：静态资源分发服务、NFS 多节点并发搜索、版本化资产分级存储、内部文件服务器认证保护、公网部署安全加固。每个场景附完整 TOML 配置文件，可直接复制使用。帮助你根据实际业务需求选择合适的搜索模式和安全策略，快速搭建高性能文件服务。

模式 行为 最佳场景
sequential 按配置顺序逐个检查，首次命中即返回 本地磁盘，需要优先级控制
concurrent 并行探测所有目录，最快响应胜出 NFS/网络存储，延迟不可控
latest_modified 检查所有目录，返回 mtime 最新的文件 镜像存储，分级部署

场景一：静态资源分发服务

需求： Web 应用的图片、文档、视频分目录存放，通过不同 URL 前缀对外提供服务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
[server]
bind = "0.0.0.0:8080"
max_file_size = "50MB"

[server.cors]
enabled = true
allow_origins = ["https://app.example.com"]
allow_methods = ["GET", "HEAD"]
max_age = 3600

[[locations]]
prefix = "/images"
mode = "sequential"
max_file_size = "20MB"

[[locations.paths]]
root = "/data/images"
extensions = ["jpg", "jpeg", "png", "gif", "webp", "svg"]

[[locations]]
prefix = "/docs"
mode = "sequential"

[[locations.paths]]
root = "/data/documents"
extensions = ["pdf", "docx", "xlsx"]

[[locations]]
prefix = "/videos"
max_file_size = "500MB"

[[locations.paths]]
root = "/data/videos"
extensions = ["mp4", "mkv", "webm"]

要点：

  • 三个前缀各自限定文件类型，防止越权访问
  • 每个 location 可独立设置 max_file_size，视频允许更大文件
  • CORS 配置允许前端跨域请求文件
  • 请求 GET /images/logo.png → 在 /data/images 中搜索 logo.png

场景二：NFS 多节点并发搜索

需求： 文件分布在多台 NFS 服务器上，延迟不可预测，需要最快响应。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[server]
bind = "0.0.0.0:8080"
connection_timeout = 600

[[locations]]
prefix = "/shared"
mode = "concurrent"

[[locations.paths]]
root = "/mnt/nfs-node-a/files"

[[locations.paths]]
root = "/mnt/nfs-node-b/files"

[[locations.paths]]
root = "/mnt/nfs-node-c/files"

要点：

  • concurrent 模式同时探测所有 NFS 节点，第一个响应的胜出
  • 剩余探测任务立即取消，避免资源浪费
  • connection_timeout = 600 适应慢速网络存储
  • 适用于网络延迟高、节点性能不均的环境
  • 注意：结果不确定性——同一文件在多个节点上存在时，不同请求可能返回不同节点的副本

场景三：版本化资产的分级存储

需求： 同一文件在生产、预发布、归档目录中可能有不同版本，始终提供最新版本。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[server]
bind = "0.0.0.0:8080"

[[locations]]
prefix = "/assets"
mode = "latest_modified"

[[locations.paths]]
root = "/data/production"

[[locations.paths]]
root = "/data/staging"

[[locations.paths]]
root = "/data/archive"

要点：

  • latest_modified 模式检查所有目录，返回修改时间（mtime）最新的文件
  • 推送新版本到 staging 目录后立即生效，无需操作 production 目录
  • 该模式无法提前退出，必须扫描所有 root 后才能决定返回哪个文件
  • 适合灰度发布、分级部署等需要版本管理的场景

场景四：内部文件服务器 + Basic Auth

需求： 团队内部文件共享，需要密码保护，但健康检查接口不受限。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[server]
bind = "0.0.0.0:8080"

[server.basic_auth]
enabled = true
username = "team"
password = "your-strong-password"
realm = "internal-docs"

[server.rate_limit]
enabled = true
requests_per_second = 20
burst_size = 50

[[locations]]
prefix = "/"

[[locations.paths]]
root = "/data/internal"

要点：

  • Basic Auth 使用常量时间比较防止计时攻击
  • /health 和 /ready 端点免认证，方便 K8s 探针和负载均衡器
  • 速率限制防止暴力破解：每 IP 每秒 20 请求，允许 50 的突发
  • 生产环境建议配合反向代理（Nginx）启用 TLS 保护传输中的凭据

场景五：公网部署全面安全加固

需求： 直接面向公网提供文件下载，需要完整的安全防护。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[server]
bind = "0.0.0.0:8080"
keepalive = true
connection_timeout = 300
max_header_size = "16KB"
max_headers = 100
max_body_size = "1MB"
max_file_size = "50MB"
stream_buffer_size = "128KB"

[server.cors]
enabled = true
allow_origins = ["*"]
allow_methods = ["GET", "HEAD"]
max_age = 86400

[server.rate_limit]
enabled = true
requests_per_second = 50
burst_size = 100
cleanup_interval = 300

[server.compression]
enabled = true
algorithms = ["gzip", "br"]
min_size = "1KB"

[[locations]]
prefix = "/public"
mode = "sequential"

[[locations.paths]]
root = "/data/public-assets"
extensions = ["jpg", "png", "webp", "pdf", "csv", "json"]

[[locations]]
prefix = "/"
mode = "sequential"

[[locations.paths]]
root = "/data/general"

要点：

  • connection_timeout 防御慢速连接（Slowloris）攻击
  • max_header_size / max_body_size 限制请求大小
  • 速率限制防止 DDoS 滥用，超限返回 429
  • gzip + Brotli 压缩减小文本类文件传输体积
  • extensions 白名单确保只暴露预期的文件类型
  • FileHunter 内置 X-Content-Type-Options: nosniff、路径遍历防护、dotfile 屏蔽等安全机制

三种搜索模式速查

模式 行为 最佳场景
sequential 按配置顺序逐个检查，首次命中即返回 本地磁盘，需要优先级控制
concurrent 并行探测所有目录，最快响应胜出 NFS/网络存储，延迟不可控
latest_modified 检查所有目录，返回 mtime 最新的文件 镜像存储，分级部署

单目录场景下三种模式行为完全一致，使用默认的 sequential 即可。

参考

配置文件的各字段含义和高级功能（CORS、速率限制、压缩等），请参考 FileHunter Wiki。