Lychee: управление фотогалереей, альбомами и доступом

Lychee нужен тем, кто хочет хранить фотографии и видео на собственном сервере, раскладывать их по вложенным альбомам, публиковать отдельные подборки, выдавать права другим пользователям и просматривать медиатеку из обычного браузера. Он особенно полезен для домашнего фотоархива, семейной галереи, портфолио фотографа и небольшой команды, которой важны собственное хранилище, понятные ссылки на альбомы, EXIF и геоданные, а не сложная пиксельная ретушь каждого кадра.

Что именно делает Lychee

В Lychee фотография рассматривается прежде всего как объект библиотеки: у нее есть оригинал, производные размеры для быстрого просмотра, название, описание, дата съемки, теги, рейтинг, технические метаданные и принадлежность к альбомам. Поэтому типичный рабочий день в системе состоит не из рисования кистью или сложной цветокоррекции, а из загрузки материала, отбора, группировки, правки метаданных, выдачи доступа и публикации. Встроенный редактор решает ограниченный набор задач, например ручной поворот, тогда как серьезную обработку RAW, удаление объектов или локальную ретушь разумно выполнять до помещения готовых файлов в галерею.

Другие инструменты: ФотоМАСТЕР.

Главный объект структуры — альбом. Альбомы разрешено вкладывать друг в друга, назначать им обложки и верхние изображения, менять порядок фотографий и вариант раскладки. Для вывода снимков предусмотрены макеты с выравниванием, «кладкой» и квадратными миниатюрами. На практике это позволяет отдельно оформить, например, «2026 → Путешествия → Исландия», клиентские съемки по проектам или несколько уровней семейного архива, не создавая для каждой темы отдельный сайт.

Вторая сторона Lychee — публикация. Альбом можно оставить приватным, открыть публично, защитить паролем, разрешить или запретить скачивание, а также выдать доступ конкретным зарегистрированным пользователям. Права задаются на уровне альбомов, поэтому одна и та же установка может одновременно содержать закрытый личный архив, публичное портфолио и рабочие подборки для коллег. Для публичной выдачи можно использовать обычное представление галереи, полноэкранный просмотр, слайд-шоу и встраивание альбома во внешний сайт.

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

Интерфейс и логика библиотеки

После входа пользователь попадает в представление альбомов. Верхняя панель служит для основных действий, а меню добавления открывается кнопкой с плюсом. В официальной документации создание альбома описано через команду New Album; клавиша n выполняет ту же задачу быстрее. Клавиша u открывает загрузку, s — поиск, а Ctrl+A или Cmd+A выделяет все альбомы в текущем представлении.

Карточка альбома — не просто папка с названием. В зависимости от настроек на ней отображаются обложка и дополнительные индикаторы, а внутри можно задать собственный порядок фотографий, отдельное изображение заголовка, пропорции миниатюр и раскладку. Это удобно, когда корневая галерея должна выглядеть как витрина, а вложенные служебные альбомы — как компактный каталог. Если внешний вид корня и внутреннего альбома не совпадает, сначала проверяют не глобальную тему, а параметры конкретного альбома.

Lychee активно использует контекстные действия и множественное выделение. В интерфейсе можно выбирать несколько фотографий через привычные сочетания с Ctrl и Shift, а затем выполнять операции над группой. Среди реальных операций — пометка избранного, назначение обложки или заголовочного кадра, переименование, перемещение, тегирование, копирование и удаление. Это важнее, чем кажется: при разборе поездки на тысячу кадров скорость зависит от того, можно ли обработать выборку за одно действие, а не открывать каждую карточку отдельно.

На уровне одной фотографии клавиши со стрелками переключают соседние кадры, r открывает изменение названия, t — тегов, d — описания, i — информационную панель, o переключает режим наложения информации, а f включает полноэкранный режим. Эти сочетания полезно освоить до большого отбора: они уменьшают количество переходов к меню и делают Lychee ближе по темпу работы к специализированному менеджеру изображений.

Установка и начало работы

Lychee работает как серверное веб-приложение: браузер является рабочим интерфейсом, но фотографии, база и фоновые задачи находятся на машине, где развернута система. Для обычной установки разработчики рекомендуют Docker Compose. В минимальной конфигурации поднимаются само приложение, база MariaDB и постоянные тома для данных. После запуска compose-файла веб-интерфейс становится доступен на назначенном порту, а при первом посещении предлагается создать учетную запись администратора.

Минимальная команда запуска выглядит как docker compose -f docker-compose.minimal.yaml up -d. Перед этим compose-файл берут из официального проекта и сохраняют локально; вставлять непроверенный вариант из случайного руководства не стоит, потому что структура томов и серверный стек менялись между крупными выпусками. В современной серверной схеме Docker используется FrankenPHP с Laravel Octane, а старый контейнер на nginx и PHP-FPM оставлен как legacy-вариант. Это имеет практическое следствие: конфигурацию старой установки нельзя обновлять простым изменением тега контейнера без проверки томов и переменных.

Для ветки 7 при ручной установке требуется PHP 8.4 или новее. Поддерживаются MySQL или MariaDB, PostgreSQL и SQLite; веб-сервером может быть Apache или nginx. Из расширений PHP критичны типичные компоненты Laravel и обработки изображений: EXIF, GD, mbstring, PDO и другие перечисленные в системных требованиях. ImageMagick не обязателен, но рекомендуется для более качественной работы с изображениями; ExifTool улучшает обработку метаданных, а FFmpeg нужен для генерации миниатюр видео.

При ручной установке веб-сервер должен отдавать именно каталог public/, а не корень проекта. Это не косметическая рекомендация: в верхнем каталоге находятся код и файл окружения, которые не должны быть доступны посетителям. Каталоги storage/, bootstrap/cache/, public/uploads и public/sym должны быть доступны на запись пользователю веб-процесса. Если через веб-интерфейс планируется менять пользовательские CSS, права записи нужны и для соответствующего каталога с собранными ресурсами.

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

Размещение в подпапке поддерживается через APP_DIR, но сами разработчики рекомендуют отдельный домен или поддомен. Причина практическая: префикс пути должны одинаково учитывать ссылки на миниатюры, статические ресурсы, WebAuthn, пользовательский CSS и другие компоненты. Ошибка в одном префиксе проявляется как «частично работающий» сайт, где вход открывается, но изображения или авторизация по ключу безопасности ломаются. Если инфраструктура позволяет, имя вроде photos.example.com проще сопровождать, чем вложенный путь.

В контейнерной установке изменения файла окружения начинают действовать только после перезапуска контейнера: современный сервер загружает и кэширует конфигурацию при старте. Поэтому типичная ситуация «исправил переменную, а поведение не изменилось» сначала проверяется обычным перезапуском сервиса, а уже потом поиском ошибки в самом значении.

Создание альбомов и построение иерархии

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

Новый альбом создается через кнопку + и пункт New Album. Если команда запускается внутри открытого альбома, создается вложенный альбом. После появления карточки имеет смысл сразу задать понятное имя, а уже затем переносить материалы. Названия должны отличаться не только датой, но и смыслом: «2026-08-18 — Балтика» удобнее десяти каталогов «18.08». У Lychee есть собственная база и собственная логика альбомов, поэтому структура на диске не считается пользовательским деревом каталога.

Существующий альбом можно переместить в другое место дерева. Панель перемещения предлагает выбрать целевой альбом, причем выбор поддерживает поиск; после выбора Lychee запрашивает подтверждение. Такой отдельный шаг полезен для больших деревьев: ошибочное перетаскивание десятка вложенных подборок способно испортить структуру сильнее, чем неверное имя. Для реорганизации сначала создайте конечную ветку, затем переносите верхний узел целиком и после операции проверьте дочерние альбомы.

Перемещение и передача владения — разные операции. Move меняет положение альбома в иерархии, но не владельца. Передача альбома другому пользователю выбирает учетную запись нового владельца и также требует подтверждения. Эту функцию следует применять осознанно: она нужна не для обычной выдачи доступа клиенту или члену семьи, а для смены того, кто владеет объектом. Для совместной работы без смены владельца используется механизм sharing.

Когда альбом должен отображаться выразительнее, назначают обложку и при необходимости отдельный header photo. Обложка представляет альбом в списке, а заголовочное изображение используется в оформлении страницы альбома. Автоматический выбор обложки опирается на сортировку фотографий; избранные кадры имеют приоритет, поэтому пометка удачного снимка звездой может повлиять и на визуальное представление альбома. Если нужен гарантированно конкретный кадр, лучше назначить его явно через действие установки обложки.

