Документация · v1

API объектного хранилища

Хранилище реализует подмножество S3 API. Ниже — только то, что отличается от поведения AWS S3, и примеры под типовые задачи. Для всего остального применима документация вашего SDK.

Быстрый старт

Понадобится пара ключей из консоли (раздел Ключи доступа) и адрес эндпоинта.

export AWS_ACCESS_KEY_ID=BDWJ7K2QX9...
export AWS_SECRET_ACCESS_KEY=••••••••••••
export AWS_DEFAULT_REGION=ru-1

# список бакетов
aws --endpoint-url https://private.bigdataweb.ru s3 ls

# загрузка каталога
aws --endpoint-url https://private.bigdataweb.ru \
    s3 sync ./build s3://static-assets/build/ --acl public-read

Совет: пропишите эндпоинт в ~/.aws/config секцией endpoint_url = https://private.bigdataweb.ru, чтобы не повторять флаг в каждой команде.

Аутентификация

• Поддерживается только AWS Signature Version 4. Подписи v2 отклоняются с 403 InvalidRequest.
• Расхождение часов клиента и сервера более 15 минут даёт 403 RequestTimeTooSkewed. Синхронизируйте время по NTP.
• Ключи выпускаются парами и привязываются к списку бакетов и набору операций (read, write, delete).
• Скомпрометированный ключ отзывается в консоли мгновенно, кэширования прав нет.

Эндпоинты и регионы

Адресация только path-style: private.bigdataweb.ru/bucket/key. Virtual-hosted-style (bucket.private.bigdataweb.ru) не поддерживается — в SDK включайте forcePathStyle / addressing_style = path.

Совместимость API

BigDataWeb Storage реализует подмножество Amazon S3 API, достаточное для бэкапов, медиа и статики. Матрица ниже — фактическая поддержка на эндпоинте private.bigdataweb.ru. Неподдерживаемые вызовы возвращают 501 NotImplemented или 403 AccessDenied.

Проверено с aws-cli 2.x, boto3, aws-sdk-js v3, rclone 1.6x, restic и django-storages. При расхождении с AWS S3 ориентируйтесь на эту таблицу, а не на документацию Amazon.

Бакеты

• Имя: от 3 до 63 символов, строчные латинские буквы, цифры и дефис. Имена глобально уникальны в пределах установки.
• Удаление возможно только для пустого бакета, включая незавершённые multipart-загрузки.
• Версионирование включается на уровне бакета и не отключается обратно — только приостанавливается.

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://private.bigdataweb.ru",
    region_name="ru-1",
    config=boto3.session.Config(s3={"addressing_style": "path"}),
)

s3.create_bucket(Bucket="app-media")
s3.put_bucket_versioning(
    Bucket="app-media",
    VersioningConfiguration={"Status": "Enabled"},
)

Объекты и multipart

• Максимальный размер объекта — 5 ТБ, одиночного PUT — 5 ГБ. Всё, что больше, загружается частями.
• Размер части: от 5 МБ до 5 ГБ, до 10 000 частей на объект. Рекомендуемый размер — 64–128 МБ.
• Незавершённые multipart-загрузки занимают место в квоте. Чистите их lifecycle-правилом.
• Поддерживаются Range-запросы, If-None-Match и пользовательские метаданные x-amz-meta-*.

# посмотреть «зависшие» загрузки
aws --endpoint-url https://private.bigdataweb.ru \
    s3api list-multipart-uploads --bucket project-backups

# прервать конкретную
aws --endpoint-url https://private.bigdataweb.ru \
    s3api abort-multipart-upload \
    --bucket project-backups --key dump.sql.gz \
    --upload-id 2~yQ8f...

Presigned-ссылки

Временные ссылки позволяют отдавать и принимать файлы напрямую, минуя бэкенд. Максимальный срок жизни — 7 суток, по умолчанию — 1 час.

# ссылка на скачивание
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "app-media", "Key": "docs/report.pdf"},
    ExpiresIn=900,
)

# ссылка на загрузку от клиента
put_url = s3.generate_presigned_url(
    "put_object",
    Params={"Bucket": "uploads", "Key": "u/42/avatar.jpg",
            "ContentType": "image/jpeg"},
    ExpiresIn=300,
)

Lifecycle-политики

Правила применяются раз в сутки и работают по префиксу ключа и возрасту объекта.

{
  "Rules": [
    {
      "ID": "logs-90d",
      "Status": "Enabled",
      "Filter": { "Prefix": "logs/" },
      "Expiration": { "Days": 90 }
    },
    {
      "ID": "abort-stale-uploads",
      "Status": "Enabled",
      "Filter": { "Prefix": "" },
      "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 }
    }
  ]
}

rclone и бэкапы

[bdw]
type = s3
provider = Other
env_auth = false
access_key_id = BDWJ7K2QX9...
secret_access_key = ••••••••••••
endpoint = https://private.bigdataweb.ru
region = ru-1
force_path_style = true
chunk_size = 128M

Для restic используйте репозиторий вида s3:https://private.bigdataweb.ru/backups-restic.

Лимиты

Коды ошибок