Azure Blob Storage

Konfiguracja produkcyjna

Azure Blob Storage oferuje skalowalne i bezpieczne przechowywanie obiektów dla plików w LibreChat. Wykonaj poniższe kroki, aby skonfigurować Azure Blob Storage.

1. Utwórz konto Azure Storage

1. Zaloguj się do Azure:

   • Otwórz Azure Portal i zaloguj się za pomocą swojego konta Microsoft.

2. Utwórz konto magazynu (Storage Account):

   • Kliknij "Create a resource" i wyszukaj "Storage account".
   • Kliknij "Create" i wypełnij wymagane szczegóły:
     • Subskrypcja i grupa zasobów: Wybierz swoją subskrypcję oraz wybierz istniejącą grupę zasobów lub utwórz nową.
     • Nazwa konta magazynu: Wprowadź unikalną nazwę (np. mylibrechatstorage).
     • Region: Wybierz region najbliższy Twoim użytkownikom.
     • Wydajność i redundancja: Wybierz poziom wydajności i redundancji, który najlepiej odpowiada Twoim potrzebom.
   • Kliknij "Review + Create", a następnie "Create". Poczekaj, aż wdrażanie zostanie zakończone.

2. Skonfiguruj uwierzytelnianie

Masz dwie opcje uwierzytelniania za pomocą swojego konta Azure Storage Account:

Opcja A: Użycie ciągu połączeniowego (Connection String)

1. Przejdź do kluczy dostępu (Access Keys):

   • W nowo utworzonym koncie magazynu przejdź do "Access keys" na pasku bocznym.

2. Kopiuj ciąg połączenia:

   • Skopiuj jeden z dostarczonych ciągów połączeniowych. Ten ciąg zawiera dane uwierzytelniające wymagane do połączenia się z Twoim kontem Blob Storage.

Opcja B: Używanie tożsamości zarządzanej (Managed Identity)

Jeśli Twoja aplikacja LibreChat działa w usłudze Azure obsługującej Managed Identity (takiej jak Azure VM, App Service lub AKS), możesz użyć jej zamiast ciągu połączeniowego (connection string).

1. Przypisz tożsamość zarządzaną (Managed Identity):

   • Upewnij się, że Twój zasób Azure (VM, App Service lub AKS) ma włączoną tożsamość zarządzaną (Managed Identity) przypisaną przez system lub przez użytkownika.

2. Przyznaj uprawnienia do przechowywania:

   • W swoim koncie magazynu przypisz rolę Storage Blob Data Contributor (lub rolę o podobnym zakresie) do swojej tożsamości zarządzanej (Managed Identity). Pozwala to aplikacji na dostęp do usługi Blob Storage bez użycia ciągu połączeniowego (connection string).

3. Zaktualizuj swoje zmienne środowiskowe

Utwórz lub zaktualizuj swój plik .env w katalogu głównym projektu za pomocą następującej konfiguracji:

# Option A: Using a Connection String
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=yourAccountKey;EndpointSuffix=core.windows.net

# Option B: Using Managed Identity (do not set the connection string if using Managed Identity)
AZURE_STORAGE_ACCOUNT_NAME=yourAccountName

AZURE_STORAGE_PUBLIC_ACCESS=false
AZURE_CONTAINER_NAME=files

• AZURE_STORAGE_CONNECTION_STRING: Ustaw tę wartość, jeśli korzystasz z Opcji A.
• AZURE_STORAGE_ACCOUNT_NAME: Ustaw tę wartość, jeśli korzystasz z Opcji B (Managed Identity). Nie ustawiaj obu jednocześnie.
• AZURE_STORAGE_PUBLIC_ACCESS: Ustaw na false, jeśli nie chcesz, aby Twoje obiekty blob były domyślnie publicznie dostępne. Ustaw na true, jeśli potrzebujesz dostępu publicznego (na przykład w przypadku obrazów widocznych publicznie).
• AZURE_CONTAINER_NAME: Jest to nazwa kontenera, z którego będzie korzystać Twoja aplikacja (np. files). Aplikacja automatycznie utworzy ten kontener, jeśli nie istnieje.

