极狐 GitLab Logo

PlantUML

  1. Tier: 基础版, 专业版, 旗舰版
  2. Offering: 私有化部署

通过 PlantUML 集成，您可以在代码片段、维基和代码库中创建图表。此集成在 JihuLab.com 上为所有用户启用，不需要任何额外配置。

要在您的极狐GitLab私有化部署实例上设置集成，您必须配置您的 PlantUML 服务器。

完成集成后，PlantUML 将 plantuml 块转换为 HTML 图像标签，源指向 PlantUML 实例。不再需要 PlantUML 图表分隔符 @startuml/@enduml，因为这些被 plantuml 块替代：

  • Markdown 文件扩展名为 .md：

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

    有关其他可接受的扩展名，请查看 languages.yaml 文件。

  • AsciiDoc 文件扩展名为 .asciidoc、.adoc 或 .asc：

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

  • reStructuredText

    plaintext
    .. plantuml::
   :caption: Caption with **bold** and *italic*

   Bob -> Alice: hello
   Alice -> Bob: hi

    尽管您可以使用 uml:: 指令以兼容 sphinxcontrib-plantuml， 极狐GitLab 仅支持 caption 选项。

如果 PlantUML 服务器配置正确，这些示例应该渲染出图表而不是代码块：

正在加载 PlantUML 图表...

在块内，您可以添加 PlantUML 支持的任何图表，例如：

  • Activity
  • Class
  • Component
  • Object
  • Sequence
  • State
  • Use Case

您可以向块定义中添加参数：

  1. id: 添加到图表 HTML 标签的 CSS ID。
  2. width: 添加到图像标签的宽度属性。
  3. height: 添加到图像标签的高度属性。

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

包含图表文件#

您可以使用 include 指令从代码库中的单独文件中包含或嵌入 PlantUML 图表。使用此功能可以在专用文件中维护复杂图表，或重用图表。例如：

  • Markdown：

    markdown
    ```plantuml
::include{file=diagram.puml}
```

  • AsciiDoc：

    plaintext
    [plantuml, format="png", id="myDiagram", width="200px"]
----
include::diagram.puml[]
----

配置您的 PlantUML 服务器#

在您可以在极狐GitLab 中启用 PlantUML 之前，设置您自己的 PlantUML 服务器以生成图表：

  1. 推荐：在 Docker 中。
  2. 在 Debian/Ubuntu 中。

Docker#

要在 Docker 中运行 PlantUML 容器，请运行以下命令：

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

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

当在 Docker 中运行极狐GitLab 时，它必须能够访问 PlantUML 容器。为此，请使用 Docker Compose。在这个基本的 docker-compose.yml 文件中，PlantUML 可以通过 URL http://plantuml:8005/ 被极狐GitLab 访问：

yaml
1version: "3"
2services:
3  gitlab:
4    image: 'gitlab/gitlab-ee:17.9.1-ee.0'
5    environment:
6      GITLAB_OMNIBUS_CONFIG: |
7        nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n    rewrite ^/-/plantuml/(.*) /$1 break;\n proxy_cache off; \n    proxy_pass  http://plantuml:8005/; \n}\n"
8
9  plantuml:
10    image: 'plantuml/plantuml-server:tomcat'
11    container_name: plantuml
12    ports:
13     - "8005:8080"

接下来，您可以：

  1. 配置本地 PlantUML 访问
  2. 验证 PlantUML 安装 是否成功

Debian/Ubuntu#

您可以在 Debian/Ubuntu 发行版中使用 Tomcat 或 Jetty 安装和配置 PlantUML 服务器。以下说明适用于 Tomcat。

先决条件：

  1. JRE/JDK 版本 11 或更高。
  2. （推荐）Jetty 版本 11 或更高。
  3. （推荐）Tomcat 版本 10 或更高。

安装#

PlantUML 建议安装 Tomcat 10.1 或更高版本。本页面的范围仅包括设置基本的 Tomcat 服务器。

  1. 安装 JDK/JRE 11：

    shell
    sudo apt update
sudo apt install default-jre-headless graphviz git

  2. 为 Tomcat 添加用户：

    shell
    sudo useradd -m -d /opt/tomcat -U -s /bin/false tomcat

  3. 安装和配置 Tomcat 10.1：

    shell
    wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.33/bin/apache-tomcat-10.1.33.tar.gz -P /tmp
