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/he/minio-to-s3-migration.he.md
Normal file
266
docs/tech-specs/he/minio-to-s3-migration.he.md
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Tech Spec: S3-Compatible Storage Backend Support"
|
||||
parent: "Hebrew (Beta)"
|
||||
---
|
||||
|
||||
# Tech Spec: S3-Compatible Storage Backend Support
|
||||
|
||||
> **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.
|
||||
|
||||
## Overview
|
||||
|
||||
השירות Librarian משתמש באחסון אובייקטים תואם ל-S3 לאחסון קבצים. מסמך זה מתאר את היישום המאפשר תמיכה בכל אחסון תואם ל-S3, כולל MinIO, Ceph RADOS Gateway (RGW), AWS S3, Cloudflare R2, DigitalOcean Spaces, ואחרים.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Storage Components
|
||||
**Blob Storage**: אחסון אובייקטים תואם ל-S3 באמצעות `minio` ספריית לקוח Python
|
||||
**Metadata Storage**: Cassandra (מאחסן מיפוי object_id ונתוני מטא-דאטה של מסמכים)
|
||||
**Affected Component**: רק השירות Librarian
|
||||
**Storage Pattern**: אחסון היברידי עם מטא-דאטה ב-Cassandra ותוכן באחסון תואם ל-S3
|
||||
|
||||
### Implementation
|
||||
**Library**: `minio` לקוח Python (תומך בכל API תואם ל-S3)
|
||||
**Location**: `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
**Operations**:
|
||||
`add()` - שמירת קובץ עם מזהה אובייקט UUID
|
||||
`get()` - שליפת קובץ לפי מזהה אובייקט
|
||||
`remove()` - מחיקת קובץ לפי מזהה אובייקט
|
||||
`ensure_bucket()` - יצירת תיקייה אם היא לא קיימת
|
||||
**Bucket**: `library`
|
||||
**Object Path**: `doc/{object_id}`
|
||||
**Supported MIME Types**: `text/plain`, `application/pdf`
|
||||
|
||||
### Key Files
|
||||
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
|
||||
|
||||
## Supported Storage Backends
|
||||
|
||||
היישום עובד עם כל מערכת אחסון אובייקטים תואמת ל-S3:
|
||||
|
||||
### Tested/Supported
|
||||
**Ceph RADOS Gateway (RGW)** - מערכת אחסון מבוזרת עם API של S3 (תצורת ברירת מחדל)
|
||||
**MinIO** - אחסון אובייקטים קל משקל, הניתן לאירוח עצמי
|
||||
**Garage** - אחסון S3-תואם, מבוזר גיאוגרפית, קל משקל
|
||||
|
||||
### Should Work (S3-Compatible)
|
||||
**AWS S3** - אחסון אובייקטים בענן של Amazon
|
||||
**Cloudflare R2** - אחסון S3-תואם של Cloudflare
|
||||
**DigitalOcean Spaces** - אחסון אובייקטים של DigitalOcean
|
||||
**Wasabi** - אחסון בענן S3-תואם
|
||||
**Backblaze B2** - אחסון גיבוי S3-תואם
|
||||
כל שירות אחר המיישם את ממשק ה-API של S3
|
||||
|
||||
## Configuration
|
||||
|
||||
### CLI Arguments
|
||||
|
||||
```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 (ברירת מחדל):**
|
||||
```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
|
||||
|
||||
## בחירת ספרייה: לקוח Python של MinIO
|
||||
|
||||
**ההצדקה:**
|
||||
קל משקל (~500KB לעומת ~50MB של 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 הוא בגודל של כ-500KB בלבד
|
||||
3. **הגדרות פשוטות** - רק נקודת קצה (endpoint) ואישורים
|
||||
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 לפייתון: https://min.io/docs/minio/linux/developers/python/API.html
|
||||
Ceph RGW S3 API: https://docs.ceph.com/en/latest/radosgw/s3/
|
||||
מדריך API של S3: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
|
||||
Loading…
Add table
Add a link
Reference in a new issue