How to Configure S3 Object Storage for ownCloud Infinite Scale

ownCloud Infinite Scale can use S3-compatible object storage for file blobs while keeping file metadata on a POSIX-compliant filesystem. That split is the first concept to understand: S3 is not a drop-in replacement for every local data directory. In the supported s3ng layout, object storage holds the binary file content, while metadata remains on POSIX storage such as a local filesystem or NFS.

This guide follows the current ownCloud Infinite Scale storage documentation available in October 2026. It is written for administrators who are new to the s3ng driver and want a configuration they can understand before adapting it to Docker Compose, systemd, Kubernetes, or another deployment method.

Official references used throughout this guide are the ownCloud S3 storage documentation, the Storage-Users service configuration, and the general storage considerations.

What S3 means in ownCloud Infinite Scale

S3 is an object-storage API originally introduced by Amazon. An S3-compatible service stores data as objects inside a bucket and exposes operations through HTTP-based APIs. ownCloud Infinite Scale uses the s3ng storage driver to place file blobs in such a bucket.

POSIX storage means a filesystem that provides the filesystem behavior Infinite Scale expects for metadata. With s3ng, metadata does not move into the S3 bucket. ownCloud explicitly documents that blobs go to S3 while metadata remains on POSIX storage.

This distinction prevents a common mistake: pointing Infinite Scale at a bucket and assuming the whole server state now lives there. It does not. Your backup and recovery plan must cover both the POSIX-side metadata and the S3-side blobs.

Step 1: Prepare the bucket, metadata storage, credentials, and network path

Before changing Infinite Scale, prepare four things:

• A dedicated S3 bucket.
• A POSIX-compliant path for s3ng metadata. For a multi-node deployment, ownCloud recommends thinking carefully about shared storage; NFS is commonly used when multiple Infinite Scale instances need access to the metadata path.
• An access key and secret key with only the bucket permissions Infinite Scale requires.
• Network reachability from the Infinite Scale host or container to the S3 endpoint, normally over HTTPS.

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

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

Шаг 2: Включите драйвер s3ng и укажите параметры подключения к S3.

Основные параметры хранилища — это STORAGE_USERS_DRIVER=s3ng. Служба Storage-Users — это компонент Infinite Scale, отвечающий за хранение пользовательских файлов. В официальной конфигурации драйвер системного хранилища также остается на обычном ocisбэкэнде.

Минимальный набор переменных окружения выглядит следующим образом:

STORAGE_USERS_DRIVER=s3ng
STORAGE_USERS_S3NG_ROOT=/var/lib/ocis/storage/users
STORAGE_SYSTEM_DRIVER=ocis

STORAGE_USERS_S3NG_ENDPOINT=https://s3.example.com
STORAGE_USERS_S3NG_REGION=us-east-1
STORAGE_USERS_S3NG_ACCESS_KEY=YOUR_ACCESS_KEY
STORAGE_USERS_S3NG_SECRET_KEY=YOUR_SECRET_KEY
STORAGE_USERS_S3NG_BUCKET=ocis-files

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

Способ развертывания определяет, куда будут помещены эти переменные. При развертывании с помощью Docker Compose они могут располагаться в разделе службы Infinite Scale environmentили загружаться из файла окружения. При развертывании с помощью systemd можно использовать файл окружения или конфигурацию юнита. Kubernetes обычно внедряет их через Secret и Deployment или StatefulSet. Важны имена переменных; синтаксис зависит от вашей платформы.

Шаг 3: Предоставьте Infinite Scale необходимые разрешения для доступа к хранилищу.

Политика корзины — это правило управления идентификацией и доступом (IAM), которое определяет, какие действия может выполнять аутентифицированный пользователь в отношении корзины и ее объектов. ownCloud публикует необходимый шаблон политики для драйвера s3ng.

bucket-nameВ приведенной ниже политике замените на настоящее имя вашего хранилища:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucket",
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": ["arn:aws:s3:::bucket-name"]
    },
    {
      "Sid": "ActionsInBucketContext",
      "Effect": "Allow",
      "Action": [
        "s3:*Object",
        "s3:*MultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": ["arn:aws:s3:::bucket-name/*"]
    }
  ]
}

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

Шаг 4: Перезапустите Infinite Scale и проверьте путь к хранилищу.

Примените конфигурацию, используя стандартную процедуру перезапуска для вашего развертывания. Например, при установке systemd может использоваться systemctl restart ocis, тогда как при развертывании Compose будут пересозданы или перезапущены затронутые контейнеры служб. Сразу после запуска проверьте журналы на наличие ошибок аутентификации, DNS, TLS, региона или разрешений.

Проверка доступности хранилища с помощью CLI вашего S3-провайдера подтверждает, что хост и учетные данные могут получить доступ к хранилищу, но сама по себе она не доказывает корректную запись больших двоичных объектов в Infinite Scale. Более эффективным сквозным тестом является запуск Infinite Scale, загрузка небольшого файла через веб-интерфейс ownCloud, его повторная загрузка и анализ журналов службы на наличие ошибок.

Если в установленной вами версии Infinite Scale есть команда обслуживания хранилища больших двоичных объектов, описанная ownCloud, вы также можете использовать её . ownCloud описывает эту команду как операцию загрузки/выгрузки/удаления, выполняемую в рамках настроенного хранилища больших двоичных объектов. Для получения информации о синтаксисе, специфичном для вашей версии, ocis storage-users blobstore checkознакомьтесь с официальной документацией по проверке хранилища больших двоичных объектов .

Не следует ожидать, что исходные имена файлов будут отображаться как обычные объекты S3.

Одно из самых распространенных заблуждений — это просматривать содержимое хранилища и ожидать увидеть знакомую структуру папок пользователя, например, такую: Documents/report.pdf. Infinite Scale рассматривает S3 как хранилище больших двоичных объектов, а не как файловую систему, доступную пользователю. Документированный s3ngформат ключей основан на идентификаторах пространств и идентификаторах больших двоичных объектов, в то время как удобочитаемое пространство имен восстанавливается из метаданных.

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

Загрузка больших файлов: проверьте размер составной части перед началом производства.

S3 использует многокомпонентную загрузку для разделения больших объектов на части. STORAGE_USERS_S3NG_PUT_OBJECT_PART_SIZEДля управления размером частей используются документы ownCloud. Задокументированное значение по умолчанию составляет 16 МиБ, если явное значение не указано.

Amazon S3 разрешает загрузку не более 10 000 частей в одном многокомпонентном файле. При размере части в 16 МиБ это соответствует примерно 160 ГиБ, прежде чем ограничение на количество частей станет проблемой. Если ваши пользователи регулярно загружают большие файлы, рассчитайте необходимый размер части до запуска системы, а не ждите, пока не произойдет сбой при передаче большого объема данных.

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

Распространенные проблемы и что следует проверить в первую очередь

Совместное резервное копирование больших двоичных объектов S3 и метаданных POSIX.

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

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

Рекомендуемая отправная точка

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

После настройки проверьте три уровня по отдельности: доступ к сети и учетным данным для доступа к хранилищу, запуск Infinite Scale без ошибок хранилища и фактическую загрузку/выгрузку через ownCloud. После успешного прохождения этих проверок переходите к мониторингу, резервному копированию, правилам жизненного цикла и настройке производительности. Такая последовательность значительно упрощает поиск и устранение неисправностей, поскольку каждый тест отвечает на отдельный вопрос, вместо того чтобы рассматривать «S3 работает» как единственный результат по принципу «всё или ничего».