Для нескольких альбомов с похожими названиями полезна одинаковая схема именования. Lychee умеет сортировать материалы, но название остается тем полем, по которому человек чаще всего ориентируется при поиске назначения подборки. В клиентской работе удобно использовать «дата — проект — этап», в семейном архиве — «год — событие», в портфолио — короткие жанровые названия. Не стоит прятать критическую информацию только в описании: карточки и выпадающие списки назначения легче читать по коротким однозначным заголовкам.

Если дерево уже получилось слишком глубоким, исправлять его лучше сверху вниз. Перенесите целый альбом в новую ветку, убедитесь, что дочерние элементы сохранились и ссылки, которыми пользуются посетители, продолжают открываться в ожидаемом контексте. Затем переименуйте узлы. Массовое удаление и повторная загрузка — плохой способ «навести порядок»: вместе с объектами можно потерять ручные теги, описания, рейтинги и настройки доступа.

Загрузка фотографий через браузер

Для обычной загрузки используются перетаскивание файлов в окно и кнопка загрузки в верхней панели. В открытом альбоме клавиша u вызывает тот же сценарий. Перед началом убедитесь, что выбран именно целевой альбом: перенос после загрузки поддерживается, но лишняя сортировка заметно увеличивает объем ручной работы, особенно если параллельно создаются миниатюры и извлекаются метаданные.

Загрузчик поддерживает chunk upload — большие файлы разбиваются на части — и параллельную обработку. Размер части задается настройкой upload_chunk_size; значение по умолчанию позволяет системе подобрать его автоматически. Число одновременно обрабатываемых изображений регулирует upload_processing_limit. Увеличивать параллелизм «на всякий случай» не стоит: обработка изображений потребляет CPU и память, поэтому на малом VPS больше одновременных задач способно не ускорить, а затормозить весь интерфейс.

Панель загрузки показывает список заданий и их состояние. Для длинного импорта полезно не закрывать ее сразу после первого успешного кадра, а дождаться окончания очереди и проверить ошибки. Настройка close_upload_on_success может автоматически закрывать панель, если все прошло успешно; при ошибках она остается открытой. На сервере с нестабильными лимитами это предпочтительнее молчаливого закрытия, потому что видно, какой конкретно файл не был принят.

Lychee умеет принимать целую папку перетаскиванием, если включено folder_upload_enabled. Верхняя папка превращается в альбом, вложенные папки — во вложенные альбомы. Глубину рекурсии ограничивает folder_upload_max_depth. Такой способ удобен для нескольких аккуратно подготовленных каталогов, но перед переносом старого диска лучше удалить технические папки и проверить названия: браузерная загрузка повторит логическую иерархию и тем самым перенесет в галерею старые организационные ошибки.

Если загрузка обрывается на больших видео или панорамах, проблема часто находится не в Lychee. При ручной установке нужно проверить ограничения PHP и обратного прокси: максимальный размер тела запроса, лимит загружаемого файла, максимальный размер POST и время выполнения. При chunk upload отдельные запросы меньше, но финальная сборка и обработка все равно требуют доступного временного каталога. Параметр USE_SYSTEM_TEMP_DIR определяет, используется ли системная временная папка; на ограниченном хостинге можно переключиться на внутренний каталог временных частей.

Еще одна типичная причина отказа — права записи. Контейнер должен видеть постоянный том для загрузок, а веб-процесс — иметь возможность создавать там файлы и подкаталоги. Если миниатюра появляется, а оригинал пропадает после перезапуска контейнера, почти всегда нужно проверить не интерфейс Lychee, а монтирование тома: данные, записанные в непостоянный слой контейнера, не предназначены для хранения медиатеки.

Импорт большого архива и синхронизация каталогов

Для тысяч файлов предпочтительнее командная синхронизация. Базовая команда имеет вид php artisan lychee:sync /path/to/import. Она обходит каталог рекурсивно и может создавать альбомы из папок. Если данные нужно положить внутрь уже существующего альбома, используется параметр --album_id. В Docker путь источника сначала монтируют в контейнер, а затем запускают команду внутри контейнера, чтобы процесс видел исходные файлы.

У синхронизации есть опции, которые нельзя включать механически. --skip_duplicates помогает пропускать уже имеющиеся элементы, --import_via_symlink меняет способ присоединения файлов, --resync_metadata позволяет повторно прочитать метаданные, а параметры удаления могут удалять из Lychee объекты, исчезнувшие из исходного каталога. Поэтому перед зеркальной синхронизацией проверяют текущие значения и запускают сухой прогон. Настройка sync_dry_run существует именно для того, чтобы сначала увидеть последствия разрушительных операций.

Отдельный механизм skip_duplicates_early ускоряет некоторые сценарии sync, проверяя названия в целевом альбоме до более дорогой проверки контрольной суммы. Это компромисс между скоростью и строгостью: одинаковое имя удобно как ранний фильтр, но содержимое файла надежнее характеризует хэш. При миграции из разнородных источников, где камеры много раз создавали IMG_0001, нельзя считать одно имя достаточным основанием для удаления кандидата.

Синхронизацию можно запускать по расписанию через cron или systemd timer. Такой вариант подходит для папки-приемника на NAS: камера или рабочая станция выгружает туда новые файлы, а сервер периодически индексирует содержимое. Но Lychee не является прозрачным просмотрщиком произвольного дерева на диске. Его FAQ прямо объясняет, что приложение ведет собственную структуру и базу. Поэтому «подмонтировать архив и никогда не импортировать» — не тот сценарий, на который рассчитана логика альбомов.

В более новых вариантах sync есть обратная синхронизация: при явно разрешенных настройках можно удалять из Lychee фотографии и альбомы, которых больше нет в обозначенном источнике. Это мощный инструмент для управляемого зеркала, но он требует резервной копии и внимательной проверки dry-run. Для архива, где пользователи вручную меняют теги и раскладывают фотографии в дополнительные альбомы, автоматическое удаление стоит применять только после понимания того, какая часть базы считается производной от файловой системы.

Импорт через серверный путь можно отключить переменной DISABLE_IMPORT_FROM_SERVER. На публичной установке это разумная мера, если администратору функция не нужна: возможность читать доступные серверу пути увеличивает последствия компрометации административной учетной записи. Безопасность здесь важнее удобства разовой миграции; после переноса архива ненужный импорт лучше закрыть.

Поддерживаемые изображения и видео

Официальная пользовательская документация перечисляет для обычной загрузки изображения jpg, jpeg, png, gif и webp, а для видео — ogv, mp4, mpg, webm, mov, m4v, avi и wmv. Поддержка контейнера еще не означает, что любой кодек внутри него воспроизведется каждым браузером. Если старый AVI загружается, но не проигрывается у посетителя, нужно различать успешное хранение файла, генерацию превью и фактическую поддержку кодека клиентским браузером.

Для нестандартных исходников существует настройка raw_formats, позволяющая дополнительно объявить расширения как raw/passthrough. Это не превращает Lychee в RAW-конвертер: идея в том, чтобы сохранить исходный файл и не пытаться обработать его как обычный JPEG. Если пользователь ожидает увидеть полноценную проявку сенсорного RAW прямо в галерее, ему нужен отдельный редактор или DAM с модулем проявки.

Параметр raw_download_enabled управляет возможностью скачивания сохраненного исходника RAW, HEIC или PSD для пользователей, у которых вообще есть право на скачивание. В клиентской галерее это важно: можно показывать удобные производные, но не отдавать тяжелые или рабочие оригиналы каждому посетителю. Право на скачивание и наличие исходного файла — разные уровни контроля.

Оригиналы, миниатюры и качество производных

Lychee не должен каждый раз отдавать браузеру многомегабайтный оригинал. При добавлении фотографии система создает варианты для разных представлений. В настройках обработки предусмотрены отдельные ограничения для small и medium, включая small_max_height, small_max_width, medium_max_height и medium_max_width. Для экранов с высокой плотностью пикселей можно создавать варианты 2× через thumb_2x, small_2x и medium_2x.

По умолчанию средний вариант ориентирован на просмотр примерно в диапазоне Full HD, а миниатюры значительно меньше. Это не следует трактовать как ограничение оригинала: производные нужны для интерфейса, а исходник остается отдельным объектом. Если посетителю разрешено скачивание в полном разрешении, сервер может отдать оригинал независимо от того, какой размер показывался в альбоме.

Настройка compression_quality задает качество JPEG при генерации миниатюр и промежуточных изображений. Слишком высокое значение увеличивает размер кэша и сетевой трафик, слишком низкое заметно портит детали и плавные градиенты. Для фотопортфолио лучше начать со стандартного значения и менять его только после просмотра типичных кадров на нескольких устройствах, а не ориентироваться на одну фотографию с удобным для кодека содержимым.

