PlantUML 在企业 wiki 嵌入：飞书 / Confluence / Notion 三套方案

企业内部文档沉淀：图比文字密度高，检索方便；但「PlantUML 源码 + 渲染图」怎么放在飞书 / Confluence / Notion 里仍然各异——这一篇列三种主流 wiki 的具体方案。

为什么企业 wiki 的图总是更麻烦？

个人博客（Hexo / Hugo）写 PlantUML 用渲染插件就行，但企业 wiki：

多人编辑：图和你都不一定能坚持维护
跨平台：手机 / iPad / PC 都需要正常展示
权限管理：每个 wiki 章节有不同可见性
不能依赖外部域名：飞书内部 wiki + 外网 plantuml.com 经常跨境不稳
导出要求：合规要求定期导出 PDF/HTML，图的格式不能崩

下面按飞书 / Confluence / Notion 三个常用工具分别说。

飞书（Lark / Feishu）文档

飞书文档的特色：自带 plantuml 渲染！直接在 /plantuml 代码块里写源码即可显示。

飞书原生支持

1
2
3

/plantuml
Alice -> Bob: Hi
Bob --> Alice: Hi back

文档顶部菜单 插入 → 代码块 → /plantuml。飞书服务器自动调 plantuml 渲染。

好处：

零配置，飞书自带渲染服务
自动同步到 wiki 主页

坑：

服务端跨境：飞书中国版用 PlantUML Server；但偶发渲染失败（OOM / 超时）
自定义主题：仅支持少数内置主题，自定义 !theme 不生效
皮肤配置：皮肤参数有时被飞书服务器忽略

客户端实时渲染（飞书小缺点补充方案）

如果服务端渲染失败，把以下代码粘到页面 <head> 里（飞书自定义 HTML 块）：

<script src="https://cdn.jsdelivr.net/npm/plantuml-encoder@1.4.0/lib/puml.min.js"></script>
<script>
document.querySelectorAll('.puml-fallback').forEach(el => {
  const code = el.textContent.trim();
  const encoded = plantumlEncoder.encode(code);
  el.innerHTML = `<img src="data:image/svg+xml,...">`;
});
</script>

实际是把服务端渲染失败的代码块降级到客户端用 plantuml.com 兜底。

飞书「妙搭」自建 PlantUML App

飞书的「妙搭」是一个零代码平台，能跑 docker 容器：

# 在妙搭里建一个应用，端口 8080
image: plantuml/plantuml-server
ports:
  - 8080:8080

然后在文档里用：

1 2	/plantuml-url http://your-miaoda-app.feishu.cn Alice -> Bob: Hi

妙搭是「飞书内网」环境，无跨境问题，企业内部用方便。

Confluence（Atlassian）

Confluence 没有原生 PlantUML 渲染——社区方案是装插件或自己搭。

方案 A：Confluence PlantUML 插件（官方）

Atlassian Marketplace 搜 “PlantUML”——付费插件 “PlantUML for Confluence”，每月 $5 起。

启用后：

安装好之后，单击 + → Other macros → PlantUML Diagram
在宏参数框里写 PlantUML 代码
Confluence 页面渲染时会调本地 Java + plantuml CLI 渲染

好处：嵌入的图直接 svg inline，可被 search API 索引。
坑：插件可能绑定 plantuml 旧版本（8.x/9.x 比官方慢一年）。

方案 B：自建 plantuml-server + macro

付费插件贵，但能自建。在 Confluence 数据中心版（Data Center/DC）里：

在 Confluence server 节点上部署 plantuml/plantuml-server docker
写一个 Confluence user macro（{plantumlserver}）调内部 API
在 Confluence 页面用 {plantumlserver} macro 把代码块转给内部 plantuml 服务渲染

// Confluence user macro 代码片段
public class PlantUMLServerMacro {
    @Override
    public String execute(...) {
        String body = parameters.get("body");
        String encoded = plantumlEncoder.encode(body);
        return "<img src='http://internal-plantuml:8080/svg/~h" + encoded + "'>";
    }
}

方案 C：嵌入图片（最朴素）

最朴素但最可靠的方案：在本地渲染图，导出 SVG/PNG，粘到 Confluence 页面。

plantuml -tsvg diagram.puml
# 用 rsync 推到 Confluence attachments
curl -u admin:token -X POST \
  -F "file=@diagram.svg" \
  -F "comment=PlantUML source diagram" \
  $CONFLUENCE/rest/api/latest/attachments

