feat(backend): модуль «замена фона» и хранилище своих картинок

Отключаемый в админке модуль `virtual_background` (дефолт — выключен, чтобы
обновление не меняло продукт у тех, кто ничего не просил). Флаг едет клиенту
двумя путями: на публичные страницы входа — через `GET /public/settings`,
участнику комнаты — в join-ответе (`JoinOut`), потому что значение нужно на
руках ДО первого рендера комнаты, а `/admin/settings` доступен только админу.

Свои картинки пользователя (`/users/me/backgrounds`, GET/POST/DELETE):
файлы на диске (`backgrounds/{user_id}/{id}.{ext}`), в БД только путь — как у
аватаров, «чтобы не грузили БД». Лимит в 10 штук проверяется на сервере под
блокировкой строки пользователя: две одновременные загрузки иначе обе увидели
бы «уже девять» и обе прошли бы. Удаление сносит и запись, и файл; чужую
картинку по её id удалить нельзя — владелец в условии запроса.

Валидация загрузки (допустимые форматы, магические байты, реальный размер)
выделена из `services/avatars.py` в общий `services/images.py`: правила у
аватара и фона одни и те же, а разъехавшись, они дали бы дыру ровно там, ради
чего проверка и написана. Публичный API аватаров не изменился.

Сжимает картинку клиент (Pillow на бэкенде нет), но серверная валидация
остаётся полноценной — запрос может прийти и мимо интерфейса.

Новый ключ настройки вписан в `_MANAGED_KEYS` тестов: без этого включённый
в общей dev-БД модуль ронял чужие тесты, которые считают себя изолированными.

backend/alembic/versions/a37c1b9e0f42_user_virtual_background_images.py

