trustgraph/docs/tech-specs/minio-to-s3-migration.ru.md

layout	title	parent
default	Технические характеристики: Поддержка хранилища, совместимого с S3	Russian (Beta)

Технические характеристики: Поддержка хранилища, совместимого с S3

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Обзор

Сервис Librarian использует объектное хранилище, совместимое с S3, для хранения двоичных данных документов. Этот документ описывает реализацию, которая обеспечивает поддержку любого хранилища, совместимого с S3, включая MinIO, Ceph RADOS Gateway (RGW), AWS S3, Cloudflare R2, DigitalOcean Spaces и другие.

Архитектура

Компоненты хранения

Хранилище двоичных данных: Объектное хранилище, совместимое с S3, через minio Python клиентскую библиотеку. Хранилище метаданных: Cassandra (хранит сопоставление object_id и метаданные документов). Затронутый компонент: Только сервис Librarian. Схема хранения: Гибридное хранилище с метаданными в Cassandra и содержимым в хранилище, совместимом с S3.

Реализация

Библиотека: minio Python клиент (поддерживает любой API, совместимый с S3). Расположение: trustgraph-flow/trustgraph/librarian/blob_store.py Операции: add() - Сохранение двоичных данных с object_id в формате UUID. get() - Получение двоичных данных по object_id. remove() - Удаление двоичных данных по object_id. ensure_bucket() - Создание бакета, если он не существует. Бакет: library Путь к объекту: doc/{object_id} Поддерживаемые типы MIME: text/plain, application/pdf

Основные файлы

1. trustgraph-flow/trustgraph/librarian/blob_store.py - Реализация BlobStore.
2. trustgraph-flow/trustgraph/librarian/librarian.py - Инициализация BlobStore.
3. trustgraph-flow/trustgraph/librarian/service.py - Конфигурация сервиса.
4. trustgraph-flow/pyproject.toml - Зависимости (пакет minio).
5. docs/apis/api-librarian.md - Документация API.

Поддерживаемые системы хранения

Реализация работает с любой системой объектного хранения, совместимой с S3:

Протестировано/Поддерживается

Ceph RADOS Gateway (RGW) - Распределенная система хранения с API S3 (конфигурация по умолчанию). MinIO - Легковесное объектное хранилище для самостоятельного размещения. Garage - Легковесное географически распределенное хранилище, совместимое с S3.

Должно работать (совместимо с S3)

AWS S3 - Облачное объектное хранилище от Amazon. Cloudflare R2 - Хранилище от Cloudflare, совместимое с S3. DigitalOcean Spaces - Объектное хранилище от DigitalOcean. Wasabi - Облачное хранилище, совместимое с S3. Backblaze B2 - Хранилище резервных копий, совместимое с S3. Любая другая служба, реализующая REST API S3.

Конфигурация

Аргументы командной строки

librarian \
  --object-store-endpoint <hostname:port> \
  --object-store-access-key <access_key> \
  --object-store-secret-key <secret_key> \
  [--object-store-use-ssl] \
  [--object-store-region <region>]

Примечание: Не включайте http:// или https:// в конечную точку. Используйте --object-store-use-ssl для включения HTTPS.

Переменные окружения (Альтернативный способ)

OBJECT_STORE_ENDPOINT=<hostname:port>
OBJECT_STORE_ACCESS_KEY=<access_key>
OBJECT_STORE_SECRET_KEY=<secret_key>
OBJECT_STORE_USE_SSL=true|false  # Optional, default: false
OBJECT_STORE_REGION=<region>     # Optional

Примеры

Ceph RADOS Gateway (по умолчанию):

--object-store-endpoint ceph-rgw:7480 \
--object-store-access-key object-user \
--object-store-secret-key object-password

MinIO:

--object-store-endpoint minio:9000 \
--object-store-access-key minioadmin \
--object-store-secret-key minioadmin

Гараж (совместимый с S3):

--object-store-endpoint garage:3900 \
--object-store-access-key GK000000000000000000000001 \
--object-store-secret-key b171f00be9be4c32c734f4c05fe64c527a8ab5eb823b376cfa8c2531f70fc427

AWS S3 с использованием SSL:

--object-store-endpoint s3.amazonaws.com \
--object-store-access-key AKIAIOSFODNN7EXAMPLE \
--object-store-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
--object-store-use-ssl \
--object-store-region us-east-1

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

Все бэкенды, совместимые с S3, требуют аутентификации AWS Signature Version 4 (или v2):

Access Key - Публичный идентификатор (например, имя пользователя) Secret Key - Приватный ключ для подписи (например, пароль)

Python-клиент MinIO автоматически обрабатывает все вычисления подписи.

Создание учетных данных

