Narzędzia do diagramów self-hosted: porównanie

Które narzędzie do tworzenia diagramów typu self-hosted wybrać?

Narzędzia do tworzenia diagramów typu self-hosted występują w dwóch wariantach, a ich architektura jest ważniejsza niż lista funkcji. draw.io oraz Excalidraw to aplikacje przeglądarkowe: kontener dostarcza kod JavaScript, przeglądarka wykonuje rysowanie, a serwer nigdy nie przetwarza treści diagramu. Kroki działa odwrotnie. Użytkownik przesyła tekst diagramu przez HTTP, a serwer odsyła gotowy obraz, co oznacza, że każdy diagram przechodzi przez własną infrastrukturę.

Wybierz draw.io, jeśli potrzebujesz pełnego edytora zintegrowanego z wiki. Wybierz Excalidraw, jeśli potrzebujesz szybkiego szkicownika i akceptujesz fakt, że dane nie są zapisywane poza przeglądarką, w której powstał rysunek. Wybierz Kroki, jeśli diagramy są zapisane w formie tekstowej i przechowywane w repozytorium git obok opisywanego kodu.

Co faktycznie zmienia samodzielne hostowanie narzędzia do tworzenia diagramów

Należy precyzyjnie określić, które elementy mają styczność z serwerem, ponieważ ten fakt decyduje o tym, czy samodzielne hostowanie zapewnia prywatność, czy jedynie dostępność.

• draw.io renderuje w przeglądarce. Kontener serwuje kod aplikacji. Plik trafia tam, gdzie użytkownik wskaże edytorowi miejsce zapisu.
• Excalidraw renderuje w przeglądarce i przechowuje bieżącą scenę w pamięci lokalnej przeglądarki. Po stronie serwera nie są zapisywane żadne dane.
• Kroki renderuje po stronie serwera. Zarówno źródło diagramu, jak i gotowy obraz znajdują się wewnątrz kontenera.

Tylko w trzecim przypadku dane trafiają na sprzęt, nad którym sprawowana jest kontrola. W dwóch pierwszych przypadkach samodzielne hostowanie zapewnia kontrolę nad zasobami i dostępność: kod JavaScript pochodzi z własnego hosta, więc edytor działa nawet wtedy, gdy zewnętrzny dostawca ma awarię, zmienia regulamin lub staje się niedostępny z danej sieci. Dla niektórych zespołów ma to wymierną wartość. Jest to jednak inne założenie niż stwierdzenie, że "diagram nigdy nie opuszcza budynku".

draw.io: oficjalny kontener, który niczego nie przechowuje

Projekt publikuje własny obraz, a szybki start opisany w pliku README sprowadza się do jednej linii.

docker run -it --rm --name="draw" -p 8080:8080 -p 8443:8443 jgraph/drawio

To polecenie udostępnia edytor na każdym adresie IP przypisanym do serwera. Na serwerze VPS należy powiązać publikowany port z interfejsem loopback i uzyskiwać do niego dostęp przez reverse proxy lub tunel SSH.

docker run -d --name drawio --restart unless-stopped -p 127.0.0.1:8080:8080 jgraph/drawio

Otwórz http://127.0.0.1:8080/?offline=1&https=0 przez tunel. Plik README określa ?offline=1 jako „funkcję bezpieczeństwa wyłączającą obsługę pamięci masowej w chmurze”. Bez niej edytor oferuje Google Drive, OneDrive oraz GitHub jako miejsca zapisu, co oznacza serwery podmiotów zewnętrznych.

Powiązanie z 127.0.0.1 chroni port przed dostępem z publicznego Internetu. Zwykłe -p 8080:8080 nie jest filtrowane przez ufw, ponieważ Docker wstawia własne reguły iptables przed łańcuchy zarządzane przez ufw. W rezultacie firewall wydaje się poprawnie skonfigurowany, podczas gdy port odpowiada na zapytania z zewnątrz. Publikowanie portów przez Docker z pominięciem ufw opisuje ten mechanizm oraz sposób naprawy.

Dwie zmienne środowiskowe mają znaczenie, gdy edytor nie działa na localhost.