@@ -0,0 +1,61 @@
+"""user virtual background images
+
+Свои картинки пользователя для замены фона видео (сессия 35):
+- таблица `user_backgrounds` — id, владелец (`ON DELETE CASCADE`), путь к файлу
+  относительно `MEDIA_ROOT`, время загрузки.
+
+Сами файлы лежат на диске в томе `media` (`backgrounds/{user_id}/{id}.{ext}`),
+в БД только путь — как у аватаров (`users.avatar_path`). Лимит «не более 10
+картинок на пользователя» — политика продукта, проверяется в
+`services/backgrounds.py`, а не ограничением БД.
+
+Настройка отключаемого модуля (`instance_settings.virtual_background`)
+миграции не требует: `instance_settings` — key-value JSONB, новая настройка
+это новая строка (см. `services/instance_settings.py`).
+
+Revision ID: a37c1b9e0f42
+Revises: 4d08a44ad153
+Create Date: 2026-08-09 23:30:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'a37c1b9e0f42'
+down_revision: Union[str, Sequence[str], None] = '4d08a44ad153'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.create_table(
+        'user_backgrounds',
+        sa.Column(
+            'id',
+            postgresql.UUID(as_uuid=True),
+            server_default=sa.text('gen_random_uuid()'),
+            nullable=False,
+        ),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column('path', sa.String(length=512), nullable=False),
+        sa.Column(
+            'created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False
+        ),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index(
+        'ix_user_backgrounds_user_created', 'user_backgrounds', ['user_id', 'created_at']
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_index('ix_user_backgrounds_user_created', table_name='user_backgrounds')
+    op.drop_table('user_backgrounds')

backend/api/admin.py

@@ -476,6 +476,7 @@ def _to_settings_out(cfg: InstanceConfig, *, transcription_queue_served: bool) -
         consent_policy_text=cfg.consent_policy_text,
         consent_policy_version=cfg.consent_policy_version,
         device_check_enabled=cfg.device_check_enabled,
+        virtual_background_enabled=cfg.virtual_background_enabled,
     )
 
 

backend/api/public.py

@@ -18,4 +18,7 @@ async def public_settings(
 ) -> PublicSettingsOut:
     """Флаги инстанса, нужные публичным страницам логина/входа гостя до аутентификации."""
     cfg = await InstanceSettingsService(session).get()
-    return PublicSettingsOut(device_check_enabled=cfg.device_check_enabled)
+    return PublicSettingsOut(
+        device_check_enabled=cfg.device_check_enabled,
+        virtual_background_enabled=cfg.virtual_background_enabled,
+    )

backend/api/users.py

@@ -1,5 +1,6 @@
-"""Роутер профиля текущего пользователя, аватара и списка пользователей."""
+"""Роутер профиля текущего пользователя, аватара, картинок фона и списка пользователей."""
 
+import uuid
 from pathlib import Path
 from typing import Annotated
 
@@ -11,9 +12,27 @@ from core.config import get_settings
 from core.db import get_session
 from core.security import hash_password, verify_password
 from models.user import User
+from models.user_background import UserBackground
 from repositories.users import UserRepository
-from schemas.auth import PasswordChangeIn, ProfileUpdateIn, UserListItemOut, UserProfileOut
+from schemas.auth import (
+    PasswordChangeIn,
+    ProfileUpdateIn,
+    UserBackgroundOut,
+    UserBackgroundsOut,
+    UserListItemOut,
+    UserProfileOut,
+)
 from services.avatars import AvatarInvalidTypeError, AvatarTooLargeError, avatar_url
+from services.backgrounds import (
+    MAX_BACKGROUNDS_PER_USER,
+    BackgroundInvalidTypeError,
+    BackgroundLimitReachedError,
+    BackgroundTooLargeError,
+    add_background,
+    background_url,
+    delete_background,
+    list_backgrounds,
+)
 from services.profile import (
     TeamNotFoundError,
     clear_avatar,
@@ -89,6 +108,60 @@ async def delete_current_user_avatar(
     await session.commit()
 
 
+@router.get("/me/backgrounds", response_model=UserBackgroundsOut)
+async def list_current_user_backgrounds(
+    user: Annotated[User, Depends(get_current_user)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> UserBackgroundsOut:
+    """Свои картинки для замены фона видео + лимит на их число."""
+    items = await list_backgrounds(session, user.id)
+    return _to_backgrounds_out(items)
+
+
+@router.post(
+    "/me/backgrounds", response_model=UserBackgroundsOut, status_code=status.HTTP_201_CREATED
+)
+async def upload_current_user_background(
+    user: Annotated[User, Depends(get_current_user)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+    file: Annotated[UploadFile, File()],
+) -> UserBackgroundsOut:
+    """Загрузить свою картинку фона (jpeg/png/webp, до 2 МБ, не более 10 штук).
+
+    Возвращает весь список заново, а не одну добавленную запись: интерфейсу всё
+    равно нужен свежий список с актуальным остатком лимита, и лишний GET следом
+    за POST не нужен.
+    """
+    try:
+        await add_background(session, _media_root(), user.id, file)
+    except BackgroundLimitReachedError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="background_limit_reached"
+        ) from exc
+    except BackgroundTooLargeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE, detail="background_too_large"
+        ) from exc
+    except BackgroundInvalidTypeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, detail="background_invalid_type"
+        ) from exc
+    await session.commit()
+    return _to_backgrounds_out(await list_backgrounds(session, user.id))
+
+
+@router.delete("/me/backgrounds/{background_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_current_user_background(
+    background_id: uuid.UUID,
+    user: Annotated[User, Depends(get_current_user)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> None:
+    """Удалить свою картинку фона вместе с файлом на диске; чужую — 404."""
+    if not await delete_background(session, _media_root(), user.id, background_id):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="background_not_found")
+    await session.commit()
+
+
 @router.post("/me/password", status_code=status.HTTP_204_NO_CONTENT)
 async def change_current_user_password(
     data: PasswordChangeIn,
@@ -126,6 +199,14 @@ async def list_users(
     ]
 
 
+def _to_backgrounds_out(items: list[UserBackground]) -> UserBackgroundsOut:
+    """Собрать ответ списка картинок фона: id + публичный URL, плюс лимит с сервера."""
+    return UserBackgroundsOut(
+        items=[UserBackgroundOut(id=item.id, url=background_url(item.path)) for item in items],
+        limit=MAX_BACKGROUNDS_PER_USER,
+    )
+
+
 def _media_root() -> Path:
     """Каталог загруженных медиа-файлов (см. `core/config.py::Settings.media_root`)."""
     return Path(get_settings().media_root)

backend/core/plugins/config.py

@@ -138,3 +138,9 @@ class InstanceConfig(BaseModel):
     # Дефолт False сохраняет поведение существующих инсталляций — см.
     # `services/instance_settings.py`.
     device_check_enabled: bool = False
+    # Замена фона видео на картинку (сессия 35): отключаемый модуль, дефолт
+    # False сохраняет поведение существующих инсталляций. Нужен клиенту в двух
+    # местах и потому едет двумя путями: на публичные страницы входа — через
+    # `GET /public/settings`, участнику комнаты — в ответе join
+    # (`schemas/conferences.py::JoinOut`), см. `services/instance_settings.py`.
+    virtual_background_enabled: bool = False

backend/models/__init__.py

@@ -18,6 +18,7 @@ from models.phrase import Phrase
 from models.session import ConferenceSession
 from models.team import Team
 from models.user import User
+from models.user_background import UserBackground
 from models.webhook_event import LivekitWebhookEvent
 
 __all__ = [
@@ -36,4 +37,5 @@ __all__ = [
     "SessionAudioTrack",
     "Team",
     "User",
+    "UserBackground",
 ]

backend/models/user_background.py

@@ -0,0 +1,45 @@
+"""Модель UserBackground — своя картинка пользователя для замены фона видео.
+
+В БД хранится только путь к файлу относительно `MEDIA_ROOT`
+(`backgrounds/{user_id}/{background_id}.{ext}`) — ровно тот же приём, что и у
+аватаров (`users.avatar_path`, `services/avatars.py`): «чтобы не грузили БД»
+(требование оператора). Сами файлы лежат на диске в томе `media`, который
+nginx раздаёт напрямую по `location /media/`.
+
+Лимит на число картинок (`MAX_BACKGROUNDS_PER_USER`) проверяется в сервисе, а
+не ограничением БД: он про политику продукта, а не про целостность данных, и
+администратор может захотеть его поменять.
+"""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Index, String, func, text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from models.base import Base
+
+
+class UserBackground(Base):
+    """Загруженная пользователем картинка фона."""
+
+    __tablename__ = "user_backgrounds"
+    __table_args__ = (
+        # Выборка всегда одна и та же — «все фоны этого пользователя, свежие
+        # сверху» (`services/backgrounds.py::list_backgrounds`), и она же
+        # считает лимит при загрузке.
+        Index("ix_user_backgrounds_user_created", "user_id", "created_at"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, server_default=text("gen_random_uuid()")
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    # Путь относительно `MEDIA_ROOT`: `backgrounds/{user_id}/{id}.{ext}`.
+    path: Mapped[str] = mapped_column(String(512), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )

backend/schemas/admin.py

@@ -170,6 +170,8 @@ class SettingsOut(BaseModel):
     consent_policy_version: int
     # Проверка устройств на входе (сессия 33) — см. `core/plugins/config.py::InstanceConfig`.
     device_check_enabled: bool
+    # Замена фона видео (сессия 35) — см. `core/plugins/config.py::InstanceConfig`.
+    virtual_background_enabled: bool
 
 
 class TestEmailIn(BaseModel):

backend/schemas/auth.py

@@ -86,6 +86,29 @@ class UserProfileOut(UserOut):
     team_name: str | None = None
 
 
+class UserBackgroundOut(BaseModel):
+    """Своя картинка пользователя для замены фона видео (`GET /users/me/backgrounds`).
+
+    Отдаётся только URL файла (`/media/backgrounds/...`, раздаёт nginx) и id для
+    удаления — путь на диске наружу не показывается.
+    """
+
+    id: uuid.UUID
+    url: str
+
+
+class UserBackgroundsOut(BaseModel):
+    """Список своих картинок фона вместе с лимитом.
+
+    Лимит приезжает с сервера, а не зашит в интерфейс: он проверяется на
+    сервере (`services/backgrounds.py`), и фронт не должен угадывать его
+    отдельной константой, которая разъедется при первой же правке.
+    """
+
+    items: list[UserBackgroundOut]
+    limit: int
+
+
 class PasswordChangeIn(BaseModel):
     """Тело смены пароля текущим пользователем (`POST /users/me/password`).
 