sudo tar xzvf /tmp/apache-tomcat-10*tar.gz -C /opt/tomcat --strip-components=1
sudo chown -R tomcat:tomcat /opt/tomcat/
sudo chmod -R u+x /opt/tomcat/bin

  4. 创建一个 systemd 服务。编辑 /etc/systemd/system/tomcat.service 文件并添加：

    shell
    1[Unit]
2Description=Tomcat
3After=network.target
4
5[Service]
6Type=forking
7
8User=tomcat
9Group=tomcat
10
11Environment="JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64"
12Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom"
13Environment="CATALINA_BASE=/opt/tomcat"
14Environment="CATALINA_HOME=/opt/tomcat"
15Environment="CATALINA_PID=/opt/tomcat/temp/tomcat.pid"
16Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC"
17
18ExecStart=/opt/tomcat/bin/startup.sh
19ExecStop=/opt/tomcat/bin/shutdown.sh
20
21RestartSec=10
22Restart=always
23
24[Install]
25WantedBy=multi-user.target

    JAVA_HOME 应该是 sudo update-java-alternatives -l 中看到的相同路径。

  5. 要配置端口，请编辑您的 /opt/tomcat/conf/server.xml 并选择您的端口。推荐：

    • 将 Tomcat 关闭端口从 8005 改为 8006
    • 使用端口 8005 作为 Tomcat HTTP 端点。应避免使用默认端口 8080，因为 Puma 在端口 8080 上监听指标。
    diff
    - <Server port="8006" shutdown="SHUTDOWN">
+ <Server port="8005" shutdown="SHUTDOWN">

- <Connector port="8005" protocol="HTTP/1.1"
+ <Connector port="8080" protocol="HTTP/1.1"

  6. 重新加载并启动 Tomcat：

    shell
    sudo systemctl daemon-reload
sudo systemctl start tomcat
sudo systemctl status tomcat
sudo systemctl enable tomcat

    Java 进程应在这些端口上监听：

    shell
    root@gitlab-omnibus:/plantuml-server# ❯ ss -plnt | grep java
LISTEN   0        1          [::ffff:127.0.0.1]:8006                   *:*       users:(("java",pid=27338,fd=52))
LISTEN   0        100                         *:8005                   *:*       users:(("java",pid=27338,fd=43))

  7. 安装 PlantUML 并复制 .war 文件：

    使用最新版本的 plantuml-jsp（例如：plantuml-jsp-v1.2024.8.war）。

    shell
    wget -P /tmp https://github.com/plantuml/plantuml-server/releases/download/v1.2024.8/plantuml-jsp-v1.2024.8.war
sudo cp /tmp/plantuml-jsp-v1.2024.8.war /opt/tomcat/webapps/plantuml.war
sudo chown tomcat:tomcat /opt/tomcat/webapps/plantuml.war
sudo systemctl restart tomcat

Tomcat 服务应重新启动。重新启动完成后，PlantUML 集成已准备好并在端口 8005 上监听请求：http://localhost:8005/plantuml。

要更改 Tomcat 默认值，请编辑 /opt/tomcat/conf/server.xml 文件。

使用此方法时，默认 URL 不同。基于 Docker 的镜像使服务在根 URL 上可用，没有相对路径。相应地调整下面的配置。

接下来，您可以：

  1. 配置本地 PlantUML 访问。确保链接中配置的 proxy_pass 端口与 server.xml 中的 Connector 端口匹配。
  2. 验证 PlantUML 安装 是否成功。

配置本地 PlantUML 访问#

PlantUML 服务器在您的服务器上本地运行，因此默认情况下无法从外部访问。您的服务器必须捕获外部 PlantUML 调用到 https://gitlab.example.com/-/plantuml/ 并将其重定向到本地 PlantUML 服务器。根据您的设置，URL 可以是以下之一：

  • http://plantuml:8080/
  • http://localhost:8080/plantuml/
  • http://plantuml:8005/
  • http://localhost:8005/plantuml/

如果您正在运行 极狐GitLab 并使用 TLS，您必须配置此重定向，因为 PlantUML 使用不安全的 HTTP 协议。

要启用此重定向：

  1. 根据您的设置方法，在 /etc/gitlab/gitlab.rb 中添加以下行：

    ruby
    # Docker 安装
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n  rewrite ^/-/plantuml/(.*) /$1 break;\n  proxy_cache off; \n    proxy_pass  http://plantuml:8005/; \n}\n"

