jandrop/file-manager-ui

File Manager Web UI

File Manager API的现代、生产级Web界面，基于React、Vite和Material UI（Material Design 3）构建，提供美观且响应式的文件管理体验。

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

核心功能

🎨 现代UI/UX

• Material Design 3组件，带有流畅动画
• 深色与浅色模式，支持主题偏好持久化
• 响应式设计，在桌面、平板和移动设备上无缝工作
• 专业美学，具备生产环境就绪的外观

📁 文件管理

• 浏览目录，带有直观的面包屑导航
• 上传文件，支持拖放和进度跟踪
• 下载文件，可直接从浏览器操作
• 创建文件夹，带有验证功能
• 重命名文件/文件夹，支持内联编辑
• 删除文件/文件夹，带有确认对话框
• 搜索文件，支持实时过滤
• 文件类型图标，便于识别

⚡ 性能优化

• 快速加载，通过优化的Vite构建实现
• 缓存API调用，使用React Query
• 流畅动画和过渡效果
• 实时更新所有操作结果

快速开始

前置条件

需运行File Manager API，使用Docker Compose时UI容器会自动连接到API。

使用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
      - CORS_ORIGINS=["http://localhost:8764"]
    volumes:
      - /mnt/user:/mnt/user
    restart: unless-stopped
    networks:
      - file-manager-network

  file-manager-ui:
    image: docker.xuanyuan.run/jandrop/file-manager-ui:latest
    container_name: file-manager-ui
    ports:
      - "8764:8764"
    depends_on:
      - file-manager-api
    restart: unless-stopped
    networks:
      - file-manager-network

networks:
  file-manager-network:
    driver: bridge

运行命令：

bash
docker-compose up -d

访问UI：http://localhost:8764

独立使用

若已运行API，可单独启动UI：

bash
docker run -d \
  --name file-manager-ui \
  -p 8764:8764 \
  --link file-manager-api:file-manager-api \
  docker.xuanyuan.run/jandrop/file-manager-ui:latest

注意：UI容器需与API容器通信，使用--link或Docker网络。

配置说明

网络配置

UI需连接到API，默认nginx配置期望API位于http://file-manager-api:8000。

• Docker Compose：网络自动配置
• docker run：使用--link标志
• 自定义网络：创建网络并将两个容器加入同一网络

API密钥配置

若API需要密钥：

1. 首次访问时UI会提示输入密钥
2. 密钥存储在浏览器localStorage中
3. 自动包含在所有API请求中

也可通过浏览器控制台设置：

javascript
localStorage.setItem('api_key', 'your-api-key-here');

端口

• 8764：Web UI HTTP端口（默认）

支持的架构

镜像支持多种架构：

• linux/amd64（x86_64）
• linux/arm64（ARM 64位，Apple Silicon，树莓派）

Docker会自动拉取适合平台的架构版本。

详细功能

文件操作

• 上传文件：拖放支持、多文件选择、进度跟踪、大小验证
• 删除文件/文件夹：确认对话框、递归删除、警告提示
• 重命名：内联验证、冲突预防、键盘快捷键
• 创建文件夹：名称验证、路径显示、父目录处理

主题系统

• 浅色/深色模式切换
• 主题偏好持久化
• 平滑过渡动画
• WCAG合规颜色

文件类型图标

基于扩展名的智能图标：文件夹、图片、视频、音频、文档、表格、归档、代码文件等。

响应式设计

适配桌面、平板、移动设备的布局。

API兼容性

UI专为File Manager API设计，建议使用匹配版本的API和UI容器。

故障排除

• UI容器持续重启：检查API是否运行、是否在同一网络
• 无法访问UI：验证容器运行状态、端口映射、防火墙设置
• API连接错误：检查CORS设置、直接测试API健康状态
• 上传失败：检查文件大小限制、目标文件夹权限

反向代理示例（Nginx）

nginx
server {
    listen 80;
    server_name files.yourdomain.com;

    location / {
        proxy_pass http://localhost:8764;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /api/ {
        proxy_pass http://localhost:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

版本标签

• latest：最新稳定版
• 1.x.x：特定版本
• main：开发版

健康检查

UI包含健康检查，验证nginx运行状态：

bash
docker inspect --format='{{.State.Health.Status}}' file-manager-ui

技术栈

• React 18.2
• Vite 5
• Material UI 5（Material Design 3）
• TanStack Query（React Query）
• Nginx（服务和API代理）

许可证

本项目采用MIT许可证。

基于React构建 • 用Material UI美化 • 为性能优化