backend/schemas/conferences.py

@@ -138,6 +138,11 @@ class JoinOut(BaseModel):
     # на руках ДО публикации своего трека (см. `services/conference_access.py`).
     publish_quality_cap: PublishQualityCap
     stage_max_tiles: StageMaxTiles
+    # Тоггл инстанса `virtual_background.enabled` — гасит замену фона целиком
+    # (кнопка в тулбаре комнаты и применение процессора к треку). Едет здесь,
+    # а не через `/admin/settings` (доступен только админу): значение нужно
+    # участнику — в том числе гостю — до первого рендера комнаты.
+    virtual_background_enabled: bool
 
 
 class ConferenceOut(BaseModel):

backend/schemas/public.py

@@ -16,3 +16,8 @@ class PublicSettingsOut(BaseModel):
     # Проверка устройств на входе (сессия 33) — см.
     # `core/plugins/config.py::InstanceConfig.device_check_enabled`.
     device_check_enabled: bool
+    # Замена фона видео (сессия 35) — нужен превью на `JoinPage`, чтобы
+    # показать выбор фона ещё до входа в комнату. Участнику УЖЕ в комнате тот
+    # же флаг приезжает в join-ответе (`JoinOut.virtual_background_enabled`):
+    # эта страница публичная и `GET /admin/settings` ей недоступен.
+    virtual_background_enabled: bool

backend/services/avatars.py

@@ -3,80 +3,49 @@
 Файл лежит на диске `MEDIA_ROOT/avatars/{user_id}.{ext}`; в БД (`users.avatar_path`)
 хранится путь относительно `MEDIA_ROOT` (`avatars/{user_id}.{ext}`) — тот же
 приём, что и у записей аудиотреков (`recordings_dir`, `core/config.py`).
+
+Сама проверка содержимого (допустимые форматы, магические байты, реальный
+размер) живёт в `services/images.py` — она общая с картинками фона видео
+(`services/backgrounds.py`).
 """
 
 import uuid
-from collections.abc import Callable
 from pathlib import Path
 
 from fastapi import UploadFile
 
+from services.images import (
+    ImageInvalidTypeError,
+    ImageTooLargeError,
+    read_and_validate_image,
+)
+
 # Лимит размера загружаемого аватара — 2 МБ.
 MAX_AVATAR_SIZE_BYTES = 2 * 1024 * 1024
 
-# Читаем файл чанками, не доверяя заголовку `Content-Length` (клиент может
-# солгать о размере) — реальный размер считается по факту прочитанных байт.
-_CHUNK_SIZE_BYTES = 64 * 1024
 
-# Допустимые типы изображений -> расширение файла на диске.
+class AvatarTooLargeError(ImageTooLargeError):
-_ALLOWED_CONTENT_TYPES: dict[str, str] = {
-    "image/jpeg": "jpg",
-    "image/png": "png",
-    "image/webp": "webp",
-}
-
-# Магические байты (сигнатуры) форматов — заголовку `Content-Type` от клиента
-# доверять нельзя (легко подделать), реальный формат определяется по
-# содержимому файла.
-_MAGIC_CHECKS: dict[str, Callable[[bytes], bool]] = {
-    "image/jpeg": lambda head: head[:3] == b"\xff\xd8\xff",
-    "image/png": lambda head: head[:8] == b"\x89PNG\r\n\x1a\n",
-    "image/webp": lambda head: head[:4] == b"RIFF" and head[8:12] == b"WEBP",
-}
-
-# Достаточно первых 12 байт, чтобы проверить все сигнатуры выше (WebP —
-# самая длинная проверка, требует байты 8..11 включительно).
-_MAGIC_HEAD_SIZE = 12
-
-
-class AvatarTooLargeError(Exception):
     """Загружаемый файл превышает `MAX_AVATAR_SIZE_BYTES` (413)."""
 
 
-class AvatarInvalidTypeError(Exception):
+class AvatarInvalidTypeError(ImageInvalidTypeError):
     """`Content-Type` не входит в список допустимых либо не совпадает с содержимым (415)."""
 
 
 async def read_and_validate_avatar(file: UploadFile) -> tuple[bytes, str]:
-    """Прочитать содержимое файла аватара чанками и провалидировать тип/размер.
+    """Прочитать содержимое файла аватара и провалидировать тип/размер.
 
-    Возвращает `(содержимое, расширение)`. Порядок проверок: сначала
+    Возвращает `(содержимое, расширение)`. Ошибки общего валидатора
-    заявленный `Content-Type` (быстрый отсев), затем фактический размер по
+    перезаворачиваются в «аватарные» — вызывающий код (`api/users.py`,
-    мере чтения, затем магические байты содержимого — заявленный тип должен
+    `api/admin.py`) отображает их в 413/415 и не должен знать про
-    совпасть с реальным (иначе подделка `Content-Type` не даст загрузить,
+    `services/images.py`.
-    например, исполняемый файл под видом `image/png`).
     """
