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

layout	title	parent
default	Tech Spec: S3-Compatible Storage Backend Support	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

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 (ברירת מחדל):

--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

בחירת ספרייה: לקוח Python של MinIO

ההצדקה: קל משקל (~500KB לעומת ~50MB של 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 הוא בגודל של כ-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