services:
  drawio:
    image: jgraph/drawio
    container_name: drawio
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      DRAWIO_SERVER_URL: "https://drawio.example.com/"
      DRAWIO_BASE_URL: "https://drawio.example.com"

Końcowy ukośnik nie jest błędem. Plik README definiuje DRAWIO_SERVER_URL jako „Publiczny adres URL wdrożenia z końcowym ukośnikiem”, a DRAWIO_BASE_URL jako „Ten sam adres URL bez końcowego ukośnika”, używany przez przeglądarkę, lightbox oraz ścieżki kodu osadzonego. Jeśli edytor jest udostępniany w podkatalogu, takim jak https://www.example.com/drawio/, obie wartości muszą zawierać tę ścieżkę, ponieważ aplikacja buduje na ich podstawie adresy URL przeglądarki i osadzania.

Trwałość danych: brak, zgodnie z założeniami projektu. W pliku Compose nie zdefiniowano żadnego wolumenu, ponieważ kontener nie przechowuje danych diagramów. Plik .drawio to kod XML, który edytor przekazuje do przeglądarki, a wybrany cel zapisu decyduje o jego lokalizacji: pobranie na komputer użytkownika lub aplikacja, w której osadzono edytor. Należy tworzyć kopie zapasowe tego miejsca docelowego. Jeśli jest nim folder na serwerze VPS, ochronie podlega ten folder oraz menedżer plików używany do uzyskania do niego dostępu, ponieważ draw.io nie przechowuje żadnych kopii.

Co nadal opuszcza serwer. Eksport do PDF jest najbardziej oczywistym przykładem. Plik README opisuje DRAWIO_SELF_CONTAINED jako „Ustawienie na 1 w celu kierowania żądań eksportu przez ExportProxyServlet (/service/0) serwera Tomcat zamiast bezpośredniego wywoływania serwera eksportu”. Należy to rozumieć odwrotnie: domyślnie żądanie eksportu nie pozostaje wewnątrz wdrożenia. Projekt publikuje również jgraph/export-server, „samodzielny serwer eksportu obrazów draw.io”, dla użytkowników wymagających renderowania na własnym sprzęcie. ENABLE_DRAWIO_PROXY jest domyślnie wyłączone i aktywuje punkt końcowy /proxy, który pobiera zewnętrzne adresy URL obrazów w imieniu przeglądarki, więc należy pozostawić tę opcję wyłączoną, chyba że jest niezbędna.

Excalidraw: statyczny pakiet bez backendu

Oficjalna strona obrazu podaje następujące polecenie.

docker run --rm -dit --name excalidraw -p 5000:80 excalidraw/excalidraw:latest

Przenieś opublikowany port na interfejs loopback z tego samego powodu, co poprzednio.

docker run -d --name excalidraw --restart unless-stopped -p 127.0.0.1:5000:80 excalidraw/excalidraw:latest

Wewnątrz kontenera nginx serwuje skompilowany pakiet JavaScript na porcie 80. Opublikowany obraz zajmuje około 41 MB po kompresji (Docker Hub, sierpień 2026), co wskazuje na jego minimalną zawartość. Brak bazy danych, magazynu sesji czy katalogu przesyłania plików, ponieważ na serwerze nie ma żadnych danych do przechowywania.

Strona obrazu jasno określa ograniczenie: „W tej chwili samodzielne hostowanie własnej instancji nie wspiera funkcji udostępniania ani współpracy”. Przyciski nadal są widoczne w interfejsie, dlatego warto znać przyczynę. Współpraca w czasie rzeczywistym wymaga serwera websocket, publikowanego oddzielnie jako excalidraw/excalidraw-room. Link do udostępniania wymaga usługi magazynowania, która przechowa zaszyfrowaną scenę. Adresy obu tych elementów są kompilowane do pakietu na etapie budowania jako zmienne Vite (VITE_APP_WS_SERVER_URL, VITE_APP_BACKEND_V2_GET_URL, VITE_APP_BACKEND_V2_POST_URL), a wartości produkcyjne w repozytorium wskazują na własne usługi hostowane przez Excalidraw. Vite podstawia te wartości podczas budowania, więc stają się one dosłownymi ciągami znaków wewnątrz kodu JavaScript. Ustawienie ich jako zmiennych środowiskowych kontenera nic nie zmienia, ponieważ żaden kod nie odczytuje ich w czasie wykonywania. Skierowanie współpracy na własny serwer pokoi oznacza konieczność zbudowania frontendu ze źródeł z własnymi wartościami. Sprawdź stan tego serwera, zanim zaczniesz planować jego użycie: obraz excalidraw/excalidraw-room w serwisie Docker Hub nie był przebudowywany od ponad dwóch lat (stan na sierpień 2026).