low_quality_image_placeholder включает создание облегченного placeholder для прогрессивной загрузки. Пользователь сначала видит быстрый предварительный образ, а затем более качественный вариант. На большой публичной галерее это субъективно делает прокрутку плавнее, но добавляет еще один тип производного файла, который занимает место и создается процессором при импорте.

Параметр keep_original_untouched особенно важен, если сервер считается частью архива. Автоматическое исправление ориентации через auto_fix_orientation способно физически изменить и повторно сжать изображение; сохранение нетронутого оригинала оставляет исходный файл отдельно. Если приоритет — долговременная сохранность материала, не отключайте эту защиту только ради экономии диска, пока не продумана другая резервная копия.

Сервер обработки выбирает ImageMagick, когда он доступен и разрешен настройкой imagick; иначе возможен откат к GD. Разница проявляется не в кнопках интерфейса, а в поддержке форматов, качестве и возможностях серверной обработки. Поэтому при «странной» миниатюре полезно проверить, какой драйвер реально используется, а не только сравнивать браузеры.

Метаданные: EXIF, дата съемки и описание

После загрузки Lychee извлекает EXIF и показывает технические сведения о снимке. Для практической библиотеки важны не только модель камеры и параметры экспозиции, но прежде всего дата съемки и ориентация. Когда время в файле корректно, оно становится основой хронологического просмотра и сортировки. Если архив собран из мессенджеров, сканов и экспортов, даты нередко отсутствуют или отражают момент копирования, поэтому их следует проверить до построения таймлайна.

В интерфейсе дата относится к редактируемым данным фотографии. Это позволяет исправить снимок, которому сканер или редактор записал неверное время. При массовой миграции сначала полезно синхронизировать метаданные средствами, умеющими работать пакетно, а затем импортировать результат. Ручная правка сотен дат уже после создания альбомов возможна, но становится отдельным проектом.

ExifTool в требованиях Lychee отмечен как необязательный инструмент, который дает более качественную работу с EXIF. Если сервер строится для разнородного архива с файлами разных камер и приложений, его наличие разумно. Путь к бинарнику задается exiftool_path, а состояние поддержки отражает has_exiftool. Если часть полей «пропала» после переезда на новый сервер, проверьте не только сами файлы, но и наличие этого инструмента в новом окружении.

Кроме встроенного EXIF, можно предпочитать XMP-метаданные, если рядом с фотографиями есть sidecar-файлы; за это отвечает prefer_available_xmp_metadata. Такой сценарий полезен после Lightroom и других менеджеров, где подписи, рейтинг или дополнительные поля хранятся во внешнем XMP. До массового импорта стоит проверить несколько файлов: разные программы записывают XMP не одинаково, и «предпочитать XMP» не означает автоматически импортировать любую пользовательскую схему полей.

Название и описание в Lychee — самостоятельные поля библиотеки. Заголовок удобно использовать для короткого человекочитаемого имени, описание — для контекста: места, события, авторской заметки или сведений для клиента. В режиме просмотра клавиша r вызывает работу с названием, d — с описанием. Эти поля видны независимо от имени файла, поэтому можно сохранить исходное техническое имя камеры и одновременно дать кадру понятное представление.

Информационный слой на фотографии переключается клавишей o. В официальных материалах интерфейса описаны состояния без оверлея, с описанием, датой и EXIF. Это удобнее постоянной боковой панели, если при просмотре нужно быстро сравнить кадры и время съемки. Выбранный режим сохраняется при переходах, поэтому для технической проверки серии можно включить EXIF один раз и листать стрелками.

GPS и карта фотографий

Если в EXIF присутствуют координаты, Lychee может использовать их для географического представления. Карта полезна не только в отпускном архиве: фотографу она помогает проверить, где снималась серия, а семейной библиотеке — найти события по месту, когда название альбома забыто. Координаты берутся из метаданных, поэтому фотографии без GPS не появятся «автоматически» в нужной точке только по тексту описания.

Для расшифровки координат в названия мест применяется геокодирование, и конфигурация содержит ограничение частоты запросов LOCATION_DECODING_REQUESTS_PER_SECOND. Повышать его без собственного сервиса геокодирования не следует: внешние службы вводят ограничения не случайно. При большом первичном импорте лучше дать фоновой обработке время, чем создавать агрессивный поток запросов и получать ошибки.

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

Если карта остается пустой, проверка идет по цепочке. Сначала открывают информационную панель конкретного снимка и убеждаются, что координаты действительно извлечены. Затем проверяют доступность картографического провайдера и настройки сети сервера. Только после этого имеет смысл переиндексировать метаданные. Частая ошибка — ожидать GPS от изображения, которое уже прошло через социальную сеть или мессенджер и было очищено от EXIF.

Теги, рейтинг и отбор

Иерархия альбомов отвечает на вопрос «где лежит подборка», а теги — «какие свойства объединяют кадры». Один снимок может относиться к поездке, но одновременно иметь теги «портрет», «ночь», «85 мм» и имя человека. Поэтому теги удобнее второй параллельной системы папок: не нужно создавать копии файла ради каждого признака.

Теги можно назначать одной фотографии или группе выбранных файлов. Для отдельного кадра работает клавиша t. Перед созданием сотен тегов полезно определить словарь: «Москва» и «москва» или «портрет» и «портреты» могут стать отдельными значениями и ухудшить поиск. Лучше выбрать одно написание, а редкие уточнения оставлять в описании.

В ветке 7 есть рейтинг от одной до пяти звезд. Он подходит для отбора внутри большой съемки: низкие оценки можно использовать как рабочий статус, высокие — как кандидатов в портфолио. Настройки smart albums позволяют включать подборки по уровням рейтинга, а отдельные «My Rated Pictures» относятся к оценкам текущего пользователя. Некоторые расширенные подборки и статистика зависят от редакции, поэтому при проектировании процесса надо различать базовые рейтинги и дополнительные функции Supporter Edition.

Звезда избранного и числовой рейтинг решают похожие, но не одинаковые задачи. Избранное — быстрый бинарный признак, рейтинг — градация. Если команда начнет использовать оба механизма без правила, возникнут вопросы вроде «почему пять звезд, но не favorite». Практичная схема: favorite обозначает кадры для публичной витрины, рейтинг — внутренний уровень отбора. Тогда поведение понятно и человеку, и автоматическим альбомам.

Автоматические альбомы удобны как представления базы, а не как дополнительное место хранения. Снимок не перемещается физически только потому, что попал в выборку «5 звезд». Это снижает риск дублирования и позволяет менять критерий без копирования файлов. При резервном копировании, однако, важно сохранять не только uploads: правила, оценки и связи находятся в базе.

Поиск и навигация по большой коллекции

Поиск Lychee работает поверх данных, которые система хранит о фотографиях и альбомах. Поэтому его качество напрямую зависит от дисциплины метаданных: содержательное название, теги, правильная дата и геоданные полезнее сотен каталогов с именами камеры. Поиск вызывается клавишей s на экране альбомов; в больших библиотеках это быстрее ручного раскрытия нескольких уровней дерева.

Не следует путать Lychee с AI-каталогизатором. В базовом сценарии система не обещает автоматически распознать «собаку на пляже» или найти человека по лицу так, как это делают PhotoPrism и Immich. Сильная сторона Lychee — управляемая пользователем галерея, альбомы, метаданные и права. Если автоматическая классификация содержания является центральной задачей, этот критерий нужно учитывать до миграции, а не пытаться компенсировать отсутствующий индекс тысячами ручных тегов.

Для быстрого перехода между соседними фотографиями не нужно возвращаться в сетку: стрелки влево и вправо открывают предыдущий и следующий кадр. Информационная панель вызывается i, полноэкранный режим — f. Сочетание этих действий дает эффективный режим проверки: открыть первый снимок серии, включить нужный оверлей и пройти всю последовательность стрелками.

Полноэкранный просмотр, слайд-шоу и Frame

Lychee предлагает несколько способов показать готовую подборку. Обычный просмотр сохраняет элементы управления, полноэкранный режим убирает лишнее, слайд-шоу последовательно показывает фотографии текущего альбома, а Frame ориентирован на экран, где изображения могут меняться как фоторамка. Эти режимы не создают новых копий альбома: они меняют представление уже существующих объектов.

