Как подключиться к S3 хранилищу: пошаговое руководство с примерами

В предыдущей статье мы разбирали, как устроено объектное хранилище изнутри – бакеты, объекты, ключи, репликация. Теперь пора подключиться руками и начать с ним работать.

Статья пригодится разработчикам, системным администраторам и всем, кому нужно перенести резервные копии, медиафайлы или логи в хранилище, совместимое с S3 (объектным хранилищем). Дальше пойдёт разбор шести способов подключения, от консольных утилит до графических клиентов и Python-библиотек. У каждого свои сильные стороны, выбор зависит от задачи. Для автоматизации в скриптах подходят AWS CLI или boto3. Для быстрого просмотра содержимого бакета и перетаскивания файлов мышкой удобнее графические клиенты вроде S3 Browser (клиент для работы с объектным хранилищем) или Cyberduck (графический клиент). Для монтирования бакета как сетевого диска есть s3fs (файловая система для монтирования хранилища). Все примеры приводятся для хранилища HOSTKEY (провайдер услуг), но универсальны и работают с любым сервисом, совместимым с S3 (объектным хранилищем), требуется лишь подставить свой адрес сервиса (endpoint) и ключи.

Что нужно для подключения к S3 (объектному хранилищу)

Минимальный набор для подключения к любому хранилищу, совместимому с S3 (объектным хранилищем), состоит из трёх вещей. Они одинаковые везде, меняется только то, где их взять.

Ключ доступа (Access Key) и секретный ключ (Secret Key) – это пара идентификаторов, которые играют роль логина и пароля. Только в отличие от обычной авторизации, эти ключи не передаются с каждым запросом в открытом виде. Они используются для криптографической подписи запроса по схеме AWS Signature Version 4 (алгоритм подписи запросов). Сервер по подписи понимает, что запрос пришел от того, у кого эти ключи есть, и что сам запрос не был изменён по дороге. Получают ключи в личном кабинете провайдера. У HOSTKEY (провайдер услуг) это раздел S3 Storage в Invapi, вкладка «Учетные данные».

Адрес сервиса (endpoint) – это URL, по которому S3-клиент находит ваше хранилище. У Amazon S3 он зашит в библиотеки по умолчанию, у любого другого сервиса его нужно указывать явно. Для HOSTKEY это `https://s3-nl.hostkey.com`. Без явного endpoint клиенты по умолчанию пытаются достучаться до Amazon, и ничего не получится.

Имя бакета нужно для большинства операций. Бакет создаётся один раз, после чего внутри него уже можно создавать объекты. Имя бакета обязано быть глобально уникальным, поэтому HOSTKEY автоматически добавляет к нему префикс из идентификатора пользователя – это снимает проблему с тем, что популярные имена вроде `backups` или `media` давно заняты.

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

Получение учетных данных в HOSTKEY

Прежде чем подключаться, нужно создать хранилище и получить ключи. Это занимает пару минут.

Войдите в личный кабинет в Invapi, перейдите в раздел S3 Storage и нажмите кнопку создания нового хранилища:

В форме укажите регион (по умолчанию NL – Нидерланды), придумайте имя бакета (только строчные буквы, цифры и дефисы, максимум 63 символа, начинается и заканчивается буквой или цифрой), выберите тариф Standart Storage и нажмите «Заказать».

После создания откройте вкладку «Учётные данные».

Здесь вы увидите четыре значения:

• Имя хоста (Endpoint URL) – `https://s3-nl.hostkey.com`.Одинаковое для всех клиентов в локации NL (Нидерланды).
• Идентификатор пользователя S3 – служебный идентификатор. В большинстве клиентов он не нужен, но в некоторых случаях может пригодиться.
• Ключ доступа (Access Key) – публичная часть пары ключей.
• Секретный ключ (Secret Key) – приватная часть. Выкладывать его в открытый код, отправлять в репозитории или пересылать мессенджерами не стоит ни при каких обстоятельствах.

Значения ключей открываются по клику на иконку с глазом справа от поля. Только после этого ключи копируются кнопкой рядом, без раскрытия в буфер уйдут одни звёздочки.

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

Подключение через AWS CLI

AWS CLI это официальная консольная утилита от Amazon. Несмотря на название, она прекрасно работает с любым хранилищем, совместимым с S3 (объектным хранилищем), нужно только указать другой адрес сервиса (конечную точку). Это, пожалуй, основной инструмент для автоматизации: всё, что можно сделать руками через графический клиент, можно сделать командой и добавить в скрипт.

Установка AWS CLI

Установить AWS CLI можно двумя способами. Какой выбрать, зависит от того, есть ли у вас Python и насколько вы дружите с менеджером пакетов pip (менеджер пакетов Python)