-    declared_type = file.content_type
+    try:
-    if declared_type not in _ALLOWED_CONTENT_TYPES:
+        return await read_and_validate_image(file, MAX_AVATAR_SIZE_BYTES)
-        raise AvatarInvalidTypeError(f"unsupported_content_type: {declared_type}")
+    except ImageTooLargeError as exc:
-
+        raise AvatarTooLargeError(str(exc)) from exc
-    chunks: list[bytes] = []
+    except ImageInvalidTypeError as exc:
-    total_size = 0
+        raise AvatarInvalidTypeError(str(exc)) from exc
-    while True:
-        chunk = await file.read(_CHUNK_SIZE_BYTES)
-        if not chunk:
-            break
-        total_size += len(chunk)
-        if total_size > MAX_AVATAR_SIZE_BYTES:
-            raise AvatarTooLargeError(f"file exceeds {MAX_AVATAR_SIZE_BYTES} bytes")
-        chunks.append(chunk)
-    content = b"".join(chunks)
-
-    magic_check = _MAGIC_CHECKS[declared_type]
-    if not magic_check(content[:_MAGIC_HEAD_SIZE]):
-        raise AvatarInvalidTypeError("content_does_not_match_declared_content_type")
-
-    return content, _ALLOWED_CONTENT_TYPES[declared_type]
 
 
 def _avatar_relative_path(user_id: uuid.UUID, ext: str) -> str:

backend/services/backgrounds.py

@@ -0,0 +1,135 @@
+"""Свои картинки пользователя для замены фона видео: лимит, файлы на диске, URL.
+
+Как и аватары (`services/avatars.py`), картинки лежат **файлами на диске**
+(`MEDIA_ROOT/backgrounds/{user_id}/{background_id}.{ext}`), а в БД — только
+путь (`user_backgrounds.path`): требование оператора «чтобы не грузили БД».
+Раздаёт их nginx напрямую (`location /media/`), в обход backend.
+
+Картинку ужимает КЛИЕНТ (canvas → WebP, см. `frontend/src/lib/imageResize.ts`):
+фон всё равно рендерится в браузере, и ставить Pillow на сервер ради одной
+операции не нужно. Но валидация здесь остаётся полноценной — запрос может
+прийти и мимо интерфейса.
+
+Имя файла — id самой записи, а не порядковый номер: запись никогда не
+перезаписывается (загрузка всегда создаёт новую), поэтому URL картинки
+неизменен и его можно кэшировать браузером без cache-busting-параметра,
+в отличие от аватара.
+"""
+
+import uuid
+from pathlib import Path
+
+from fastapi import UploadFile
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from models.user import User
+from models.user_background import UserBackground
+from services.images import (
+    ImageInvalidTypeError,
+    ImageTooLargeError,
+    read_and_validate_image,
+)
+
+# Сколько своих картинок разрешено одному пользователю — прямое требование
+# задачи («но не более 10»). Проверяется здесь, на сервере: ограничение только
+# в интерфейсе обходится curl'ом.
+MAX_BACKGROUNDS_PER_USER = 10
+
+# Лимит размера загружаемого файла — 2 МБ, как у аватара. Клиент присылает
+# ужатый WebP (обычно 100–300 КБ), так что до лимита доходит только тот, кто
+# шлёт запрос в обход интерфейса.
+MAX_BACKGROUND_SIZE_BYTES = 2 * 1024 * 1024
+
+
+class BackgroundTooLargeError(ImageTooLargeError):
+    """Загружаемый файл превышает `MAX_BACKGROUND_SIZE_BYTES` (413)."""
+
+
+class BackgroundInvalidTypeError(ImageInvalidTypeError):
+    """`Content-Type` не входит в список допустимых либо не совпадает с содержимым (415)."""
+
+
+class BackgroundLimitReachedError(Exception):
+    """У пользователя уже `MAX_BACKGROUNDS_PER_USER` картинок (409)."""
+
+
+async def list_backgrounds(session: AsyncSession, user_id: uuid.UUID) -> list[UserBackground]:
+    """Все картинки пользователя, свежие сверху."""
+    result = await session.execute(
+        select(UserBackground)
+        .where(UserBackground.user_id == user_id)
+        .order_by(UserBackground.created_at.desc(), UserBackground.id.desc())
+    )
+    return list(result.scalars().all())
+
+
+async def add_background(
+    session: AsyncSession, media_root: Path, user_id: uuid.UUID, file: UploadFile
+) -> UserBackground:
+    """Провалидировать, сохранить на диск и завести запись о новой картинке.
+
+    Бросает `BackgroundTooLargeError`/`BackgroundInvalidTypeError`/
+    `BackgroundLimitReachedError`. Коммит — за вызывающим (роутером), как и в
+    остальных эндпоинтах профиля.
+
+    Строка пользователя блокируется (`FOR UPDATE`) на время проверки лимита:
+    без этого две одновременные загрузки (двойной клик по кнопке) обе
+    увидели бы «уже 9» и обе прошли бы — лимит, проверяемый на сервере,
+    обязан держаться и в этом случае.
+    """
+    await session.execute(select(User.id).where(User.id == user_id).with_for_update())
+    count = await session.scalar(
+        select(func.count()).select_from(UserBackground).where(UserBackground.user_id == user_id)
+    )
+    if (count or 0) >= MAX_BACKGROUNDS_PER_USER:
+        raise BackgroundLimitReachedError(f"limit is {MAX_BACKGROUNDS_PER_USER}")
+
+    try:
+        content, ext = await read_and_validate_image(file, MAX_BACKGROUND_SIZE_BYTES)
+    except ImageTooLargeError as exc:
+        raise BackgroundTooLargeError(str(exc)) from exc
+    except ImageInvalidTypeError as exc:
+        raise BackgroundInvalidTypeError(str(exc)) from exc
+
+    # id генерируем здесь, а не полагаемся на `server_default`: он нужен ДО
+    # вставки, чтобы собрать имя файла на диске.
+    background_id = uuid.uuid4()
+    relative_path = f"backgrounds/{user_id}/{background_id}.{ext}"
+    background = UserBackground(id=background_id, user_id=user_id, path=relative_path)
+    session.add(background)
+    # Запись сначала, файл потом: если вставка не пройдёт (лимит, гонка,
+    # отвалившаяся БД), на диске не останется мусора.
+    await session.flush()
+
+    file_path = media_root / relative_path
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_bytes(content)
+    return background
+
+
+async def delete_background(
+    session: AsyncSession, media_root: Path, user_id: uuid.UUID, background_id: uuid.UUID
+) -> bool:
+    """Удалить картинку пользователя вместе с файлом. `False` — записи нет (404).
+
+    `user_id` в условии обязателен: без него владелец записи не проверялся бы
+    и любой аутентифицированный пользователь мог бы удалить чужую картинку,
+    зная её id.
+    """
+    background = await session.scalar(
+        select(UserBackground).where(
+            UserBackground.id == background_id, UserBackground.user_id == user_id
+        )
+    )
+    if background is None:
+        return False
+    file_path = media_root / background.path
+    file_path.unlink(missing_ok=True)
+    await session.delete(background)
+    return True
+
+
+def background_url(path: str) -> str:
+    """Публичный URL картинки фона (раздаётся nginx из тома `media`)."""
+    return f"/media/{path}"

