PlantUML & GitLab · Gitlab 中文文檔

# PlantUML & GitLab > 原文：[https://docs.gitlab.com/ee/administration/integration/plantuml.html](https://docs.gitlab.com/ee/administration/integration/plantuml.html) * [PlantUML Server](#plantuml-server) * [Docker](#docker) * [Debian/Ubuntu](#debianubuntu) * [Making local PlantUML accessible using custom GitLab setup](#making-local-plantuml-accessible-using-custom-gitlab-setup) * [Security](#security) * [GitLab](#gitlab) * [Creating Diagrams](#creating-diagrams) # PlantUML & GitLab[](#plantuml--gitlab "Permalink") 在 GitLab 8.16 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) . 在 GitLab 中啟用并配置[PlantUML](https://plantuml.com)集成后，我們便能夠在片段，Wiki 和存儲庫中創建的 AsciiDoc 和 Markdown 文檔中創建簡單的圖表. ## PlantUML Server[](#plantuml-server "Permalink") 在 GitLab 中啟用 PlantUML 之前；您需要設置自己的 PlantUML 服務器以生成圖表. ### Docker[](#docker "Permalink") 使用 Docker，您可以僅運行如下容器： ``` docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat ``` **PlantUML URL**將是運行容器的服務器的主機名. 在 Docker 中運行 GitLab 時，它將需要有權訪問 PlantUML 容器. 最簡單的方法是使用[Docker Compose](https://s0docs0docker0com.icopy.site/compose/) . 一個簡單`docker-compose.yml`文件將是： ``` version: "3" services: gitlab: image: 'gitlab/gitlab-ce:12.2.5-ce.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 ``` 在這種情況下，可以通過 URL `http://plantuml:8080/`訪問 GitLab 的`http://plantuml:8080/` . ### Debian/Ubuntu[](#debianubuntu "Permalink") 在使用 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 ``` 上面的命令序列將生成可以使用 Tomcat 部署的 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`文件來更改這些默認值. 請注意，默認 URL 與使用基于 Docker 的映像時不同，后者在 URL 的根目錄中提供服務，而沒有相對路徑. 相應地調整以下配置. ### Making local PlantUML accessible using custom GitLab setup[](#making-local-plantuml-accessible-using-custom-gitlab-setup "Permalink") PlantUML 服務器在您的服務器上本地運行，因此無法從外部訪問. 因此，有必要捕獲外部 PlantUML 調用并將其重定向到本地服務器. 想法是將每次調用`https://gitlab.example.com/-/plantuml/`重定向到本地 PlantUML 服務器`http://plantuml:8080/`或`http://localhost:8080/plantuml/` ，具體取決于您的建立. 要啟用重定向，請在`/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 ``` ### Security[](#security "Permalink") PlantUML 具有允許獲取網絡資源的功能. ``` @startuml start ' ... !include http://localhost/ stop; @enduml ``` **如果您自行托管 PlantUML 服務器，則應放置網絡控件以隔離它.** ## GitLab[](#gitlab "Permalink") 您需要從"管理"區域下的"設置"啟用 PlantUML 集成. 為此，請使用管理員帳戶登錄并執行以下操作： * 在 GitLab 中，轉到**管理區域>設置>集成** . * 展開**PlantUML**部分. * Check **啟用 PlantUML** checkbox. * Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. **注意：**如果使用的是運行 v1.2020.9 及更高版本的 PlantUML 服務器（例如[plantuml.com](https://plantuml.com) ），請設置`PLANTUML_ENCODING`環境變量以啟用`deflate`壓縮. 在 Omnibus 上，可以在`/etc/gitlab.rb`進行設置： ``` gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' } ``` 從 GitLab 13.1 和更高版本開始，PlantUML 集成現在[需要 URL 中的標頭前綴](https://github.com/plantuml/plantuml/issues/117#issuecomment-6235450160)來區分不同的編碼類型. ## Creating Diagrams[](#creating-diagrams "Permalink") 啟用并配置 PlantUML 集成后，我們可以開始使用分隔的塊向我們的 AsciiDoc 代碼片段，Wiki 和存儲庫添加圖表： * **Markdown** ``` ```plantuml Bob -> Alice : hello Alice -> Bob : hi ``` ``` * **AsciiDoc** ``` [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`](https://s0pypi0org.icopy.site/project/sphinxcontrib-plantuml/)兼容，但是請注意，我們目前僅支持`caption`選項. 上面的塊將被轉換為 HTML 圖像標簽，其源指向 PlantUML 實例. 如果已正確配置 PlantUML 服務器，則應呈現一個不錯的圖而不是塊： ![](https://img.kancloud.cn/e8/b2/e8b2a887b7db3fa71ccc3ee6d1ec34e3_120x155.png) 在塊內，您可以通過 PlantUML 添加任何受支持的圖，例如[Sequence](https://plantuml.com/sequence-diagram) ， [Use Case](https://plantuml.com/use-case-diagram) ， [Class](https://plantuml.com/class-diagram) ， [Activity](https://plantuml.com/activity-diagram-legacy) ， [Component](https://plantuml.com/component-diagram) ， [State](https://plantuml.com/state-diagram)和[Object](https://plantuml.com/object-diagram)圖. 您不需要使用 PlantUML 圖定界符`@startuml` / `@enduml`因為它們已被 AsciiDoc `plantuml`塊替換. 可以將一些參數添加到 AsciiDoc 塊定義中： * `format` ：可以是`png`或`svg` . 請注意，并非所有瀏覽器都支持`svg` ，因此請謹慎使用. 默認值為`png` . * `id` ：添加到圖 HTML 標記的 CSS ID. * `width` ：寬度屬性添加到圖像標簽. * `height` ：高度屬性添加到圖像標簽. Markdown 不支持任何參數，并且將始終使用 PNG 格式.