Способ 1: через pip. Универсальный вариант, работает на Windows, Linux и macOS. Требует установленного Python.

pip install awscli boto3

Проверить, что всё установилось:

aws --version

Обновляется так же – через pip:

pip install--upgrade awscli boto3

Способ 2:MSI (установщик Windows)-установщик для Windows. Если Python не нужен сам по себе, а нужна только AWS CLI, то берите MSI (установщик Windows). Чище ставится в систему, не зависит от Python, не выдает предупреждений в терминале.

Скачать установщик через консоль:

curl -o AWSCLIV2.msi https://awscli.amazonaws.com/AWSCLIV2.msi

Запустить тихую установку:

msiexec /i AWSCLIV2.msi /quiet /norestart

После этого перезапустите терминал и проверьте:

aws --version

Можно поступить иначе, скачать установщик с сайта Amazon и запустить двойным кликом.

Ставить AWS CLI через pip и MSI одновременно не стоит. Если уже установлена pip-версия и поверх запустить MSI, в системе окажутся два разных aws.exe в разных местах. Какой из них вызовется, зависит от порядка путей в переменной PATH (переменная окружения путей) . Дальше начинается долгий вечер с попытками понять, почему обновление через pip не срабатывает. Проверить, нет ли дублирования:

where aws

Если показывает несколько путей, то удалите одну версию.

Настройка профиля

В AWS CLI есть профили, именованные наборы учётных данных, которые удобны при нескольких аккаунтах или нескольких разных хранилищах. Один профиль для основного облака, другой для тестового, третий для бэкапов клиента.

Создаем профиль для HOSTKEY:

aws configure --profile hostkey

Утилита спросит четыре значения:

AWS Access Key ID [None]: ваш_ключ_доступа
AWS Secret Access Key [None]: ваш_секретный_ключ
Default region name [None]: nl
Default output format [None]: json

Регион для HOSTKEY – `nl`. Формат вывода `json` удобен для скриптов; если планируете читать вывод глазами, можно поставить `table`.

Проверить, что всё записалось правильно:

aws configure list--profile hostkey

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

Основные операции

Каждая команда AWS CLI для работы с HOSTKEY должна включать два дополнительных параметра: `--profile hostkey` (какой профиль использовать) и `--endpoint-url https://s3-nl.hostkey.com` (на какой сервис идти). Без `--endpoint-url` клиент пойдёт в Amazon.

Чтобы не повторять это каждый раз, можно создать псевдоним в shell. Для bash в `~/.bashrc`:

alias hk='aws --profile hostkey --endpoint-url https://s3-nl.hostkey.com'

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

Список бакетов:

aws s3 ls --profile hostkey --endpoint-url https://s3-nl.hostkey.com

Выведет дату создания и имя каждого вашего бакета.

Содержимое бакета:

aws s3 ls s3://имя-бакета/ --profile hostkey --endpoint-url https://s3-nl.hostkey.com

Слеш в конце имени важен. Без него команда отработает иначе.

Загрузка файла:

awss3cp test.txt s3://имя-бакета/ --profile hostkey --endpoint-url https://s3-nl.hostkey.com

`cp` – команда копирования, синтаксис как у обычного `cp`: источник, потом назначение. Имя файла можно поменять при загрузке, указав его в назначении: `s3://имя-бакета/новое-имя.txt`.

Скачивание файла:

aws s3 cp s3://имя-бакета/test.txt./локальный.txt --profile hostkey --endpoint-url https://s3-nl.hostkey.com

Та же команда `cp`, источник и назначение поменялись местами.

Удаление файла:

aws s3 rm s3://имя-бакета/test.txt --profile hostkey --endpoint-url https://s3-nl.hostkey.com

Создание бакета:

aws s3 mb s3://новый-бакет --profile hostkey --endpoint-url https://s3-nl.hostkey.com

`mb` – make bucket. Имя должно быть глобально уникальным.

Удаление пустого бакета:

aws s3 rb s3://имя-бакета --profile hostkey --endpoint-url https://s3-nl.hostkey.com

Если в бакете остались объекты, удаление не пройдёт. Для удаления вместе с содержимым нужен флаг `--force`. Уточняющих вопросов команда не задаёт и сносит всё внутри без предупреждения, так что осторожнее.

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

aws s3 sync ./локальная-папка s3://имя-бакета/удалённая-папка/ --profile hostkey --endpoint-url https://s3-nl.hostkey.com

Стрелочки можно поменять местами, чтобы синхронизировать в обратную сторону – из бакета в локальную папку.

Если в путях есть пробелы – обязательно в кавычках:

aws s3 sync "C:\Users\Имя\Мои Документы" s3://имя-бакета/docs/ --profile hostkey --endpoint-url https://s3-nl.hostkey.com

Где хранятся настройки

После `aws configure` создаются два файла:

• В Linux и macOS: `~/.aws/credentials` и `~/.aws/config`.
• В Windows: `C:\Users\ИМЯ\.aws\credentials` и `C:\Users\ИМЯ\.aws\config`.

В `credentials` лежат ключи, в `config` – регион и формат вывода. Файлы текстовые, можно редактировать вручную. Но имейте в виду: файл с ключами – это файл с паролями. Не выкладывайте его в публичные репозитории, не передавайте через незащищённые каналы, ставьте на него ограничивающие права (`chmod 600 ~/.aws/credentials` в Linux).

Полный сброс конфигурации, если что-то пошло не так:

Linux/macOS:

rm -rf ~/.aws

Windows:

rmdir /S/Q %USERPROFILE%\.aws

После этого настраиваете заново через `aws configure --profile hostkey`.

Типичные ошибки

• `aws не является командой` – после установки не перезапустился терминал, либо путь к утилите не попал в PATH. Перезапустите консоль; если не помогло, выполните `where aws` и проверьте, что путь действительно прописан в системных переменных.
• `Invalid bucket name` – имя бакета не соответствует правилам. Только строчные буквы, цифры, дефисы, длина 3–63 символа, без точек подряд, без подчёркиваний.
• `AccessDenied` – неправильные ключи или нет прав. Проверьте, что ключи скопированы полностью (по `aws configure list --profile hostkey` посмотрите, какие последние символы видит CLI, и сравните с панелью HOSTKEY). Если уверены, что ключи правильные – попробуйте пересоздать профиль.
• `SSL: CERTIFICATE_VERIFY_FAILED` – проблема с системным хранилищем сертификатов, обычно бывает на старых системах или за корпоративным прокси. Решается обновлением сертификатов в системе или флагом `--no-verify-ssl` (но это плохая идея, потому что отключает проверку HTTPS целиком).

Подключение через S3 Browser

S3 Browser (графический клиент) это графический клиент для Windows. Бесплатная версия позволяет работать с любым хранилищем, совместимым с S3 (объектным хранилищем), без ограничений на размер файлов или количество подключений. Удобен, когда нужно быстро посмотреть, что лежит в бакете, перетащить файлы мышкой, настроить права доступа через привычный интерфейс.

Установка

Скачайте дистрибутив с s3browser.com и установите обычным образом. Установщик не требует прав администратора и не оставляет следов в реестре кроме самого приложения. После установки запустите программу.

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

При первом запуске S3 Browser сразу предложит добавить аккаунт. Если окно не появилось, откройте меню Accounts >> Add New Account.

Заполните форму:

• Display name (Отображаемое имя) – любое удобное имя для отображения в списке. Например, `HOSTKEY S3` или `Бэкапы прод`.
• Account type (Тип аккаунта) – обязательно выберите S3 Compatible Storage. Не Amazon S3 Storage. Это самая частая ошибка: при выборе Amazon S3 клиент игнорирует поле endpoint и пытается подключиться к Amazon.
• API endpoint (Конечная точка API) – `s3-nl.hostkey.com`. Без `https://` в начале и без слеша в конце. Шифрование включается отдельной галочкой ниже.
• Access Key ID (Идентификатор ключа доступа) – ваш ключ доступа из панели управления оборудованием Invapi.
• Secret Access Key (Секретный ключ) – секретный ключ.
• Use secure transfer (SSL/TLS) (Использовать защищенную передачу) – оставьте включённым. Это и есть включение HTTPS.
• Encrypt Access Keys with a password (Зашифровать ключи доступа паролем) – необязательная опция. Если включить, S3 Browser попросит мастер-пароль при каждом запуске и без него ключи в локальной базе будут зашифрованы. Рекомендую включить, особенно если на компьютере работает не только владелец.

После нажатия кнопки Add new account в левой панели должен появиться список бакетов. Если его нет, стоит перепроверить ключи и тип хранилища в настройках аккаунта.

Работа с файлами

Дальше всё интуитивно. В левой панели лежит список бакетов, в правой содержимое выбранного. Загрузка идёт через кнопку Upload (Загрузить) или перетаскиванием из проводника. Для скачивания достаточно выделить файл и нажать Download (Скачать). Папки (точнее, виртуальные папки, в S3 это просто префиксы в именах) создаются через New Folder (Новая папка).