backend/services/conference_access.py

@@ -56,13 +56,15 @@ def build_join(
     hand_queue_enabled: bool,
     publish_quality_cap: PublishQualityCap,
     stage_max_tiles: StageMaxTiles,
+    virtual_background_enabled: bool,
     avatar_url: str | None = None,
     is_organizer: bool = False,
 ) -> JoinOut:
     """Построить ответ join: LiveKit access-токен для входа в комнату конференции.
 
     Имя LiveKit-комнаты всегда равно `conference.slug` (ADR-001, п.4).
-    `chat_enabled`/`hand_queue_enabled`/`publish_quality_cap`/`stage_max_tiles`
+    `chat_enabled`/`hand_queue_enabled`/`publish_quality_cap`/`stage_max_tiles`/
+    `virtual_background_enabled`
     — снятые вызывающей стороной значения `instance_settings`: читаются здесь
     параметрами, а не заново из БД, чтобы не плодить отдельный запрос настроек
     на каждый join.
@@ -96,4 +98,5 @@ def build_join(
         hand_queue_enabled=hand_queue_enabled,
         publish_quality_cap=publish_quality_cap,
         stage_max_tiles=stage_max_tiles,
+        virtual_background_enabled=virtual_background_enabled,
     )

backend/services/conferences.py

@@ -158,6 +158,7 @@ class ConferenceService:
                 hand_queue_enabled=cfg.hand_queue.enabled,
                 publish_quality_cap=cfg.media_limits.publish_quality_cap,
                 stage_max_tiles=cfg.media_limits.stage_max_tiles,
+                virtual_background_enabled=cfg.virtual_background_enabled,
                 avatar_url=resolve_avatar_url(self._media_root, owner_avatar_path),
                 is_organizer=True,
             )
@@ -255,6 +256,7 @@ class ConferenceService:
             hand_queue_enabled=cfg.hand_queue.enabled,
             publish_quality_cap=cfg.media_limits.publish_quality_cap,
             stage_max_tiles=cfg.media_limits.stage_max_tiles,
+            virtual_background_enabled=cfg.virtual_background_enabled,
             avatar_url=resolve_avatar_url(self._media_root, user.avatar_path),
             is_organizer=conference.owner_id is not None and conference.owner_id == user.id,
         )
@@ -280,6 +282,7 @@ class ConferenceService:
             hand_queue_enabled=cfg.hand_queue.enabled,
             publish_quality_cap=cfg.media_limits.publish_quality_cap,
             stage_max_tiles=cfg.media_limits.stage_max_tiles,
+            virtual_background_enabled=cfg.virtual_background_enabled,
         )
 
     async def mute_participant(

backend/services/images.py

@@ -0,0 +1,79 @@
+"""Общая валидация загружаемых картинок: тип по содержимому и реальный размер.
+
+Выделено из `services/avatars.py`, когда те же правила понадобились фонам
+видео (`services/backgrounds.py`): списки допустимых форматов и сигнатур
+должны быть в одном месте — разъехавшись, они дали бы дыру ровно в том
+месте, ради которого проверка и написана.
+
+Правила намеренно не смягчаются для «уже проверенных на клиенте» файлов:
+браузер жмёт картинку фона перед отправкой (canvas → WebP), но запрос к API
+может прийти и мимо интерфейса — клиенту верить нельзя.
+"""
+
+from collections.abc import Callable
+
+from fastapi import UploadFile
+
+# Читаем файл чанками, не доверяя заголовку `Content-Length` (клиент может
+# солгать о размере) — реальный размер считается по факту прочитанных байт.
+_CHUNK_SIZE_BYTES = 64 * 1024
+
+# Допустимые типы изображений -> расширение файла на диске.
+ALLOWED_IMAGE_CONTENT_TYPES: dict[str, str] = {
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/webp": "webp",
+}
+
+# Магические байты (сигнатуры) форматов — заголовку `Content-Type` от клиента
+# доверять нельзя (легко подделать), реальный формат определяется по
+# содержимому файла.
+_MAGIC_CHECKS: dict[str, Callable[[bytes], bool]] = {
+    "image/jpeg": lambda head: head[:3] == b"\xff\xd8\xff",
+    "image/png": lambda head: head[:8] == b"\x89PNG\r\n\x1a\n",
+    "image/webp": lambda head: head[:4] == b"RIFF" and head[8:12] == b"WEBP",
+}
+
+# Достаточно первых 12 байт, чтобы проверить все сигнатуры выше (WebP —
+# самая длинная проверка, требует байты 8..11 включительно).
+_MAGIC_HEAD_SIZE = 12
+
+
+class ImageTooLargeError(Exception):
+    """Загружаемый файл превышает переданный лимит размера (413)."""
+
+
+class ImageInvalidTypeError(Exception):
+    """`Content-Type` не входит в список допустимых либо не совпадает с содержимым (415)."""
+
+
+async def read_and_validate_image(file: UploadFile, max_size_bytes: int) -> tuple[bytes, str]:
+    """Прочитать файл чанками и провалидировать тип/размер.
+
+    Возвращает `(содержимое, расширение)`. Порядок проверок: сначала
+    заявленный `Content-Type` (быстрый отсев), затем фактический размер по
+    мере чтения, затем магические байты содержимого — заявленный тип должен
+    совпасть с реальным (иначе подделка `Content-Type` не даст загрузить,
+    например, исполняемый файл под видом `image/png`).
+    """
+    declared_type = file.content_type
+    if declared_type not in ALLOWED_IMAGE_CONTENT_TYPES:
+        raise ImageInvalidTypeError(f"unsupported_content_type: {declared_type}")
+
+    chunks: list[bytes] = []
+    total_size = 0
+    while True:
+        chunk = await file.read(_CHUNK_SIZE_BYTES)
+        if not chunk:
+            break
+        total_size += len(chunk)
+        if total_size > max_size_bytes:
+            raise ImageTooLargeError(f"file exceeds {max_size_bytes} bytes")
+        chunks.append(chunk)
+    content = b"".join(chunks)
+
+    magic_check = _MAGIC_CHECKS[declared_type]
+    if not magic_check(content[:_MAGIC_HEAD_SIZE]):
+        raise ImageInvalidTypeError("content_does_not_match_declared_content_type")
+
+    return content, ALLOWED_IMAGE_CONTENT_TYPES[declared_type]

backend/services/instance_settings.py

@@ -56,6 +56,7 @@ _KEY_CONTACT_EMAIL = "contact_email"
 _KEY_MEDIA_LIMITS = "media_limits"
 _KEY_CONSENT_POLICY = "consent_policy"
 _KEY_DEVICE_CHECK = "device_check"
+_KEY_VIRTUAL_BACKGROUND = "virtual_background"
 
 BOOTSTRAP_MANAGED_KEYS: tuple[str, ...] = (
     _KEY_CHAT,
@@ -81,6 +82,10 @@ _DEFAULT_REGISTRATION_EMAIL_DOMAIN_VALUE: dict[str, Any] = {"enabled": False, "d
 _DEFAULT_CONTACT_EMAIL_VALUE: dict[str, Any] = {"enabled": False, "email": None}
 _DEFAULT_MEDIA_LIMITS_VALUE: dict[str, Any] = {"publish_quality_cap": "off", "stage_max_tiles": 25}
 _DEFAULT_DEVICE_CHECK_VALUE = {"enabled": False}
+_DEFAULT_VIRTUAL_BACKGROUND_VALUE = {"enabled": False}
+"""Замена фона видео (сессия 35). Дефолт — выключено: фича постоянно считает
+нейросеть сегментации на клиенте, и включать её самим фактом обновления у тех,
+кто ничего не просил, нельзя (то же правило, что и у остальных модулей)."""
 
 DEFAULT_CONSENT_POLICY_TEXT = """Это типовой шаблон для предварительной демонстрации. Текст не проходил проверку юриста и не может использоваться как окончательная редакция без такой проверки. Администратор обязан заменить плейсхолдеры в квадратных скобках и, при необходимости, весь текст — под свою организацию и юрисдикцию.
 