# Debian/Ubuntu 安装
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n  rewrite ^/-/plantuml/(.*) /$1 break;\n  proxy_cache off; \n    proxy_pass  http://localhost:8005/plantuml; \n}\n"

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

    shell
    sudo gitlab-ctl reconfigure

验证 PlantUML 安装#

要验证安装是否成功：

  1. 直接测试 PlantUML 服务器：

    shell
    # Docker 安装
curl --location --verbose "http://localhost:8005/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000"

# Debian/Ubuntu 安装
curl --location --verbose "http://localhost:8005/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000"

    您应该收到包含文本 hello 的 SVG 输出。

  2. 通过访问以下 URL 测试极狐GitLab 能否通过 NGINX 访问 PlantUML：

    plaintext
    http://gitlab.example.com/-/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

    将 gitlab.example.com 替换为您的极狐GitLab 实例 URL。您应该看到一个显示 hello 的渲染 PlantUML 图表。

    plaintext
    Bob -> Alice : hello

配置 PlantUML 安全性#

PlantUML 具有允许获取网络资源的功能。如果您自托管 PlantUML 服务器，请实施网络控制以隔离它。例如，利用 PlantUML 的安全配置文件。

plaintext
1@startuml
2start
3    ' ...
4    !include http://localhost/
5stop;
6@enduml

确保 PlantUML SVG 图表输出安全#

在生成 SVG 格式的 PlantUML 图表时，配置您的服务器以增强安全性。在您的 NGINX 配置中禁用 SVG 输出路由，以防止潜在的安全问题。

要禁用 SVG 输出路由，请在托管 PlantUML 服务的 NGINX 服务器上添加以下配置：

nginx
location ~ ^/-/plantuml/svg/ {
    return 403;
}

此配置可防止潜在的恶意图表代码在浏览器中执行。

启用 PlantUML 集成#

在配置好本地 PlantUML 服务器后，您就可以启用 PlantUML 集成：

  1. 以管理员用户身份登录极狐GitLab。
  2. 在左侧边栏的底部，选择 管理员。
  3. 在左侧边栏，转到 设置 > 常规 并展开 PlantUML 部分。
  4. 选择 启用 PlantUML 复选框。
  5. 将 PlantUML 实例设置为 https://gitlab.example.com/-/plantuml/，然后选择 保存更改。

根据您的 PlantUML 和极狐GitLab 版本号，您可能还需要执行以下步骤：

  1. 对于运行 v1.2020.9 及更高版本的 PlantUML 服务器，例如 plantuml.com，您必须设置 PLANTUML_ENCODING 环境变量以启用 deflate 压缩。在 Linux 包安装中，您可以通过以下命令在 /etc/gitlab/gitlab.rb 中设置此值：
ruby
gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }

在极狐GitLab Helm chart 中，您可以通过向 global.extraEnv 部分添加一个变量来设置它，如下所示：

yaml
global:
extraEnv:
  PLANTUML_ENCODING: deflate
  1. deflate 是 PlantUML 的默认编码类型。要使用其他编码类型，PlantUML 集成 需要 URL 中的头部前缀 来区分不同的编码类型。

故障排除#

渲染的图表 URL 更新后保持不变#

渲染的图表会被缓存。要查看更新，请尝试以下步骤：

  1. 如果图表在 Markdown 文件中，请对 Markdown 文件进行小改动并提交。这将触发重新渲染。
  2. 使 Markdown 缓存失效 以强制清除数据库或 Redis 中的任何缓存 Markdown。

如果您仍然看不到更新的 URL，请检查以下内容：

  1. 确保极狐GitLab 实例可以访问 PlantUML 服务器。
  2. 验证您的极狐GitLab 设置中是否启用了 PlantUML 集成。
  3. 检查极狐GitLab 日志中与 PlantUML 渲染相关的错误。
  4. 清除您的极狐GitLab Redis 缓存。

在浏览器中打开 PlantUML 页面时出现 404 错误#

当 PlantUML 服务器设置在 Debian 或 Ubuntu 中时，您可能会在访问 https://gitlab.example.com/-/plantuml/ 时遇到 404 错误。

即使集成正常工作，也可能发生这种情况。这不一定表示您的 PlantUML 服务器或配置有问题。

要确认 PlantUML 是否正常工作，您可以验证 PlantUML 安装。