Gdzie faktycznie znajduje się rysunek. Scena znajduje się w pamięci lokalnej przeglądarki (local storage), na danym urządzeniu, dla danego źródła (origin). Otwórz ten sam adres URL w oknie prywatnym, a płótno będzie puste – to najszybszy sposób, aby się o tym przekonać. Wyczyśczenie danych witryny usuwa rysunek, a brak kopii serwerowej uniemożliwia jego przywrócenie. Dlatego należy instruować użytkowników, aby korzystali z funkcji „Save to...” i przechowywali plik .excalidraw, który jest formatem JSON, w miejscu objętym kopią zapasową. Współdzielona instancja zapewnia każdej osobie własne, prywatne płótno. Należy traktować ją jako osobisty szkicownik, który jest jedynie hostowany na serwerze.

Kroki: diagramy jako kod, renderowane na własnym serwerze

Kroki to bramka HTTP obsługująca wiele silników renderujących. Wysyłasz tekst metodą POST i otrzymujesz w odpowiedzi plik SVG lub PNG. Graphviz, PlantUML, D2 oraz kilka innych narzędzi są wbudowane w obraz bramki. Renderowanie Mermaid, BPMN i Excalidraw odbywa się w osobnych kontenerach, dlatego użycie Compose jest najbardziej uzasadnionym sposobem uruchomienia tego rozwiązania. Poniżej znajduje się przykład z dokumentacji Kroki.

services:
  kroki:
    image: yuzutech/kroki
    depends_on:
      - mermaid
      - bpmn
      - excalidraw
    environment:
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "8000:8000"
    tmpfs:
      - /tmp:exec
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw
    expose:
      - "8004"

expose nie publikuje żadnych portów na hoście, dzięki czemu kontenery towarzyszące są dostępne wyłącznie dla bramki wewnątrz sieci Compose. Jest to pożądane zachowanie. Zmień linię bramki na "127.0.0.1:8000:8000", chyba że wiki korzystająca z usługi działa na innym hoście. Jeśli nie tworzyłeś wcześniej pliku Compose na serwerze, uruchamianie Docker Compose na VPS opisuje strukturę plików oraz cykl docker compose up -d.

Wykonaj dwa testy poprawności w podanej kolejności, ponieważ ich ewentualne niepowodzenia wynikają z różnych przyczyn.

curl -s -X POST http://127.0.0.1:8000/graphviz/svg \
  -H 'Content-Type: text/plain' \
  --data-binary 'digraph G {Hello->World}' | head -c 60

Graphviz działa wewnątrz bramki, więc wygenerowanie dokumentu SVG potwierdza poprawność działania samej bramki. Następnie przetestuj ścieżkę komunikacji między kontenerami.

curl -s -X POST http://127.0.0.1:8000/mermaid/svg \
  -H 'Content-Type: text/plain' \
  --data-binary 'graph TD; A-->B;' | head -c 60

Plik SVG uzyskany z drugiego polecenia potwierdza, że KROKI_MERMAID_HOST zostało poprawnie rozwiązane, a kontener towarzyszący odpowiedział. Jeśli pierwszy test kończy się powodzeniem, a drugi nie, problem leży w komunikacji między kontenerami; przed modyfikacją składni diagramu zapoznaj się z docker compose logs kroki.

Formularz GET koduje diagram bezpośrednio w adresie URL, co pozwala na osadzanie obrazów w wiki bez użycia wtyczek. Dokumentacja zawiera odpowiedni enkoder.

cat hello.dot | python -c "import sys; import base64; import zlib; print(base64.urlsafe_b64encode(zlib.compress(sys.stdin.read().encode('utf-8'), 9)).decode('ascii'))"

