Хостване на Kroki на Managed VPS: диаграмите ви, генерирани на ваш сървър

Хостването на Kroki на Managed VPS означава да генерирате диаграмите си PlantUML, Mermaid, GraphViz, D2, BPMN или Excalidraw на своя собствена машина, която нашите екипи поддържат актуална и наблюдават денем и нощем. Kroki е свободен софтуер с лиценз MIT. Това ръководство следва официалната му документация: шлюзът и придружаващите го контейнери, инсталиране с Docker Compose, конфигурацията, HTTPS, защитата на публична инстанция, свързването на Asciidoctor и MkDocs, резервните копия и обновленията.

Simon Vasconcelos Lee Автор: Публикувано на 20 ноември 2026 г.Време за четене: 14 минути

Всички ръководства

Накратко

  1. Лицензът MIT позволява свободно да използвате, променяте и разпространявате Kroki, във фирма и другаде, стига да запазите бележката за авторските права.
  2. Kroki превръща диаграма, написана като текст, в изображение чрез един-единствен HTTP API: PlantUML, GraphViz, D2, Structurizr и много други са включени в образа yuzutech/kroki.
  3. Mermaid, BPMN, Excalidraw и diagrams.net изискват всеки свой придружаващ контейнер, свързан с шлюза чрез променливите KROKI_*_HOST: Docker Compose ги стартира заедно.
  4. Kroki няма акаунти и база данни. Стартира в режим SECURE, който му пречи да чете файлове или мрежата; достъпът до публична инстанция се контролира в обратния прокси.
  5. Архивирайте конфигурацията, compose.yaml и тази на проксито, след това обновявайте с docker compose pull, като първо четете бележките към всяка версия.

Какво прави Kroki

Kroki предоставя единен HTTP API, който приема диаграма, описана като текст, и връща изображение. Вашата документация, уики или платформа за код изпраща изходния текст на диаграмата; Kroki отговаря със SVG и, в зависимост от вида на диаграмата, с PNG, PDF или JPEG. README изброява BlockDiag, BPMN, Bytefield, C4 с PlantUML, D2, DBML, diagrams.net, Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom и WireViz.

Документацията на разширението Asciidoctor Kroki посочва три причини да пуснете собствен сървър вместо публичната инстанция kroki.io: корпоративна защитна стена, която я блокира, закъснението, когато сте далеч от тази европейска инстанция, и поверителността, когато изходните текстове на диаграмите трябва да останат във вашата инфраструктура.

Какво позволява лицензът MIT

Kroki се публикува под лиценза MIT. Той дава безплатно правото да използвате, копирате, променяте, сливате, публикувате, разпространявате, преотстъпвате и продавате копия на софтуера. Следователно можете да го пуснете за своята фирма, своя екип или своите клиенти, без да купувате лиценз.

Единственото условие е да запазите бележката за авторските права и текста на лиценза във всички копия или съществени части на софтуера. Текстът предоставя софтуера „както е“, без гаранция. Библиотеките за диаграми, включени в Kroki, запазват всяка своя собствен лиценз.

Шлюзът и придружаващите го контейнери

Kroki има модулна архитектура. Шлюз, написан на Java върху Vert.x, приема всяка заявка и я насочва към правилната библиотека. Задължителен е само образът yuzutech/kroki: документацията отбелязва, че в зависимост от диаграмите ви той може да е достатъчен.

ОбразКакво генерираЗадължителен
yuzutech/krokiШлюзът, както и ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML и C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom и WireVizДа
yuzutech/kroki-mermaidMermaid: блок-схеми, диаграми на последователността и диаграми на ГантНе
yuzutech/kroki-bpmnBPMN, с bpmn-jsНе
yuzutech/kroki-excalidrawExcalidraw, стилът „нарисувано на ръка“Не
yuzutech/kroki-diagramsnetdiagrams.net, все още експерименталенНе

Оразмеряване на сървъра

