jandrop/file-manager-api

File Manager API

一个强大的RESTful API服务，用于管理文件和目录，专为Unraid服务器设计，但可在任何Linux系统上运行。基于FastAPI构建，针对Docker部署进行了优化。

!https://img.shields.io/docker/pulls/jandrop/file-manager-api !https://img.shields.io/docker/image-size/jandrop/file-manager-api !https://img.shields.io/badge/license-MIT-blue.svg

核心功能

• 📁 文件浏览: 支持带排序和筛选选项的目录导航
• 📤 文件上传: 多文件上传，带大小限制和验证
• 📥 文件下载: 通过API直接流式传输文件
• 📂 目录操作: 创建、删除（支持递归选项）
• ✏️ 文件操作: 移动、复制、重命名和删除文件
• 🔍 搜索: 支持通配符的文件搜索
• 💾 磁盘使用: 实时磁盘空间信息
• 🔒 安全: API密钥认证和可配置权限
• 🌐 CORS支持: 适用于Web和移动应用
• ⚡ 性能: 异步/等待机制确保高性能操作

快速开始

基础使用

bash
docker run -d \
  --name file-manager-api \
  -p 8000:8000 \
  -v /mnt/user:/mnt/user \
  -e BASE_PATH=/mnt/user \
  -e API_KEY=your_secret_key \
  docker.xuanyuan.run/jandrop/file-manager-api:latest

访问API文档：http://localhost:8000/docs

使用Docker Compose（推荐）

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  file-manager-api:
    image: docker.xuanyuan.run/jandrop/file-manager-api:latest
    container_name: file-manager-api
    ports:
      - "8000:8000"
    environment:
      - BASE_PATH=/mnt/user
      - API_KEY=your_secret_key_here
      - MAX_UPLOAD_SIZE=10737418240  # 10GB
      - ENABLE_FILE_DELETION=true
      - ENABLE_RECURSIVE_DELETE=true
    volumes:
      - /mnt/user:/mnt/user
    restart: unless-stopped

然后运行：

bash
docker-compose up -d

环境变量

API端点

文件浏览

• GET /api/v1/files/browse - 列出目录内容
• GET /api/v1/files/info - 获取文件/目录信息

文件操作

• GET /api/v1/files/download - 下载文件
• POST /api/v1/files/upload - 上传文件
• DELETE /api/v1/files/file - 删除文件
• PUT /api/v1/files/rename - 重命名文件/目录
• POST /api/v1/files/move - 移动文件/目录
• POST /api/v1/files/copy - 复制文件/目录

目录操作

• POST /api/v1/files/directory - 创建目录
• DELETE /api/v1/files/directory - 删除目录

工具

• GET /api/v1/files/search - 搜索文件
• GET /api/v1/files/disk-usage - 获取磁盘使用信息
• GET /health - 健康检查端点

使用示例

浏览目录

bash
curl "http://localhost:8000/api/v1/files/browse?path=/mnt/user/documents"

上传文件

bash
curl -X POST \
  -H "X-API-Key: your_secret_key" \
  -F "file=@/path/to/file.pdf" \
  -F "destination_path=/mnt/user/uploads" \
  http://localhost:8000/api/v1/files/upload

下载文件

bash
curl -H "X-API-Key: your_secret_key" \
  -O "http://localhost:8000/api/v1/files/download?path=/mnt/user/file.txt"

搜索文件

bash
curl "http://localhost:8000/api/v1/files/search?path=/mnt/user&query=*.pdf"

认证

要启用API密钥认证，设置API_KEY环境变量：

bash
docker run -d \
  -e API_KEY=your_secret_key \
  docker.xuanyuan.run/jandrop/file-manager-api:latest

然后在请求中包含密钥：

bash
curl -H "X-API-Key: your_secret_key" \
  http://localhost:8000/api/v1/files/browse?path=/mnt/user

卷

挂载需要管理的文件系统目录：

bash
# 适用于Unraid
-v /mnt/user:/mnt/user

# 适用于特定目录
-v /path/to/files:/mnt/user

# 多个卷
-v /data:/data
-v /media:/media

端口

• 8000 - API HTTP端口（默认）

健康检查

API包含健康检查端点/health：

bash
curl http://localhost:8000/health

响应：

json
{
  "status": "healthy",
  "base_path": "/mnt/user",
  "base_path_exists": true
}

支持的架构

该镜像支持多种架构：

• linux/amd64 (x86_64)
• linux/arm64 (ARM 64位，Apple Silicon，树莓派)

Docker会自动为你的平台拉取正确的架构版本。

Web UI（可选）

需要Web界面？可搭配File Manager UI使用：

yaml
services:
  file-manager-api:
    image: docker.xuanyuan.run/jandrop/file-manager-api:latest
    # ... 配置

  file-manager-ui:
    image: docker.xuanyuan.run/jandrop/file-manager-ui:latest
    ports:
      - "8764:8764"
    depends_on:
      - file-manager-api

安全考虑

• 使用API密钥: 生产环境中务必设置API密钥
• 配置CORS: 将CORS_ORIGINS限制为仅受信任的应用
• 使用HTTPS: 生产环境中通过反向代理启用SSL/TLS
• 文件权限: 确保正确的文件系统权限
• 网络隔离: 使用Docker网络隔离容器
• 监控访问: 定期检查日志中的可疑活动

故障排除

权限错误

如果遇到权限问题：

bash
# 查看容器日志
docker logs file-manager-api

# 验证挂载路径是否存在
docker exec file-manager-api ls -la /mnt/user

无法访问文件

• 验证BASE_PATH是否设置正确
• 检查卷是否正确挂载
• 确保目录存在且有正确权限

健康检查失败

bash
# 检查API是否响应
docker exec file-manager-api curl http://localhost:8000/health

# 查看详细日志
docker logs file-manager-api

文档

• API文档: 可在http://localhost:8000/docs访问（Swagger UI）
• 替代文档: 可在http://localhost:8000/redoc访问（ReDoc）

版本标签

• latest - 最新稳定版本
• 1.x.x - 特定版本标签
• main - 最新开发构建

基于FastAPI构建 • Docker驱动 • 针对Unraid优化