gitlab 集成Kroki

参考文档

• https://docs.gitlab.com/administration/integration/kroki/
• https://kroki.io/
• https://structurizr.com/dsl
  
  

Kroki说明

• Kroki 提供一个统一的 API（应用编程接口）。
• 该 API 支持多种“绘图/建模”语言和工具，方便把不同格式的图快速转换成图像或其他可用格式。
  
  

具体支持的内容（按类别大致分组）

• BlockDiag 家族：BlockDiag、SeqDiag、ActDiag、NwDiag、PacketDiag、RackDiag 等。
• BPMN：业务流程建模符号。
• Bytefield、Ditaa、Erd、TikZ、PlantUML、UMLet、Vega/Vega-Lite、WaveDrom 等：涵盖各种图形、流程、数据关系和可视化表示。
• C4：与 PlantUML 一起使用的 C4 模型（架构层级和关系图）。
• D2、GraphViz、Mermaid、Nomnoml、Pikchr、Structurizr、Excalidraw、SvgBob、Symbolator、Turbo 等：不同风格和语法的图形描述工具或可视化风格。
• 以及更多未来会增加的支持。
  
  

核心含义

• 通过一个统一的接口，你可以用多种语言或工具来描述图，然后通过 Kroki 转换成常见的图片格式（如 PNG、SVG 等）。
• 这极大地简化了集成和工作流，因为不需要为每种绘图语言单独处理渲染逻辑。
  
  

简单的使用场景

• 在笔记、文档或代码库中，用你熟悉的标记语言描述图，然后让 Kroki 在服务器端统一生成图像。
• 将不同团队使用的不同描述语言统一渲染成一致的输出，提高协作效率。
  
  

通过 Kroki 集成，您可以在 AsciiDoc、Markdown、reStructuredText 和 Textile 中创建图表代码。

在 GitLab 中启用 Kroki

你需要在设置的管理区域启用 Kroki 集成。请用管理员账户登录并按照以下步骤操作：

• 左侧边栏底部，选择 Admin（管理员）。
• 进入 Settings（设置）> General（常规）。
• 展开 Kroki 部分。
• 选中 Enable Kroki（启用 Kroki）复选框。
• 输入 Kroki 的 URL，例如 https://kroki.io，也可以使用自己搭建的Kroki 服务。
  
  

Kroki服务

当你启用 Kroki 时，GitLab 会把图表发送到 Kroki 实例以将其显示为图片。你可以使用免费的公共云实例 https://kroki.io，或在你自己的基础设施上安装 Kroki。安装 Kroki 之后，请确保在设置中更新 Kroki URL，使之指向你的实例。

Kroki 的图表不会存储在 GitLab 上，因此标准的 GitLab 访问控制和其他用户权限限制不会生效。

docker部署Kroki服务 docker run -d --name kroki -p 8080:8000 yuzutech/kroki

Kroki 的 URL 是运行容器的服务器主机名。yuzutech/kroki Docker 镜像开箱即用地支持大多数图表类型。若要查看完整列表，请参阅 Kroki 安装文档。

支持的图表类型包括：

• Bytefield
• D2
• DBML
• Ditaa
• Erd
• GraphViz
• Nomnoml
• PlantUML
  
  
  • C4 模型（与 PlantUML 一起使用）
    
    
• Structurizr（非常适合 C4 模型图）
• Svgbob
• UMlet
• Vega
• Vega-Lite
• WaveDrom
  
  

如果你想使用额外的图表库，请参阅 Kroki 安装文档以了解如何启动 Kroki 伴随容器。

创建图表

启用并配置 Kroki 集成后，您就可以在 AsciiDoc 或 Markdown 文档中使用带定界符的代码块来添加图表：

• Markdown
  ```plantuml
  Bob -> Alice : hello
  Alice -> Bob : hi
  ```
• AsciiDoc
  [plantuml]
  ....
  Bob->Alice : hello
  Alice -> Bob : hi
  ....
• reStructuredText
  .. code-block:: plantuml
  ​
     Bob->Alice : hello
     Alice -> Bob : hi
• Textile
  bc[plantuml]. Bob->Alice : hello
  Alice -> Bob : hi
  

带定界符的块将转换为指向 Kroki 实例的 HTML 图像标签。如果 Kroki 服务器配置正确，这将呈现出一个漂亮的图表，而不是该块内容：

                               
登录/注册后可看大图

Kroki 支持十几个图表库。以下是 AsciiDoc 的一些示例：