Документацията не дава цифри за паметта или процесора. Тя обаче посочва какво натоварва най-много: придружаващите контейнери Mermaid, BPMN, Excalidraw и diagrams.net генерират всяка диаграма в браузър Chromium без графичен интерфейс. За да не надхвърли поредица от преобразувания паметта на контейнера, всеки от тях ограничава едновременните генерирания: по подразбиране 6 за Mermaid, BPMN и diagrams.net и 4 за Excalidraw. Следващите заявки изчакват реда си в опашка.

На Managed VPS ни разкажете за диаграмите си, за придружаващите контейнери, които им трябват, и за очаквания трафик, и ще ви препоръчаме подходящия размер.

Инсталиране с Docker Compose

Документацията препоръчва контейнери, Docker или Podman, за да не се налага да инсталирате всяка библиотека на ръка. На сървър с инсталиран Docker създайте папка и поставете в нея този compose.yaml, взет от документацията:

compose.yaml
services:
  kroki:
    image: yuzutech/kroki:0.36.0
    restart: unless-stopped
    depends_on:
      - mermaid
      - bpmn
      - excalidraw
    environment:
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "127.0.0.1:8000:8000"
    # If you mount /tmp yourself, keep the exec option
    tmpfs:
      - /tmp:exec
  mermaid:
    image: yuzutech/kroki-mermaid:0.36.0
    restart: unless-stopped
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn:0.36.0
    restart: unless-stopped
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw:0.36.0
    restart: unless-stopped
    expose:
      - "8004"
Терминал
docker compose up -d

За diagrams.net, все още експериментален, README добавя четвърти придружаващ контейнер. Добавете тази услуга, както и променливата KROKI_DIAGRAMSNET_HOST=diagramsnet в environment на kroki:

compose.yaml, услуга за добавяне
  diagramsnet:
    image: yuzutech/kroki-diagramsnet:0.36.0
    restart: unless-stopped
    expose:
      - "8005"

Проверка, че всичко отговаря

От сървъра маршрутът /health връща състоянието на шлюза и версиите на библиотеките, които той включва. Следващите две заявки генерират диаграма GraphViz през шлюза, след това диаграма Mermaid през нейния придружаващ контейнер:

Терминал, на сървъра
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/graphviz/svg --data-raw 'digraph G {Hello->World}'
curl http://127.0.0.1:8000/mermaid/svg --data-raw 'graph TD; A-->B'

Без Docker: самостоятелният jar

Другият път в документацията е самостоятелният сървър, публикуван на страницата с версиите в хранилището като kroki-standalone-server-v0.36.0.jar. Той изисква Java 21 или по-нова версия и не включва библиотеки за диаграми: всяка се инсталира отделно, а пътят до нея се задава с променлива като KROKI_DOT_BIN_PATH, когато изпълнимият файл не е в PATH. За адреса за слушане предпочетете KROKI_LISTEN, тъй като документацията за конфигурацията обявява, че KROKI_PORT ще бъде премахната:

Терминал
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar

Конфигурация: променливи, без акаунти, без база данни

Kroki няма администраторска страница, потребителски акаунти и база данни: конфигурацията му е набор от променливи на средата или системни свойства на Java при jar файла. В Docker Compose те се поставят в блока environment на съответната услуга, след което docker compose up -d пресъздава контейнера. Най-важните настройки за един сървър:

ПроменливаПо подразбиранеКакво прави
KROKI_SAFE_MODEsecureНивото на сигурност, описано по-долу
KROKI_LISTENВсички интерфейси, порт 8000Адресът и портът за слушане; приема и UNIX сокет, unix://, последвано от път
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST127.0.0.1Къде шлюзът достига всеки придружаващ контейнер; съответните променливи _PORT задават порта, а KROKI_DIAGRAMSNET_HOST обслужва diagrams.net
KROKI_COMMAND_TIMEOUT5 секундиНай-дългото изчакване за изпълним файл за диаграми, като dot
KROKI_CONVERT_TIMEOUT20 секундиНай-дългото изчакване за библиотека на Java, като PlantUML
KROKI_DELEGATE_TIMEOUT_MS30 000Най-дългото изчакване за придружаващ контейнер, в милисекунди
KROKI_MAX_URI_LENGTH4096Дължината на URL адреса, приемана при GET, над която Kroki отговаря с 414
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'Заглавката Content-Security-Policy, изпращана с всеки отговор
KROKI_CORS_ALLOWED_HEADERSНяма допълнителниДопълнителни заглавки, разрешени при извиквания от друг сайт

