Help us learn about your current experience with the documentation. Take the survey.

PlantUML

  • 版本：免费、高级、旗舰
  • 产品：GitLab 自管理实例

使用 PlantUML 集成，在代码片段、Wiki 和仓库中创建图表。 GitLab.com 已为所有用户集成 PlantUML，无需额外配置。

要在 GitLab 自管理实例上设置此集成，必须配置您的 PlantUML 服务器。

完成集成后，PlantUML 会将 plantuml 代码块转换为 HTML 图像标签，源指向 PlantUML 实例。由于 plantuml 代码块会替换 PlantUML 图表分隔符 @startuml/@enduml，因此无需使用这些分隔符：

  • 扩展名为 .md 的 Markdown 文件：

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

    其他支持的扩展名请参考 languages.yaml 文件。

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

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

  • reStructuredText 文件：

    .. plantuml::
   :caption: 包含 **粗体** 和 *斜体* 的标题

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

    虽然可以使用 uml:: 指令兼容 sphinxcontrib-plantuml， 但 GitLab 仅支持 caption 选项。

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

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

在代码块内，可添加任何 PlantUML 支持的图表类型，例如：

为代码块定义添加参数：

  • id：添加到图表 HTML 标签的 CSS ID。
  • width：添加到图像标签的宽度属性。
  • height：添加到图像标签的高度属性。

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

包含图表文件

要在仓库中包含或嵌入独立的 PlantUML 图表文件，使用 include 指令。此功能可用于在专用文件中维护复杂图表，或复用图表。例如：

  • Markdown：

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

  • AsciiDoc：

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

配置 PlantUML 服务器

在 GitLab 中启用 PlantUML 前，需先搭建自己的 PlantUML 服务器以生成图表：

Docker

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

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

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

当 GitLab 在 Docker 中运行时，必须能访问 PlantUML 容器。使用 Docker Compose 可实现此需求。在以下基础 docker-compose.yml 文件中，GitLab 可通过 URL http://plantuml:8005/ 访问 PlantUML：

version: "3"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:17.9.1-ee.0'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n    rewrite ^/-/plantuml/(.*) /$1 break;\n proxy_cache off; \n    proxy_pass  http://plantuml:8005/; \n}\n"

  plantuml:
    image: 'plantuml/plantuml-server:tomcat'
    container_name: plantuml
    ports:
     - "8005:8080"

接下来您可以：

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

Debian/Ubuntu

可在 Debian/Ubuntu 系统中使用 Tomcat 或 Jetty 安装配置 PlantUML 服务器。以下说明针对 Tomcat。

前置要求：

  • JRE/JDK 11 或更高版本。
  • （推荐）Jetty 11 或更高版本。
  • （推荐）Tomcat 10 或更高版本。

安装步骤

PlantUML 推荐安装 Tomcat 10.1 或更高版本。本文档仅涵盖基础 Tomcat 服务器搭建，生产级配置请参考 Tomcat 文档。

  1. 安装 JDK/JRE 11：

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

  2. 为 Tomcat 添加用户：

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

  3. 安装并配置 Tomcat 10.1：

    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 文件并添加：

    [Unit]
Description=Tomcat
After=network.target

[Service]
Type=forking

User=tomcat
Group=tomcat

Environment="JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64"
Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom"
Environment="CATALINA_BASE=/opt/tomcat"
Environment="CATALINA_HOME=/opt/tomcat"
Environment="CATALINA_PID=/opt/tomcat/temp/tomcat.pid"
Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC"

ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh

RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

    JAVA_HOME 应与 sudo update-java-alternatives -l 显示的路径一致。

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

    • 将 Tomcat 关闭端口从 8005 改为 8006
    • 使用端口 8005 作为 Tomcat HTTP 端点。避免使用默认端口 8080，因为 Puma 在该端口监听指标。
    - <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：

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

    Java 进程应监听以下端口：

    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）。背景信息请参考 issue 265。

    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 服务器在本地运行，默认无法外部访问。服务器必须捕获外部对 https://gitlab.example.com/-/plantuml/ 的 PlantUML 调用，并将其重定向到本地 PlantUML 服务器。根据您的配置，URL 可能是以下之一：

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

如果运行启用 TLS 的 GitLab，必须配置此重定向，因为 PlantUML 使用不安全的 HTTP 协议。较新浏览器（如 Google Chrome 86+）不会在 HTTPS 页面加载不安全的 HTTP 资源。

启用此重定向：

  1. 根据您的安装方式，在 /etc/gitlab/gitlab.rb 中添加以下行：

    # 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. 运行以下命令激活更改：

    sudo gitlab-ctl reconfigure

验证 PlantUML 安装

验证安装是否成功：

  1. 直接测试 PlantUML 服务器：

    # 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：

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

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

    Bob -> Alice : hello

配置 PlantUML 安全性

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

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

保护 PlantUML SVG 图表输出

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

要禁用 SVG 输出路由，在托管 PlantUML 服务的 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 版本号，可能还需要执行以下步骤：

  • 对于运行 v1.2020.9 及更高版本的 PlantUML 服务器（如 plantuml.com），必须设置 PLANTUML_ENCODING 环境变量以启用 deflate 压缩。在 Linux 包安装中，可通过以下命令在 /etc/gitlab/gitlab.rb 中设置：

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

    在 GitLab Helm chart 中，可通过向 global.extraEnv 部分添加变量来设置：

    global:
extraEnv:
  PLANTUML_ENCODING: deflate

  • deflate 是 PlantUML 的默认编码类型。要使用其他编码类型，PlantUML 集成需要在 URL 中添加头前缀以区分不同编码类型。

故障排除

更新后渲染的图表 URL 未改变

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

  • 如果图表在 Markdown 文件中，对文件做微小修改并提交。这会触发重新渲染。
  • 使 Markdown 缓存失效 以强制清除数据库或 Redis 中的缓存。

如果仍未看到更新的 URL，请检查以下项：

  • 确保 GitLab 实例可访问 PlantUML 服务器。
  • 验证 GitLab 设置中是否启用了 PlantUML 集成。
  • 检查 GitLab 日志中是否有 PlantUML 渲染相关的错误。
  • 清除 GitLab Redis 缓存。

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

当 PlantUML 服务器在 Debian 或 Ubuntu 中搭建时，访问 https://gitlab.example.com/-/plantuml/ 可能出现 404 错误。

即使集成正常工作也可能发生此情况。这不一定表示 PlantUML 服务器或配置存在问题。

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