Almacenamiento de archivos

FileField y ImageField almacenan los archivos subidos a través de un backend de almacenamiento que usted configura con el parámetro storage del campo.

Cree el backend de almacenamiento una sola vez y reutilícelo en todos los campos que guarden archivos en la misma ubicación.

Ejemplo mínimo

from contextlib import asynccontextmanager

from fastapi import FastAPI
from sqlalchemy import JSON, Integer, String, create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from starlette_admin import ImageField
from starlette_admin.contrib.sqla import Admin, ModelView
from starlette_admin.storage import LocalStorage

engine = create_engine("sqlite:///admin.sqlite")

local = LocalStorage(base_dir="uploads", name="local")


class Base(DeclarativeBase):
    pass


class Book(Base):
    __tablename__ = "book"

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    title: Mapped[str] = mapped_column(String(200))
    cover: Mapped[dict | None] = mapped_column(JSON, nullable=True)


class BookView(ModelView):
    fields = [
        "id",
        "title",
        ImageField("cover", storage=local, upload_folder="covers"),
    ]


@asynccontextmanager
async def lifespan(app: FastAPI):
    Base.metadata.create_all(engine)
    yield


app = FastAPI(lifespan=lifespan)

admin = Admin(engine, title="Bookstore", secret_key="change-me")
admin.add_view(BookView(Book))
admin.mount_to(app)

Cuando un usuario sube una portada a través del admin, este:

• guarda el archivo en uploads/covers/
• almacena un objeto JSON de metadatos en la columna cover

La base de datos nunca contiene el archivo en sí, una ruta del sistema de archivos ni datos binarios.

Qué se guarda en la base de datos

El admin representa un archivo subido como un objeto FileInfo serializado en el campo del modelo.

{
  "filename": "product-photo.jpg",
  "content_type": "image/jpeg",
  "size": 204800,
  "storage": "s3",
  "key": "uploads/products/a1b2c3_product-photo.jpg",
  "url": "https://..."
}

• filename: nombre de archivo original saneado, usado para mostrarlo
• content_type: tipo MIME detectado en el momento de la subida
• size: tamaño del archivo en bytes
• storage: nombre del backend registrado, usado para resolver la ubicación del archivo al generar URLs y al eliminarlo
• key: ruta relativa al almacenamiento o clave del objeto
• url: URL pública almacenada en caché

LocalStorage guarda un valor vacío en url, porque las URLs dependen de la petición activa. S3Storage guarda una URL pública o presignada, según su configuración.

Sea cual sea el backend, FileField regenera la URL en el momento de renderizar mediante storage.url() en lugar de confiar en el valor almacenado.

ImageField añade width y height.

El admin sanea cada nombre de archivo con secure_filename antes de almacenarlo: elimina los componentes de ruta y reemplaza los caracteres fuera de [A-Za-z0-9_.-] por _. Consulte Seguridad.

Backends de almacenamiento

Almacenamiento local

from starlette_admin.storage import LocalStorage

local = LocalStorage(base_dir="uploads", name="local")

El admin sirve los archivos a través de esta ruta:

/_files/{storage}/{path}

No necesita ninguna configuración adicional de archivos estáticos.

LocalStorage.url() construye las URLs a partir del contexto de la petición actual, por lo que el campo url almacenado permanece vacío y se recalcula bajo demanda.

Almacenamiento en Amazon S3

from starlette_admin.storage import S3Storage

s3 = S3Storage(
    bucket="my-bucket",
    prefix="admin/",
    region="eu-west-1",
    public=False,
)

Instale las dependencias opcionales:

pip install starlette-admin[s3]

Esto instala aiobotocore.

Cuando usted proporciona endpoint_url, el admin construye las URLs como:

{endpoint_url}/{bucket}/{key}

en lugar de usar el formato virtual-hosted de AWS.

Múltiples archivos (multiple=True)

Establezca multiple=True en un FileField o ImageField para aceptar varias subidas en un mismo campo.

from starlette_admin import FileField
from starlette_admin.contrib.sqla import ModelView
from starlette_admin.storage import LocalStorage

local = LocalStorage(base_dir="uploads/attachments", name="attachments")


class TicketView(ModelView):
    fields = [
        "id",
        "subject",
        FileField(
            "attachments",
            storage=local,
            upload_folder="tickets/",
            multiple=True,
        ),
    ]

La base de datos guarda una lista JSON de objetos FileInfo, y el admin procesa cada archivo de forma independiente durante la validación y el almacenamiento.

Validación

La validación se ejecuta en este orden:

1. accept
2. max_size
3. validators personalizados

Un validador personalizado es un callable que recibe la petición, el campo, un UploadFile y los valores completos del formulario enviado. Debe devolver None o lanzar ValueError.

El siguiente ejemplo valida el contenido real del archivo con la librería filetype:

import filetype
from starlette.datastructures import UploadFile
from starlette.requests import Request
from starlette_admin.fields import BaseField

ALLOWED_DOCUMENT_MIME_TYPES = {
    "application/pdf",
    "application/msword",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
}


def validate_document_type(
    request: Request, field: BaseField, upload: UploadFile, form_values: dict
) -> None:
    upload.file.seek(0)
    try:
        header = upload.file.read(2048)
        kind = filetype.guess(header)
        detected = kind.mime if kind else "application/octet-stream"
    finally:
        upload.file.seek(0)

    if detected not in ALLOWED_DOCUMENT_MIME_TYPES:
        raise ValueError(
            f"Invalid file type '{detected}'. Only PDF, DOC, and DOCX are allowed."
        )

Limitaciones en la limpieza de archivos

starlette-admin sube los archivos al backend de almacenamiento y escribe los metadatos FileInfo en la base de datos, pero no limpia los archivos tras un fallo o una eliminación. De ello se derivan dos comportamientos:

• Transacciones fallidas: Si una transacción de base de datos se revierte después de que la subida haya finalizado, el archivo permanece en el backend de almacenamiento. Las escrituras en el almacenamiento no disponen de mecanismo de rollback.
• Eliminaciones y actualizaciones: Eliminar una fila o reemplazar un archivo elimina la referencia FileInfo de la base de datos, pero el archivo antiguo permanece en LocalStorage o S3Storage.

Este diseño mantiene simple la capa de almacenamiento y evita que errores a nivel de aplicación desencadenen operaciones destructivas. La contrapartida es que se acumulan archivos huérfanos. Para evitar que el almacenamiento crezca sin límite, deberá reconciliarlos usted mismo. Un patrón habitual es un trabajo periódico en segundo plano que compare las claves de su backend de almacenamiento con las referencias FileInfo activas de su base de datos.

Alternativa transaccional

Si su aplicación necesita que las operaciones de almacenamiento de archivos sean transaccionales junto con las escrituras en la base de datos, utilice una librería que vincule el almacenamiento de archivos con la unidad de trabajo de SQLAlchemy.

En lugar del parámetro storage= del campo, use sqlalchemy-file. Esta librería almacena los archivos como parte del ciclo de flush y rollback del ORM, de modo que una transacción fallida o la eliminación de una fila deshacen la escritura correspondiente del archivo. Para ver un ejemplo funcional, consulte examples/13-sqlachemy-file.

Próximos pasos

• Campos: Referencia de FileField e ImageField.
• Exportación e importación: Cómo se incluyen los archivos en los paquetes de exportación.
• Seguridad: Comportamiento de saneamiento automático y validación.