FileHunter 部署指南：三种方式快速上手

FileHunter 是一款用 Rust 编写的高性能多路径文件搜索 HTTP 服务器，编译后仅约 3MB。本文介绍三种部署方式：从 GitHub Release 下载预构建二进制文件、Docker 容器化部署、从源码编译。涵盖配置文件编写、Docker Compose 编排、systemd 服务管理的完整流程，帮助你在 5 分钟内将 FileHunter 部署到生产环境。适合需要跨目录文件服务、静态资源分发的运维和后端开发者。

什么是 FileHunter

FileHunter 通过 URL 前缀路由请求到不同的文件搜索目录组，找到文件后以 chunked streaming 方式返回，找不到则返回 404。典型场景：文件分散在多个存储路径，需要通过统一的 HTTP 接口对外提供服务。

核心特性：

• 多前缀 URL 路由，按 location 隔离不同类型文件
• 三种搜索模式：顺序、并发、最新修改时间
• 自动协商 HTTP/1.1 & HTTP/2
• 路径遍历防护、dotfile 屏蔽等安全加固
• 可选 Basic Auth、CORS、速率限制、响应压缩

---

方式一：从 GitHub Release 下载二进制文件

最快的上手方式——直接下载预构建的二进制文件，无需安装 Rust 工具链。

1. 下载

访问 Releases 页面，根据你的系统架构选择对应的压缩包：

平台	文件名
Linux x86_64 (glibc)	filehunter-x86_64-unknown-linux-gnu.tar.gz
Linux x86_64 (musl/Alpine)	filehunter-x86_64-unknown-linux-musl.tar.gz
Linux ARM64 (glibc)	filehunter-aarch64-unknown-linux-gnu.tar.gz
Linux ARM64 (musl/Alpine)	filehunter-aarch64-unknown-linux-musl.tar.gz
macOS x86_64 (Intel)	filehunter-x86_64-apple-darwin.tar.gz
macOS ARM64 (Apple Silicon)	filehunter-aarch64-apple-darwin.tar.gz

命令行下载示例（以 Linux x86_64 为例）：

# 下载最新版本
curl -LO https://github.com/finch-xu/filehunter/releases/latest/download/filehunter-x86_64-unknown-linux-gnu.tar.gz

# 校验完整性（可选）
curl -LO https://github.com/finch-xu/filehunter/releases/latest/download/checksums-sha256.txt
sha256sum -c checksums-sha256.txt --ignore-missing

# 解压
tar xzf filehunter-x86_64-unknown-linux-gnu.tar.gz

# 移动到系统路径（可选）
sudo mv filehunter /usr/local/bin/

提示： musl 版本为静态链接，适合 Alpine Linux 或无 glibc 的极简环境。

2. 编写配置文件

创建 config.toml：

[server]
bind = "0.0.0.0:8080"
max_file_size = "10MB"

[[locations]]
prefix = "/"

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

这是最简配置：监听 8080 端口，所有请求路由到 /data/files 目录。

3. 启动

filehunter --config config.toml

开启 debug 日志查看请求详情：

RUST_LOG=filehunter=debug filehunter --config config.toml

4. 验证

# 健康检查
curl http://localhost:8080/health

# 请求文件（假设 /data/files/photo.jpg 存在）
curl -I http://localhost:8080/photo.jpg

5. 注册为 systemd 服务（可选）

创建 /etc/systemd/system/filehunter.service：

[Unit]
Description=FileHunter File Search Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/filehunter --config /etc/filehunter/config.toml
Environment=RUST_LOG=filehunter=info
Restart=on-failure
User=filehunter
Group=filehunter
NoNewPrivileges=true
ProtectSystem=strict
ReadOnlyPaths=/data

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now filehunter

---

方式二：Docker 部署

1. 准备配置文件

config.toml（路径必须与容器内 volume 挂载路径一致）：

[server]
bind = "0.0.0.0:8080"
max_file_size = "50MB"

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

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

[[locations]]
prefix = "/"

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

2. 使用 GHCR 预构建镜像（推荐）

无需本地编译，直接拉取官方镜像（支持 amd64 和 arm64）：

docker run -d \
  --name filehunter \
  -p 8080:8080 \
  --read-only \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  -v ./config.toml:/etc/filehunter/config.toml:ro \
  -v /data/images:/data/images:ro \
  -v /data/general:/data/general:ro \
  ghcr.io/finch-xu/filehunter:latest

3. Docker Compose（推荐）

创建 docker-compose.yml：

services:
  filehunter:
    image: ghcr.io/finch-xu/filehunter:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.toml:/etc/filehunter/config.toml:ro
      - /data/images:/data/images:ro
      - /data/general:/data/general:ro
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    restart: unless-stopped

docker compose up -d

提示： 每个 config.toml 中的 root 路径都需要对应一条 volume 挂载。增减 location 时同步更新 volumes 列表。

安全加固说明：

• read_only: true：容器根文件系统只读
• cap_drop: ALL：移除所有 Linux capabilities
• no-new-privileges：禁止提权
• 所有 volume 均以 :ro 只读挂载

4. 本地构建镜像（可选）

如果需要自定义 Dockerfile：

docker build -t filehunter .
docker run -d -p 8080:8080 \
  -v ./config.toml:/etc/filehunter/config.toml:ro \
  -v /data/files:/data/files:ro \
  filehunter:latest

---

方式三：从源码编译

适合需要自定义修改或贡献代码的开发者。

1. 前置要求

• Rust 1.93+（edition 2024）

# 安装 Rust（如未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. 编译

git clone https://github.com/finch-xu/filehunter.git
cd filehunter

# Release 编译，启用 LTO + strip，产物约 3MB
cargo build --release

编译产物位于 ./target/release/filehunter。

3. 运行

./target/release/filehunter --config config.toml

后续的配置文件编写、验证、systemd 注册步骤与方式一相同。

---

三种方式对比

维度	Release 二进制	Docker 部署	源码编译
上手速度	最快，下载即用	快，需容器运行时	最慢，需 Rust 工具链
资源占用	最小（~3MB）	多一层容器开销	编译时占用较多
隔离性	依赖 systemd 加固	天然容器隔离	同 Release 二进制
自定义灵活性	无法修改源码	可自定义 Dockerfile	完全自定义
适用场景	大多数生产环境	K8s/容器编排环境	开发者/贡献者

---

下一步

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