{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- 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
您可以向块定义中添加参数:
-
id
: 添加到图表 HTML 标签的 CSS ID。 -
width
: 添加到图像标签的宽度属性。 -
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 服务器以生成图表:
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"
接下来,您可以:
Debian/Ubuntu
您可以在 Debian/Ubuntu 发行版中使用 Tomcat 或 Jetty 安装和配置 PlantUML 服务器。以下说明适用于 Tomcat。
先决条件:
- JRE/JDK 版本 11 或更高。
- (推荐)Jetty 版本 11 或更高。
- (推荐)Tomcat 版本 10 或更高。
安装
PlantUML 建议安装 Tomcat 10.1 或更高版本。本页面的范围仅包括设置基本的 Tomcat 服务器。
-
安装 JDK/JRE 11:
sudo apt update sudo apt install default-jre-headless graphviz git
-
为 Tomcat 添加用户:
sudo useradd -m -d /opt/tomcat -U -s /bin/false tomcat
-
安装和配置 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
-
创建一个 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
中看到的相同路径。 -
要配置端口,请编辑您的
/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"
- 将 Tomcat 关闭端口从
-
重新加载并启动 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))
-
安装 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 >}}
接下来,您可以:
-
配置本地 PlantUML 访问。确保链接中配置的
proxy_pass
端口与server.xml
中的 Connector 端口匹配。 - 验证 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 协议。
要启用此重定向:
-
根据您的设置方法,在
/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"
-
要激活更改,请运行以下命令:
sudo gitlab-ctl reconfigure
验证 PlantUML 安装
要验证安装是否成功:
-
直接测试 PlantUML 服务器:
# Docker 安装 curl --location --verbose "http://localhost:8005/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000" # Debian/Ubuntu 安装 curl --location --verbose "http://localhost:8005/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000"
您应该收到包含文本
hello
的 SVG 输出。 -
通过访问以下 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 集成:
- 以管理员用户身份登录极狐GitLab。
- 在左侧边栏的底部,选择 管理员。
- 在左侧边栏,转到 设置 > 常规 并展开 PlantUML 部分。
- 选择 启用 PlantUML 复选框。
- 将 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 文件进行小改动并提交。这将触发重新渲染。
- 使 Markdown 缓存失效 以强制清除数据库或 Redis 中的任何缓存 Markdown。
如果您仍然看不到更新的 URL,请检查以下内容:
- 确保极狐GitLab 实例可以访问 PlantUML 服务器。
- 验证您的极狐GitLab 设置中是否启用了 PlantUML 集成。
- 检查极狐GitLab 日志中与 PlantUML 渲染相关的错误。
- 清除您的极狐GitLab Redis 缓存。
在浏览器中打开 PlantUML 页面时出现 404
错误
当 PlantUML 服务器设置在 Debian 或 Ubuntu 中时,您可能会在访问 https://gitlab.example.com/-/plantuml/
时遇到 404
错误。
即使集成正常工作,也可能发生这种情况。这不一定表示您的 PlantUML 服务器或配置有问题。
要确认 PlantUML 是否正常工作,您可以验证 PlantUML 安装。