Из чуть менее очевидных возможностей. Правый клик на файле открывает контекстное меню, в нём есть Generate Web URL (Сгенерировать веб-ссылку) – генерация прямой публичной ссылки на файл. Полезно, когда нужно дать кому-то скачать конкретный объект, не открывая весь бакет. Можно настроить срок действия ссылки и сократить ее через Bitly (сервис сокращения ссылок) или TinyURL (сервис сокращения ссылок) прямо из интерфейса.

Права доступа настраиваются через пункт Edit Permissions (ACL) (Изменить права доступа) того же контекстного меню. Файл можно открыть всем на чтение без авторизации, оставить приватным или раздать права по группам пользователей. Для повседневных задач хватает двух кнопок – Make public (Сделать публичным) и Make private (Сделать приватным), они делают то же самое в один клик.

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

Подключение через Cyberduck

Cyberduck (графический клиент) это графический клиент для macOS и Windows. По функциональности похож на S3 Browser (графический клиент), но интерфейс приятнее, есть нативная поддержка macOS, плюс умеет работать не только с S3 (объектным хранилищем), но и с FTP (протоколом передачи файлов), SFTP (защищенным протоколом передачи файлов), WebDAV (протоколом для работы с веб-серверами) и другими протоколами. Бесплатный, с открытым исходным кодом.

Установка и подключение

Скачайте Cyberduck с cyberduck.io. Для Windows есть установщик, под macOS – обычный .dmg. Запустите программу и нажмите Open Connection (Открыть соединение) в верхней панели (или Cmd+N (комбинация клавиш) в macOS, Ctrl+N (комбинация клавиш) в Windows).

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

Настройка профиля

Перед первым подключением нужно включить специальный профиль совместимости. Откройте Edit >> Preferences >> Profiles (Правка >> Настройки >> Профили) , в строке поиска введите `path`, после чего находятся два профиля. Галочку нужно поставить напротив S3 (Deprecated path style requests, т.е.S3 с устаревшим стилем запросов пути).

Без этого шага Cyberduck будет подключаться, показывать список бакетов, но при попытке открыть бакет падать с ошибкой `Failed to parse XML document`. Это известный баг совместимости с хранилищами на Ceph. Сервер отвечает корректно, проблема на стороне клиента. Разобрать ответ Cyberduck не может. Профиль deprecated path style requests эту проблему обходит.

Подключение

Нажмите Open Connection (Открыть соединение) (Ctrl+N (комбинация клавиш)). В выпадающем списке вверху выберите S3 (Deprecated path style requests) (S3 с устаревшим стилем запросов пути), не обычный Amazon S3, а именно этот профиль.

Заполните поля:

• Server – `s3-nl.hostkey.com`. Без https:// и без слешей.
• Port – 443 (подставляется автоматически).
• Access Key ID – ваш ключ доступа.
• Secret Access Key – секретный ключ.

Нажмите Connect. Откроется список бакетов.

Работа с файлами

Двойной клик на бакете открывает его содержимое. Файлы перетаскиваются мышкой между Cyberduck (графическим клиентом) и Проводником. Для синхронизации папок есть команда File >> Synchronize (Файл >> Синхронизировать).

Подключение можно сохранить как закладку через Bookmark >> New Bookmark (Закладка >> Новая закладка) – тогда оно появится в списке и открывается двойным кликом.

Типичные ошибки

• `Connection failed: Operation timed out` – проверьте поле Server, там должно быть `s3-nl.hostkey.com` без префиксов и слешей.
• `Failed to parse XML document` – не включён профиль S3 (Deprecated path style requests) или при подключении выбран обычный Amazon S3 вместо него. Вернитесь к настройке профиля выше.

Подключение через Rclone (консольную утилиту для синхронизации)

Rclone (консольная утилита для синхронизации) это кроссплатформенная консольная утилита, заточенная под синхронизацию данных между разными хранилищами. По возможностям она шире, чем aws s3 sync (команда синхронизации). Работает одновременно с десятками протоколов, в том числе S3 (объектным хранилищем), Google Drive (облачным хранилищем), Dropbox (облачным хранилищем), OneDrive (облачным хранилищем), FTP (протоколом передачи файлов), SFTP (защищенным протоколом передачи файлов), и это далеко не полный список. Поддерживает шифрование на лету, фильтры по именам, дедупликацию.

Если основная задача в том, чтобы переливать большие объемы данных между разными хранилищами или делать бэкапы со сжатием и шифрованием, Rclone подходит лучше AWS CLI.

Установка

В Linux обычно ставится из пакетного менеджера дистрибутива:

Debian/Ubuntu

sudo apt install rclone

Fedora

sudo dnf install rclone

Arch

sudo pacman -S rclone

В macOS – через Homebrew (менеджер пакетов):

brew install rclone

В Windows – через winget (менеджер пакетов Windows):

winget install Rclone.Rclone