4. Skonfiguruj LibreChat, aby używać Azure Blob Storage

Zaktualizuj plik konfiguracyjny LibreChat (librechat.yaml), aby określić, że aplikacja powinna używać Azure Blob Storage do obsługi plików:

version: 1.3.5
cache: true
fileStrategy: "azure_blob"

fileStrategies:
  avatar: "firebase"
  image: "firebase"
  document: "azure_blob"

Podsumowanie

1. Utwórz konto magazynu (Storage Account):
   Zaloguj się do Azure Portal, utwórz konto magazynu i poczekaj na zakończenie wdrażania.

2. Skonfiguruj uwierzytelnianie:

• Opcja A: Pobierz ciąg połączeniowy z "Access keys" na swoim koncie magazynu.
• Opcja B: Użyj tożsamości zarządzanej (Managed Identity), włączając ją w swoim zasobie Azure i przyznając jej odpowiednie uprawnienia do magazynu.

3. Aktualizacja zmiennych środowiskowych:
   W pliku .env ustaw jedną z poniższych opcji:

• AZURE_STORAGE_CONNECTION_STRING (dla Opcji A), lub
• AZURE_STORAGE_ACCOUNT_NAME (dla Opcji B), wraz z:
• AZURE_STORAGE_PUBLIC_ACCESS oraz
• AZURE_CONTAINER_NAME.

4. Skonfiguruj LibreChat:
   Ustaw fileStrategy na "azure_blob" w swoim pliku konfiguracyjnym librechat.yaml.

Dzięki tym krokom Twoja aplikacja LibreChat automatycznie utworzy kontener (jeśli nie istnieje) oraz będzie zarządzać przesyłaniem, pobieraniem i usuwaniem plików przy użyciu Azure Blob Storage. Managed Identity stanowi bezpieczną alternatywę, eliminując potrzebę stosowania długoterminowych poświadczeń.

Lokalne środowisko programistyczne z Azurite

Do lokalnego programowania i testowania możesz użyć Azurite, emulatora Azure Storage, który zapewnia lokalne środowisko do testowania integracji z Azure Blob Storage bez konieczności posiadania rzeczywistego konta Azure.

1. Skonfiguruj Azurite

Możesz uruchomić Azurite na kilka sposobów:

Opcja A: Użycie rozszerzenia VS Code (zalecane do programowania)

1. Zainstaluj rozszerzenie Azurite dla VS Code
2. Otwórz paletę poleceń (Ctrl+Shift+P lub Cmd+Shift+P)
3. Wyszukaj i wybierz "Azurite: Start"

To uruchomi Azurite w tle z domyślnymi ustawieniami.

Opcja B: Używając Docker

docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite

Opcja C: Użycie npm

npm install -g azurite
azurite --silent --location /path/to/azurite/workspace --debug /path/to/debug/log

2. Skonfiguruj zmienne środowiskowe dla lokalnego programowania

Dodaj następujące zmienne środowiskowe do swojego pliku .env:

# Azurite connection string for local development
AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
AZURE_STORAGE_PUBLIC_ACCESS=true
AZURE_CONTAINER_NAME=files

Uwagi:

• Wartość AccountKey to domyślny klucz programistyczny używany przez Azurite
• Połączenie używa protokołu http zamiast https na potrzeby lokalnego programowania
• BlobEndpoint wskazuje na lokalną instancję Azurite działającą na porcie 10000

3. Weryfikacja połączenia

Aby zweryfikować, czy Twoja aplikacja może połączyć się z lokalną instancją Azurite:

1. Uruchom swoją aplikację LibreChat
2. Spróbuj przesłać plik przez interfejs
3. Sprawdź logi Azurite, aby potwierdzić połączenie i operacje

Jeśli używasz rozszerzenia VS Code, możesz wyświetlić logi Azurite w panelu Output, wybierając "Azurite Blob" z listy rozwijanej.