Диаграмите Excalidraw създават дълги URL адреси. Ако увеличите KROKI_MAX_URI_LENGTH, документацията препоръчва да останете на 8192 знака или по-малко, макар повечето браузъри да приемат повече в таг <img>. За най-големите диаграми заявка POST пренася изходния текст в тялото, а не в URL адреса.

Kroki няма нужда от тайна, за да работи. Две незадължителни настройки съдържат такава: токенът KROKI_COMPANION_REGISTRATION_TOKEN, полезен, ако разрешите регистрацията на придружаващи контейнери от трети страни, описана в раздела за защитата, и частният ключ на сертификат, ако оставите Kroki сам да обслужва HTTPS. Пазете ги извън всяко хранилище на код.

HTTPS: обратният прокси

Шлюзът обслужва своя API по HTTP. Обратен прокси пред него слуша на портове 80 и 443, получава сертификата от Let’s Encrypt, криптира трафика и го препраща към Kroki на 127.0.0.1:8000. Там се филтрира и достъпът, както показва следващият раздел.

С Caddy

Caddy сам получава и подновява сертификата за посоченото име, а директивата му reverse_proxy предава заглавките X-Forwarded-For, X-Forwarded-Proto и X-Forwarded-Host без допълнителна настройка:

Caddyfile
diagrams.example.com {
	encode gzip
	reverse_proxy 127.0.0.1:8000
}

С Nginx

Този блок server слуша на порт 80, за да може Certbot да настрои HTTPS. Две ограничения на Nginx се срещат с тези на Kroki: тяло на заявка над 1 MB по подразбиране се отказва с 413, което client_max_body_size коригира за големи диаграми, изпратени с POST; ред на заявка, по-дълъг от 8 KB, получава 414, което large_client_header_buffers коригира, ако увеличите KROKI_MAX_URI_LENGTH над тази стойност.

Блок на Nginx
server {
    listen 80;
    listen [::]:80;
    server_name diagrams.example.com;

    client_max_body_size 1m;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:8000;
    }
}
Терминал
sudo nginx -t
sudo certbot --nginx

HTTPS без прокси

Документацията описва и криптиране от самия Kroki: KROKI_SSL=true, със сертификата и частния ключ във формат PEM, като текст чрез KROKI_SSL_CERT и KROKI_SSL_KEY или като файлове чрез KROKI_SSL_CERT_PATH и KROKI_SSL_KEY_PATH. Тогава подновяването на сертификата се прави на ръка, докато пред прокси Caddy или Certbot се грижат за него сами.

Защита на инстанция, отворена към интернет

Kroki няма удостоверяване: всеки, който достигне API, може да го накара да генерира диаграми. Затова защитата му се опира на три неща, описани в документацията и в бележките към версиите: режимът на сигурност, ограниченията за размер и време и онова, което проксито пропуска. Започнете, като определите кой трябва да достига сървъра ви.

Кой извиква сървъра ви?

Режимът на сигурност

KROKI_SAFE_MODE задава три нива, всяко от които включва ограниченията на предишното. Документацията обяснява, че някои библиотеки могат да четат файлове или URL адреси, като директивите !include на PlantUML, и че Kroki, който не проверява техния код, блокира такъв достъп по подразбиране. Тя приканва всеки, който поддържа сървър, да избере нивото, подходящо за неговата употреба.