Или вручную. Скачайте zip-архив с rclone.org, выберите Windows AMD64, распакуйте и положите `rclone.exe` в любую папку из PATH.

Для Linux и macOS есть универсальный способ через официальный скрипт установки:

curl https://rclone.org/install.sh | sudo bash

На Windows этот скрипт не работает, остаются варианты с winget или ручной установкой.

Проверка установки:

rclone version

Настройка подключения

Rclone хранит подключения (он называет их remote) в одном конфигурационном файле, и настраивать их можно интерактивно или вручную. Интерактивно проще:

rclone config

Запускается мастер, в котором по шагам:

1. На вопрос n) New remote нажмите `n`.
2. name – введите имя для подключения, например `hostkey`. Это имя будет использоваться в командах.
3. Storage – из длинного списка выберите номер, соответствующий Amazon S3 Compliant Storage Providers (Поставщикам хранилищ, совместимых с Amazon S3) . На момент написания статьи это номер 4, но порядок может меняться, ориентируйтесь по названию.
4. provider – выберите Ceph Object Storage (объектное хранилище Ceph) . Несмотря на то что в списке есть пункт Other для любых S3-совместимых сервисов, HOSTKEY работает на Ceph, поэтому правильнее выбрать именно его.
5. env_auth – нажмите Enter, оставив значение по умолчанию false. Это означает что rclone будет использовать ключи, которые мы введём на следующих шагах, а не искать их в переменных окружения.
6. access_key_id – ваш ключ доступа.
7. secret_access_key – секретный ключ.
8. region – нажмите Enter, оставив поле пустым. HOSTKEY не использует регионы в классическом смысле, и пустое значение работает корректно. .
9. endpoint – s3-nl.hostkey.com. Без https:// – rclone добавляет протокол автоматически.
10. location_constraint – оставьте пустым.
11. acl – нажмите Enter, оставив значение `private`. Это означает что файлы будут доступны только владельцу аккаунта – безопасное поведение по умолчанию.
12. Дальше будет несколько вопросов про продвинутые настройки. На все можно отвечать значениями по умолчанию.
13. Мастер покажет итоговую конфигурацию и спросит Keep this "hostkey" remote? – нажмите y для подтверждения. После этого вернётесь в главное меню – нажмите q для выхода.

Если вы предпочитаете сразу написать конфиг руками, добавьте в файл `~/.config/rclone/rclone.conf` (Linux/macOS) или `%APPDATA%\rclone\rclone.conf` (Windows) такой блок:

[hostkey]
type = s3
provider = Ceph
access_key_id = ваш_ключ_доступа
secret_access_key = ваш_секретный_ключ
region =
endpoint = s3-nl.hostkey.com
acl = private

Основные команды

Обратите внимание на двоеточие после имени remote – hostkey:. Это обязательный синтаксис rclone, т.к. без двоеточия утилита воспримет имя как локальную папку, а не как удаленное хранилище. Если в пути есть пробелы – заключите его в кавычки.

В синтаксисе rclone путь к удалённому объекту выглядит как `имя-remote:путь`. Например, `hostkey:my-bucket/folder/file.txt`.

Список бакетов:

rclone lsd hostkey:

Содержимое бакета:

rclone ls hostkey:имя-бакета

Загрузка файла:

rclone copy ./локальный-файл.txt hostkey:имя-бакета/

Скачивание файла:

rclone copy hostkey:имя-бакета/файл.txt ./

Синхронизация папки это то, ради чего часто и ставят rclone:

rclone sync ./локальная-папка hostkey:имя-бакета/удалённая-папка/

В отличие от `aws s3 sync` (команды синхронизации), команда `rclone sync` по умолчанию удаляет в назначении файлы, которых нет в источнике. Это поведение полноценной синхронизации, и если вы не хотите, чтобы что-то удалялось, используйте `rclone copy`. Особенно осторожно с направлением: `rclone sync hostkey:bucket ./local` сотрёт всё, чего нет в бакете, из вашей локальной папки.

Прогресс и статистика во время передачи:

rclone copy ./папка hostkey:бакет/ --progress

Шифрование на лету. Rclone умеет создавать зашифрованный remote (удаленное хранилище) поверх обычного. Файлы шифруются перед отправкой и расшифровываются при скачивании, а в самом хранилище имена файлов выглядят как случайные строки. Настраивается через тот же `rclone config` выбором типа `crypt`. Полезно для бэкапов конфиденциальных данных.

Подключение через Python (язык программирования) с использованием boto3 (библиотеки для Python)

