基于 OpenResty 的极简文件服务，面向 程序到程序 的调用场景： 列目录、查元信息、下载文件、流式打包 zip，全部带 Bearer Token 鉴权， 一个 Docker 镜像跑起来。

详细接口请看 API.md。

• RESTful 响应：成功体直接就是数据，错误体 { "error": "<code>", "message": "..." }，状态码表达成功/失败
• CORS 全开，预检 OPTIONS 自动应答
• Bearer Token 鉴权（支持多 token，逗号分隔；留空则关闭鉴权）
• 支持 Range 断点续传
• 流式 zip 打包（单路径 / 多路径批量、include/exclude/flatten）
• 递归 list（深度、glob 过滤、增量 since、NDJSON 流式输出）
• 实时计算 SHA-256，不做缓存
• 批量 stat，一次请求拿多个路径
• 每次请求 X-Request-Id 贯穿，方便排查

# 把你的文件放到 ./data 目录下（容器内只读挂载）
docker compose up --build
# 服务监听 http://localhost:8080

docker build -t ngx-filebox .
docker run --rm -p 8080:80 \
    -e FILEBOX_TOKENS=secret123 \
    -v /path/to/your/files:/data/files:ro \
    ngx-filebox

TOKEN=secret123
BASE=http://localhost:8080/api
H="Authorization: Bearer $TOKEN"

curl -sH "$H" "$BASE/health"
curl -sH "$H" "$BASE/list/"
curl -sH "$H" "$BASE/stat/some/file.txt"
curl -sH "$H" -o out.pdf "$BASE/file/some/file.pdf"
curl -sH "$H" -o archive.zip "$BASE/zip/some/dir"

变量	默认值	说明
FILEBOX_ROOT	/data/files	文件根目录绝对路径
FILEBOX_TOKENS	(空)	允许的 Bearer token，逗号分隔；空 = 不鉴权
FILEBOX_MAX_ZIP_FILES	10000	单次 zip 最大文件数
FILEBOX_MAX_ZIP_SIZE	10737418240	单次 zip 未压缩总大小上限（默认 10 GiB）
TZ	Asia/Shanghai	时区

方法	路径	说明
GET	/api/health	健康检查（无鉴权）
GET	/api/list/<path>	列目录（支持递归、过滤、增量、NDJSON）
GET	/api/stat/<path>	查单个条目元信息
GET	/api/file/<path>	下载文件（支持 Range）
GET	/api/zip/<path>	流式 zip 一个文件或目录
POST	/api/zip	批量 zip 多个路径（请求体传列表）
POST	/api/batch/stat	批量查询元信息

完整参数、请求体、响应格式、错误码请看 API.md。

.
├── Dockerfile
├── docker-compose.yml
├── nginx.conf
├── conf.d/filebox.conf
├── lua/
│   ├── entry.lua
│   └── filebox/
│       ├── auth.lua
│       ├── config.lua
│       ├── errors.lua
│       ├── path.lua
│       ├── response.lua
│       ├── router.lua
│       ├── sha256.lua
│       ├── util.lua
│       └── handlers/
│           ├── batch.lua
│           ├── file.lua
│           ├── list.lua
│           ├── stat.lua
│           └── zip.lua
├── API.md
└── README.md

• 符号链接 不会 被打进 zip（避免通过 symlink 逃出根目录），在 list / stat 里仍然会以 type: "symlink" 呈现。
• SHA-256 每次请求都实时计算，对大文件要注意请求耗时。
• JSON / NDJSON 响应在 nginx 层启用了 gzip。
• TLS、外层鉴权、审计等建议放在上游反代（Nginx / Caddy / 云厂 LB）上做。