mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 08:56:21 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
266
docs/tech-specs/ru/minio-to-s3-migration.ru.md
Normal file
266
docs/tech-specs/ru/minio-to-s3-migration.ru.md
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Технические характеристики: Поддержка хранилища, совместимого с S3"
|
||||
parent: "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.
|
||||
|
||||
## Конфигурация
|
||||
|
||||
### Аргументы командной строки
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
### Переменные окружения (Альтернативный способ)
|
||||
|
||||
```bash
|
||||
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 (по умолчанию):**
|
||||
```bash
|
||||
--object-store-endpoint ceph-rgw:7480 \
|
||||
--object-store-access-key object-user \
|
||||
--object-store-secret-key object-password
|
||||
```
|
||||
|
||||
**MinIO:**
|
||||
```bash
|
||||
--object-store-endpoint minio:9000 \
|
||||
--object-store-access-key minioadmin \
|
||||
--object-store-secret-key minioadmin
|
||||
```
|
||||
|
||||
**Гараж (совместимый с S3):**
|
||||
```bash
|
||||
--object-store-endpoint garage:3900 \
|
||||
--object-store-access-key GK000000000000000000000001 \
|
||||
--object-store-secret-key b171f00be9be4c32c734f4c05fe64c527a8ab5eb823b376cfa8c2531f70fc427
|
||||
```
|
||||
|
||||
**AWS S3 с использованием SSL:**
|
||||
```bash
|
||||
--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:**
|
||||
```bash
|
||||
# Use default credentials or create user via MinIO Console
|
||||
minioadmin / minioadmin
|
||||
```
|
||||
|
||||
**Для Ceph RGW:**
|
||||
```bash
|
||||
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`
|
||||
|
||||
```python
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue