{{< details >}}

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

{{< /details >}}

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

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

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

  • Markdown 文件扩展名为 .md

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

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

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

    [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, 极狐GitLab 仅支持 caption 选项。

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

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

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

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

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

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

包含图表文件

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

  • Markdown

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

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

配置您的 PlantUML 服务器

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

  1. 推荐:在 Docker 中
  2. 在 Debian/Ubuntu 中

Docker

要在 Docker 中运行 PlantUML 容器,请运行以下命令:

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 访问:

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。

先决条件:

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

安装

PlantUML 建议安装 Tomcat 10.1 或更高版本。本页面的范围仅包括设置基本的 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 在端口 8080 上监听指标。
    - <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)。

    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 文件。

{{< alert type=”note” >}}

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

{{< /alert >}}

接下来,您可以:

  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 中添加以下行:

    # 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。您应该看到一个显示 hello 的渲染 PlantUML 图表。

    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 版本号,您可能还需要执行以下步骤:

  1. 对于运行 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
  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 安装