НивоКакво прави
SECURE, по подразбиранеПредотвратява всеки опит за четене на файлове от файловата система или на ресурси от мрежата
SAFEРазчита на почистването на заявките, извършвано от собствения защитен режим на всяка библиотека
UNSAFEИзключва всички функции за сигурност

На публична инстанция запазете SECURE. Заглавката Content-Security-Policy, изпращана по подразбиране от версия 0.36.0, допълва тази защита: скрипт, вмъкнат в SVG, не се изпълнява в произхода на Kroki, дори когато изображението се отвори директно.

Ограничения за размер и време

Времената за изчакване от таблицата с конфигурацията ограничават всяко преобразуване. Придружаващите контейнери добавят свои, предвидени срещу изчерпването на ресурсите:

Ограничаване на достъпа в проксито

Когато Kroki се извиква само от вашия конвейер за публикуване, най-простият вариант е да приемате единствено неговия IP адрес. С Caddy съпоставителят remote_ip отделя останалите адреси, а respond им изпраща 403:

Caddyfile
diagrams.example.com {
	@external not remote_ip 203.0.113.10
	respond @external 403
	reverse_proxy 127.0.0.1:8000
}

С Nginx директивите allow и deny в блока location вършат същото, като печели първото съвпадащо правило:

Блок на Nginx, в location /
allow 203.0.113.10;
deny all;

Основното удостоверяване на проксито е другият път: basic_auth с Caddy, чиято парола се хешира с caddy hash-password, или auth_basic и файл, създаден с htpasswd, с Nginx. То е подходящо за клиенти, които изпращат идентификационните данни при всяко извикване, като curl -u; за конвейер на документация проверете дали инструментът му може да ги предава. За инстанция, която остава публична, Nginx може също да ограничи броя на заявките от един IP адрес с модула си limit_req, настроен според броя на диаграмите в страниците ви.

Придружаващи контейнери от трети страни

Kroki може да приема придружаващи контейнери от трети страни, които се регистрират чрез API /services. Това откриване е изключено по подразбиране и винаги остава изключено в режим SECURE. Ако го включите с KROKI_ENABLE_COMPANION_DISCOVERY=true, документацията ви моли да държите /services в доверена мрежа и горещо препоръчва токена KROKI_COMPANION_REGISTRATION_TOKEN: без него Kroki предупреждава при стартиране, че всеки клиент на шлюза може да регистрира придружаващ контейнер.

Свързване на Asciidoctor, MkDocs и други инструменти

Asciidoctor Kroki и приставката за MkDocs по подразбиране сочат към https://kroki.io. Нужен им е само URL адресът на вашия сървър, включително префикса https://.

Asciidoctor и Antora

Разширението Asciidoctor Kroki чете атрибута kroki-server-url в заглавката на документа, в командния ред или в playbook файла на Antora. Добавете kroki-fetch-diagram, за да изтегляте изображенията при изграждането, вместо HTML да сочи към сървъра ви; тази опция изисква защитен режим на Asciidoctor server или по-нисък.

Заглавка на документ AsciiDoc
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:

MkDocs

Приставката mkdocs-kroki-plugin чете server_url, чиято стойност по подразбиране идва от променливата на средата KROKI_SERVER_URL. С http_method: POST изображенията се съхраняват до всяка страница в изградения сайт и се кешират между две изграждания:

mkdocs.yml
plugins:
  - kroki:
      server_url: https://diagrams.example.com
      http_method: POST

Други интеграции

Страницата за инструменти от трети страни в документацията изброява също GitLab, който генерира диаграми на Kroki в Markdown, AsciiDoc, reST и Textile, Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, разширения за Visual Studio Code и IntelliJ, както и Kroki.jl за Julia. Работи и всеки HTTP клиент, както в този пример от документацията:

Терминал
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'

Резервни копия: конфигурация, без данни

