Rozwiązywanie problemów

Zacznij od logu usługi, która pokazuje objaw: docker compose logs <usługa>. Dla serwera uruchom to samo polecenie w jego katalogu deploy/.

Instalacja i start

Objaw	Przyczyna	Rozwiązanie
docker compose kończy się komunikatem set MCP_DOMAIN in .env (lub required variable MCP_DOMAIN is missing a value)	Brak .env albo brak MCP_DOMAIN w nim	Skopiuj platform.env do .env i ustaw MCP_DOMAIN. Jeśli .env zapisałeś przez echo, sprawdź go poleceniem tail .env, czy nie ma przerwanej linii.
init zatrzymuje start i podaje powód w docker compose logs init	Certyfikat nie zawiera domeny, klucz do niego nie pasuje albo łańcuch nie weryfikuje się względem certs/company-ca.crt lub publicznego CA	Popraw certs/ zgodnie z komunikatem i uruchom docker compose up -d.
gateway-init wypisuje warn broker ...: connection refused	Broker jeszcze startuje. To normalne przy pierwszym starcie.	Poczekaj kilka minut.
Po docker compose restart gateway-init zgłasza błąd, ale platforma działa	restart uruchamia jednorazowy gateway-init jednocześnie z Keycloakiem	Uruchom docker compose up -d. Uruchomi gateway-init ponownie, w kolejności.
docker compose logs init kończy się warn certificates or trust stores changed	init wymienił certyfikat lub magazyn zaufania w działającej instalacji	Wykonaj polecenie docker compose restart ..., które podaje ostrzeżenie.
nginx nie startuje, keycloak-config zakończył się błędem	Administrator startowy realmu master miał już OTP, zanim keycloak-config ruszył, więc jednorazowa konfiguracja nie mogła się zalogować	Uruchom samego nginx: docker compose up -d --no-deps nginx, wykonaj ręcznie w konsolach Keycloaka kroki z keycloak/configure.sh (OTP dla każdego administratora realmu master, polityka haseł, wykrywanie ataków siłowych, role klienta dla mcp-platform-admin), potem uruchom docker compose run --rm keycloak-config mark-done. Zobacz README mcp-platform, sekcja “Install”.
Przekierowanie z portu 80 lub adresy z platformy tracą port	https działa na porcie innym niż 443, a MCP_PUBLIC_ORIGIN nie jest ustawione	Ustaw MCP_PUBLIC_ORIGIN=https://<domena>:<port> i uruchom docker compose up -d.
Usługi Redis gatewaya nie czytają swoich plików	Obraz gatewaya zbudowano przed ustaleniem identyfikatora grupy i działa z gid 999	Użyj obrazu gatewaya z ghcr.io/aiwcorpo w wersji, którą wskazuje pakiet.
Compose próbuje pobierać obrazy firm trzecich na hoście offline	Docker Engine z klasycznym magazynem obrazów nie zachowuje skrótów rejestru dla załadowanych obrazów	Dodaj compose.offline.yaml do COMPOSE_FILE i ustaw PULL_POLICY=never (instalacja offline).
Skrypty powłoki z pakietu nie działają na Windows	Edytor lub rozpakowywacz zamienił końce linii na CRLF	Rozpakuj od nowa i zachowaj końce linii LF.
Broker nie startuje po usunięciu openbao-keys z hosta	OpenBao jest zapieczętowany, dopóki ktoś go nie odpieczętuje	Odpieczętuj przez bao operator unseal (Kopia zapasowa).

Logowanie i klienci AI

Objaw	Przyczyna	Rozwiązanie
Claude Code pokazuje serwer jako połączony, bez możliwości i bez narzędzi	Gateway 2.0.0 nie zwraca ttlMs i cacheScope na liście narzędzi dla MCP 2026-07-28 (issue 1)	Zaktualizuj gateway do 2.0.1 (Aktualizacja).
Claude Code: ERR_CONNECTION_REFUSED na localhost:33418 (konfiguracja lokalna)	Claude Code nie ufa lokalnemu CA	Ustaw NODE_EXTRA_CA_CERTS na plik CA w tej samej powłoce i zaloguj się ponownie.
Przeglądarka ostrzega o certyfikacie (konfiguracja lokalna)	System nie ufa lokalnemu CA	Dodaj CA do magazynu certyfikatów systemu (Instalacja lokalna).
Akcja administracyjna odpowiada step_up_required	Logowanie jest starsze niż 5 minut albo nie ma drugiego składnika	Zaloguj się ponownie z OTP.

Serwery MCP

Objaw	Przyczyna	Rozwiązanie
Serwer zatrzymuje się przy starcie: nie może pobrać kluczy	Host serwera nie rozwiązuje <platforma> albo nie ufa jej certyfikatowi	Popraw DNS. Jeśli certyfikat platformy podpisało firmowe CA, dodaj je do magazynu zaufania serwera i odkomentuj JAVA_TOOL_OPTIONS (Instalacja serwera MCP).
Dodawanie serwera: tls_handshake_failed lub manifest_unreachable	Serwer nie działa albo port 8443 jest zamknięty między hostem platformy a hostem serwera	Sprawdź docker compose ps na hoście serwera i otwórz port dla hosta platformy.
Dodawanie serwera: plain_http_not_allowed	Adres http:// bez zaznaczonego “allow plain http”	Zaznacz tylko dla serwerów w sieci Dockera platformy. Dla serwerów gdzie indziej użyj https.
Dodawanie serwera: adres odrzucony	Rozwiązuje się na adres pętli zwrotnej, link-local (także 169.254.169.254), nieokreślony lub multicast	Użyj prawdziwego adresu serwera. Test lokalny: host.docker.internal (Instalacja lokalna).
Status serwera certificate_changed	Przypięty serwer przedstawił nowy certyfikat, na przykład po odtworzeniu wolumenu state	Porównaj nowy odcisk i zatwierdź go w portalu.
Wywołanie narzędzia: upstream_unavailable, w logu serwera SSLHandshakeException	Magazyn zaufania serwera nie ma CA systemu docelowego albo JAVA_TOOL_OPTIONS jest zakomentowane	Zaimportuj CA, potem docker compose up -d --force-recreate na hoście serwera.
Wywołanie narzędzia: upstream_unavailable, status serwera unreachable	Serwer nie odpowiada pod swoim adresem	Sprawdź adres, port i log serwera.
Brakuje narzędzi serwera, jego polityki są pending_approval	Nowa lub zmieniona polityka czeka na zatwierdzenie	Zatwierdź ją w Administracji (Serwery).
Zapis tokenu w portalu: “usługa jest chwilowo niedostępna”	Broker nie ufa CA systemu	Dopisz to CA do certs/company-ca.crt, uruchom docker compose up -d, potem polecenie restartu z docker compose logs init | grep warn.
Konfiguracja lokalna: serwer nie pobiera kluczy	W compose.override.yaml brak extra_hosts dla mcp.localhost, magazyn zaufania nie ma lokalnego CA albo JAVA_TOOL_OPTIONS jest zakomentowane	Powtórz kroki 3.2 do 3.4 z Instalacji lokalnej.
Konfiguracja lokalna na Linuksie: gateway nie widzi host.docker.internal	Nazwa nie jest zdefiniowana na Linuksie	Dodaj extra_hosts: ["host.docker.internal:host-gateway"] dla usługi gateway.

Problemy właściwe dla jednego serwera (ograniczenia wersji Jiry i Confluence, role OpenSearch, układ service desk) są w sekcji “Common problems” jego deploy README, do którego prowadzi Instalacja serwera MCP.