В слайд-шоу кадры идут в порядке текущего альбома; воспроизведение можно запустить из интерфейса, а стрелки позволяют вручную перейти дальше или назад. Это отличается от Frame, который задуман скорее для автономного дисплея и может выбирать изображения иначе. Если клиент должен увидеть строго выстроенную историю съемки, используйте слайд-шоу и заранее настройте сортировку альбома.

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

Публичные альбомы и права на скачивание

Публикация в Lychee строится вокруг прав альбома. Альбом можно оставить приватным или сделать доступным публике. Для публичного альбома разрешается включить пароль, отдельно определить возможность скачивания и решить, должен ли он появляться в общей публичной галерее. Такая комбинация удобна для клиентских съемок: ссылка работает без создания учетной записи, но содержимое можно закрыть паролем и не выводить на витрину сайта.

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

Альбомы могут выгружаться ZIP-архивом с фотографиями в исходном разрешении. Для очень больших подборок есть режим разбивки архива на несколько частей: download_archive_chunked включает его, а download_archive_chunk_size ограничивает число фотографий в одной части. Такая схема полезна, когда создание одного огромного ZIP упирается в память, время выполнения или нестабильный клиентский канал.

download_archive_drop_extension_enabled помогает избежать двойных расширений в архивах, если пользовательские заголовки уже содержат суффикс файла. Это небольшая настройка, но она показывает важное различие между названием объекта в базе и фактическим именем выгружаемого файла. Перед передачей архива клиенту полезно один раз скачать тестовый ZIP и проверить, как выглядят имена внутри.

Глобальные настройки grants_download и grants_full_photo_access задают поведение для случаев, не перекрытых отдельными правами. Их нельзя менять, не понимая модели доступа: удобная галочка «разрешить всем» способна незаметно увеличить объем доступных данных. Для публичной галереи безопаснее начинать с минимальных прав и расширять их по конкретным альбомам.

Общий доступ конкретным пользователям

Вместо публичной ссылки альбом можно расшарить зарегистрированным пользователям той же установки. Документация различает доступ на чтение и более полные права; кросс-пользовательский sharing позволяет нескольким людям работать с одной подборкой, не меняя ее владельца. Это полезно для семейного архива и небольшой редакции, где учетные записи постоянны и пароль на каждую ссылку был бы неудобен.

Права нужно назначать по принципу задачи. Человек, которому требуется только просмотр, не должен получать возможность менять структуру. Пользователь, который отбирает и дополняет проект, может получить расширенный доступ. Отдельно контролируется скачивание. Такая детализация снижает риск случайного удаления и позволяет одной установке обслуживать и авторов, и зрителей.

Контекстное меню может отличаться у владельца и у приглашенного пользователя. В официальном FAQ отдельно разбирается ситуация, когда расширенное меню правой кнопки не появляется у нового пользователя: это нормально, если он не владеет альбомом и имеет только предоставленное чтение. Поэтому при проверке жалобы «кнопка пропала» сначала сравнивают роль и права учетных записей, а не переустанавливают фронтенд.

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

Пользователи, регистрация и уровни доверия

Администратор управляет учетными записями через раздел Users. Lychee поддерживает создание, изменение и удаление пользователей, страницу регистрации и приглашения. Пригласительные ссылки удобны для контролируемого онбординга, когда открытая регистрация не нужна. В документации также упоминаются trust levels, определяющие набор возможностей пользователя.

На одной установке каждый человек может иметь собственные материалы и одновременно получать доступ к чужим альбомам. Это отличается от простой галереи с одним общим паролем: действия можно привязать к учетной записи и точнее распределить права. Для семейного сервера это позволяет отделить личные коллекции, а для небольшой студии — рабочие зоны фотографов.

Часть административных возможностей относится к Supporter Edition: учет занимаемого места по пользователям, квоты загрузки, внутренние заметки, несколько администраторов и группы пользователей. Базовую модель Lychee не следует описывать так, будто все эти инструменты входят в любой экземпляр. Если проекту нужны квоты или групповое управление, редакцию проверяют до развертывания, а не после заполнения диска.

В версии с группами удобнее назначать права не десяткам учетных записей по одной, а устойчивым ролям: редакция, семья, клиентская команда. Однако группа не отменяет необходимости правильно определить публичность альбома. Публичный объект остается доступен шире группы, если настройки это разрешают.

Вход: пароль, WebAuthn и OAuth

Lychee поддерживает традиционный логин и пароль, WebAuthn и OAuth. WebAuthn позволяет использовать аппаратный ключ безопасности или биометрию устройства, а OAuth — внешний поставщик идентификации. Для собственного сервера это дает выбор: оставить автономные учетные записи либо связать вход с уже существующей системой организации.

Если настроен альтернативный безопасный способ входа, базовую авторизацию можно отключить параметром DISABLE_BASIC_AUTH. Делать это до проверки WebAuthn или OAuth нельзя: ошибка конфигурации способна оставить администратора без рабочего входа. Сначала регистрируют и тестируют второй способ в отдельной сессии, затем сохраняют резервный административный путь и только после этого ужесточают настройки.

WebAuthn чувствителен к правильному внешнему адресу приложения и схеме публикации через прокси. Если APP_URL, доверенные прокси или путь установки заданы неверно, обычная страница может открываться, а регистрация ключа — завершаться ошибкой из-за несовпадения origin. Это еще одна причина использовать отдельный домен и завершать TLS предсказуемо.

В панели WebAuthn ключам можно давать понятные алиасы и видеть сведения о регистрации. Если у пользователя несколько устройств, названия «рабочий ноутбук», «домашний ключ» полезнее безликих записей. При потере устройства администратор и пользователь должны понимать, какой credential нужно удалить, не уничтожая остальные.

Настройки внешнего вида альбома

Для представления фотографий Lychee предлагает несколько раскладок: justified, masonry и square. Justified стремится собирать строки одинаковой высоты из кадров разных пропорций, masonry сохраняет «колоночную» разницу высот, square делает сетку предсказуемых квадратных миниатюр. Выбор зависит от контента: репортаж с горизонтальными и вертикальными кадрами обычно выигрывает от justified, каталог однотипных объектов — от квадратной сетки.

Отдельно меняется пропорция миниатюр. Эта настройка затрагивает представление, а не геометрию оригинала. Если портреты в квадратной сетке выглядят обрезанными, не нужно кадрировать файлы заново: сначала проверьте режим миниатюр и макет. Для публичного портфолио это безопаснее, чем создавать отдельные экспортные копии только ради сетки.

Сортировку можно задавать на уровне альбома. Практическое правило простое: если порядок важен для повествования, задайте его явно перед публикацией; если альбом служит архивом, лучше сортировать по корректной дате съемки. Полагаться на имя файла можно только при строгой и стабильной схеме именования.

Timeline выводит материалы хронологически. В документации по альбомам он отмечен как функция Supporter Edition, поэтому не стоит строить обязательный пользовательский сценарий вокруг таймлайна, не проверив доступность редакции. Обычная сортировка по дате остается полезной и без него, но визуальная временная группировка — отдельная возможность.

Flow — еще один вариант представления, ориентированный на ленту недавних альбомов. Он удобен, когда галерея обновляется сериями и посетители хотят видеть новое содержание последовательно, а не заходить в иерархический каталог. Для архивного корня Flow и дерево альбомов решают разные задачи; чаще всего один из режимов выбирают как основное публичное представление, не пытаясь сделать их взаимозаменяемыми.

Настройки интерфейса и персонализация

Панель Settings разделяет обычные параметры и более полный набор. Большое количество опций — сильная сторона Lychee, но одновременно источник ошибок. Изменять десятки значений сразу неудобно: если после этого сломается вид альбома, трудно понять причину. Лучше зафиксировать исходное состояние и менять группы параметров по одной: сначала интерфейс, затем обработку изображений, затем права.

Сайт можно персонализировать через пользовательский CSS, а собственный JavaScript — через custom.js или соответствующую область настроек. Это дает свободу подогнать внешний вид под портфолио, но пользовательский код становится частью сопровождения. После крупного обновления его нужно тестировать: внутренние классы и структура фронтенда могут измениться, и старый селектор перестанет попадать в нужный элемент.

Если оформление важно для бизнеса, храните CSS и JavaScript рядом с инфраструктурным кодом или хотя бы в резервной копии. Правка только в браузерной панели удобна до первого аварийного восстановления. В Docker пользовательские файлы можно монтировать в каталог собранных ресурсов, чтобы они переживали замену контейнера и были явно описаны в compose-конфигурации.

Параметр site_title меняет название сайта. В расширенной настройке можно управлять положением элементов входа и другими деталями. Но чрезмерная кастомизация не должна скрывать базовые действия — поиск, вход, загрузку, переход к галерее. Пользователь, который не знает вашу тему, должен без объяснений понять, где вернуться к альбомам.