• GraphViz
  graphviz 示例
  [graphviz]
  ....
  digraph finite_state_machine {
     rankdir=LR;
     node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
     node [shape = circle];
     LR_0 -> LR_2 [ label = "SS(B)" ];
     LR_0 -> LR_1 [ label = "SS(S)" ];
     LR_1 -> LR_3 [ label = "S($end)" ];
     LR_2 -> LR_6 [ label = "SS(b)" ];
     LR_2 -> LR_5 [ label = "SS(a)" ];
     LR_2 -> LR_4 [ label = "S(A)" ];
     LR_5 -> LR_7 [ label = "S(b)" ];
     LR_5 -> LR_5 [ label = "S(a)" ];
     LR_6 -> LR_6 [ label = "S(b)" ];
     LR_6 -> LR_5 [ label = "S(a)" ];
     LR_7 -> LR_8 [ label = "S(b)" ];
     LR_7 -> LR_5 [ label = "S(a)" ];
     LR_8 -> LR_6 [ label = "S(b)" ];
     LR_8 -> LR_5 [ label = "S(a)" ];
  }
  ....
  md 文件中的示例写法
  ```graphviz
  digraph finite_state_machine {
     rankdir=LR;
     node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
     node [shape = circle];
     LR_0 -> LR_2 [ label = "SS(B)" ];
     LR_0 -> LR_1 [ label = "SS(S)" ];
     LR_1 -> LR_3 [ label = "S($end)" ];
     LR_2 -> LR_6 [ label = "SS(b)" ];
     LR_2 -> LR_5 [ label = "SS(a)" ];
     LR_2 -> LR_4 [ label = "S(A)" ];
     LR_5 -> LR_7 [ label = "S(b)" ];
     LR_5 -> LR_5 [ label = "S(a)" ];
     LR_6 -> LR_6 [ label = "S(b)" ];
     LR_6 -> LR_5 [ label = "S(a)" ];
     LR_7 -> LR_8 [ label = "S(b)" ];
     LR_7 -> LR_5 [ label = "S(a)" ];
     LR_8 -> LR_6 [ label = "S(b)" ];
     LR_8 -> LR_5 [ label = "S(a)" ];
  }
  ```
  ​
  渲染图效果
  
                                 
  登录/注册后可看大图
• C4 (based on PlantUML)
  c4plantuml 示例
  [c4plantuml]
  ....
  @startuml
  !include C4_Context.puml
  ​
  title System Context diagram for Internet Banking System
  ​
  Person(customer, "Banking Customer", "A customer of the bank, with personal bank accounts.")
  System(banking_system, "Internet Banking System", "Allows customers to check their accounts.")
  ​
  System_Ext(mail_system, "E-mail system", "The internal Microsoft Exchange e-mail system.")
  System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information.")
  ​
  Rel(customer, banking_system, "Uses")
  Rel_Back(customer, mail_system, "Sends e-mails to")
  Rel_Neighbor(banking_system, mail_system, "Sends e-mails", "SMTP")
  Rel(banking_system, mainframe, "Uses")
  @enduml
  ....
  md 文件中的示例写法
  ```c4plantuml
  @startuml
  !include C4_Context.puml
  ​
  title System Context diagram for Internet Banking System
  ​
  Person(customer, "Banking Customer", "A customer of the bank, with personal bank accounts.")
  System(banking_system, "Internet Banking System", "Allows customers to check their accounts.")
  ​
  System_Ext(mail_system, "E-mail system", "The internal Microsoft Exchange e-mail system.")
  System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information.")
  ​
  Rel(customer, banking_system, "Uses")
  Rel_Back(customer, mail_system, "Sends e-mails to")
  Rel_Neighbor(banking_system, mail_system, "Sends e-mails", "SMTP")
  Rel(banking_system, mainframe, "Uses")
  @enduml
  渲染效果图
  
  
  
                                 
  登录/注册后可看大图
• Nomnoml
  [nomnoml]
  ....
  [Pirate|eyeCount: Int|raid();pillage()|
     [beard]--[parrot]
     [beard]-:>[foul mouth]
  ]
  ​
  [<abstract>Marauder]<:--[Pirate]
  [Pirate]- 0..7[mischief]
  [jollyness]->[Pirate]
  [jollyness]->[rum]
  [jollyness]->[singing]
  [Pirate]-> *[rum|tastiness: Int|swig()]
  [Pirate]->[singing]
  [singing]<->[rum]
  ....
  md 文件中的示例写法
  ```nomnoml
  [Pirate|eyeCount: Int|raid();pillage()|
     [beard]--[parrot]
     [beard]-:>[foul mouth]
  ]
  ​
  [<abstract>Marauder]<:--[Pirate]
  [Pirate]- 0..7[mischief]
  [jollyness]->[Pirate]
  [jollyness]->[rum]
  [jollyness]->[singing]
  [Pirate]-> *[rum|tastiness: Int|swig()]
  [Pirate]->[singing]
  [singing]<->[rum]
  ```
  渲染效果图
  
                                 
  登录/注册后可看大图
  
  

gitlab 仓库中完整 README.md 文件内容 ```plantuml
Bob -> Alice : hello
Alice -> Bob : hi
```
---
​
```mermaid
graph TD
   A[User] --> B[GitLab]
   B --> C[Kroki]
   C --> D[SVG Output]