@@ -154,6 +159,7 @@ class SettingsUpdateIn(BaseModel):
     consent_required: bool | None = None
     consent_policy_text: str | None = None
     device_check_enabled: bool | None = None
+    virtual_background_enabled: bool | None = None
 
 
 class BootstrapOverrides(BaseModel):
@@ -207,6 +213,7 @@ def build_bootstrap_defaults(
         _KEY_MEDIA_LIMITS: dict(_DEFAULT_MEDIA_LIMITS_VALUE),
         _KEY_CONSENT_POLICY: dict(_DEFAULT_CONSENT_POLICY_VALUE),
         _KEY_DEVICE_CHECK: dict(_DEFAULT_DEVICE_CHECK_VALUE),
+        _KEY_VIRTUAL_BACKGROUND: dict(_DEFAULT_VIRTUAL_BACKGROUND_VALUE),
     }
     if overrides is None:
         return defaults
@@ -345,6 +352,10 @@ class InstanceSettingsService:
             cfg.device_check_enabled = patch.device_check_enabled
             await self._set(_KEY_DEVICE_CHECK, {"enabled": patch.device_check_enabled})
 
+        if patch.virtual_background_enabled is not None:
+            cfg.virtual_background_enabled = patch.virtual_background_enabled
+            await self._set(_KEY_VIRTUAL_BACKGROUND, {"enabled": patch.virtual_background_enabled})
+
         if patch.registration_team_choice is not None:
             cfg.registration_team_choice = patch.registration_team_choice
             await self._set(
@@ -616,4 +627,7 @@ def _build_config(rows: dict[str, Any]) -> InstanceConfig:
         device_check_enabled=rows.get(_KEY_DEVICE_CHECK, _DEFAULT_DEVICE_CHECK_VALUE).get(
             "enabled", False
         ),
+        virtual_background_enabled=rows.get(
+            _KEY_VIRTUAL_BACKGROUND, _DEFAULT_VIRTUAL_BACKGROUND_VALUE
+        ).get("enabled", False),
     )

backend/tests/test_conferences_api.py

@@ -21,6 +21,7 @@ from models.guest import GuestAccess
 from models.invitee import ConferenceInvitee
 from models.user import User
 from services.conference_ids import generate_number, generate_slug
+from services.instance_settings import InstanceSettingsService, SettingsUpdateIn
 
 FUTURE = datetime.now(UTC) + timedelta(days=3)
 
