Udostępnij przez

Zabezpieczenia i wdrażanie

Usługa DevUI została zaprojektowana jako przykładowa aplikacja do programowania lokalnego. Na tej stronie opisano zagadnienia dotyczące zabezpieczeń i najlepsze rozwiązania, jeśli musisz uwidocznić interfejs DevUI poza hostem lokalnym.

Ostrzeżenie

Interfejs DevUI nie jest przeznaczony do użytku produkcyjnego. W przypadku wdrożeń produkcyjnych utwórz własny interfejs niestandardowy przy użyciu zestawu SDK platformy Agent z odpowiednimi środkami zabezpieczeń.

Wkrótce

Dokumentacja usługi DevUI dla języka C# jest dostępna wkrótce. Sprawdź ponownie później lub przejrzyj dokumentację języka Python, aby uzyskać wskazówki koncepcyjne.

Tryby interfejsu użytkownika

Interfejs DevUI oferuje dwa tryby kontrolujące dostęp do funkcji:

Tryb dewelopera (ustawienie domyślne)

Pełny dostęp do wszystkich funkcji:

  • Panel debugowania z informacjami o śledzeniu
  • Gorące przeładowywanie dla szybkiego rozwoju (/v1/entities/{id}/reload)
  • Narzędzia wdrażania (/v1/deployments)
  • Pełne komunikaty o błędach na potrzeby debugowania
devui ./agents  # Developer mode is the default

Tryb użytkownika

Uproszczony, ograniczony interfejs:

  • Interfejs czatu i zarządzanie konwersacjami
  • Lista jednostek i podstawowe informacje
  • Interfejsy API dla programistów są wyłączone (ponowne ładowanie, wdrażanie)
  • Ogólne komunikaty o błędach (szczegóły rejestrowane po stronie serwera)
devui ./agents --mode user

Authentication

Włącz uwierzytelnianie tokenu elementu nośnego z flagą --auth :

devui ./agents --auth

Po włączeniu uwierzytelniania:

  • W przypadku hosta lokalnego: token jest generowany automatycznie i wyświetlany w konsoli programu
  • W przypadku wdrożeń narażonych na dostęp z sieci : należy podać token za pomocą DEVUI_AUTH_TOKEN zmiennej środowiskowej lub --auth-token flagi
# Auto-generated token (localhost only)
devui ./agents --auth

# Custom token via CLI
devui ./agents --auth --auth-token "your-secure-token"

# Custom token via environment variable
export DEVUI_AUTH_TOKEN="your-secure-token"
devui ./agents --auth --host 0.0.0.0

Wszystkie żądania interfejsu API muszą zawierać prawidłowy Bearer token w nagłówku Authorization :

curl http://localhost:8080/v1/entities \
  -H "Authorization: Bearer your-token-here"

Jeśli musisz uwidocznić interfejs DevUI użytkownikom końcowym (niezalecane w środowisku produkcyjnym):

devui ./agents --mode user --auth --host 0.0.0.0

Ta konfiguracja:

  • Ogranicza interfejsy API dostępne dla deweloperów
  • Wymaga uwierzytelnienia
  • Wiąże się ze wszystkimi interfejsami sieciowymi

Funkcje zabezpieczeń

Interfejs DevUI obejmuje kilka środków zabezpieczeń:

Funkcja Opis
Powiązanie hosta lokalnego Domyślnie wiąże się z 127.0.0.1
Tryb użytkownika Ogranicza API programistyczne
Uwierzytelnianie elementu nośnego Opcjonalne uwierzytelnianie oparte na tokenach
Ładowanie jednostek lokalnych Ładuje tylko jednostki z katalogów lokalnych lub w pamięci
Brak zdalnego wykonywania Brak możliwości zdalnego wykonywania kodu

Najlepsze praktyki

Zarządzanie poświadczeniami

  • Przechowywanie kluczy interfejsu API i sekretów w plikach .env
  • Nigdy nie zatwierdzaj .env plików do kontroli źródła
  • Używanie .env.example plików do dokumentowania wymaganych zmiennych
# .env.example (safe to commit)
OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

# .env (never commit)
OPENAI_API_KEY=sk-actual-key
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/

Bezpieczeństwo sieci

  • Zachowaj powiązanie interfejsu DevUI z hostem lokalnym na potrzeby programowania
  • Użyj zwrotnego serwera proxy (nginx, Caddy), jeśli wymagany jest dostęp zewnętrzny
  • Włączanie protokołu HTTPS za pośrednictwem zwrotnego serwera proxy
  • Implementowanie prawidłowego uwierzytelniania na poziomie serwera proxy

Zabezpieczenia jednostek

  • Przed uruchomieniem przejrzyj cały kod agenta/przepływu pracy
  • Wczytuj tylko jednostki z zaufanych źródeł
  • Należy zachować ostrożność przy użyciu narzędzi, które mają skutki uboczne (dostęp do plików, wywołania sieciowe)

Oczyszczanie zasobów

Zarejestruj hooki czyszczące, aby prawidłowo zamknąć poświadczenia i zasoby w trakcie wyłączania systemu.

from azure.identity.aio import DefaultAzureCredential
from agent_framework import Agent
from agent_framework.azure import AzureOpenAIChatClient
from agent_framework_devui import register_cleanup, serve

credential = DefaultAzureCredential()
client = AzureOpenAIChatClient()
agent = Agent(name="MyAgent", chat_client=client)

# Register cleanup hook - credential will be closed on shutdown
register_cleanup(agent, credential.close)
serve(entities=[agent])

Zagadnienia dotyczące narzędzi MCP

W przypadku korzystania z narzędzi MCP (Model Context Protocol) z interfejsem DevUI:

# Correct - DevUI handles cleanup automatically
mcp_tool = MCPStreamableHTTPTool(url="http://localhost:8011/mcp", chat_client=chat_client)
agent = Agent(tools=mcp_tool)
serve(entities=[agent])

Ważne

Nie używaj async with menedżerów kontekstu podczas tworzenia agentów za pomocą narzędzi MCP dla devUI. Połączenia zostaną zamknięte przed wykonaniem. Narzędzia MCP używają inicjowania z opóźnieniem i łączą się automatycznie podczas pierwszego użycia.

Dalsze kroki

  • Last updated on