Клавиатурные сокращения как рабочий инструмент

Lychee показывает справку по горячим клавишам, и ее стоит оставить включенной хотя бы на первых сессиях. В глобальных диалогах Enter подтверждает действие, Esc закрывает или возвращает назад. На экране альбомов n, u и s соответствуют созданию, загрузке и поиску.

Внутри альбома n создает вложенный альбом, r меняет заголовок, d — описание, i показывает информацию, f переключает полноэкранный режим. Удаление привязано к сочетанию с Backspace и управляющей клавишей, что снижает риск случайного нажатия одной кнопки.

В просмотре фото стрелки перемещают по серии, t открывает теги, s переключает favorite, а o меняет информационный оверлей. Для отбора это позволяет практически не уводить курсор к панелям. Если браузер или операционная система перехватывает конкретное сочетание, лучше использовать экранную кнопку, а не переназначать системный shortcut ценой неожиданного поведения в других приложениях.

Импорт по ссылке, с сервера и из Dropbox

Помимо обычной загрузки в текущем интерфейсе предусмотрены отдельные действия Import from Link, Import from Server и Import from Dropbox. Их назначение различается. Импорт по ссылке просит сервер получить удаленный файл, серверный импорт берет доступный приложению локальный путь, а Dropbox использует внешний выбор файлов и требует собственной настройки интеграции.

Для Dropbox нужен dropbox_key. Диагностика Lychee прямо предупреждает, если ключ пуст и импорт не сможет работать. Если эта функция не используется, предупреждение можно отключить предусмотренным значением конфигурации, а не оставлять администратора с постоянной «красной» диагностикой. В корпоративной среде ключ следует хранить как секрет и не вставлять в пользовательский CSS, скрипты или публичные инструкции.

Импорт по URL связан с серверными запросами к внешним адресам, поэтому в современных выпусках уделяется внимание защите от SSRF и способу загрузки. Настройка USE_FOPEN_FOR_URL_IMPORTS существует как совместимый вариант, но штатный путь с curl лучше контролирует некоторые риски повторного разрешения адреса. Если функция не нужна пользователям, ее доступ и права стоит ограничить вместе с другими административными действиями.

Серверный импорт полезен, когда архив уже физически находится рядом с Lychee и нет смысла отправлять гигабайты через браузер. Однако он не отменяет модель собственной базы. После импорта файлы и связи должны рассматриваться как часть управляемого состояния Lychee; произвольное перемещение содержимого непосредственно в служебных каталогах способно рассинхронизировать базу и хранилище.

Небольшой встроенный редактор и границы обработки

В настройках есть editor_enabled, разрешающий ручной поворот изображения. Вместе с автоматическим исправлением EXIF-ориентации это закрывает типичную проблему «фото лежит боком», но не превращает Lychee в замену Lightroom, Photoshop или ФотоМАСТЕР. Здесь нет задачи выполнять сложную локальную цветокоррекцию, заменять фон, ретушировать кожу или собирать многослойный монтаж.

Это ограничение полезно учитывать при построении конвейера. Хорошая схема для фотографа: RAW проявляется и ретушируется в профильном редакторе, итоговые JPEG или подходящие веб-форматы экспортируются с корректными метаданными, затем Lychee берет на себя каталогизацию, представление, доступ и выдачу. Если пытаться переносить этап художественной обработки внутрь галереи, пользователь быстро упрется в отсутствие инструментов, которых разработчики и не обещают.

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

Хранилище, локальный диск и S3

По умолчанию Lychee хранит медиаданные в назначенном каталоге загрузок. В Docker ветки 7 постоянный том обычно монтируется в /app/public/uploads, служебные данные — в /app/storage/app, логи — в /app/storage/logs, временные файлы — в /app/storage/tmp. Эти пути важны не потому, что пользователь должен вручную раскладывать фотографии, а потому, что именно их нужно включить в резервирование и правильно смонтировать.

Конфигурация также поддерживает S3-совместимое хранилище через S3_ENABLED и стандартные параметры доступа. Этот вариант полезен, когда приложение и медиа должны масштабироваться отдельно или когда объектное хранилище уже является частью инфраструктуры. Но S3 не избавляет от базы: альбомы, права, пользователи, описания, рейтинги и связи остаются в СУБД.

Выбор между локальным диском и объектным хранилищем зависит от окружения. Домашнему серверу проще локальный ZFS/Btrfs-массив с понятным резервированием. Облачному развертыванию удобнее S3-совместимый backend с политиками жизненного цикла. Не стоит выбирать S3 только из-за слова «облако»: стоимость исходящего трафика и запросов может оказаться выше стоимости обычного диска, особенно если публичная галерея часто отдает большие изображения.

LYCHEE_UPLOADS, LYCHEE_UPLOADS_DIR и LYCHEE_UPLOADS_URL позволяют настроить расположение и URL загрузок. Эти параметры лучше не менять после наполнения библиотеки без плана миграции. Ошибка в физическом пути даст пропавшие файлы, ошибка в публичном URL — битые изображения при сохранных данных. Любое такое изменение сначала проверяют на копии или тестовом экземпляре.

Резервное копирование и восстановление

Полная резервная копия Lychee состоит как минимум из базы данных, оригиналов/загрузок и значимой конфигурации. Копирование только каталога фотографий недостаточно: без базы исчезнут структура альбомов, пользователи, права, теги, описания и рейтинги. Копирование только базы еще хуже — записи будут указывать на отсутствующие файлы.

Для контейнерной установки удобно отделить постоянные тома от контейнера и резервировать их обычными средствами инфраструктуры. Базу MySQL/MariaDB или PostgreSQL следует снимать согласованным дампом либо снапшотом, который гарантирует целостность. SQLite требует аккуратного копирования файла базы с учетом активных записей. Перед крупным обновлением разумно иметь отдельную точку восстановления, а не полагаться только на ежедневную ротацию.

Проверка резервной копии — это восстановление, а не факт появления архива на другом диске. Периодически разверните тестовый экземпляр, подключите копию БД и медиакаталог и откройте несколько альбомов с разными правами. Так обнаруживаются проблемы с отсутствующими пользовательскими ресурсами, неправильными ключами окружения и неполной копией томов раньше, чем произойдет авария.

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

Производительность без выдуманных «магических» цифр

Скорость Lychee зависит от четырех разных контуров: базы данных, обработки изображений, диска и доставки файлов браузеру. Нельзя оценить систему одной цифрой «столько-то фотографий в секунду». Галерея с 100 000 уже обработанных JPEG и быстрым кэшем может листаться легче, чем одновременная загрузка сотни RAW на сервер с медленным CPU, хотя количество объектов у первой намного больше.

В Docker ветки 7 используется FrankenPHP с Laravel Octane: приложение держит части фреймворка в памяти и повторно использует их между запросами. Разработчики также предусмотрели отдельный worker mode для фоновых задач. Практический смысл архитектуры в том, что веб-запросы и тяжелая обработка загрузок можно разнести, а несколько worker-процессов — масштабировать независимо от фронтового сервиса.

Чтобы worker действительно обрабатывал очередь, QUEUE_CONNECTION должен быть одинаково настроен у API и работников, а сервис worker запускается с LYCHEE_MODE=worker. Поддерживаются, в частности, база или Redis как backend очереди. Если worker «ничего не делает», проверяют эти переменные, общую базу, общие тома и его логи. Простое добавление второго контейнера без общей очереди работы не распределит.

На небольшом сервере не нужно начинать с четырех работников только потому, что документация допускает масштабирование. Сначала измеряют собственную очередь: загрузить типичную партию, посмотреть CPU, память, I/O и время ожидания веб-интерфейса. Если процессор уже полностью занят одним преобразованием ImageMagick, дополнительный параллелизм лишь усилит конкуренцию. Если CPU простаивает, а очередь последовательна, увеличение worker может помочь.

Для Redis есть две разные роли, которые легко перепутать: очередь фоновых заданий и кэш ответов. Настройка ENABLE_REQUEST_CACHING открывает параметры Redis-backed response caching в административной панели, но это не то же самое, что выбор Redis для очереди. Перед оптимизацией нужно определить, где задержка — в повторных запросах API, в SQL, в генерации миниатюр или в чтении файлов.

Большие галереи выигрывают от предварительно созданных миниатюр: браузер не должен декодировать оригинал камеры ради маленькой плитки. Цена — дополнительное место на диске и CPU во время импорта. Если диск ограничен, уменьшение числа HiDPI-вариантов дает реальную экономию, но сначала следует оценить качество на Retina/HiDPI-экранах.