文档：source puml 在 git，渲染产物 svg 在 Confluence attachments。需要图同步？用 CI 自动 git diff --exit-code：

1 2	plantuml -tsvg docs/diagrams/system.puml diff docs/diagrams/system.svg $CONF_SVN_SYSTEM_SVG \|\| echo "图过期"

Confluence vs PlantUML 兼容

Confluence 7.x 默认禁用 inline <script>——客户端 plantuml 实时渲染需要管理员开启
Confluence Cloud 强制 https——内网 plantuml 服务器要么走 SSL，要么用 Confluence 反向代理
Confluence 的搜索默认不索引 inline SVG 内容——图里的中文字搜索不到，要给 image 加 <title> 或 alt=

Notion

Notion 的代码块渲染 Mermaid，但不渲染 PlantUML——必须自己解决。

方案 A：代码块 + Mermaid 替代

1
2
3

sequenceDiagram
  Alice->>Bob: Hi
  Bob-->>Alice: Hi back

如果你的图已经用 Mermaid 写就最简单——但 Notion 不支持 PlantUML，要么手写 Mermaid 要么加扩展。

方案 B：Notion API + plantuml server

Notion 的 webhook 是单向的；真正「自动同步图」的方案：

在 Notion page 里放一个代码块，写 PlantUML 源码
CI 任务轮询 Notion API 拿出源码，渲染成 SVG
把 SVG 上传回 Notion（API）替换图像

# notion_plantuml_sync.py
import requests, base64, urllib.parse

NOTION_TOKEN = "secret_..."

def render_puml_to_svg(puml_code):
    encoded = plantuml_encoder.encode(puml_code)
    r = requests.get(f"https://www.plantuml.com/plantuml/svg/~1{encoded}")
    return r.text  # raw SVG

# ... Notion API 拉代码块、塞 SVG、回传

工具链复杂，但企业内用起来顺。

方案 C：浏览器扩展（最简陋但能用）

浏览器扩展 PlantUML Visualizer：检测页面里的 text/plantuml 代码块，自动渲染成图。

坑：扩展只在自己电脑上生效；别人打开 Notion 页看不到图。

方案 D：嵌入 iframe 指向 puml.online

如果你的 wiki 在内部网络，可以建一个静态页面用 plantuml 渲染，然后 Notion 里嵌 <iframe>：

<iframe
  src="https://internal-puml.example.com/?code=...puml-encoded..."
  width="600" height="300" frameborder="0">
</iframe>

内网 puml 服务注意安全——别让用户随便往 URL 里塞 shellcode。

三套方案的对比

维度	飞书 wiki	Confluence	Notion
原生 PlantUML	✅（自家支持）	❌ 需插件/服务端	❌ 需自建
CJK 支持	✅（自带字体）	视插件版本	视方案
跨境问题	偶发（中国版）	主要在 DC 自建	客户端渲染避开
图源版本控制	飞书自带历史版本	Confluence page version	Notion page version
PDF 导出	✅ 内置	✅ 内置	❌ 只能 print
检索	飞书自带	全文 + 图附件名	仅检索 SVG 名字

落地的”最佳实践”

选择标准

飞书为主 → 直接用 /plantuml 代码块；配置飞书妙搭自建 plantuml 备份
Confluence DC（数据中心） → 付费插件值得（如果产品规模够大）；否则走 user macro + 内部 plantuml server
Confluence Cloud → 走 image 嵌入（方案 C）+ CI 同步图
Notion → 选 Mermaid 或自建内部图渲染服务；别尝试复杂方案

通用规约

不管哪个 wiki：

图源 + 图必须分开——图源（.puml）放 git（PR review），图存 wiki（直接看）
CI 验证——每个图有 CI 单元（渲染不报错 + 非空 SVG）
文末加 source block——wiki 图的下方贴 PlantUML 源码（让人能复制）
CJK 字体统一——所有图统一 skinparam defaultFontName "Noto Sans CJK SC"
定期导出 PDF——wiki 定期 export to PDF，图表也能保留

小结

飞书：原生支持，企业内部首选
Confluence：插件付费，用 image 嵌入 + CI 兜底
Notion：硬伤（不支持 PlantUML），建议改用 Mermaid 或自建