Для MinIO:

# Use default credentials or create user via MinIO Console
minioadmin / minioadmin

Для Ceph RGW:

radosgw-admin user create --uid="trustgraph" --display-name="TrustGraph Service"
# Returns access_key and secret_key

Для AWS S3: Создайте пользователя IAM с разрешениями S3 Сгенерируйте ключ доступа в консоли AWS

Выбор библиотеки: MinIO Python Client

Обоснование: Легковесная (~500 КБ против ~50 МБ у boto3) Совместима с S3 - работает с любым конечным пунктом API S3 Более простой API, чем boto3, для основных операций Уже используется, не требуется миграция Проверена в боевых условиях с MinIO и другими системами S3

Реализация BlobStore

Расположение: trustgraph-flow/trustgraph/librarian/blob_store.py

from minio import Minio
import io
import logging

logger = logging.getLogger(__name__)

class BlobStore:
    """
    S3-compatible blob storage for document content.
    Supports MinIO, Ceph RGW, AWS S3, and other S3-compatible backends.
    """

    def __init__(self, endpoint, access_key, secret_key, bucket_name,
                 use_ssl=False, region=None):
        """
        Initialize S3-compatible blob storage.

        Args:
            endpoint: S3 endpoint (e.g., "minio:9000", "ceph-rgw:7480")
            access_key: S3 access key
            secret_key: S3 secret key
            bucket_name: Bucket name for storage
            use_ssl: Use HTTPS instead of HTTP (default: False)
            region: S3 region (optional, e.g., "us-east-1")
        """
        self.client = Minio(
            endpoint=endpoint,
            access_key=access_key,
            secret_key=secret_key,
            secure=use_ssl,
            region=region,
        )

        self.bucket_name = bucket_name

        protocol = "https" if use_ssl else "http"
        logger.info(f"Connected to S3-compatible storage at {protocol}://{endpoint}")

        self.ensure_bucket()

    def ensure_bucket(self):
        """Create bucket if it doesn't exist"""
        found = self.client.bucket_exists(bucket_name=self.bucket_name)
        if not found:
            self.client.make_bucket(bucket_name=self.bucket_name)
            logger.info(f"Created bucket {self.bucket_name}")
        else:
            logger.debug(f"Bucket {self.bucket_name} already exists")

    async def add(self, object_id, blob, kind):
        """Store blob in S3-compatible storage"""
        self.client.put_object(
            bucket_name=self.bucket_name,
            object_name=f"doc/{object_id}",
            length=len(blob),
            data=io.BytesIO(blob),
            content_type=kind,
        )
        logger.debug("Add blob complete")

    async def remove(self, object_id):
        """Delete blob from S3-compatible storage"""
        self.client.remove_object(
            bucket_name=self.bucket_name,
            object_name=f"doc/{object_id}",
        )
        logger.debug("Remove blob complete")

    async def get(self, object_id):
        """Retrieve blob from S3-compatible storage"""
        resp = self.client.get_object(
            bucket_name=self.bucket_name,
            object_name=f"doc/{object_id}",
        )
        return resp.read()

Ключевые преимущества

1. Отсутствие привязки к конкретному поставщику - Работает с любым хранилищем, совместимым с S3.
2. Легковесность - Клиент MinIO занимает всего около 500 КБ.
3. Простая настройка - Только конечная точка и учетные данные.
4. Отсутствие миграции данных - Замена между бэкендами без перебоев.
5. Проверено в боевых условиях - Клиент MinIO работает со всеми основными реализациями S3.

Статус реализации

Весь код был обновлен для использования общих имен параметров S3:

✅ blob_store.py - Обновлено для приема endpoint, access_key, secret_key ✅ librarian.py - Обновлены имена параметров ✅ service.py - Обновлены аргументы командной строки и конфигурация ✅ Обновлена документация

Планируемые улучшения

1. Поддержка SSL/TLS - Добавить флаг --s3-use-ssl для HTTPS.
2. Логика повторных попыток - Реализовать экспоненциальную задержку для временных сбоев.
3. Временные URL-адреса - Генерировать временные URL-адреса для загрузки/скачивания.
4. Поддержка нескольких регионов - Репликация объектов между регионами.
5. Интеграция с CDN - Предоставление объектов через CDN.
6. Классы хранения - Использование классов хранения S3 для оптимизации затрат.
7. Политики жизненного цикла - Автоматическое архивирование/удаление.
8. Версионирование - Хранение нескольких версий объектов.

Ссылки

MinIO Python Client: https://min.io/docs/minio/linux/developers/python/API.html Ceph RGW S3 API: https://docs.ceph.com/en/latest/radosgw/s3/ S3 API Reference: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html