Библиотека boto3 (библиотека для Python) разработана Amazon для работы с AWS (облачной платформой Amazon) из Python (языка программирования). Как и AWS CLI, она нормально работает с любым хранилищем, совместимым с S3 (объектным хранилищем), нужно лишь указать endpoint. Для автоматизации в Python-скриптах, обработки данных в пайплайнах или интеграции с веб-приложением подходит именно она.

Установка

pip install boto3

Если уже устанавливали awscli (инструмент командной строки) по инструкции выше, то boto3 (библиотека для Python) уже стоит, дополнительно ничего делать не нужно.

Создание клиента

В boto3 (библиотеке для Python) есть две модели работы. Высокоуровневый resource удобнее для типичных операций (загрузка, скачивание файлов, работа с объектами), а низкоуровневый client даёт полный контроль и доступ ко всем параметрам программного интерфейса (API). Для большинства задач хватает resource.

Минимальный код для подключения:

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='https://s3-nl.hostkey.com',
    aws_access_key_id='ваш_ключ_доступа',
    aws_secret_access_key='ваш_секретный_ключ',
    region_name='nl',
)

Указывать endpoint обязательно – без него boto3 пойдёт в Amazon. Имя региона тоже нужно, хотя на работу с HOSTKEY он по сути не влияет, но boto3 проверяет его наличие.

Хранение учётных данных

Хранить ключи прямо в исходном коде плохая идея. Рано или поздно кто-нибудь закоммитит файл в публичный репозиторий, и ключи могут быть скомпрометированы очень быстро, иногда в течение минут. У AWS есть отдельный мониторинг, который сканирует GitHub на предмет утёкших ключей. Уровень автоматического реагирования и уведомлений отличается у разных поставщиков, так что об утечке иногда узнают только по счёту.

Есть три надежных способа хранить ключи отдельно от кода.

Файл `~/.aws/credentials` – тот же, что использует AWS CLI. boto3 умеет его читать автоматически. Если уже настроили профиль через `aws configure --profile hostkey`, можно просто указать имя профиля при создании сессии:

import boto3

session = boto3.Session(profile_name='hostkey')
s3 = session.client('s3', endpoint_url='https://s3-nl.hostkey.com')

Переменные окружения – удобно для контейнеров и CI/CD:

exportAWS_ACCESS_KEY_ID=ваш_ключ_доступа
exportAWS_SECRET_ACCESS_KEY=ваш_секретный_ключ
exportAWS_DEFAULT_REGION=nl

В коде тогда вообще не нужно ничего указывать кроме эндпоинта:

s3 = boto3.client('s3', endpoint_url='https://s3-nl.hostkey.com')

Для промышленной эксплуатации ключи обычно хранят в менеджерах секретов вроде Vault (системы управления секретами), AWS Secrets Manager (сервиса управления секретами) или Doppler (платформы управления секретами). На личных проектах такое решение чаще всего избыточно.

Основные операции

Список бакетов:

response = s3.list_buckets()
for bucket in response['Buckets']:
    print(bucket['Name'], bucket['CreationDate'])

Список объектов в бакете:

response = s3.list_objects_v2(Bucket='имя-бакета')
for obj in response.get('Contents', []):
    print(obj['Key'], obj['Size'])

Если объектов много, list_objects_v2 возвращает их пачками по 1000. Для полного перебора нужно использовать paginator:

paginator = s3.get_paginator('list_objects_v2')
for page in paginator.paginate(Bucket='имя-бакета'):
    for obj in page.get('Contents', []):
        print(obj['Key'])

Загрузка файла:

s3.upload_file('локальный.txt', 'имя-бакета', 'remote.txt')

Скачивание файла:

s3.download_file('имя-бакета', 'remote.txt', 'локальный.txt')

Загрузка из памяти – без создания временного файла:

data = b'Hello, S3!'
s3.put_object(Bucket='имя-бакета', Key='hello.txt', Body=data)

Чтение в память:

response = s3.get_object(Bucket='имя-бакета', Key='hello.txt')
data = response['Body'].read()

Удаление объекта:

s3.delete_object(Bucket='имя-бакета', Key='remote.txt')

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

url = s3.generate_presigned_url(
    'get_object',
    Params={'Bucket': 'имя-бакета', 'Key': 'remote.txt'},
    ExpiresIn=3600,  время жизни ссылки в секундах
)
print(url)

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

Обработка ошибок

boto3 кидает исключения класса `botocore.exceptions.ClientError` для большинства проблем со стороны сервера. У исключения есть код ошибки и человеческое описание:

from botocore.exceptions import ClientError

try:
    s3.head_object(Bucket='имя-бакета', Key='не-существует.txt')
except ClientError as e:
    code = e.response['Error']['Code']
    ifcode == '404':
        print('Файл не найден')
    elif code == '403':
        print('Нет доступа')
    else:
        print('Ошибка:', e)