Kroki е без състояние: не пази нищо между две заявки и дори регистърът на придружаващите контейнери от трети страни изчезва след рестартиране. Изходните текстове на диаграмите ви се намират в хранилищата на документацията ви, а изображенията им в изградените ви сайтове. На сървъра на Kroki се архивира неговата конфигурация:

ЕлементКакво съдържаАрхивиране
compose.yamlОбразите, техните тагове и променливите KROKI_*Да
Файлът .env, ако има такъвПроменливи, държани извън compose.yaml, като токен или сертификатДа, на сигурно място
Конфигурацията на прокситоCaddyfile или блокът на Nginx, както и файлът с паролитеДа
Docker образитеСамият софтуерНе: docker compose pull ги изтегля отново
Терминал, в папката на compose.yaml
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile

Адаптирайте списъка към проксито си, правете ново копие след всяка промяна в конфигурацията и го изпращайте извън сървъра. Записано на диска му, то влиза и в нощните му резервни копия. Възстановяването означава да върнете тези файлове и да изпълните docker compose up -d.

Обновления

С фиксирани тагове сменете версията на четирите образа в compose.yaml, след което от неговата папка изпълнете:

Терминал
docker compose pull
docker compose up -d

Kroki следва семантичното версиониране и всяка версия публикува промените си в CHANGELOG.md и на страницата на версията. Прочетете ги преди обновяване, особено раздела им „Security“: версия 0.35.0 от 5 ноември 2026 г. и версия 0.36.0 от 9 ноември 2026 г. поправят отдалечено изпълнение на код чрез диаграми Bytefield и TikZ, XSS уязвимости в GoAT и DBML и фалшифициране на заявки от страна на сървъра чрез BlockDiag и придружаващите контейнери. На отворена инстанция внедрете тези версии без отлагане.

Версия 0.36.0 добавя също заглавката Content-Security-Policy по подразбиране и механизма за оформление TALA за D2. За ръчното инсталиране тя посочва Java 21 като минимална версия.

Кой какво прави на Managed VPS

Самостоятелното хостване изисква да поддържате сървъра освен приложението. На Managed VPS нашите екипи поемат сървъра и следят проактивно вашата инстанция; Kroki остава ваш софтуер, с неговата конфигурация и придружаващите му контейнери.

ТемаНашите екипиВие
СървърътОбновления на системата и на сигурността, включително намеси на сървъраМоментът, който пасва на вашата дейност
НаблюдениетоСървър, следен денонощно, 7 дни в седмицата, с намеса, без да се чака обаждането виЧетенето на журналите на вашата инстанция
KrokiПроактивно проследяване: грешки, забавяния, паметта на придружаващите контейнери и дисковото пространство се откриват, препоръчва се корекцияИнсталирането, обновяванията и настройките му, които прилагате вие или вашият AI асистент
Диаграмите и достъпътСървърът, който ги генерира, наблюдаван и архивиранРежимът на сигурност, придружаващите контейнери, ограниченията и правилата за достъп в проксито
Резервните копияВсяка нощ, криптирани и пазени извън машината; възстановяването е включеноКопията на конфигурацията, които пазите другаде, и заявката за възстановяване, когато ви потрябва
МиграциятаСегашният ви сървър е мигриран, безплатноМоментът на превключването

Ако предпочитате нашите екипи да се намесват в самото приложение, тази услуга се фактурира на час или на фиксирана цена, с оферта, съобщена преди намесата.

Kroki, на сървър, поддържан вместо вас

С Managed VPS от Simafri нашите екипи поддържат актуален сървъра на вашата инстанция на Kroki, наблюдават го денем и нощем и се намесват, без да чакат обаждането ви; те следят проактивно и вашата инстанция и ви препоръчват полезните корекции, които прилагате вие или вашият AI асистент. Резервните копия се криптират всяка нощ и се пазят извън машината, възстановяването им е включено, а миграцията от сегашния ви сървър е безплатна.

Разгледайте Managed VPS

Често задавани въпроси

Безплатен ли е Kroki за фирма?