```
---
```structurizr
workspace {
​
   model {
     user = person "User"
     system = softwareSystem "System" {
       user -> this "Uses"
     }
   }
​
   views {
     systemContext system {
       include *
       autolayout lr
     }
   }
}
```
---
​
```structurizr
workspace "Name" "Description" {
​
     !identifiers hierarchical
​
     model {
         u = person "User"
         ss = softwareSystem "Software System" {
             wa = container "Web Application"
             db = container "Database Schema" {
                 tags "Database"
             }
         }
​
         u -> ss.wa "Uses"
         ss.wa -> ss.db "Reads from and writes to"
     }
​
     views {
         systemContext ss "Diagram1" {
             include *
             autolayout lr
         }
​
         container ss "Diagram2" {
             include *
             autolayout lr
         }
​
         styles {
             element "Element" {
                 color #f8289c
                 stroke #f8289c
                 strokeWidth 7
                 shape roundedbox
             }
             element "Person" {
                 shape person
             }
             element "Database" {
                 shape cylinder
             }
             element "Boundary" {
                 strokeWidth 5
             }
             relationship "Relationship" {
                 thickness 4
             }
         }
     }
​
     configuration {
         scope softwaresystem
     }
​
}
```
---
```graphviz
digraph finite_state_machine {
   rankdir=LR;
   node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
   node [shape = circle];
   LR_0 -> LR_2 [ label = "SS(B)" ];
   LR_0 -> LR_1 [ label = "SS(S)" ];
   LR_1 -> LR_3 [ label = "S($end)" ];
   LR_2 -> LR_6 [ label = "SS(b)" ];
   LR_2 -> LR_5 [ label = "SS(a)" ];
   LR_2 -> LR_4 [ label = "S(A)" ];
   LR_5 -> LR_7 [ label = "S(b)" ];
   LR_5 -> LR_5 [ label = "S(a)" ];
   LR_6 -> LR_6 [ label = "S(b)" ];
   LR_6 -> LR_5 [ label = "S(a)" ];
   LR_7 -> LR_8 [ label = "S(b)" ];
   LR_7 -> LR_5 [ label = "S(a)" ];
   LR_8 -> LR_6 [ label = "S(b)" ];
   LR_8 -> LR_5 [ label = "S(a)" ];
}
```
---
```c4plantuml
@startuml
!include C4_Context.puml
​
title System Context diagram for Internet Banking System
​
Person(customer, "Banking Customer", "A customer of the bank, with personal bank accounts.")
System(banking_system, "Internet Banking System", "Allows customers to check their accounts.")
​
System_Ext(mail_system, "E-mail system", "The internal Microsoft Exchange e-mail system.")
System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information.")
​
Rel(customer, banking_system, "Uses")
Rel_Back(customer, mail_system, "Sends e-mails to")
Rel_Neighbor(banking_system, mail_system, "Sends e-mails", "SMTP")
Rel(banking_system, mainframe, "Uses")
@enduml
```
---
```nomnoml
[Pirate|eyeCount: Int|raid();pillage()|
   [beard]--[parrot]
   [beard]-:>[foul mouth]
]
​
[<abstract>Marauder]<:--[Pirate]
[Pirate]- 0..7[mischief]
[jollyness]->[Pirate]
[jollyness]->[rum]
[jollyness]->[singing]
[Pirate]-> *[rum|tastiness: Int|swig()]
[Pirate]->[singing]
[singing]<->[rum]
```

                               
登录/注册后可看大图