W systemie Ubuntu polecenie to zwraca python: command not found, ponieważ system dostarcza python3 i nie zawiera niewersjonowanego python. Użyj python3. Wynik należy dodać na końcu adresu URL w formacie /{diagram-type}/{output-format}/{encoded-diagram}, co pozwala na użycie dowolnego znacznika <img>. Istnieje ograniczenie: KROKI_MAX_URI_LENGTH domyślnie wynosi 4096 bajtów, więc długie diagramy muszą być przesyłane metodą POST.

Kroki przetwarza przesłany tekst, dlatego kluczowe są ustawienia bezpieczeństwa. KROKI_SAFE_MODE domyślnie przyjmuje wartość SECURE, co jest najbardziej restrykcyjnym z trzech poziomów, a KROKI_PLANTUML_ALLOW_INCLUDE domyślnie ustawiono na false. Te wartości domyślne wynikają z faktu, że dyrektywa !include w PlantUML odczytuje pliki i adresy URL z perspektywy silnika renderującego. Złagodzenie tych ustawień w publicznie dostępnym punkcie końcowym umożliwia użytkownikom zewnętrznym odczyt plików z wnętrza kontenera. Nie zmieniaj tych ustawień, chyba że znasz konkretną ścieżkę dostępu, którą należy uwzględnić, a następnie wskaż ją za pomocą KROKI_PLANTUML_INCLUDE_PATH.

Pamięć: co najbardziej obciąża mały VPS

Kolejność jest przewidywalna, gdy wiadomo, co uruchamia każdy kontener.

• Obraz Excalidraw to nginx serwujący pliki statyczne. Jest to zdecydowanie najtańszy z tych trzech komponentów.
• draw.io uruchamia Tomcat, serwer aplikacji Java, więc zawiera JVM (Java virtual machine), niezależnie od tego, czy ktoś aktualnie rysuje.
• Bramka Kroki to również usługa Java, dostarczana jako plik jar w przypadku instalacji ręcznych.
• Komponent mermaid jest najbardziej kosztowny. Jego Dockerfile instaluje Chromium i ustawia PUPPETEER_EXECUTABLE_PATH=/usr/lib/chromium/chrome, ponieważ Mermaid renderuje diagramy w rzeczywistym silniku przeglądarki.

Wartości w stanie spoczynku mówią zatem niewiele. Kluczową liczbą jest skok zużycia podczas renderowania diagramu, a KROKI_MERMAID_MAX_CONCURRENCY domyślnie wynosi 6, co oznacza, że jednocześnie może być przetwarzanych sześć procesów renderowania w przeglądarce. Należy dokonać pomiaru na własnym serwerze, zamiast polegać na publikowanych danych.

docker stats --no-stream
docker system df

Uruchom pierwsze polecenie, gdy system jest w stanie spoczynku, a następnie ponownie podczas renderowania dużego diagramu mermaid w pętli. Jeśli skok zużycia jest zbyt duży dla małego planu, należy nałożyć limity, zamiast zgadywać: ustawianie limitów pamięci dla usługi Compose pokazuje składnię oraz zachowanie kontenera po osiągnięciu limitu. Rezygnacja z komponentu mermaid jest również poprawnym rozwiązaniem, ponieważ bramka nadal obsługuje wszystkie wbudowane w nią mechanizmy renderowania.

Żaden z tych programów nie zawiera modelu użytkownika, więc należy go dodać przed nimi

draw.io nie posiada kont. Excalidraw nie posiada kont. Kroki odpowiada na każde żądanie, które do niego dotrze. Każdy mechanizm logowania musi zostać zaimplementowany na poziomie proxy.

sudo apt update && sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd alice

htpasswd -c tworzy plik i nadpisuje istniejący, dlatego przy pierwszym uruchomieniu należy przekazać -c, a później już nigdy więcej.

