Подключить S3 для вложений

S3 хранит байты вложений. Права, названия и связи остаются в PostgreSQL 17. Это не то же самое, что отправка резервных копий в S3.

Что получить у провайдера

HTTPS endpoint, регион, закрытый bucket, отдельный префикс установки и технические ключи с ограниченными правами. Нужны ListBucket по префиксу и GetObject, PutObject, DeleteObject внутри него. Не используйте root-ключи.

DEV, production и восстановление должны иметь разные префиксы. Запретите публичные ACL, чтение и запись. Провайдер должен поддерживать SigV4 и условную запись без перезаписи существующего ключа.

Настройка

ATTACHMENTS_STORAGE=s3
S3_ENDPOINT=https://s3.example.com
S3_BUCKET=ngensia-files
S3_PREFIX=production-unique-installation/
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

Значения замените параметрами провайдера; для virtual-host адресации может требоваться false.

mkdir -p secrets
chmod 700 secrets
nano secrets/s3-credentials.json

{
  "accessKeyId": "ВЫДАННЫЙ_ACCESS_KEY",
  "secretAccessKey": "ВЫДАННЫЙ_SECRET_KEY"
}

Для временных ключей добавьте sessionToken и план обновления. В этом Compose-комплекте secret должен читаться пользователем node внутри контейнера: файл получает 644, но его родительский каталог на хосте остаётся закрытым 700.

chmod 644 secrets/s3-credentials.json

Не ослабляйте права каталога и не помещайте ключи в образ. Для внутреннего CA используйте доверенный сертификат через NODE_EXTRA_CA_CERTS и read-only mount; не отключайте TLS.

Проверка подключения

После подготовки установки:

sh ngensia.sh storage-check

Команда проверяет запись, чтение, запрет перезаписи и анонимного доступа, затем удаляет свой случайный тестовый объект. При сетевом сбое удаления он может остаться — не очищайте из-за этого весь bucket. При ошибке S3 перехода на диск нет.

Место для резервной копии

Копия S3-системы сначала выгружает все вложения в локальный Docker volume transfers, а затем сохраняет архив во внешнем каталоге. На файловой системе Docker нужен запас минимум под полный экспорт вложений; внешнему назначению — под архив и базу. Проверка свободного места назначения не проверяет локальный volume. При ошибке экспорт может остаться: сохраните журнал и удаляйте только конкретный проверенный временный каталог после разбора, не весь volume или bucket.

Перенести работающую систему с диска

1. Сделайте проверенную внешнюю копию, пока используется disk.
2. Остановите приложение и всех писателей, оставив PostgreSQL работающим.
3. Настройте S3 и новый пустой префикс.
4. Выполните команды:

sh ngensia.sh storage-check
sh ngensia.sh storage-import
sh ngensia.sh storage-verify
sh ngensia.sh start

Для остановки приложения в исходном режиме disk: docker compose --env-file .env -f compose.yml stop app. Импорт не удаляет исходные файлы. Совпадающие объекты пропускаются; конфликт или неверная сумма останавливает перенос.

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

Приёмка провайдера

Локальная проверка S3-совместимого сервера не доказывает работу любого облака. Повторите сценарий на выбранном bucket. S3-overlay также добавляет приложению исходящий сетевой доступ; при необходимости ограничьте его инфраструктурными правилами.

Копии в S3 · Дисковое хранение · Восстановление