PlantUML & GitLab

原文：https://docs.gitlab.com/ee/administration/integration/plantuml.html

• PlantUML Server

  • Docker
  • Debian/Ubuntu
  • Making local PlantUML accessible using custom GitLab setup
  • Security

• GitLab

• Creating Diagrams

PlantUML & GitLab

在 GitLab 8.16 中引入 .

在 GitLab 中启用并配置PlantUML集成后，我们便能够在片段，Wiki 和存储库中创建的 AsciiDoc 和 Markdown 文档中创建简单的图表.

PlantUML Server

在 GitLab 中启用 PlantUML 之前； 您需要设置自己的 PlantUML 服务器以生成图表.

Docker

使用 Docker，您可以仅运行如下容器：

docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat 

PlantUML URL将是运行容器的服务器的主机名.

在 Docker 中运行 GitLab 时，它将需要有权访问 PlantUML 容器. 最简单的方法是使用Docker Compose .

一个简单docker-compose.yml文件将是：

version: "3"
services:
  gitlab:
    image: 'gitlab/gitlab-ce:12.2.5-ce.0'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n    proxy_cache off; \n    proxy_pass  http://plantuml:8080/; \n}\n"

  plantuml:
    image: 'plantuml/plantuml-server:tomcat'
    container_name: plantuml 

在这种情况下，可以通过 URL http://plantuml:8080/访问 GitLab 的http://plantuml:8080/ .

Debian/Ubuntu

在使用 Tomcat 的 Debian / Ubuntu 发行版中，安装和配置自己的 PlantUML 服务器非常容易.

首先，您需要从源代码创建一个plantuml.war文件：

sudo apt-get install graphviz openjdk-8-jdk git-core maven
git clone https://github.com/plantuml/plantuml-server.git
cd plantuml-server
mvn package 

上面的命令序列将生成可以使用 Tomcat 部署的 WAR 文件：

sudo apt-get install tomcat8
sudo cp target/plantuml.war /var/lib/tomcat8/webapps/plantuml.war
sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war
sudo service tomcat8 restart 

Tomcat 服务重新启动后，PlantUML 服务将准备就绪，并在端口 8080 上侦听请求：

http://localhost:8080/plantuml 

您可以通过编辑/etc/tomcat8/server.xml文件来更改这些默认值.

请注意，默认 URL 与使用基于 Docker 的映像时不同，后者在 URL 的根目录中提供服务，而没有相对路径. 相应地调整以下配置.

Making local PlantUML accessible using custom GitLab setup

PlantUML 服务器在您的服务器上本地运行，因此无法从外部访问. 因此，有必要捕获外部 PlantUML 调用并将其重定向到本地服务器.

想法是将每次调用https://gitlab.example.com/-/plantuml/重定向到本地 PlantUML 服务器http://plantuml:8080/或http://localhost:8080/plantuml/ ，具体取决于您的建立.

要启用重定向，请在/etc/gitlab/gitlab.rb添加以下行：

# Docker deployment
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass  http://plantuml:8080/; \n}\n"

# Built from source
nginx['custom_gitlab_server_config'] = "location /-/plantuml { \n rewrite ^/-/(plantuml.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8080/plantuml; \n}\n" 

要激活更改，请运行以下命令：

sudo gitlab-ctl reconfigure 

Security

PlantUML 具有允许获取网络资源的功能.

@startuml
start
    ' ...
    !include http://localhost/
stop;
@enduml 

如果您自行托管 PlantUML 服务器，则应放置网络控件以隔离它.

GitLab

您需要从"管理"区域下的"设置"启用 PlantUML 集成. 为此，请使用管理员帐户登录并执行以下操作：

• 在 GitLab 中，转到管理区域>设置>集成 .
• 展开PlantUML部分.
• Check 启用 PlantUML checkbox.
• Set the PlantUML instance as https://gitlab.example.com/-/plantuml/.

注意：如果使用的是运行 v1.2020.9 及更高版本的 PlantUML 服务器（例如plantuml.com ），请设置PLANTUML_ENCODING环境变量以启用deflate压缩. 在 Omnibus 上，可以在/etc/gitlab.rb进行设置：

gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' } 

从 GitLab 13.1 和更高版本开始，PlantUML 集成现在需要 URL 中的标头前缀来区分不同的编码类型.

Creating Diagrams

启用并配置 PlantUML 集成后，我们可以开始使用分隔的块向我们的 AsciiDoc 代码片段，Wiki 和存储库添加图表：

• Markdown

  ```plantuml Bob -> Alice : hello
  Alice -> Bob : hi

  ```

• AsciiDoc

  [plantuml, format="png", id="myDiagram", width="200px"]
  ----
  Bob->Alice : hello
  Alice -> Bob : hi
  ---- 

  • reStructuredText

  .. plantuml::
     :caption: Caption with **bold** and *italic*
  
     Bob -> Alice: hello
     Alice -> Bob: hi 

  您也可以使用uml::指令与sphinxcontrib-plantuml兼容，但是请注意，我们目前仅支持caption选项.

上面的块将被转换为 HTML 图像标签，其源指向 PlantUML 实例. 如果已正确配置 PlantUML 服务器，则应呈现一个不错的图而不是块：

在块内，您可以通过 PlantUML 添加任何受支持的图，例如Sequence ， Use Case ， Class ， Activity ， Component ， State和Object图. 您不需要使用 PlantUML 图定界符@startuml / @enduml因为它们已被 AsciiDoc plantuml块替换.

可以将一些参数添加到 AsciiDoc 块定义中：

• format ：可以是png或svg . 请注意，并非所有浏览器都支持svg ，因此请谨慎使用. 默认值为png .
• id ：添加到图 HTML 标记的 CSS ID.
• width ：宽度属性添加到图像标签.
• height ：高度属性添加到图像标签.

Markdown 不支持任何参数，并且将始终使用 PNG 格式.