• 配置您的 PlantUML 服务器
  • Docker
    • 配置本地 PlantUML 访问
  • Debian/Ubuntu
    • 安装
    • 当在浏览器中打开 PlantUML 页面时出现 404 错误
  • 配置 PlantUML 安全
• 启用 PlantUML 集成
• 故障排查
  • 更新之后渲染的图标 URL 依旧保持相同

PlantUML

在极狐GitLab 中启用和配置 PlantUML 集成后，您可以在片段、wiki 和仓库中创建图表。此集成为所有 SaaS 用户启用，不需要任何额外配置。

在私有化部署实例上设置集成，您必须配置您的 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

您可以将参数添加到代码块定义：

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

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

配置您的 PlantUML 服务器

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

• 在 Docker 中.
• 在 Debian/Ubuntu 中.

Docker

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

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

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

在 Docker 中运行极狐GitLab 时，它必须有权访问 PlantUML 容器。为此，请使用 Docker Compose。在下面基本的 docker-compose.yml 文件中，极狐GitLab 可以通过 URL http://plantuml:8080/ 访问 PlantUML：

version: "3"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:12.2.5-ee.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

配置本地 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+无法加载不安全的 HTTP 资源。

要启用重定向：

1. 将如下内容添加到 /etc/gitlab/gitlab.rb：

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

2. 运行如下命令使配置生效：

   sudo gitlab-ctl reconfigure
   

Debian/Ubuntu

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

先决条件：

• JRE/JDK 版本为 11 及以后。
• (Recommended) Jetty 版本为 11 及以后。
• (Recommended) Tomcat 版本为 10 及以后。

安装

PlantUML 推荐安装 TOmcat 10 及以上版本。本页面的内容仅涵盖搭建基础的 Tomcat 服务器。关于生产就绪的配置，可以查看Tomcat 文档。

1. 安装 JDK/JRE 11：

   sudo apt update
   sudo apt-get install graphviz default-jdk git-core
   

2. 为 Tomcat 添加用户：

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

3. 安装并配置 Tomcat 10：

   wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.15/bin/apache-tomcat-10.1.15.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 并选择您的端口。避免使用 8080，因为 Puma 会在 8080 监听指标。

   <Server port="8006" shutdown="SHUTDOWN">
   ...
       <Connector port="8005" 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# netstat -plnt | grep java
   tcp6       0      0 127.0.0.1:8006          :::*                    LISTEN      14935/java
   tcp6       0      0 :::8005                 :::*                    LISTEN      14935/java
   

7. 在 /etc/gitlab/gitlab.rb 中修改您的 NGINX 配置。确保 proxy_pass 和 server.xml 中的连接器端口相匹配：

   nginx['custom_gitlab_server_config'] = "location /-/plantuml {
       rewrite ^/-/(plantuml.*) /$1 break;
       proxy_set_header  HOST               $host;
       proxy_set_header  X-Forwarded-Host   $host;
       proxy_set_header  X-Forwarded-Proto  $scheme;
       proxy_cache off;
       proxy_pass http://localhost:8005/plantuml;
   }"
   

8. 重新配置极狐GitLab 以读取新的变更：

   sudo gitlab-ctl reconfigure
   

9. 安装 PlantUML 并拷贝 .war 文件：

   使用最新版本的 plantuml-jsp（比如： plantuml-jsp-v1.2023.12.war）： Use the latest release of plantuml-jsp (example: plantuml-jsp-v1.2023.12.war).

   wget -P /tmp https://github.com/plantuml/plantuml-server/releases/download/v1.2023.12/plantuml-jsp-v1.2023.12.war
   sudo cp /tmp/plantuml-jsp-v1.2023.12.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

如要测试 PlantUML 服务器是否正常工作，运行 curl --location --verbose "http://localhost:8005/plantuml/"。

要改变 Tomcat 的默认配置，编辑 /opt/tomcat/conf/server.xml 文件。

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

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

即使集成配置正确，也可能会遇到此错误。这并不意味着您的 PlantUML 服务器或配置有问题。

配置 PlantUML 安全

PlantUML 具有允许获取网络资源的功能。如果您自托管 PlantUML 服务器，请设置网络控制来将其隔离。

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

启用 PlantUML 集成

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

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

取决于极狐GitLab 和 PlantUML 的版本，您可以还需要执行其他步骤。

• 对于运行 v1.2020.9 及更高版本的 PlantUML 服务器，例如 plantuml.com，您必须设置 PLANTUML_ENCODING 环境变量来启用 deflate 压缩。在 Omnibus GitLab 中，您可以使用以下命令在 /etc/gitlab.rb 中设置此值：

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

  在 GitLab Helm chart 中，您可以将变量添加到 global.extraEnv 部分，如下所示：

  global:
  extraEnv:
    PLANTUML_ENCODING: deflate
  

• deflate 是 PlantUML 的默认编码类型。要使用不同的编码类型，PlantUML 集成现在需要 URL 中的 header前缀，区分不同的编码类型。

故障排查

更新之后渲染的图标 URL 依旧保持相同

渲染图标被缓存。要查看更新，尝试如下步骤：

• 如果图标是 Markdown 文件，向 Markdown 文件做一个小改动。这会触发重新渲染。
• 无效的 Markdown 缓存会让数据库或 Reids 中任何缓存的 Markdown 被清除

如果您还是为看到更新的 URL，检查如下内容：

• 确保能够从极狐GitLab 实例访问 PlantUML 服务器。
• 验证极狐GitLab 设置中已启用了 PlantUML 集成。
• 检查与 PlantUML 渲染相关的极狐GitLab 日志。
• 清除您的极狐GitLab Redis 缓存。