PlantUML 和极狐GitLab
在极狐GitLab 中启用和配置 PlantUML 集成后,您可以在片段、wiki 和仓库中创建图表。此集成为所有 SaaS 用户启用,不需要任何额外配置。
在私有化部署实例上设置集成,您必须:
完成集成后,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 支持的任何图表,例如:
您可以将参数添加到代码块定义:
-
format
:可以是png
(默认)或svg
。谨慎使用svg
,因为并非所有浏览器都支持,Markdown 也不支持。 -
id
:添加到图表 HTML 标签的 CSS ID。 -
width
:添加到图像标签的宽度属性。 -
height
:添加到图像标签的高度属性。
Markdown 不支持任何参数,始终使用 PNG 格式。
配置您的 PlantUML 服务器
在极狐GitLab 中启用 PlantUML 之前,请设置您自己的 PlantUML 服务器来生成图表:
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
Debian/Ubuntu
您可以使用 Tomcat 在 Debian/Ubuntu 发行版中安装和配置 PlantUML 服务器:
-
运行以下命令,从源代码创建一个
plantuml.war
文件:sudo apt-get install graphviz openjdk-8-jdk git-core maven git clone https://github.com/plantuml/plantuml-server.git cd plantuml-server mvn package
-
使用以下命令部署上一步中的
.war
文件:sudo apt-get install tomcat8 sudo cp target/plantuml.war /var/lib/tomcat8/webapps/plantuml.war sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war sudo service tomcat8 restart
Tomcat 服务应该重新启动。 重启完成后,PlantUML 服务已准备就绪并正在侦听端口 8080 上的请求:http://localhost:8080/plantuml
要更改这些默认值,请编辑 /etc/tomcat8/server.xml
文件。
配置本地 PlantUML 访问
PlantUML 服务器在您的服务器上本地运行,因此默认情况下无法从外部访问。您的服务器必须捕获对 https://gitlab.example.com/-/plantuml/
的外部 PlantUML 调用,并将它们重定向到本地 PlantUML 服务器。根据您的设置,URL 为以下之一:
http://plantuml:8080/
http://localhost:8080/plantuml/
如果您使用 TLS 运行极狐GitLab,则必须配置此重定向,因为 PlantUML 使用不安全的 HTTP 协议。 Google Chrome 86+ 等较新的浏览器不会在通过 HTTPS 提供的页面上加载不安全的 HTTP 资源。
启用重定向:
-
根据您的设置方法,在
/etc/gitlab/gitlab.rb
中添加以下行:# Docker deployment nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n" # Built from source nginx['custom_gitlab_server_config'] = "location /-/plantuml { \n rewrite ^/-/(plantuml.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8080/plantuml; \n}\n"
-
要激活更改,请运行以下命令:
sudo gitlab-ctl reconfigure
配置 PlantUML 安全
PlantUML 具有允许获取网络资源的功能。如果您自托管 PlantUML 服务器,请设置网络控制来将其隔离。
@startuml
start
' ...
!include http://localhost/
stop;
@enduml
启用 PlantUML 集成
配置本地 PlantUML 服务器后,您就可以启用 PlantUML 集成:
- 以管理员用户身份登录极狐GitLab。
- 在顶部栏上,选择 主菜单 > 管理员。
- 在左侧边栏上,转到 设置 > 通用 并展开 PlantUML 部分。
- 选中 启用 PlantUML 复选框。
- 将 PlantUML 实例设置为
https://gitlab.example.com/-/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
-
对于极狐GitLab 13.1 及更高版本,PlantUML 集成现在需要 URL 中的 header前缀,区分不同的编码类型。