@@ -117,6 +118,12 @@ async def test_create_instant_conference_returns_active_with_join(
     # инсталляции не должны получить внезапно ухудшенное качество).
     assert body["join"]["publish_quality_cap"] == "off"
     assert body["join"]["stage_max_tiles"] == 25
+    # Замена фона — отключаемый модуль (сессия 35); значение нужно клиенту ДО
+    # первого рендера комнаты, поэтому едет в join. Здесь проверяется только
+    # НАЛИЧИЕ поля: тумблер живёт в общей dev-БД, и сравнение с дефолтом
+    # ломалось бы от того, что разработчик включил модуль руками (см.
+    # `test_join_reports_virtual_background_toggle` — там значение задаётся явно).
+    assert isinstance(body["join"]["virtual_background_enabled"], bool)
 
 
 async def test_create_instant_conference_join_metadata_contains_owner_avatar_url(
@@ -718,6 +725,30 @@ async def test_join_closed_conference_correct_password_returns_200(
     assert response.json()["room_name"] == conference.slug
 
 
+@pytest.mark.parametrize("enabled", [True, False])
+async def test_join_reports_virtual_background_toggle(
+    client: httpx.AsyncClient, db_session: AsyncSession, enabled: bool
+) -> None:
+    """Тумблер модуля «замена фона» доезжает до участника в ответе join.
+
+    Значение задаётся ЯВНО, а не берётся из общей dev-БД: клиенту оно нужно до
+    первого рендера комнаты, и подмена тумблера обязана менять ответ join, а не
+    только `/admin/settings` (тот доступен лишь администратору).
+    """
+    owner = await _make_user(db_session)
+    conference = await _make_conference(db_session, owner_id=owner.id)
+    await InstanceSettingsService(db_session).update(
+        SettingsUpdateIn(virtual_background_enabled=enabled)
+    )
+    await db_session.commit()
+
+    response = await client.post(
+        f"/api/v1/conferences/{conference.id}/join", json={}, headers=_auth_headers(owner)
+    )
+    assert response.status_code == 200, response.text
+    assert response.json()["virtual_background_enabled"] is enabled
+
+
 # --- Аватар в метаданных LiveKit-токена -----------------------------------------
 
 

backend/tests/test_instance_settings.py

@@ -76,6 +76,7 @@ _MANAGED_KEYS = (
     "media_limits",
     "consent_policy",
     "device_check",
+    "virtual_background",
 )
 
 
@@ -135,6 +136,7 @@ async def test_ensure_bootstrapped_imports_yaml_defaults(
         "media_limits",
         "consent_policy",
         "device_check",
+        "virtual_background",
     }
     cfg = await service.get()
     assert cfg.transcriber.provider == "faster_whisper_cpu"
@@ -164,6 +166,9 @@ async def test_ensure_bootstrapped_imports_yaml_defaults(
     # Проверка устройств на входе (сессия 33) — выключена по умолчанию,
     # существующие инсталляции не должны молча начать спрашивать доступ.
     assert cfg.device_check_enabled is False
+    # Замена фона видео (сессия 35) — выключена по умолчанию: фича постоянно
+    # считает сегментацию на клиенте, включать её обновлением нельзя.
+    assert cfg.virtual_background_enabled is False
 
 
 async def test_ensure_bootstrapped_is_idempotent_and_keeps_admin_edits(
@@ -214,6 +219,22 @@ async def test_update_device_check_enabled(
     assert cfg.device_check_enabled is False
 
 
+async def test_update_virtual_background_enabled(
+    db_session: AsyncSession, clean_instance_settings: None
+) -> None:
+    service = InstanceSettingsService(db_session)
+    await service.ensure_bootstrapped(PLUGINS_YAML)
+
+    cfg = await service.update(SettingsUpdateIn(virtual_background_enabled=True))
+    assert cfg.virtual_background_enabled is True
+
+    cfg = await service.get()
+    assert cfg.virtual_background_enabled is True
+
+    cfg = await service.update(SettingsUpdateIn(virtual_background_enabled=False))
+    assert cfg.virtual_background_enabled is False
+
+
 @pytest.mark.parametrize(
     ("preset", "chat_enabled", "ai_enabled", "ai_level"),
     [

backend/tests/test_public_api.py

@@ -8,11 +8,13 @@ from services.instance_settings import InstanceSettingsService, SettingsUpdateIn
 
 
 @pytest_asyncio.fixture(autouse=True)
-async def _reset_device_check(db_session: AsyncSession) -> None:
+async def _reset_public_flags(db_session: AsyncSession) -> None:
-    """Сбросить `device_check_enabled` перед каждым тестом — общая dev-БД не изолирована
+    """Сбросить публичные тогглы перед каждым тестом — общая dev-БД не изолирована
     от ручных правок администратора (та же дисциплина, что и `_reset_registration_gating`
     в `test_auth.py`); `db_session` не коммитится в реальную БД, см. `conftest.py`."""
-    await InstanceSettingsService(db_session).update(SettingsUpdateIn(device_check_enabled=False))
+    await InstanceSettingsService(db_session).update(
+        SettingsUpdateIn(device_check_enabled=False, virtual_background_enabled=False)
+    )
 
 
 async def test_public_settings_disabled_by_default(
@@ -20,7 +22,7 @@ async def test_public_settings_disabled_by_default(
 ) -> None:
     response = await client.get("/api/v1/public/settings")
     assert response.status_code == 200, response.text
-    assert response.json() == {"device_check_enabled": False}
+    assert response.json() == {"device_check_enabled": False, "virtual_background_enabled": False}
 
 
 async def test_public_settings_reflects_enabled(
@@ -31,7 +33,21 @@ async def test_public_settings_reflects_enabled(
 
     response = await client.get("/api/v1/public/settings")
     assert response.status_code == 200, response.text
-    assert response.json() == {"device_check_enabled": True}
+    assert response.json()["device_check_enabled"] is True
+
+
+async def test_public_settings_reflects_virtual_background_enabled(
+    client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """Замена фона нужна и на публичном превью входа (`JoinPage`) — до аутентификации."""
+    await InstanceSettingsService(db_session).update(
+        SettingsUpdateIn(virtual_background_enabled=True)
+    )
+    await db_session.commit()
+
+    response = await client.get("/api/v1/public/settings")
+    assert response.status_code == 200, response.text
+    assert response.json()["virtual_background_enabled"] is True
 
 
 async def test_public_settings_requires_no_auth(

backend/tests/test_users_api.py

@@ -1,4 +1,4 @@
-"""Интеграционные тесты `/api/v1/users`: список пользователей, профиль, аватар."""
+"""Интеграционные тесты `/api/v1/users`: список пользователей, профиль, аватар, картинки фона."""
 
 import uuid
 from collections.abc import Generator
@@ -12,6 +12,7 @@ from core.config import get_settings
 from core.security import create_access_token, hash_password
 from models.team import Team
 from models.user import User
+from services.backgrounds import MAX_BACKGROUNDS_PER_USER
 
 # Минимальные валидные по магическим байтам содержимые (без полноценного
 # декодирования — `services/avatars.py` проверяет только сигнатуру/размер).
@@ -393,3 +394,150 @@ async def test_list_users_search_by_q_filters_by_name_or_email(
     ids = {item["id"] for item in response.json()}
     assert str(match.id) in ids
     assert str(requester.id) not in ids
+
+
+# --- Свои картинки фона (`/users/me/backgrounds`) -----------------
+
+
+async def _upload_background(
+    client: httpx.AsyncClient, user: User, *, name: str = "bg.webp"
+) -> httpx.Response:
+    return await client.post(
+        "/api/v1/users/me/backgrounds",
+        headers=_auth_headers(user),
+        files={"file": (name, _WEBP_BYTES, "image/webp")},
+    )
+
+
+async def test_backgrounds_list_is_empty_by_default_and_reports_limit(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+
+    response = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(user))
+    assert response.status_code == 200, response.text
+    body = response.json()
+    assert body["items"] == []
+    assert body["limit"] == MAX_BACKGROUNDS_PER_USER
+
+
+async def test_upload_background_saves_file_and_returns_url(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+
+    response = await _upload_background(client, user)
+    assert response.status_code == 201, response.text
+    items = response.json()["items"]
+    assert len(items) == 1
+    url = items[0]["url"]
+    assert url == f"/media/backgrounds/{user.id}/{items[0]['id']}.webp"
+    # Файл лежит на диске, в БД только путь — см. `services/backgrounds.py`.
+    assert (media_root / url.removeprefix("/media/")).read_bytes() == _WEBP_BYTES
+
+
+async def test_upload_background_spoofed_content_type_returns_415(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """`Content-Type: image/webp`, но байты — JPEG: клиенту не верим и здесь."""
+    user = await _make_user(db_session)
+    await db_session.commit()
+
+    response = await client.post(
+        "/api/v1/users/me/backgrounds",
+        headers=_auth_headers(user),
+        files={"file": ("bg.webp", _JPEG_BYTES, "image/webp")},
+    )
+    assert response.status_code == 415
+    assert response.json()["detail"] == "background_invalid_type"
+
+
+async def test_upload_background_too_large_returns_413(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+    oversized = _WEBP_BYTES + b"\x00" * (2 * 1024 * 1024)
+
+    response = await client.post(
+        "/api/v1/users/me/backgrounds",
+        headers=_auth_headers(user),
+        files={"file": ("bg.webp", oversized, "image/webp")},
+    )
+    assert response.status_code == 413
+    assert response.json()["detail"] == "background_too_large"
+
+
+async def test_upload_background_over_limit_returns_409_and_keeps_ten(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """Лимит держится на СЕРВЕРЕ: интерфейс можно обойти прямым запросом."""
+    user = await _make_user(db_session)
+    await db_session.commit()
+    for _ in range(MAX_BACKGROUNDS_PER_USER):
+        assert (await _upload_background(client, user)).status_code == 201
+
+    response = await _upload_background(client, user)
+    assert response.status_code == 409
+    assert response.json()["detail"] == "background_limit_reached"
+
+    listing = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(user))
+    assert len(listing.json()["items"]) == MAX_BACKGROUNDS_PER_USER
+
+
+async def test_delete_background_removes_file_and_row(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+    created = (await _upload_background(client, user)).json()["items"][0]
+    file_path = media_root / created["url"].removeprefix("/media/")
+    assert file_path.exists()
+
+    response = await client.delete(
+        f"/api/v1/users/me/backgrounds/{created['id']}", headers=_auth_headers(user)
+    )
+    assert response.status_code == 204
+    assert not file_path.exists()
+
+    listing = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(user))
+    assert listing.json()["items"] == []
+
+
+async def test_delete_other_users_background_returns_404(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """Знание id чужой картинки не даёт её удалить — владелец в условии запроса."""
+    owner = await _make_user(db_session)
+    stranger = await _make_user(db_session)
+    await db_session.commit()
+    created = (await _upload_background(client, owner)).json()["items"][0]
+
+    response = await client.delete(
+        f"/api/v1/users/me/backgrounds/{created['id']}", headers=_auth_headers(stranger)
+    )
+    assert response.status_code == 404
+    assert (media_root / created["url"].removeprefix("/media/")).exists()
+
+
+async def test_backgrounds_list_does_not_leak_other_users_images(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    owner = await _make_user(db_session)
+    stranger = await _make_user(db_session)
+    await db_session.commit()
+    await _upload_background(client, owner)
+
+    response = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(stranger))
+    assert response.json()["items"] == []
+
+
+async def test_backgrounds_require_authentication(
+    media_root: Path, client: httpx.AsyncClient
+) -> None:
+    assert (await client.get("/api/v1/users/me/backgrounds")).status_code == 401
+    assert (
+        await client.delete(f"/api/v1/users/me/backgrounds/{uuid.uuid4()}")
+    ).status_code == 401