Да. Kroki е с лиценз MIT: можете да го използвате, променяте и разпространявате във фирма, без да купувате лиценз, стига да запазите бележката за авторските права. Остава цената на сървъра, на който работи.

Нужни ли са ми придружаващите контейнери на Kroki?

Само за диаграмите, които те генерират. Образът yuzutech/kroki е достатъчен за PlantUML, GraphViz, D2, Structurizr и повечето формати. Mermaid, BPMN, Excalidraw и diagrams.net изискват всеки своя придружаващ контейнер, свързан чрез KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST или KROKI_DIAGRAMSNET_HOST.

Как да инсталирам Kroki с Docker Compose?

Създайте compose.yaml с образа yuzutech/kroki, неговия порт 8000, публикуван на 127.0.0.1, и нужните ви придружаващи контейнери, като yuzutech/kroki-mermaid, свързани чрез променливите KROKI_*_HOST. Изпълнете docker compose up -d, проверете /health, след това поставете обратен прокси с HTTPS пред порт 8000.

Има ли Kroki администраторски акаунт?

Не, Kroki няма акаунти, администраторска страница и база данни. Конфигурацията му е набор от променливи на средата KROKI_*, а достъпът до API се контролира в обратния прокси, по IP адрес или с основно удостоверяване.

Как да защитя публична инстанция на Kroki?

Запазете режима SECURE, включен по подразбиране, който пречи на библиотеките да четат файлове или мрежата. Оставете ограниченията за време и размер, обновявайте веднага щом версия поправи уязвимост и, ако Kroki се извиква само от вашия конвейер за публикуване, приемайте в проксито единствено неговия адрес.

Как да използвам сървъра си Kroki с Asciidoctor или MkDocs?

С Asciidoctor задайте на атрибута kroki-server-url URL адреса на сървъра си, а kroki-fetch-diagram, за да изтегляте изображенията при изграждането. С MkDocs задайте server_url в конфигурацията на приставката kroki, а http_method: POST, за да съхранявате изображенията заедно със сайта.

Какво да архивирам на сървър с Kroki?

Само конфигурацията му: compose.yaml, евентуален файл .env и конфигурацията на обратния прокси. Kroki не пази данни, а Docker образите му се изтеглят отново с docker compose pull.

Покрива ли Managed VPS Kroki?

Managed VPS покрива сървъра: система, сигурност, наблюдение и резервни копия. Нашите екипи следят проактивно и вашата инстанция и ви препоръчват полезните корекции, които прилагате вие. Намеса в самото приложение се фактурира на час или на фиксирана цена.

Източници и официална документация

Свързани ръководства

Хостване на BookStack на Managed VPS: документацията ви у васХостването на BookStack на Managed VPS означава да пазите документацията си на своя собствена машина, която нашите екипи поддържат актуална и наблюдават денем и нощем. BookStack е свободен софтуер с лиценз MIT, лесен за пускане: PHP, MySQL или MariaDB и уеб сървър, без Docker. Това ръководство следва официалната му документация: инсталирането, HTTPS, данните, имейлите, сигурността, резервните копия и обновленията.Колко RAM е нужна за VPS: правилото, според всяка употребаПаметта (RAM) е ресурсът, който най-често определя размера на един VPS: тя свършва първа, а когато свърши, сървърът не се забавя, а спира услуги. Това ръководство дава правилото за изчисление, колко консумира всеки компонент на едно приложение, типични профили и начина да измерите сървър, който вече работи.Разлика между управляван и неуправляван VPS: кой какво правиРазликата между управляван и неуправляван VPS се свежда до един въпрос: кой се грижи за сървъра, след като той вече работи. Думата „управляван“ обаче няма официално определение и от един хостинг доставчик до друг обхваща всичко от простото инсталиране на системата до цялостното стопанисване на сървъра. Това ръководство показва кой какво прави, ред по ред, заедно с междинното ниво на експертното съдействие, и дава въпросите, които премахват двусмислието, преди да подпишете.
Свържете се с нас