Типичные коды ошибок: `NoSuchBucket`, `NoSuchKey`, `AccessDenied`, `InvalidAccessKeyId`, `SignatureDoesNotMatch`. Последняя обычно означает, что секретный ключ скопирован неполностью или с лишними пробелами.

Подключение через s3cmd (консольную утилиту для управления S3)

Утилита s3cmd (консольная утилита для управления S3) написана на Python (языке программирования) и работает с S3 (объектным хранилищем) уже много лет. По возможностям пересекается с AWS CLI (инструментом командной строки Amazon), синтаксис местами проще, а в некоторых дистрибутивах ставится по умолчанию.

Установка

Debian/Ubuntu

sudo apt install s3cmd

Fedora

sudo dnf install s3cmd

macOS

brew install s3cmd

Через pip – везде

pip install s3cmd

Настройка

Запустите интерактивный мастер:

s3cmd --configure

Мастер пройдёт по нескольким шагам. Ключевые ответы для HOSTKEY:

• - - Secret Key – секретный ключ.
• Default Region – `nl`.
• S3 Endpoint – `s3-nl.hostkey.com`.
• DNS-style bucket+hostname:port template – `%(bucket)s.s3-nl.hostkey.com`. Это шаблон для virtual-hosted адресации, которую мы разбирали в первой статье.
• Encryption password – оставьте пустым, если шифрование на стороне клиента не нужно.
• Use HTTPS protocol – `Yes`.

В конце мастер предложит проверить подключение – нажмите `y`. Если всё в порядке, конфигурация запишется в файл.

После сохранения конфига найдите файл `s3cmd.ini` и откройте его в текстовом редакторе. На Windows он может находиться в нестандартном месте – узнать точный путь можно командой:

dir /s/b"C:\Users\ИМЯ\s3cmd.ini" 

Или поиском:

where /R C:\Users\ИМЯ s3cmd.ini

Найдите строку:

host_bucket = %(bucket)s.s3-nl.hostkey.com

И замените на:

host_bucket =

Без этого s3cmd будет использовать virtual-hosted адресацию и падать с ошибкой SSL-сертификата при обращении к содержимому бакета.

Основные команды

Список бакетов

s3cmd ls

Содержимое бакета

s3cmd ls s3://имя-бакета/

Загрузка файла

s3cmd put локальный.txt s3://имя-бакета/

На Windows (операционной системе) при загрузке файлов s3cmd (консольная утилита для управления S3) выводит предупреждение Module python-magic (библиотека для определения типов файлов) is not available, это нормально, на работу не влияет. Полная поддержка python-magic (библиотеки для определения типов файлов) доступна только в Linux (операционной системе) и macOS (операционной системе).

Скачивание

s3cmd get s3://имя-бакета/файл.txt./локальный.txt

Удаление

s3cmd del s3://имя-бакета/файл.txt

Синхронизация папки

s3cmd sync ./папка/ s3://имя-бакета/папка/

Создание бакета

s3cmd mb s3://новый-бакет

Удаление бакета

s3cmd rb s3://бакет

Синтаксис компактнее, чем у AWS CLI (инструмента командной строки Amazon), но возможностей в целом меньше. Для нового проекта между `s3cmd` (консольной утилитой для управления S3) и `aws cli` (инструментом командной строки Amazon) чаще имеет смысл выбрать AWS CLI (инструмент командной строки Amazon). Утилита активно развивается, документация полнее, и под нее проще найти готовые примеры. У s3cmd (консольной утилиты для управления S3) тоже есть свои сильные стороны, особенно для тех, кто давно с ней работает, но как стартовая точка для незнакомого инструмента AWS CLI (инструмента командной строки Amazon) выглядит надёжнее.

Подключение S3 как файловой системы (s3fs)

s3fs (файловая система для S3) позволяет смонтировать бакет S3 (объектного хранилища) как обычную папку в файловой системе. После монтирования с бакетом получается работать любыми инструментами, которые работают с файлами. Подойдут команда копирования `cp`, команда списка файлов `ls`, текстовые редакторы, графические файловые менеджеры. На первый взгляд звучит как идеальное решение, но есть существенные оговорки.

s3fs отлично работает в нескольких сценариях:

• Нужно дать доступ к данным легаси-приложению, которое умеет работать только с локальными файлами и которое нельзя переписать.
• Простой бэкап через `rsync` (утилиту синхронизации) или `tar` (архиватор), без необходимости разбираться с S3 API.
• Совместное хранилище для редко изменяемых данных – медиафайлов, документов, артефактов сборок.

Когда не подходит

