PlantUML 嵌入 Confluence / Jira / Notion 的实战做法

团队 wiki 是 PlantUML 图的最大消费场景。这篇是 Confluence / Jira / Notion 三家平台把 .puml 文件变成可点开 SVG 的落地经验,以及自托管 plantuml 服务在企业网络里的坑。

为什么 wiki 集成这么重要

PlantUML 的代码可以在 git 里 review,但评审者不会天天开 git。90% 的阅读发生在 Confluence / Jira / Notion 的页面里。如果 wiki 上的图永远是 PNG 截图,版本就跟代码脱钩了——设计改完三个月,wiki 里还是旧图。

理想的链路:*.puml 源文件在 git → CI 渲染成 SVG → 自动 push 回 wiki → wiki 页面永远显示最新版本。

Confluence 的三种写法

方案 A:PlantUML Macro 插件(Data Center 版自带)

Confluence Data Center 默认带一个 PlantUML plugin(wiki 管理员从 marketplace 装),写法跟 GitLab/GitHub 一样:

@startuml
Alice -> Bob: ping
Bob --> Alice: pong
@enduml

优点:零配置,所见即所得。

缺点:

默认指向 https://www.plantuml.com/plantuml(公共服务器),所有图发到第三方
企业内网无法访问 plantuml.com → 显示红框
没有版本管理,谁改了 puml 不知道

修法:管理员在 Confluence 管理后台把 PlantUML 服务器改成自托管地址:

1 2	Confluence Admin → Add-ons → PlantUML → Server URL http://plantuml.internal.company.com:8080

方案 B:用 `!include` 引用 Confluence 页面附件

1
2
3

@startuml
!include https://confluence.internal.company.com/download/attachments/123456/sequence.puml
@enduml

把 sequence.puml 作为附件上传到 Confluence 页面,然后用 !include 拉取。好处是单点管理,改一个文件所有页面同步更新。

方案 C:CI 自动渲染 + 上传图片

# .github/workflows/wiki-sync.yml
name: wiki-sync
on:
  push:
    paths: [docs/diagrams/**/*.puml]
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          docker run --rm -v $PWD:/data plantuml/plantuml \
            -tsvg docs/diagrams/**/*.puml
      - name: upload to confluence
        run: |
          for f in docs/diagrams/*.svg; do
            curl -u "$USER:$TOKEN" -X POST \
              -F "file=@$f" \
              -F "comment=auto-sync from git $GITHUB_SHA" \
              "https://confluence.internal.company.com/rest/api/content/123456/child/attachment"
          done

Jira 的特殊场景

Jira 工单里贴图不是为了文档化,是为了让评审/PR 评论能引用图。

最稳的写法:Jira 描述里直接写 PlantUML 文本 + plantuml.com/plantuml 链接:

[plantuml]
----
@startuml
participant User
participant API
User -> API: POST /login
API --> User: 200 OK
@enduml
----

新版 Jira Cloud 支持 {plantuml} macro,自动渲染。

Notion 的两种写法

Notion 没有原生 PlantUML 支持,只有 code block。

方案 A:嵌入已渲染的 SVG

把 SVG 文件上传到 Notion 的 file block,Notion 显示矢量图。图是死的,改 .puml 要重新上传。

方案 B:用 Notion API 自动同步

import requests
NOTION_TOKEN = "secret_..."
PAGE_ID = "..."

svg_path = "docs/diagrams/login-flow.svg"
with open(svg_path, "rb") as f:
    r = requests.patch(
        f"https://api.notion.com/v1/blocks/{PAGE_ID}/children",
        headers={"Authorization": f"Bearer {NOTION_TOKEN}",
                 "Notion-Version": "2022-06-28"},
        json={
            "children": [{
                "object": "block",
                "type": "image",
                "image": {"type": "external",
                          "external": {"url": f"https://github.com/your-org/repo/raw/main/docs/diagrams/login-flow.svg"}}
            }]
        })

安全/审计取舍

方式	数据流向	合规风险	实时性
plantuml.com 公共服务器	图内容 → 第三方	高(图里可能有架构/账号)	高
企业内自托管 plantuml 服务器	内网	低	高
CI 渲染 + 图片上传	图内容 → wiki(已审核)	低	延迟 1-2 分钟
用户手动截图	不出图	低	经常过期

原则:含架构/账号/IP 的图,绝不走 plantuml.com。自托管 plantuml 服务器内存占用低(<100MB),Docker 一行起:

1
2
3

docker run -d --name plantuml -p 8080:8080 \
  -e PLANTUML_SECURITY_PROFILE=strict \
  plantuml/plantuml-server:tomcat

PLANTUML_SECURITY_PROFILE=strict 关掉 !include 远程 URL,防止 SSRF。

常见踩坑

Confluence PlantUML macro 显示红框:内网访问不到 plantuml.com。改 server URL。
Jira Cloud {plantuml} 不渲染:Jira Cloud 默认禁用外部 macro,要管理员在 “Manage apps” 里启用。
Notion 上传的 SVG 显示模糊:Notion 对 SVG 有时会强制缩放,导出时加 width=100% 让 SVG 自身响应式。
CI 渲染失败但 wiki 不报错:wiki 端永远显示上一次成功的图。CI 要监控渲染产物数量,缺失就 fail。