kroki图标渲染服务配置说明

一、环境准备

前提：Docker + Docker Compose 已装好。因为内网拉镜像慢，/etc/docker/daemon.json 配置了国内镜像加速：

{

"registry-mirrors": [

"https://docker.1ms.run",

"https://docker.m.daocloud.io",

"https://dockerproxy.com",

"https://docker.nju.edu.cn"

]

}

改完执行 systemctl restart docker 生效。

二、创建目录和 compose 文件

mkdir -p /data/kroki && cd /data/kroki

写 docker-compose.yml（当前线上正在用的这份）：

services:

kroki:

image: yuzutech/kroki:latest

container_name: kroki

restart: unless-stopped

depends_on:

kroki-mermaid
kroki-bpmn
kroki-excalidraw

ports:

"8001:8001" # 主机8001 → 容器8001，默认8000

environment:

KROKI_PORT: 8001 #改端口要加

KROKI_MAX_URI_LENGTH: "8000" #KROKI_MAX_URI_LENGTH 不是端口，是 GET 请求 URL 的最大长度（字符数）------kroki 支持把图表源码编码后放在 URL 里用 GET 请求渲染，这个参数限制 URL 最长多少字符。原文件里的 8000 碰巧和容器端口数字一样

KROKI_SAFE_MODE: "UNSAFE"

KROKI_MAX_BODY_SIZE: 20M

KROKI_MERMAID_HOST: kroki-mermaid

KROKI_MERMAID_PORT: 8002

KROKI_BPMN_HOST: kroki-bpmn

KROKI_BPMN_PORT: 8003

KROKI_EXCALIDRAW_HOST: kroki-excalidraw

KROKI_EXCALIDRAW_PORT: 8004

healthcheck:

test: $"CMD-SHELL", "curl -fs http://localhost:8001/health \|\| exit 1"$

interval: 30s

timeout: 5s

retries: 3

start_period: 30s

kroki-mermaid:

image: yuzutech/kroki-mermaid:latest

container_name: kroki-mermaid

restart: unless-stopped

kroki-bpmn:

image: yuzutech/kroki-bpmn:latest

container_name: kroki-bpmn

restart: unless-stopped

kroki-excalidraw:

image: yuzutech/kroki-excalidraw:latest

container_name: kroki-excalidraw

restart: unless-stopped

关键点说明：

mermaid/bpmn/excalidraw 是重渲染器，主镜像内置不支持，需要单独的配套容器。它们在 compose 内部网络里互相用容器名访问
*配套容器必须配 KROKI__PORT 环境变量**，因为这些镜像内部监听的不是 8000（mermaid=8002、bpmn=8003、excalidraw=8004）。不配就会 502
配套容器不映射端口到主机，只在 docker 内网通信
vega/vegalite/plantuml/graphviz/ditaa/blockdiag/wireviz 等都在主镜像里内置，不用额外容器（kroki-vega 独立镜像已不存在）
KROKI_SAFE_MODE: UNSAFE 是内网环境放开 include 等受限功能，公网服务不要这么配

三、拉镜像并启动

cd /data/kroki

docker compose pull # 走镜像加速拉取

docker compose up -d

四、验证

健康检查（看到 (healthy) 状态）

docker ps --format '{{.Names}}\t{{.Status}}' | grep kroki

接口验证

curl http://localhost:8001/health

mermaid 渲染测试

echo 'graph TD; A-->B;' | curl -s --data-binary @- \

-H 'Content-Type: text/plain' \

http://localhost:8001/mermaid/svg

五、踩过的坑

POST 图表源码必须用 Content-Type: text/plain 发送。用 x-www-form-urlencoded 会被表单解码器限制字段长度，报 TooLongFormFieldException
配套容器不配 KROKI_*_PORT 环境变量时，对应图表类型渲染失败
主机 8000 已被占用，所以 kroki 映射到 8001

六、当前状态

4 个容器全部运行中（kroki 主服务 healthy，已连续运行 2 天），开机自启已通过 restart: unless-stopped + Docker 服务自启保障。日常维护只需要 cd /data/kroki && docker compose restart 或升级时 `docker compose pull && docker

compose up -d`