Dokumentacja konfiguracji

Usługi

Uruchomienie instancji Private Channels oznacza zarządzanie następującymi usługami Docker Compose:

Kontener	Rola
`private-channel-postgres-primary`	Baza danych stanu węzła zapisu (PostgreSQL 16)
`private-channel-postgres-replica`	Baza danych stanu węzła odczytu (replika strumieniowa)
`private-channel-postgres-indexer`	Baza danych indeksera i operatora
`private-channel-write-node`	Odbiera i wykonuje transakcje (port 8900, tylko pętla zwrotna)
`private-channel-read-node`	Obsługuje zapytania odczytu RPC (port 8901, tylko pętla zwrotna)
`private-channel-gateway`	Kieruje żądania między węzłami zapisu i odczytu; egzekwuje RBAC (port 8899)
`private-channel-indexer-solana`	Monitoruje Solana pod kątem zdarzeń `Deposit` za pośrednictwem Yellowstone gRPC
`private-channel-indexer-private-channel`	Monitoruje kanał pod kątem zdarzeń `Burn` poprzez odpytywanie RPC
`private-channel-operator-solana`	Mintuje tokeny kanału po potwierdzeniu depozytów
`private-channel-operator-private-channel`	Wywołuje `ReleaseFunds` na Mainnecie po potwierdzeniu wypłat
`private-channel-auth`	Opcjonalna usługa JWT/RBAC (profil Docker: `auth`)

Kontenery obserwacyjne (prometheus, grafana, cadvisor) są również uwzględnione.

Gateway

Poniższe wartości mają rozsądne ustawienia domyślne dla konfiguracji Docker Compose w sieci devnet. Nadpisuj je tylko wtedy, gdy uruchamiasz bramę poza Dockerem lub wdrażasz na produkcję.

Zmienna środowiskowa	Domyślna	Wymagana	Opis
`GATEWAY_PORT`	`8899` (devnet)	Nie	Port nasłuchu
`GATEWAY_WRITE_URL`	`http://write-node:8900` (wartość z pliku env devnet; brak domyślnej wartości binarnej)	Tak	URL węzła zapisu – żądania `sendTransaction` są tu kierowane
`GATEWAY_READ_URL`	`http://read-node:8901` (wartość z pliku env devnet; brak domyślnej wartości binarnej)	Tak	URL węzła odczytu – wszystkie pozostałe metody RPC są tu kierowane
`GATEWAY_CORS_ALLOWED_ORIGIN`	`*`	Nie	Wartość nagłówka `Access-Control-Allow-Origin`
`JWT_SECRET`	-	Nie	Włącza RBAC; musi być zgodny z `JWT_SECRET` usługi auth
`AUTH_DATABASE_URL`	-	Jeśli ustawiono `JWT_SECRET`	Baza danych auth do weryfikacji własności portfela
`AUTH_DATABASE_MAX_CONNECTIONS`	`10`	Nie	Rozmiar puli połączeń bazy danych auth
`METRICS_PORT`	`9101`	Nie	Port metryk Prometheus
`RUST_LOG`	`info`	Nie	Poziom logowania

GATEWAY_WRITE_URL i GATEWAY_READ_URL używają nazw hostów usług Docker Compose (write-node, read-node) podczas działania w Dockerze. Używaj odpowiedników localhost tylko wtedy, gdy uruchamiasz binarkę bramy bezpośrednio poza Dockerem.

Wbudowana domyślna wartość binarki bramy dla GATEWAY_PORT to 8898. Zarówno .env.example, jak i .env.devnet ustawiają ją na 8899, co jest wartością faktycznie używaną przez konfigurację Docker Compose (plik versions.env zawiera wyłącznie wersje łańcucha narzędzi i obrazów, nie porty usług). Domyślna wartość 8898 ma zastosowanie tylko wtedy, gdy uruchamiasz binarkę bezpośrednio bez pliku env.

GATEWAY_CORS_ALLOWED_ORIGIN domyślnie przyjmuje wartość *, co pozwala każdemu źródłu wywoływać bramę z przeglądarki. Ogranicz tę wartość do rzeczywistego źródła swojej aplikacji przed jakimkolwiek wdrożeniem produkcyjnym.

Węzeł zapisu i węzeł odczytu

Pełna dokumentacja konfiguracji węzła zapisu i węzła odczytu znajduje się w docs/CONFIG.md w repozytorium.

Usługa Auth

Zmienna środowiskowa	Wymagana	Opis
`JWT_SECRET`	Tak	Klucz podpisujący HS256; musi być zgodny z `JWT_SECRET` bramy
`AUTH_PORT`	Nie (domyślnie `8903`)	Port nasłuchu
`AUTH_DATABASE_URL`	Tak	Ciąg połączenia PostgreSQL dla bazy danych auth
`CORS_ALLOWED_ORIGIN`	Nie (domyślnie `*`)	Wartość nagłówka `Access-Control-Allow-Origin` dla tej usługi (niezależna od `GATEWAY_CORS_ALLOWED_ORIGIN` bramy)
`AUTH_DATABASE_MAX_CONNECTIONS`	Nie (domyślnie `10`)	Rozmiar puli połączeń bazy danych auth

Dokumentacja portów usług

Usługa	Port hosta	Powiązanie
Gateway	8899	Wszystkie interfejsy
Węzeł zapisu	8900	Tylko pętla zwrotna
Węzeł odczytu	8901	Tylko pętla zwrotna
Streamer	8902	Tylko wewnętrzny (`expose`, niepublikowany do hosta); nie jest częścią stosu devnet
Usługa Auth	8903	Wszystkie interfejsy
Metryki operatora	9102, 9103	Wszystkie interfejsy
Grafana	37429	Wszystkie interfejsy
Prometheus	9090	Wszystkie interfejsy
cAdvisor	8080	Wszystkie interfejsy

Uwaga dotycząca bezpieczeństwa: Porty węzła zapisu i węzła odczytu są powiązane wyłącznie z pętlą zwrotną (127.0.0.1). Gateway, usługa Auth, metryki operatora, Grafana, Prometheus i cAdvisor są publikowane na każdym interfejsie sieciowym w konfiguracji Docker Compose devnet. Zabezpiecz je zaporą na poziomie hosta lub sieci dla wszystkich środowisk wykraczających poza lokalne środowisko deweloperskie; RBAC obejmuje wyłącznie własne metody JSON-RPC bramy, a nie te pozostałe usługi. Wyjątkiem jest Streamer: jest to nieuwierzytelniony wewnętrzny strumień danych, który Docker nigdy nie publikuje do hosta.

Wymagania sieciowe

Zasady zapory ogniowej i wymagania dotyczące przepustowości znajdziesz w docs/TECHNICAL_REQUIREMENTS.md w repozytorium.