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/pt/minio-to-s3-migration.pt.md
Normal file
266
docs/tech-specs/pt/minio-to-s3-migration.pt.md
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Especificação Técnica: Suporte a Backend de Armazenamento Compatível com S3"
|
||||
parent: "Portuguese (Beta)"
|
||||
---
|
||||
|
||||
# Especificação Técnica: Suporte a Backend de Armazenamento Compatível com 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.
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O serviço Librarian utiliza armazenamento de objetos compatível com S3 para o armazenamento de blobs de documentos. Esta especificação documenta a implementação que permite o suporte a qualquer backend compatível com S3, incluindo MinIO, Ceph RADOS Gateway (RGW), AWS S3, Cloudflare R2, DigitalOcean Spaces e outros.
|
||||
|
||||
## Arquitetura
|
||||
|
||||
### Componentes de Armazenamento
|
||||
**Armazenamento de Blobs**: Armazenamento de objetos compatível com S3 através da biblioteca cliente `minio` Python.
|
||||
**Armazenamento de Metadados**: Cassandra (armazena o mapeamento object_id e os metadados do documento).
|
||||
**Componente Afetado**: Apenas o serviço Librarian.
|
||||
**Padrão de Armazenamento**: Armazenamento híbrido com metadados no Cassandra e conteúdo no armazenamento compatível com S3.
|
||||
|
||||
### Implementação
|
||||
**Biblioteca**: Cliente `minio` Python (suporta qualquer API compatível com S3).
|
||||
**Localização**: `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
**Operações**:
|
||||
`add()` - Armazenar blob com object_id UUID.
|
||||
`get()` - Recuperar blob por object_id.
|
||||
`remove()` - Excluir blob por object_id.
|
||||
`ensure_bucket()` - Criar bucket se não existir.
|
||||
**Bucket**: `library`
|
||||
**Caminho do Objeto**: `doc/{object_id}`
|
||||
**Tipos MIME Suportados**: `text/plain`, `application/pdf`
|
||||
|
||||
### Arquivos Chave
|
||||
1. `trustgraph-flow/trustgraph/librarian/blob_store.py` - Implementação do BlobStore.
|
||||
2. `trustgraph-flow/trustgraph/librarian/librarian.py` - Inicialização do BlobStore.
|
||||
3. `trustgraph-flow/trustgraph/librarian/service.py` - Configuração do serviço.
|
||||
4. `trustgraph-flow/pyproject.toml` - Dependências (pacote `minio`).
|
||||
5. `docs/apis/api-librarian.md` - Documentação da API.
|
||||
|
||||
## Backends de Armazenamento Suportados
|
||||
|
||||
A implementação funciona com qualquer sistema de armazenamento de objetos compatível com S3:
|
||||
|
||||
### Testados/Suportados
|
||||
**Ceph RADOS Gateway (RGW)** - Sistema de armazenamento distribuído com API S3 (configuração padrão).
|
||||
**MinIO** - Armazenamento de objetos auto-hospedado leve.
|
||||
**Garage** - Armazenamento S3-compatível geo-distribuído leve.
|
||||
|
||||
### Deve Funcionar (Compatível com S3)
|
||||
**AWS S3** - Armazenamento de objetos em nuvem da Amazon.
|
||||
**Cloudflare R2** - Armazenamento S3-compatível da Cloudflare.
|
||||
**DigitalOcean Spaces** - Armazenamento de objetos da DigitalOcean.
|
||||
**Wasabi** - Armazenamento em nuvem S3-compatível.
|
||||
**Backblaze B2** - Armazenamento de backup S3-compatível.
|
||||
Qualquer outro serviço que implemente a API REST S3.
|
||||
|
||||
## Configuração
|
||||
|
||||
### Argumentos da Linha de Comando
|
||||
|
||||
```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>]
|
||||
```
|
||||
|
||||
**Observação:** Não inclua `http://` ou `https://` no endpoint. Use `--object-store-use-ssl` para habilitar HTTPS.
|
||||
|
||||
### Variáveis de Ambiente (Alternativa)
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### Exemplos
|
||||
|
||||
**Ceph RADOS Gateway (padrão):**
|
||||
```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
|
||||
```
|
||||
|
||||
**Armazenamento (compatível com S3):**
|
||||
```bash
|
||||
--object-store-endpoint garage:3900 \
|
||||
--object-store-access-key GK000000000000000000000001 \
|
||||
--object-store-secret-key b171f00be9be4c32c734f4c05fe64c527a8ab5eb823b376cfa8c2531f70fc427
|
||||
```
|
||||
|
||||
**AWS S3 com 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
|
||||
```
|
||||
|
||||
## Autenticação
|
||||
|
||||
Todos os backends compatíveis com S3 requerem a autenticação AWS Signature Version 4 (ou v2):
|
||||
|
||||
**Chave de Acesso** - Identificador público (como nome de usuário)
|
||||
**Chave Secreta** - Chave de assinatura privada (como senha)
|
||||
|
||||
O cliente Python da MinIO gerencia automaticamente todos os cálculos de assinatura.
|
||||
|
||||
### Criando Credenciais
|
||||
|
||||
**Para MinIO:**
|
||||
```bash
|
||||
# Use default credentials or create user via MinIO Console
|
||||
minioadmin / minioadmin
|
||||
```
|
||||
|
||||
**Para o Ceph RGW:**
|
||||
```bash
|
||||
radosgw-admin user create --uid="trustgraph" --display-name="TrustGraph Service"
|
||||
# Returns access_key and secret_key
|
||||
```
|
||||
|
||||
**Para AWS S3:**
|
||||
Crie um usuário IAM com permissões S3
|
||||
Gere uma chave de acesso no Console da AWS
|
||||
|
||||
## Seleção da Biblioteca: Cliente Python MinIO
|
||||
|
||||
**Justificativa:**
|
||||
Leve (~500KB vs ~50MB do boto3)
|
||||
Compatível com S3 - funciona com qualquer endpoint de API S3
|
||||
API mais simples que o boto3 para operações básicas
|
||||
Já em uso, não é necessária migração
|
||||
Testado em batalha com MinIO e outros sistemas S3
|
||||
|
||||
## Implementação do BlobStore
|
||||
|
||||
**Localização:** `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()
|
||||
```
|
||||
|
||||
## Benefícios Principais
|
||||
|
||||
1. **Sem Dependência de Fornecedor** - Funciona com qualquer armazenamento compatível com S3.
|
||||
2. **Leve** - O cliente MinIO tem apenas ~500KB.
|
||||
3. **Configuração Simples** - Apenas endpoint e credenciais.
|
||||
4. **Sem Migração de Dados** - Substituição direta entre backends.
|
||||
5. **Testado em Combate** - O cliente MinIO funciona com todas as principais implementações S3.
|
||||
|
||||
## Status da Implementação
|
||||
|
||||
Todo o código foi atualizado para usar nomes de parâmetros S3 genéricos:
|
||||
|
||||
✅ `blob_store.py` - Atualizado para aceitar `endpoint`, `access_key`, `secret_key`.
|
||||
✅ `librarian.py` - Nomes de parâmetros atualizados.
|
||||
✅ `service.py` - Argumentos da CLI e configuração atualizados.
|
||||
✅ Documentação atualizada.
|
||||
|
||||
## Melhorias Futuras
|
||||
|
||||
1. **Suporte SSL/TLS** - Adicionar a flag `--s3-use-ssl` para HTTPS.
|
||||
2. **Lógica de Repetição** - Implementar retrocesso exponencial para falhas transitórias.
|
||||
3. **URLs Pré-assinadas** - Gerar URLs temporárias de upload/download.
|
||||
4. **Suporte Multi-região** - Replicar blobs entre regiões.
|
||||
5. **Integração CDN** - Servir blobs via CDN.
|
||||
6. **Classes de Armazenamento** - Usar classes de armazenamento S3 para otimização de custos.
|
||||
7. **Políticas de Ciclo de Vida** - Arquivamento/exclusão automática.
|
||||
8. **Versionamento** - Armazenar múltiplas versões de blobs.
|
||||
|
||||
## Referências
|
||||
|
||||
Cliente Python MinIO: https://min.io/docs/minio/linux/developers/python/API.html
|
||||
API S3 Ceph RGW: https://docs.ceph.com/en/latest/radosgw/s3/
|
||||
Referência da API S3: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
|
||||
Loading…
Add table
Add a link
Reference in a new issue