server {
    listen 443 ssl;
    server_name drawio.example.com;

    location / {
        auth_basic "diagrams";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Zastosuj konfigurację za pomocą sudo nginx -t && sudo systemctl reload nginx. Kluczowa jest część nginx -t: przeładowanie przy błędnej konfiguracji pozostawia aktywną starą wersję, dzięki czemu serwis nadal działa, a wprowadzone zmiany nie wchodzą w życie. Konfiguracja reverse proxy, wyjaśniona linia po linii omawia blok nagłówków oraz ścieżki certyfikatów, które pominięto w tym fragmencie.

Uwierzytelnianie podstawowe (Basic Auth) jest niewłaściwym narzędziem dla Kroki i warto zrozumieć dlaczego. Strona wiki osadza obraz Kroki za pomocą znacznika <img>. Przeglądarka czytelnika pobiera ten adres URL jako zasób podrzędny i nie wysyła poświadczeń do innego źródła (origin), przez co żądanie kończy się błędem 401, a każdy diagram na stronie wyświetla się jako uszkodzony obraz. Zamiast tego należy odizolować Kroki od publicznego Internetu. Umieść usługę w tej samej sieci Docker co kontener z wiki i pozwól wiki łączyć się z nią za pomocą nazwy usługi, nie publikując żadnych portów na hoście. Jak sieci Compose rozwiązują nazwy usług to element, który umożliwia takie działanie.

Diagramy przechowywane obok wiki hostowanego samodzielnie

Jest to najczęstszy powód, dla którego użytkownicy decydują się na takie rozwiązanie. Strona wiki wymaga ilustracji, a nikt nie chce, aby była ona zrzutem ekranu z czyjegoś laptopa.

BookStack posiada wbudowany mechanizm integracji z edytorem hostowanym samodzielnie. Domyślny adres URL osadzania to https://embed.diagrams.net/?embed=1&proto=json&spin=1&configure=1, a jedna linia w .env pozwala na przekierowanie go do własnego kontenera.

DRAWIO=https://drawio.example.com/?embed=1&proto=json&spin=1&configure=1

Należy dokładnie skopiować ciąg zapytania. Dokumentacja BookStack podaje, że embed=1&proto=json&spin=1 „są wymagane do poprawnego działania integracji z BookStack”, ponieważ określają protokół komunikatów JSON, za pomocą którego obie strony wymieniają dane. Ta sama strona wskazuje na stealth=1 „jeśli nie chcesz korzystać z zewnętrznych usług”, co jest opcją wybieraną w przypadku, gdy celem hostowania samodzielnego było zablokowanie połączeń wychodzących. Po skonfigurowaniu tego połączenia, BookStack zapisuje rysunek w swoim własnym magazynie obrazów obok strony, dzięki czemu kopia zapasowa wiki zawiera również kopie diagramów.

Jeśli wybór oprogramowania wiki nie został jeszcze dokonany, należy zacząć od tego kroku. Wybór między BookStack, Wiki.js a Outline to wcześniejsza decyzja, ponieważ to wiki determinuje sposób dołączania diagramu do strony, a tym samym wskazuje, które z tych narzędzi należy zintegrować.

Tryby awarii i komunikaty, które zobaczysz

Edytor rysunków w BookStack otwiera się i wyświetla nieskończone ładowanie. Wskaźnik ładowania spin=1 oczekuje na uzgodnienie połączenia, które nie nadchodzi. Sprawdź, czy embed=1&proto=json&spin=1 znajduje się w wartości DRAWIO oraz czy w nazwie hosta nie ma literówki.

Ramka edytora pozostaje pusta w wiki działającym przez HTTPS. Konsola przeglądarki zgłasza błąd treści mieszanej (mixed content), próbując załadować http:// wewnątrz https://. Przeglądarka blokuje ramkę, przez co draw.io nie uruchamia się. Udostępnij edytor przez HTTPS.

Kroki zwraca 413 Request Entity Too Large. Ten komunikat pochodzi z nginx, a nie z Kroki. Domyślny limit client_max_body_size w nginx wynosi 1 MB, a domyślny limit KROKI_MAX_BODY_SIZE w samym Kroki to 1mb, więc duże źródło PlantUML napotyka na niższy z tych limitów. Zwiększ obie wartości.

Mermaid nie działa, podczas gdy graphviz działa poprawnie. Brama jest sprawna, ale nie można nawiązać połączenia z komponentem towarzyszącym. Sprawdź, czy usługa działa za pomocą docker compose ps, a następnie zweryfikuj, czy KROKI_MERMAID_HOST odpowiada nazwie usługi, ponieważ domyślnie przyjmuje ona wartość 127.0.0.1, co wewnątrz kontenera bramy oznacza samą bramę.

Współpraca w Excalidraw nie nawiązuje połączenia. Jeśli zbudowano frontend korzystający z własnego serwera pokoi i umieszczono go za nginx, proxy musi dokonać aktualizacji połączenia za pomocą proxy_set_header Upgrade $http_upgrade; oraz proxy_set_header Connection "upgrade";. Bez nich uzgodnienie websocket jest traktowane jako zwykłe żądanie HTTP i sesja nie zostaje rozpoczęta.

Płótno jest puste po wyczyszczeniu przeglądarki. Scena była przechowywana w pamięci lokalnej urządzenia i nie istnieje jej kopia na serwerze. Rozwiązaniem jest wyrobienie nawyku: eksportuj plik .excalidraw dla każdego rysunku, który warto zachować.

FAQ

Czy samodzielne hostowanie draw.io zapewnia prywatność diagramów?

Samodzielne hostowanie oznacza uruchomienie kodu aplikacji na własnym serwerze, co nie jest tożsame z zapewnieniem prywatności danych. draw.io renderuje się w przeglądarce użytkownika, więc kontener nigdy nie przechowuje plików diagramów. Prywatność zależy zatem od miejsca zapisu pliku oraz od tego, które połączenia wychodzące pozostaną aktywne. Należy użyć ?offline=1, aby wyłączyć cele zapisu w chmurze. Trzeba również pamiętać, że żądania eksportu trafiają do zewnętrznego serwera eksportu, chyba że skonfiguruje się DRAWIO_SELF_CONTAINED=1 i samodzielnie uruchomi jgraph/export-server.

Dlaczego współpraca w czasie rzeczywistym nie działa w samodzielnie hostowanym Excalidraw?

Oficjalna dokumentacja obrazu wskazuje, że samodzielne hostowanie „nie wspiera funkcji udostępniania ani współpracy”. Współpraca na żywo wymaga osobnego serwera websocket excalidraw/excalidraw-room, a linki do udostępniania wymagają usługi przechowywania danych. Adresy obu tych usług są wkompilowane w pakiet JavaScript na etapie budowania jako zmienne Vite, takie jak VITE_APP_WS_SERVER_URL, dlatego ustawienie zmiennych środowiskowych w uruchomionym kontenerze nie przynosi efektu. Użycie własnego serwera pokoi wymaga zbudowania frontendu ze źródeł z własnymi wartościami.

Jak renderować diagramy Mermaid na własnym serwerze?

Należy uruchomić Kroki wraz z towarzyszącym kontenerem mermaid i ustawić KROKI_MERMAID_HOST na nazwę tej usługi. Następnie należy wysłać tekst diagramu metodą POST na adres /mermaid/svg i odczytać SVG z odpowiedzi lub zakodować diagram w adresie URL typu GET i wskazać go w tagu <img>. Kontener towarzyszący obsługuje Chromium poprzez Puppeteer, ponieważ Mermaid wymaga silnika przeglądarki, dlatego należy zaplanować zasoby pamięci: KROKI_MERMAID_MAX_CONCURRENCY domyślnie obsługuje sześć renderowań jednocześnie.

Czy muszę zabezpieczyć te narzędzia hasłem?

Tak, ponieważ żadne z nich nie posiada systemu kont. draw.io oraz Excalidraw udostępniają pełny edytor każdemu, kto zna adres URL, a Kroki renderuje każdy przesłany do niego tekst. Uwierzytelnianie podstawowe (Basic Auth) na poziomie reverse proxy jest wystarczające dla obu edytorów. W przypadku Kroki należy pozostawić usługę niepubliczną w sieci Docker współdzielonej z wiki, ponieważ żądanie <img> z przeglądarki czytelnika nie przeniesie poświadczeń do innego źródła (origin), co spowodowałoby błąd wyświetlania każdego osadzonego diagramu.