Видео создает отдельную нагрузку. FFmpeg нужен для миниатюр и некоторых операций с видеоматериалом, а исходный файл может быть намного тяжелее фотографии. Если галерея содержит много видео, трафик и пространство планируют отдельно от фото. Не стоит экстраполировать размер JPEG-архива на коллекцию 4K MOV.

Безопасная публикация в интернет

Первое правило — TLS перед публичным сервером. В Docker Lychee часто находится за nginx, Traefik или Caddy, которые завершают HTTPS и передают запрос приложению. В такой схеме важно правильно настроить APP_URL, APP_FORCE_HTTPS при необходимости и TRUSTED_PROXIES. Иначе приложение может генерировать неправильные схемы ссылок, а журнал — видеть адрес прокси вместо клиента.

Второе правило — не включать APP_DEBUG на публичном сервере и оставлять APP_ENV=production. В режиме разработки диагностические страницы рассчитаны на разработчика, а не посетителя. Они могут показывать стек вызовов и переменные окружения. Исправление ошибки через публичный debug — плохой обмен удобства на утечку инфраструктурных деталей.

Третье правило — ключи и пароли не должны попадать в репозиторий с compose-файлом. Docker-конфигурация Lychee поддерживает передачу некоторых секретов через файлы, включая APP_KEY_FILE, DB_PASSWORD_FILE и ADMIN_PASSWORD_FILE. Даже если домашняя установка не использует Docker secrets, принцип остается тем же: секреты отделяют от общего конфигурационного шаблона.

Четвертое правило — отключать неиспользуемые поверхности. Если серверный импорт не нужен, есть DISABLE_IMPORT_FROM_SERVER. Если WebAuthn не используется и мешает политике организации, его можно отключить; если наоборот парольный вход больше не нужен после надежной настройки внешней идентификации, можно отключить basic auth. Безопасная конфигурация — не максимальное количество включенных функций, а минимальный необходимый набор.

Защита изображений от прямого хотлинка реализуется через временные подписанные ссылки; для Supporter Edition доступны более защищенные AES-ссылки. Эти механизмы не превращают опубликованную фотографию в DRM: пользователь, который видит изображение в браузере, в принципе может сохранить отображаемые данные или сделать скриншот. Их задача — ограничить произвольное повторное использование прямого URL и усложнить обход правил доступа.

Публичные пароли тоже не должны рассматриваться как полноценная учетная запись. Один общий пароль легко переслать. Для постоянной рабочей группы надежнее зарегистрированные пользователи с индивидуальными правами, а парольный альбом оставить для временной выдачи клиенту.

Глобальная страница общего доступа

Когда расшаренных объектов становится много, отдельная страница sharing помогает увидеть их в одном месте. Это полезно администратору: вместо проверки каждого альбома можно пройтись по существующим публикациям и убрать те, которые больше не нужны. В рабочем процессе такую ревизию имеет смысл делать регулярно, особенно после завершения клиентских проектов.

Ревизия доступа должна включать не только наличие ссылки, но и скачивание, пароль, публичное появление на корневой странице и права конкретных пользователей. Альбом, который когда-то был «временно публичным», легко забыть. Периодическая проверка важнее сложной первоначальной схемы, которую никто потом не сопровождает.

Диагностика и обслуживание

У Lychee есть диагностические проверки и журнал, и ими лучше пользоваться до ручного редактирования базы. Если функция не работает, полезно сначала определить слой ошибки: браузер, приложение, очередь, база, файловая система или внешний сервис. Например, пустая миниатюра после загрузки может означать успешную запись в базу, но сбой ImageMagick; ошибка входа WebAuthn — нормальную работу PHP, но неверный внешний origin.

Параметр LOG_VIEWER_ENABLED управляет встроенным просмотром логов. На production доступ к диагностике должен оставаться административным. Для Docker параллельно доступны обычные логи контейнеров. Если используется worker, смотрят журнал не только API-контейнера, но и рабочего процесса: веб-часть может успешно принять загрузку и поставить задачу в очередь, после чего ошибка возникает уже на обработчике.

Встроенная проверка обновлений управляется UPDATE_CHECK_ENABLED, а проверка известных уязвимостей — VULNERABILITY_CHECK_ENABLED. На изолированной системе их можно отключить по требованиям сети, но тогда ответственность за отслеживание обновлений и security advisory полностью переходит к администратору. «Сервер не выходит в интернет» не означает, что можно забыть о патчах, особенно если пользователи загружают произвольные медиа.

После обновления проверьте не только номер сборки. Откройте корень, приватный и публичный альбом, загрузите тестовый файл, создайте миниатюру, проверьте вход и скачивание. При переходе между крупными выпусками отдельно сверяются тома Docker и требования PHP. Такой короткий smoke test обнаруживает большую часть эксплуатационных проблем раньше пользователей.

Типичные ошибки при установке и способы их устранения

Страница открывается, но картинки и стили сломаны

Чаще всего проверяют APP_URL, APP_DIR и конфигурацию reverse proxy. Если Lychee фактически работает в подпапке, а префикс не задан или задан дважды, маршруты приложения могут открываться, а статические ресурсы — запрашиваться по неверному пути. Самый надежный способ исключить класс таких ошибок — отдельный домен или поддомен.

Вторая причина — веб-сервер смотрит не в public/. При ручной установке document root должен указывать туда. Попытка сделать корень проекта публичным одновременно ломает ожидаемую схему маршрутизации и создает риск доступа к конфигурации. Исправлять это rewrite-правилами поверх неправильного корня не следует.

После изменения .env ничего не происходит

Для современного контейнера с FrankenPHP конфигурация читается при старте. Перезапустите сервис, затем убедитесь, что переменная из compose не перекрывает значение смонтированного .env. Приоритет имеет окружение, переданное контейнеру. Поэтому изменение файла внутри контейнера может вообще не влиять на конечное значение и к тому же пропадет после пересоздания.

Загрузка останавливается на больших файлах

Сверяют лимиты самого Lychee, PHP и прокси. Chunk upload помогает передавать большие объекты частями, но слишком маленький лимит запроса на nginx или слишком короткий timeout все равно способен разрывать операцию. Проверьте свободное место в временной папке и в постоянном хранилище: при сборке частей одновременно может требоваться дополнительный объем.

Если небольшие JPEG проходят, а видео нет, проверьте расширение, размер и FFmpeg. Если файл записался, но нет миниатюры, проблема может быть в видеообработке, а не в uploader. Разделение «не загрузилось» и «не обработалось после загрузки» экономит время диагностики.

Загруженные файлы исчезают после обновления контейнера

Это признак неправильных volume mounts. Медиа и база должны находиться в постоянных томах или внешней СУБД. Контейнер приложения рассматривается как заменяемый. Проверьте фактический путь /app/public/uploads и другие постоянные каталоги ветки 7, затем сопоставьте их с host-путями. После исправления сделайте тест: загрузите файл, пересоздайте контейнер и убедитесь, что он остался.

Ошибка прав доступа на диск

В ручной установке веб/PHP-пользователь должен читать код и писать в storage/, bootstrap/cache/, каталог загрузок и каталог символических ссылок. CLI-пользователь, запускающий sync, тоже должен иметь нужные права. Вместо постоянного chmod 777 лучше настроить общую группу и наследование групповых прав. Полные права всем маскируют проблему и расширяют последствия компрометации.

Миниатюры выглядят неверно или не создаются

Проверьте наличие ImageMagick и выбранный драйвер, затем разрешение исходника и формат. Для видео — FFmpeg. Если проблема только у фотографий с определенной камерой, смотрят EXIF orientation и поведение auto_fix_orientation. Если исходник повернут правильно, а старые миниатюры нет, может потребоваться регенерация производных, а не повторная загрузка файла.

Даты фотографий неправильные

Сначала определите источник даты. У некоторых изображений нет EXIF времени съемки, у экспортов оно потеряно, у сканов по определению отсутствует. Настройка использования времени последнего изменения файла может помочь для части коллекции, но опасна после массового копирования, когда mtime отражает миграцию. Для архивов лучше сначала нормализовать даты и XMP, а затем импортировать.

На карте нет снимков

Проверьте GPS в метаданных конкретного кадра. Если координат нет, карта не восстановит их из имени альбома. Если координаты есть, но подписи мест не появляются, проверяются сетевой доступ и геокодирование. Не запускайте повторный импорт всей библиотеки до подтверждения, что проблема действительно в метаданных.

WebAuthn не регистрирует ключ

Сверьте внешний домен, HTTPS, APP_URL, настройки прокси и фактический origin в браузере. WebAuthn намеренно строг к происхождению. Если сервер доступен по нескольким именам, выберите одно каноническое. После исправления удалите неудачную регистрацию только если она действительно появилась в списке credentials, чтобы не затронуть рабочие ключи.

У приглашенного пользователя нет контекстного меню

Сравните ownership и выданные права. Пользователь с чтением не должен получать команды владельца. Это штатное поведение, а не ошибка JavaScript. Если ему действительно требуется редактирование, расширьте права альбома; если нужно передать ответственность полностью, используйте transfer, а не случайный набор разрешений.

Синхронизация хочет удалить слишком много

Немедленно оставьте sync_dry_run включенным и проверьте путь источника, album_id и параметры delete-missing. Ошибка часто возникает, когда контейнер не видит смонтированный каталог и считает источник пустым. Пока dry-run показывает неожиданные удаления, реальный destructive sync запускать нельзя.

Дубликаты не распознаются так, как ожидалось

Различайте раннюю проверку имени и проверку контрольной суммы. Повторяющиеся имена камер нормальны для многолетнего архива; разные имена одного и того же файла тоже встречаются после экспорта. Для критической дедупликации не полагайтесь только на название. Перед массовым удалением сравните несколько реальных пар и убедитесь, что правило соответствует вашим данным.

Dropbox импорт показывает предупреждение

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

Сайт стал медленным после массовой загрузки

Сначала посмотрите очередь фоновых задач. Если worker не запущен или QUEUE_CONNECTION расходится, тяжелая работа может обрабатываться не тем способом, который ожидался. Затем проверяют CPU, память, диск и БД. Не меняйте одновременно число workers, размер chunk, качество JPEG и кэш: иначе невозможно понять, какая настройка дала эффект.

Практический сценарий: домашний фотоархив

Для домашнего сервера разумно начать с трех корневых альбомов: семейные события, путешествия и архив. Внутри использовать годы и события, а людей, места и темы отмечать тегами. Это дает две независимые навигации: хронологическую через альбомы и смысловую через метаданные. Рейтинг можно использовать для отбора лучших кадров, favorite — для публичной витрины.

Первую миграцию лучше делать партиями по нескольку каталогов. После каждой партии проверить даты, поворот, GPS и миниатюры. Когда схема подтверждена, оставшуюся коллекцию можно синхронизировать CLI. Сразу после переноса сделать полный backup базы и uploads: это точка, к которой можно вернуться до последующей ручной разметки.

Для родственников создаются отдельные учетные записи или публичные альбомы с паролем. Постоянным участникам удобнее аккаунты, случайным зрителям — ссылка. Точные координаты домашней съемки перед публичной публикацией лучше проверить отдельно. Для просмотра на телевизоре можно использовать слайд-шоу или Frame, не создавая второй набор файлов.

Практический сценарий: выдача съемки клиенту

Фотограф обрабатывает исходники во внешнем редакторе и экспортирует финальные JPEG с корректным цветовым профилем и метаданными. В Lychee создается отдельный альбом проекта, настраиваются обложка, порядок и подходящая раскладка. Превью проверяется на телефоне, потому что клиент часто открывает ссылку именно там.

Далее выбирается модель доступа. Для разовой передачи — публичный альбом с паролем и нужным download permission. Для постоянного заказчика — учетная запись и прямой share. Если отдавать оригиналы не нужно, скачивание отключается. Если фотографий много, включается chunked ZIP, чтобы клиент не зависел от одного огромного архива.

После завершения проекта доступ ревизуется на global sharing page. Временную публикацию можно закрыть, не удаляя сам альбом. Это важнее автоматического удаления через 30 дней: фотограф сохраняет внутренний архив, но публичная поверхность не растет бесконечно.

Практический сценарий: небольшая команда

В команде сначала определяют владельцев корневых альбомов и правила именования. Перемещение отвечает за структуру, transfer — за смену владельца, sharing — за сотрудничество. Если эти три действия использовать как синонимы, со временем права становятся непредсказуемыми. Лучше дать администраторам короткое правило и проверять его на первом проекте.

Для сотрудников настраивают индивидуальные учетные записи и при необходимости OAuth или WebAuthn. Общий администраторский пароль не используют. Если доступны группы Supporter Edition, повторяющиеся права назначают группе. Если групп нет, число общих корневых зон лучше держать небольшим, чтобы администрирование не превратилось в матрицу из сотен ручных разрешений.

Тяжелые импорты выносят в workers. Веб-интерфейс, очередь и медиа используют общую базу и тома. Мониторинг должен видеть заполнение диска и длину очереди: пользователю «галерея работает», пока не закончится место для очередной пачки миниатюр. Резервная копия включает БД и пользовательские ресурсы оформления.

Практический сценарий: перенос архива с NAS

Не следует направлять Lychee прямо на случайное дерево NAS и ожидать, что оно станет постоянным файловым браузером. Сначала делают read-only копию или монтирование источника, затем тестируют lychee:sync на одной ветке. Имена папок превращаются в логическую структуру, поэтому мусорные каталоги, экспорты и дубли лучше убрать до импорта.

Если важно сохранять исходные файлы на месте, проверяется сценарий symlink и его совместимость с резервированием, правами и жизненным циклом NAS. Символическая ссылка удобна до момента, когда источник переименовали или отключили. Для архива, который должен пережить реорганизацию NAS, обычное копирование в управляемое хранилище Lychee может быть надежнее.

После первой синхронизации нельзя сразу включать delete-missing. Сначала сравнивают число и структуру альбомов, проверяют несколько дубликатов и выполняют dry-run. Только если Lychee действительно должен быть зеркалом конкретного источника, включают обратное удаление и документируют это решение.

Сравнение с аналогами

Lychee имеет смысл сравнивать не по количеству кнопок, а по тому, где находится основная работа. Он решает задачу собственной серверной фотогалереи: хранение, альбомы, доступ, публикация, метаданные и просмотр из браузера. ФотоМАСТЕР решает другую центральную задачу — редактирование изображения на рабочем устройстве. PhotoPrism и Immich ближе к Lychee по архитектуре и назначению, но делают больший акцент на автоматическом анализе медиатеки и, в случае Immich, на резервном копировании с телефона.

Lychee и ФотоМАСТЕР

ФотоМАСТЕР полезнее там, где нужно изменить пиксели. В нем подтверждены инструменты замены и размытия фона, удаления лишних объектов, автоматической ретуши портретов, коррекции лица и фигуры, цветокоррекции, эффектов и пакетной обработки. В пакетном режиме можно применить одинаковые улучшения, кривые, LUT и другие настройки к множеству фотографий. Это задачи, которые Lychee в своем интерфейсе не пытается повторять.

Lychee, напротив, сильнее после того, как изображения уже готовы. Он хранит библиотеку на сервере, создает альбомы и вложенные альбомы, извлекает EXIF и GPS, показывает карту, регулирует публичность и скачивание, позволяет делиться альбомом с учетными записями и выдает материал через веб. Поэтому эти продукты не столько заменяют друг друга, сколько могут стоять в одном конвейере: обработать кадры в редакторе, экспортировать и опубликовать в Lychee.

Если задача формулируется как «убрать человека с фона, поправить кожу, заменить небо и сохранить JPEG», выбор класса очевидно смещается к ФотоМАСТЕРу или другому фоторедактору. Если задача — «дать клиенту закрытую галерею из 600 готовых кадров, разрешить скачивание и потом снять доступ», нужен серверный инструмент вроде Lychee. Сравнивать их по числу фильтров бессмысленно: у Lychee фильтры не являются ядром продукта, а у ФотоМАСТЕРа нет роли серверной медиатеки с учетными записями.

Lychee и PhotoPrism

PhotoPrism ближе по классу: он тоже предназначен для собственной фото- и видеобиблиотеки, работает через веб и может быть размещен на своей инфраструктуре. Главное различие — автоматизация каталогизации. PhotoPrism распознает лица, автоматически присваивает метки по содержимому и местоположению, предоставляет мощные фильтры поиска и географические представления. Для человека, который хочет загрузить десятки тысяч слабо размеченных фотографий и затем искать «людей», «места» и категории, это принципиальная возможность.

Еще одно различие — отношение к существующему файловому архиву. PhotoPrism умеет индексировать originals напрямую, сохраняя имена файлов и каталогов, а также показывать представление папок. Lychee строит собственную модель библиотеки и рекомендует загружать или импортировать фотографии. Если папочная структура NAS уже является главным источником истины и менять ее нельзя, PhotoPrism соответствует этому сценарию естественнее.

