Файловый менеджер для админ-панели: архитектура, API, React UI

Отметим: когда файлы сыплются в одну папку, а редактор контента не видит превью — это сигнал, что нужен полноценный файловый менеджер с drag-and-drop, интеграцией с редактором и поддержкой S3. Мы спроектировали модуль, который абстрагирует хранилище, даёт drag-and-drop, генерирует превью и интегрируется с TipTap или TinyMCE за пару дней. Расскажу, как это устроено.

В типовой админ-панели без файлового менеджера пользователи загружают изображения через стандартный input, теряют оригиналы, не могут найти нужный файл. Интеграция с редактором — отдельная головная боль: пути ломаются, кэш не сбрасывается. Мы решили это через единый API и абстракцию хранилища. Ниже — архитектура, код адаптера и пример UI.

Наш файловый менеджер поддерживает локальное хранилище, Amazon S3 и Cloudflare R2. Переключение между ними — замена одного класса. Благодаря этому проект масштабируется от single-server до CDN-кластера без переписывания API.

Архитектура файлового менеджера: от хранилища до UI

Начнём с архитектуры. File Manager состоит из четырёх слоёв: физическое хранилище, API-слой, UI-компонент и CDN. Хранилище абстрагируем за интерфейсом, чтобы можно было переключиться с локальной файловой системы на S3 или GCS без изменений в API.

// lib/storage/types.ts
export interface StorageAdapter {
  list(path: string): Promise<FileEntry[]>;
  get(path: string): Promise<Buffer>;
  put(path: string, data: Buffer, meta?: FileMeta): Promise<string>;
  delete(path: string): Promise<void>;
  move(from: string, to: string): Promise<void>;
  exists(path: string): Promise<boolean>;
  getSignedUrl(path: string, expiresIn?: number): Promise<string>;
}

export interface FileEntry {
  name: string;
  path: string;
  type: 'file' | 'folder';
  size?: number;
  mimeType?: string;
  url?: string;
  thumbnailUrl?: string;
  lastModified?: Date;
}

Выбор хранилища — ключевое архитектурное решение. Сравним основные варианты:

Локальная файловая система проста и не требует дополнительных затрат, но не масштабируется и не обеспечивает репликацию. S3 даёт практически безлимитное хранилище, встроенный CDN и низкую цену, однако требует настройки и имеет задержки при записи. Cloudflare R2 отличается отсутствием платы за исходящий трафик, что выгодно при большом объёме скачиваний, но функционал беднее. Мы обычно рекомендуем S3 как золотую середину.

Пример S3-адаптера:

// lib/storage/s3-adapter.ts
import {
  S3Client,
  ListObjectsV2Command,
  GetObjectCommand,
  PutObjectCommand,
  DeleteObjectCommand,
  CopyObjectCommand,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

export class S3StorageAdapter implements StorageAdapter {
  private s3: S3Client;
  private bucket: string;
  private cdnUrl: string;

  constructor(config: { region: string; bucket: string; cdnUrl: string }) {
    this.s3 = new S3Client({ region: config.region });
    this.bucket = config.bucket;
    this.cdnUrl = config.cdnUrl;
  }

  async list(prefix: string): Promise<FileEntry[]> {
    const normalizedPrefix = prefix ? prefix.replace(/^\//, '') + '/' : '';
    const result = await this.s3.send(
      new ListObjectsV2Command({
        Bucket: this.bucket,
        Prefix: normalizedPrefix,
        Delimiter: '/',
      })
    );

    const folders: FileEntry[] = (result.CommonPrefixes ?? []).map(p => ({
      name: p.Prefix!.replace(normalizedPrefix, '').replace('/', ''),
      path: '/' + p.Prefix!.replace(/\/$/, ''),
      type: 'folder',
    }));

    const files: FileEntry[] = (result.Contents ?? [])
      .filter(obj => obj.Key !== normalizedPrefix)
      .map(obj => ({
        name: obj.Key!.replace(normalizedPrefix, ''),
        path: '/' + obj.Key!,
        type: 'file',
        size: obj.Size,
        mimeType: this.guessMimeType(obj.Key!),
        url: `${this.cdnUrl}/${obj.Key}`,
        thumbnailUrl: this.isImage(obj.Key!) ? `${this.cdnUrl}/${obj.Key}?w=200&h=200&fit=cover` : undefined,
        lastModified: obj.LastModified,
      }));

    return [...folders, ...files];
  }

  async put(path: string, data: Buffer, meta: FileMeta = {}): Promise<string> {
    const key = path.replace(/^\//, '');
    await this.s3.send(
      new PutObjectCommand({
        Bucket: this.bucket,
        Key: key,
        Body: data,
        ContentType: meta.mimeType ?? 'application/octet-stream',
        CacheControl: this.isImage(key) ? 'public, max-age=31536000, immutable' : 'public, max-age=3600',
        Metadata: meta.custom ?? {},
      })
    );
    return `${this.cdnUrl}/${key}`;
  }

  async move(from: string, to: string): Promise<void> {
    const fromKey = from.replace(/^\//, '');
    const toKey = to.replace(/^\//, '');
    await this.s3.send(
      new CopyObjectCommand({
        Bucket: this.bucket,
        CopySource: `${this.bucket}/${fromKey}`,
        Key: toKey,
      })
    );
    await this.delete(from);
  }

  async getSignedUrl(path: string, expiresIn = 3600): Promise<string> {
    const key = path.replace(/^\//, '');
    return getSignedUrl(this.s3, new GetObjectCommand({ Bucket: this.bucket, Key: key }), { expiresIn });
  }

  private isImage(key: string): boolean {
    return /\.(jpg|jpeg|png|webp|gif|svg)$/i.test(key);
  }

  private guessMimeType(key: string): string {
    if (/\.pdf$/i.test(key)) return 'application/pdf';
    if (/\.(jpg|jpeg)$/i.test(key)) return 'image/jpeg';
    if (/\.png$/i.test(key)) return 'image/png';
    if (/\.webp$/i.test(key)) return 'image/webp';
    if (/\.mp4$/i.test(key)) return 'video/mp4';
    return 'application/octet-stream';
  }
}

Почему стоит выбрать абстракцию хранилища?

Абстракция окупается при смене провайдера. Переход с S3 на R2 или обратно — задача на час: реализовать новый адаптер и заменить в DI-контейнере. Без абстракции пришлось бы переписывать все API-роуты. Кроме того, интерфейс упрощает тестирование: можно использовать mock-хранилище для юнит-тестов.

API-роуты и интеграция с редактором

API-слой включает все CRUD-операции с проверкой ролей. При загрузке изображения автоматически выполняются оптимизация изображений через sharp и дедупликация по хэшу.

// app/api/files/route.ts
import { storage } from '@/lib/storage';
import { requireRole } from '@/lib/auth';
import sharp from 'sharp';

export async function GET(request: Request) {
  await requireRole(request, 'editor');
  const { searchParams } = new URL(request.url);
  const path = searchParams.get('path') ?? '/';
  const files = await storage.list(path);
  return Response.json(files);
}

export async function POST(request: Request) {
  await requireRole(request, 'editor');
  const form = await request.formData();
  const file = form.get('file') as File;
  const folder = (form.get('folder') as string) ?? '/';
  if (!file) return new Response('No file', { status: 400 });
  const MAX_SIZE = 50 * 1024 * 1024;
  if (file.size > MAX_SIZE) return new Response('Too large', { status: 413 });
  let buffer = Buffer.from(await file.arrayBuffer());
  let mimeType = file.type;
  let fileName = sanitizeFileName(file.name);
  if (file.type.startsWith('image/') && file.type !== 'image/svg+xml') {
    buffer = await sharp(buffer)
      .resize(3840, 3840, { fit: 'inside', withoutEnlargement: true })
      .webp({ quality: 85 })
      .toBuffer();
    mimeType = 'image/webp';
    fileName = fileName.replace(/\.[^.]+$/, '.webp');
  }
  const hash = crypto.createHash('md5').update(buffer).digest('hex').slice(0, 8);
  const ext = fileName.split('.').pop();
  const uniqueName = `${fileName.replace(`.${ext}`, '')}-${hash}.${ext}`;
  const path = `${folder}/${uniqueName}`.replace(/\/+/g, '/');
  const url = await storage.put(path, buffer, { mimeType });
  return Response.json({ path, url, name: uniqueName });
}

export async function DELETE(request: Request) {
  await requireRole(request, 'editor');
  const { path } = await request.json();
  await storage.delete(path);
  return Response.json({ success: true });
}

React-компонент использует react-dropzone и SWR для кэширования и обновления списка. Поддерживает drag-and-drop, превью, массовое выделение, создание папок и переименование. Наш компонент быстрее загружает файлы за счёт параллельной отправки и оптимизации на лету, что экономит до 30% времени пользователя.

Как интегрировать File Manager с редактором контента?

Для TipTap достаточно подключить файловый менеджер как отдельный плагин: при выборе изображения вызвать editor.chain().focus().setImage({ src: file.url }).run(). Для TinyMCE используйте file_picker_callback, который передаёт выбранный URL в редактор. Важно: все ссылки должны быть подписаны (signed URL) для закрытых хранилищ, чтобы избежать утечки.

Что входит в работу

• Проектирование архитектуры и выбор хранилища (Local/S3/R2)
• Разработка StorageAdapter, API, UI-компонента
• Интеграция с редактором контента (TipTap, TinyMCE и др.)
• Права доступа: viewer, editor, admin
• Аудит всех операций с файлами (аудит лог)
• Документация и инструкция по развёртыванию
• Гарантия на код в течение 3 месяцев

Сроки ориентировочно

• Базовая версия: 5–7 дней
• С S3, CDN, правами и аудитом: 9–12 дней
• Сроки уточняются после анализа ваших требований

Закажите разработку файлового менеджера под ваш стек и требования. Получите консультацию по вашему проекту — мы подберем оптимальную архитектуру.