Хостването на Kroki на Managed VPS означава да генерирате диаграмите си PlantUML, Mermaid, GraphViz, D2, BPMN или Excalidraw на своя собствена машина, която нашите екипи поддържат актуална и наблюдават денем и нощем. Kroki е свободен софтуер с лиценз MIT. Това ръководство следва официалната му документация: шлюзът и придружаващите го контейнери, инсталиране с Docker Compose, конфигурацията, HTTPS, защитата на публична инстанция, свързването на Asciidoctor и MkDocs, резервните копия и обновленията.
Автор: Simon Vasconcelos Lee
Публикувано на 20 ноември 2026 г.Време за четене: 14 минути
yuzutech/kroki.KROKI_*_HOST: Docker Compose ги стартира заедно.SECURE, който му пречи да чете файлове или мрежата; достъпът до публична инстанция се контролира в обратния прокси.compose.yaml и тази на проксито, след това обновявайте с docker compose pull, като първо четете бележките към всяка версия.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.
/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000. Уеб страницата я показва като всяко друго изображение./graphviz/svg, или в тялото на JSON.Kroki-Diagram-Options-*.Документацията на разширението Asciidoctor Kroki посочва три причини да пуснете собствен сървър вместо публичната инстанция kroki.io: корпоративна защитна стена, която я блокира, закъснението, когато сте далеч от тази европейска инстанция, и поверителността, когато изходните текстове на диаграмите трябва да останат във вашата инфраструктура.
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-mermaid | Mermaid: блок-схеми, диаграми на последователността и диаграми на Гант | Не |
yuzutech/kroki-bpmn | BPMN, с bpmn-js | Не |
yuzutech/kroki-excalidraw | Excalidraw, стилът „нарисувано на ръка“ | Не |
yuzutech/kroki-diagramsnet | diagrams.net, все още експериментален | Не |
Документацията не дава цифри за паметта или процесора. Тя обаче посочва какво натоварва най-много: придружаващите контейнери Mermaid, BPMN, Excalidraw и diagrams.net генерират всяка диаграма в браузър Chromium без графичен интерфейс. За да не надхвърли поредица от преобразувания паметта на контейнера, всеки от тях ограничава едновременните генерирания: по подразбиране 6 за Mermaid, BPMN и diagrams.net и 4 за Excalidraw. Следващите заявки изчакват реда си в опашка.
yuzutech/kroki 0.36.0 тежи около 1 GB в компресиран вид. Kroki не записва данни: не пази нищо между две заявки.amd64 и arm64.depends_on и KROKI_*_HOST.На Managed VPS ни разкажете за диаграмите си, за придружаващите контейнери, които им трябват, и за очаквания трафик, и ще ви препоръчаме подходящия размер.
Документацията препоръчва контейнери, Docker или Podman, за да не се налага да инсталирате всяка библиотека на ръка. На сървър с инсталиран Docker създайте папка и поставете в нея този 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
127.0.0.1: това е първата промяна спрямо примера в документацията, който публикува 8000:8000. Kroki по подразбиране слуша на всички интерфейси, а Docker публикува порта на всеки адрес на сървъра, когато не му е посочен адрес. Тук API е достъпен само през обратния прокси.expose: той остава във вътрешната мрежа на Compose, където шлюзът ги достига по името на услугата. Променливите KROKI_MERMAID_HOST, KROKI_BPMN_HOST и KROKI_EXCALIDRAW_HOST задават това име; портовете им по подразбиране, 8002, 8003 и 8004, не е нужно да се повтарят.0.36.0 е втората промяна: примерът в документацията следва най-новата версия. Четирите образа се публикуват заедно под един и същ таг, което фиксира съгласувана версия и прави всяко обновяване съзнателно.За diagrams.net, все още експериментален, README добавя четвърти придружаващ контейнер. Добавете тази услуга, както и променливата KROKI_DIAGRAMSNET_HOST=diagramsnet в environment на kroki:
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'
Другият път в документацията е самостоятелният сървър, публикуван на страницата с версиите в хранилището като 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_MODE | secure | Нивото на сигурност, описано по-долу |
KROKI_LISTEN | Всички интерфейси, порт 8000 | Адресът и портът за слушане; приема и UNIX сокет, unix://, последвано от път |
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST | 127.0.0.1 | Къде шлюзът достига всеки придружаващ контейнер; съответните променливи _PORT задават порта, а KROKI_DIAGRAMSNET_HOST обслужва diagrams.net |
KROKI_COMMAND_TIMEOUT | 5 секунди | Най-дългото изчакване за изпълним файл за диаграми, като dot |
KROKI_CONVERT_TIMEOUT | 20 секунди | Най-дългото изчакване за библиотека на Java, като PlantUML |
KROKI_DELEGATE_TIMEOUT_MS | 30 000 | Най-дългото изчакване за придружаващ контейнер, в милисекунди |
KROKI_MAX_URI_LENGTH | 4096 | Дължината на URL адреса, приемана при GET, над която Kroki отговаря с 414 |
KROKI_CONTENT_SECURITY_POLICY | script-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. Пазете ги извън всяко хранилище на код.
Шлюзът обслужва своя API по HTTP. Обратен прокси пред него слуша на портове 80 и 443, получава сертификата от Let’s Encrypt, криптира трафика и го препраща към Kroki на 127.0.0.1:8000. Там се филтрира и достъпът, както показва следващият раздел.
Caddy сам получава и подновява сертификата за посоченото име, а директивата му reverse_proxy предава заглавките X-Forwarded-For, X-Forwarded-Proto и X-Forwarded-Host без допълнителна настройка:
diagrams.example.com {
encode gzip
reverse_proxy 127.0.0.1:8000
}
Този блок 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 над тази стойност.
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
Документацията описва и криптиране от самия Kroki: KROKI_SSL=true, със сертификата и частния ключ във формат PEM, като текст чрез KROKI_SSL_CERT и KROKI_SSL_KEY или като файлове чрез KROKI_SSL_CERT_PATH и KROKI_SSL_KEY_PATH. Тогава подновяването на сертификата се прави на ръка, докато пред прокси Caddy или Certbot се грижат за него сами.
Kroki няма удостоверяване: всеки, който достигне API, може да го накара да генерира диаграми. Затова защитата му се опира на три неща, описани в документацията и в бележките към версиите: режимът на сигурност, ограниченията за размер и време и онова, което проксито пропуска. Започнете, като определите кой трябва да достига сървъра ви.
kroki-fetch-diagram, а приставката за MkDocs с http_method: POST: изображенията се записват заедно със сайта и сървърът на Kroki вече не е нужно да бъде публичен.KROKI_SAFE_MODE задава три нива, всяко от които включва ограниченията на предишното. Документацията обяснява, че някои библиотеки могат да четат файлове или URL адреси, като директивите !include на PlantUML, и че Kroki, който не проверява техния код, блокира такъв достъп по подразбиране. Тя приканва всеки, който поддържа сървър, да избере нивото, подходящо за неговата употреба.
| Ниво | Какво прави |
|---|---|
SECURE, по подразбиране | Предотвратява всеки опит за четене на файлове от файловата система или на ресурси от мрежата |
SAFE | Разчита на почистването на заявките, извършвано от собствения защитен режим на всяка библиотека |
UNSAFE | Изключва всички функции за сигурност |
SECURE неговите !include и !includeurl се отказват, а профилът му на сигурност е SANDBOX. В SAFE профилът става ALLOWLIST, а KROKI_PLANTUML_ALLOWLIST_URL или KROKI_PLANTUML_ALLOWLIST_PATH посочват какво може да бъде включвано.UNSAFE браузърът им зарежда само локални ресурси. За да разрешите вътрешна банка с изображения, без да напускате този режим, документацията предлага KROKI_ALLOWED_ORIGINS или неговата форма за отделен контейнер, като KROKI_MERMAID_ALLOWED_ORIGINS, в придружаващия контейнер.UNSAFE: без !include за Structurizr, без външни изображения за BlockDiag, без четене на файлове за Lini.KROKI_STRUCTURIZR_SAFE_MODE или KROKI_MERMAID_SAFE_MODE, вместо да се понижава нивото на целия сървър.На публична инстанция запазете SECURE. Заглавката Content-Security-Policy, изпращана по подразбиране от версия 0.36.0, допълва тази защита: скрипт, вмъкнат в SVG, не се изпълнява в произхода на Kroki, дори когато изображението се отвори директно.
Времената за изчакване от таблицата с конфигурацията ограничават всяко преобразуване. Придружаващите контейнери добавят свои, предвидени срещу изчерпването на ресурсите:
KROKI_MERMAID_MAX_TEXT_SIZE) или с повече от 500 връзки, с 400, и прекъсва генериране след 10 секунди, с 408. Тези ограничения не могат да бъдат заобиколени чрез параметрите на заявка.KROKI_MAX_BODY_SIZE).Когато Kroki се извиква само от вашия конвейер за публикуване, най-простият вариант е да приемате единствено неговия IP адрес. С Caddy съпоставителят remote_ip отделя останалите адреси, а respond им изпраща 403:
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 вършат същото, като печели първото съвпадащо правило:
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 Kroki и приставката за MkDocs по подразбиране сочат към https://kroki.io. Нужен им е само URL адресът на вашия сървър, включително префикса https://.
Разширението Asciidoctor Kroki чете атрибута kroki-server-url в заглавката на документа, в командния ред или в playbook файла на Antora. Добавете kroki-fetch-diagram, за да изтегляте изображенията при изграждането, вместо HTML да сочи към сървъра ви; тази опция изисква защитен режим на Asciidoctor server или по-нисък.
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:
Приставката mkdocs-kroki-plugin чете server_url, чиято стойност по подразбиране идва от променливата на средата KROKI_SERVER_URL. С http_method: POST изображенията се съхраняват до всяка страница в изградения сайт и се кешират между две изграждания:
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 ги изтегля отново |
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 нашите екипи поемат сървъра и следят проактивно вашата инстанция; Kroki остава ваш софтуер, с неговата конфигурация и придружаващите му контейнери.
| Тема | Нашите екипи | Вие |
|---|---|---|
| Сървърът | Обновления на системата и на сигурността, включително намеси на сървъра | Моментът, който пасва на вашата дейност |
| Наблюдението | Сървър, следен денонощно, 7 дни в седмицата, с намеса, без да се чака обаждането ви | Четенето на журналите на вашата инстанция |
| Kroki | Проактивно проследяване: грешки, забавяния, паметта на придружаващите контейнери и дисковото пространство се откриват, препоръчва се корекция | Инсталирането, обновяванията и настройките му, които прилагате вие или вашият AI асистент |
| Диаграмите и достъпът | Сървърът, който ги генерира, наблюдаван и архивиран | Режимът на сигурност, придружаващите контейнери, ограниченията и правилата за достъп в проксито |
| Резервните копия | Всяка нощ, криптирани и пазени извън машината; възстановяването е включено | Копията на конфигурацията, които пазите другаде, и заявката за възстановяване, когато ви потрябва |
| Миграцията | Сегашният ви сървър е мигриран, безплатно | Моментът на превключването |
Ако предпочитате нашите екипи да се намесват в самото приложение, тази услуга се фактурира на час или на фиксирана цена, с оферта, съобщена преди намесата.
С Managed VPS от Simafri нашите екипи поддържат актуален сървъра на вашата инстанция на Kroki, наблюдават го денем и нощем и се намесват, без да чакат обаждането ви; те следят проактивно и вашата инстанция и ви препоръчват полезните корекции, които прилагате вие или вашият AI асистент. Резервните копия се криптират всяка нощ и се пазят извън машината, възстановяването им е включено, а миграцията от сегашния ви сървър е безплатна.
Да. Kroki е с лиценз MIT: можете да го използвате, променяте и разпространявате във фирма, без да купувате лиценз, стига да запазите бележката за авторските права. Остава цената на сървъра, на който работи.
Само за диаграмите, които те генерират. Образът yuzutech/kroki е достатъчен за PlantUML, GraphViz, D2, Structurizr и повечето формати. Mermaid, BPMN, Excalidraw и diagrams.net изискват всеки своя придружаващ контейнер, свързан чрез KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST или KROKI_DIAGRAMSNET_HOST.
Създайте compose.yaml с образа yuzutech/kroki, неговия порт 8000, публикуван на 127.0.0.1, и нужните ви придружаващи контейнери, като yuzutech/kroki-mermaid, свързани чрез променливите KROKI_*_HOST. Изпълнете docker compose up -d, проверете /health, след това поставете обратен прокси с HTTPS пред порт 8000.
Не, Kroki няма акаунти, администраторска страница и база данни. Конфигурацията му е набор от променливи на средата KROKI_*, а достъпът до API се контролира в обратния прокси, по IP адрес или с основно удостоверяване.
Запазете режима SECURE, включен по подразбиране, който пречи на библиотеките да четат файлове или мрежата. Оставете ограниченията за време и размер, обновявайте веднага щом версия поправи уязвимост и, ако Kroki се извиква само от вашия конвейер за публикуване, приемайте в проксито единствено неговия адрес.
С Asciidoctor задайте на атрибута kroki-server-url URL адреса на сървъра си, а kroki-fetch-diagram, за да изтегляте изображенията при изграждането. С MkDocs задайте server_url в конфигурацията на приставката kroki, а http_method: POST, за да съхранявате изображенията заедно със сайта.
Само конфигурацията му: compose.yaml, евентуален файл .env и конфигурацията на обратния прокси. Kroki не пази данни, а Docker образите му се изтеглят отново с docker compose pull.
Managed VPS покрива сървъра: система, сигурност, наблюдение и резервни копия. Нашите екипи следят проактивно и вашата инстанция и ви препоръчват полезните корекции, които прилагате вие. Намеса в самото приложение се фактурира на час или на фиксирана цена.
Simafri
Да поговорим за Вашия проект
Кажете ни с няколко думи от какво имате нужда: отговаряме Ви бързо.
Благодарим! Вашето запитване е изпратено. Ще се свържем с вас скоро.
Предпочитате имейл? Пишете ни на support@simafri.com.