Lychee проще объяснить как управляемую публикационную галерею с явными альбомами, обложками, доступом, паролями, скачиванием и встраиванием. Его модель хорошо ложится на портфолио и клиентские подборки. PhotoPrism сильнее там, где библиотека должна сама извлекать смысл из большого неразмеченного массива. При этом AI-функции требуют дополнительных вычислений: распознавание лиц и классификация создают нагрузку, которой в обычном ручном альбомном процессе Lychee может не быть.

Оба продукта требуют администрирования сервера, резервного копирования базы и медиаданных, а также разумного планирования ресурсов. Разница не сводится к «легкий» и «тяжелый»: конкретная нагрузка зависит от размера файлов, числа пользователей и фоновых задач. Выбирать стоит по модели данных и поиску, а не по обещаниям универсальной скорости.

Lychee и Immich

Immich строит опыт вокруг личного фотооблака и мобильных устройств. Его приложения умеют автоматически загружать новые фотографии и видео с телефона, выбирать альбомы для backup и периодически выполнять передачу в фоне. Серверная сторона умеет распознавать лица, выполнять контекстный поиск на основе CLIP, показывать таймлайн, карту, воспоминания, дубликаты, внешние библиотеки и папочное представление.

Для пользователя, который хочет самостоятельно заменить Google Photos или iCloud Photos и автоматически выгружать камеру смартфона на домашний сервер, собственный мобильный backup-клиент Immich — существенное преимущество. У Lychee загрузка через браузер, CLI, серверный импорт и Dropbox хорошо подходят для управляемых коллекций, но не создают того же мобильного сценария «снял — приложение само отправило на сервер».

Lychee интереснее, когда главной единицей является оформленный альбом и его публикация. Вложенные альбомы, обложки, header photo, несколько раскладок, права, пароль и встраивание хорошо соответствуют портфолио. Immich тоже имеет альбомы и публичные ссылки, но его пользовательский опыт в большей степени связан с общей временной лентой личной медиатеки и автоматической обработкой после загрузки.

У Immich есть встроенный редактор с базовыми настройками, кадрированием и поворотом, но для сложной ретуши он, как и Lychee, не заменяет специализированный редактор. Если выбор стоит между Immich и Lychee, ключевые вопросы — нужен ли автоматический мобильный backup, насколько важны распознавание лиц и семантический поиск, и будет ли библиотека использоваться главным образом как личное фотооблако или как управляемая галерея публикаций.

Как читать это сравнение на практике

Для домашнего архива с несколькими семейными пользователями выбор определяется привычкой поступления файлов. Если большая часть фотографий появляется на телефонах и должна копироваться автоматически, Immich закрывает этот путь напрямую. Если архив уже подготовлен на компьютере и основная цель — аккуратные альбомы, права и публичные подборки, Lychee требует меньше AI-логики, которая может быть не нужна.

Для старого NAS с десятилетней папочной структурой PhotoPrism удобен тем, что способен индексировать originals без реорганизации имен и каталогов. Lychee можно наполнить через sync и импорт, но после этого база Lychee становится существенной частью структуры. Нельзя считать каталог на диске полным описанием библиотеки.

Для фотографа, который готовит файлы клиенту, полезна связка редактора и галереи. ФотоМАСТЕР либо другой редактор используется до публикации для ретуши и пакетных изменений, а Lychee — после экспорта. Попытка выбрать «одну программу на все» здесь ухудшает процесс: серверная галерея не обязана иметь сложные кисти, а локальный редактор не обязан управлять TLS, учетными записями и серверной базой.

Ограничения Lychee, которые важно знать заранее

Первое ограничение — необходимость серверной части. Браузерный интерфейс удобен, но сам по себе ничего не хранит. Кто-то должен обновлять контейнеры или PHP, следить за базой, диском, TLS и резервными копиями. На домашнем NAS это может занимать немного времени, но ответственность не исчезает. Если пользователь не хочет администрировать вообще никакой сервис, локальный редактор или готовое облако проще.

Второе — Lychee не является прозрачным каталогом существующих папок. Его FAQ прямо говорит о собственной структуре и базе. Импорт и sync позволяют перенести дерево, в том числе рекурсивно, но после этого метаданные и связи живут в СУБД. Для тех, кто требует, чтобы любой файловый менеджер без базы видел ровно ту же организацию, это существенное архитектурное различие.

Третье — часть расширенных функций доступна только в Supporter Edition или Pro. В документации к таким возможностям относятся, в частности, некоторые элементы таймлайна, расширенное управление пользователями, защищенные AES-ссылки, цветовая экстракция и другие дополнения. Базовый проект открыт, но планировать коммерческий или командный процесс нужно по реальному набору выбранной редакции, а не по скриншоту функции из общей документации.

Четвертое — отсутствие акцента на распознавании лиц и семантическом AI-поиске. Если коллекция уже хорошо организована альбомами, тегами, датами и рейтингом, это может вообще не мешать. Если же задача — «загрузить хаос и попросить систему самой понять содержание», PhotoPrism и Immich предлагают более подходящие механизмы.

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

Когда Lychee особенно уместен

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

Он также подходит небольшим группам, которым нужны зарегистрированные пользователи и выдача прав на конкретные альбомы. При наличии Supporter Edition модель можно расширить группами, квотами и несколькими администраторами. При этом система остается фотоориентированной: это не универсальный корпоративный DAM с согласованиями, сложными workflow и десятками типов цифровых активов.

Если основная коллекция строится вокруг публичного портфолио, возможности выбора обложки, header photo, макета и встраивания дают больше контроля, чем типичная «лента камеры». Если же основной экран должен быть бесконечной временной лентой со смартфона и воспоминаниями, архитектура Immich ближе к ожиданиям.

Чек-лист перед регулярным использованием

• Определите, где будут храниться оригиналы и база, и включите оба компонента в резервное копирование.
• Задайте корректные APP_URL, APP_KEY и часовой пояс до массовой загрузки.
• Проверьте TLS и reverse proxy на том же домене, которым реально будут пользоваться посетители.
• Загрузите тестовый набор JPEG, PNG, видео и несколько нестандартных исходников из вашей коллекции.
• Сверьте даты, EXIF, ориентацию, GPS, миниатюры и полноэкранный просмотр.
• Выберите правила альбомов, тегов, favorite и рейтинга, чтобы одинаковые признаки не дублировались.
• Создайте тестового пользователя и проверьте права глазами не администратора.
• Проверьте публичный альбом с паролем, скачиванием и без него.
• Для крупных импортов настройте worker и очередь до загрузки основной библиотеки.
• Сначала запускайте опасные sync-операции в dry-run и только потом разрешайте удаление отсутствующих файлов.
• После настройки восстановите резервную копию на тестовом экземпляре и убедитесь, что галерея действительно собирается из нее.

Итог

Lychee — практичный выбор для собственной управляемой фотогалереи, когда важны вложенные альбомы, аккуратная веб-публикация, EXIF и GPS, права доступа, скачивание и контроль над местом хранения. Он не пытается заменить профессиональный редактор изображений и не строит весь опыт вокруг автоматического распознавания содержания; его сильная сторона — понятная серверная библиотека, которую владелец организует и публикует по своим правилам.

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

Водяные знаки для публичной выдачи

В Supporter Edition есть серверное наложение водяного знака. В качестве знака используется отдельная фотография из библиотеки, ее идентификатор указывается в watermark_photo_id, после чего включается watermark_enabled. Для этой функции требуется Imagick. Практически удобнее загружать PNG с прозрачным фоном и сначала проверять его на светлом и темном кадре.

Lychee не портит исходник: знак наносится на отдельные варианты изображения, а оригинальные незамаркированные производные сохраняются. Поэтому включение функции увеличивает расход хранилища. Можно отдельно определить, видят ли знак анонимные посетители и авторизованные пользователи, нужно ли делать защищенный вариант оригинала и разрешено ли загрузчику отказаться от watermark для конкретной загрузки.

Положение выбирается по сетке якорных точек, дополнительно настраиваются масштаб, прозрачность и смещение. Для уже существующих фотографий обработку можно запустить задним числом; она ставится в фоновые задания по вариантам размера. На большой библиотеке это еще одна причина иметь рабочую очередь и свободное место до массового запуска.

Водяной знак стоит воспринимать как средство сдерживания повторного использования, а не как гарантию несанкционированного копирования. Если посетителю показана фотография, отображаемое содержимое технически можно сохранить. Поэтому для клиентской выдачи watermark дополняет правильные права, запрет скачивания и контролируемые ссылки, но не заменяет их.