GitLab 项目中的 PlantUML 集成配置指南

沈书苹Peter

于 2025-06-03 09:02:29 发布

阅读量411

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00443/article/details/148392110

GitLab 项目中的 PlantUML 集成配置指南

gitlabhq GitLab CE Mirror | Please open new issues in our issue tracker on GitLab.com 项目地址: https://gitcode.com/gh_mirrors/gi/gitlabhq

什么是 PlantUML

PlantUML 是一个开源工具，允许用户通过简单的文本描述来创建各种 UML 图表。它支持多种图表类型，包括时序图、类图、用例图等。在 GitLab 中集成 PlantUML 后，用户可以直接在 Markdown、AsciiDoc 等文档中嵌入 UML 图表代码，GitLab 会自动将其渲染为可视化图表。

为什么要在 GitLab 中集成 PlantUML

文档可视化：技术文档中的架构图、流程图等可以实时更新，与代码保持同步
团队协作：所有成员都可以查看和编辑图表，版本控制与代码库集成
简化流程：无需额外工具，直接在 GitLab 中完成图表创建和维护

集成前的准备工作

在开始配置前，您需要：

确定 PlantUML 服务器的部署方式（Docker 或原生安装）
确保服务器有足够的资源运行 PlantUML 服务
了解您的 GitLab 实例的网络配置

两种部署 PlantUML 服务器的方式

1. Docker 部署（推荐）

这是最简单快捷的部署方式，适合大多数场景：

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

使用 Docker Compose 可以更好地管理服务：

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"

2. Debian/Ubuntu 原生部署

适合需要更精细控制的生产环境：

安装 Java 环境：

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

安装并配置 Tomcat：

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

部署 PlantUML 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

配置 GitLab 与 PlantUML 集成

配置 Nginx 反向代理：

# 在 /etc/gitlab/gitlab.rb 中添加
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n  rewrite ^/-/plantuml/(.*) /$1 break;\n  proxy_cache off; \n    proxy_pass  http://plantuml:8005/; \n}\n"

重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```
在 GitLab 管理界面启用 PlantUML：
- 以管理员身份登录
- 进入"管理区域" > "设置" > "通用"
- 展开"PlantUML"部分
- 勾选"启用 PlantUML"
- 设置 PlantUML 实例 URL 为 https://gitlab.example.com/-/plantuml/

使用 PlantUML 创建图表

在 Markdown 中使用

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

在 AsciiDoc 中使用

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

支持的图表类型

活动图
类图
组件图
对象图
时序图
状态图
用例图

安全配置建议

限制网络访问：配置 PlantUML 的安全策略，防止从不受信任的来源加载内容
禁用 SVG 输出：在 Nginx 配置中添加规则阻止 SVG 格式请求
```
location ~ ^/-/plantuml/svg/ {
    return 403;
}
```
定期更新：保持 PlantUML 服务器更新到最新版本