В первой статье уже разбирали, что S3 не поддерживает частичное обновление файлов. Любое изменение объекта означает полную перезапись. s3fs скрывает этот факт от приложений, но не отменяет его. Когда приложение пишет в файл по чуть-чуть (база данных, лог-файл с активной записью, покадровый видеомонтаж), каждое изменение оборачивается скачиванием всего объекта, правкой и повторной заливкой. Производительность получится катастрофической.

То же касается произвольного доступа. S3 (объектное хранилище) умеет читать диапазоны байтов, но за каждым из них стоит отдельный HTTP (протокол передачи гипертекста)-запрос. Открыть через s3fs (файловую систему для S3) большой файл в Excel (табличном процессоре) и пролистать выйдет медленно, а прочитать его целиком в память вполне нормально.

Операции вроде `ls` (команды списка файлов) в больших папках работают медленно, потому что превращаются в листинг бакета, который сам по себе не самая быстрая операция. На бакете с миллионом файлов `ls` может выполняться десятки секунд.

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

s3fs (файловая система для S3) работает только в Linux (операционной системе) и macOS (операционной системе). Под Windows (операционной системой) есть аналог rclone-mount (утилита монтирования) или WinFsp (файловая система для Windows).

Установка в Linux:

Debian/Ubuntu

sudo apt install s3fs

Fedora

sudo dnf install s3fs-fuse

Arch

sudo pacman -S s3fs-fuse

В macOS через Homebrew:

brew install gromgit/fuse/s3fs-mac

Сохраните учетные данные в файл с правильными правами:

echo"ваш_ключ_доступа:ваш_секретный_ключ" > ~/.passwd-s3fs
chmod 600 ~/.passwd-s3fs

Права 600 (доступ только владельцу) обязательны, т.к. без них s3fs откажется использовать файл.

Создайте точку монтирования и смонтируйте бакет:

mkdir ~/s3-mount
s3fs имя-бакета ~/s3-mount \
    -o passwd_file=~/.passwd-s3fs \
    -o url=https://s3-nl.hostkey.com \
    -o use_path_request_style

Параметр `use_path_request_style` важен – без него s3fs пытается использовать virtual-hosted адресацию, которая может не работать с нестандартными endpoint (точками подключения).

После монтирования можно работать с папкой `~/s3-mount` как с обычной:

ls ~/s3-mount/
cp файл.txt ~/s3-mount/

Размонтирование:

fusermount -u ~/s3-mount    Linux
umount ~/s3-mount           macOS

Для постоянного монтирования при загрузке системы добавьте строку в `/etc/fstab`:

имя-бакета /home/user/s3-mount fuse.s3fs _netdev,allow_other,passwd_file=/home/user/.passwd-s3fs,url=https://s3-nl.hostkey.com,use_path_request_style 0 0

Параметр `_netdev` подсказывает системе, что это сетевое монтирование, и не пытаться его подключить до того, как поднимется сеть.

Лучшие практики при работе с S3

Несколько правил, которые экономят нервы и деньги. Они не зависят от поставщика и применимы к любому S3-совместимому хранилищу.

Поменьше публичного доступа. По умолчанию все бакеты приватные, и это разумно. Открывать на чтение стоит только то, что действительно должно быть публичным, причём на уровне отдельных объектов или префиксов, а не всего бакета. Для временной публикации файлов подойдут подписанные ссылки с ограниченным временем жизни (`generate_presigned_url` в boto3 или Generate Web URL в S3 Browser). Они безопаснее и сами перестают работать через заданный срок.

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

Политики жизненного цикла. Холодные данные вроде старых бэкапов или архивных логов можно автоматически переводить в более дешевый класс хранения через 30–90 дней, а ещё через какое-то время удалять. На больших объемах экономия получается заметной.

Не складывать всё в один префикс. Когда все объекты называются `logs/2025-04-29/...`, при росте нагрузки начинаются троттлинги, все запросы летят в один внутренний шард индекса. Ключи лучше распределять по префиксам так, чтобы нагрузка ложилась равномерно. Например, добавлять хеш в начало ключа или использовать дату в обратном формате, чтобы свежие записи не оказывались соседями.

Мониторинг и логирование. Большинство S3-совместимых сервисов умеет писать access-логи каждого запроса в отдельный бакет. На рабочих системах это полезно. Так можно понять, кто куда обращается, выловить аномалии, разобраться, почему счёт за трафик внезапно вырос.

Бэкапы важных данных в другом регионе или у другого поставщика. Один S3-сервис не панацея. Если что-то случится с дата-центром, с поставщиком или с самим аккаунтом, без отдельной копии в другом месте данные пропадут. Кросс-региональная репликация и регулярная синхронизация с другим хранилищем считается нормальной практикой для критичных данных.

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