1. Ubuntu 上 PlantUML 到底解决什么问题PlantUML 是一个用纯文本描述图表的工具你写几行类似伪代码的语句它就能渲染出序列图、用例图、类图、活动图、组件图、状态图等十几种 UML 图还支持 JSON、YAML、网络拓扑、甘特图、思维导图等非 UML 图形。它适合谁后端开发写接口时序、架构师画组件依赖、测试同学梳理用例流程、技术文档作者维护图文同步——只要你想让图和代码一样能进 Git、能 diff、能 reviewPlantUML 就是那个把图形变成文本的桥梁。在 Ubuntu 上从零搭建这条绘图链路核心就三件事装好 Java 运行时、装好 PlantUML 本体或 VS Code 插件、配好渲染环境。听起来简单但实际踩坑点集中在 Java 版本不匹配、Graphviz 缺失导致部分图渲染失败、VS Code 插件找不到 java 可执行文件这几处。这篇就按安装 → 插件接入 → 序列图语法逐段拆 → 配置骨架 → 渲染验证 → 报错排查的顺序走一遍每一步都给可复制的命令和配置。另外如果你在团队里想让多个项目共用一套模型调用凭证避免每个仓库都散落一份 Key可以借助 TaoToken 做统一 Key 管理把模型对话、编码辅助的调用入口收敛到一处。下面会在配置骨架里给出接入片段但主线仍然是 PlantUML 本身。2. 前置环境Java 与 Graphviz 检查PlantUML 本体是一个 Java 程序所以第一步永远是确认 Java 环境。Ubuntu 上推荐用 apt 装 OpenJDK版本选 11 或 17 都行不必死守老教程里的 8。sudo apt update sudo apt install -y openjdk-17-jdk java -version执行后你应该看到类似openjdk version 17.0.x的输出。如果java -version报 command not found说明 PATH 没配好可以用update-alternatives --config java检查候选。接着装 Graphviz。PlantUML 的序列图其实不依赖 Graphviz但类图、组件图、状态图等需要它做布局缺了会报Dot executable does not exist或Cannot find Graphviz。sudo apt install -y graphviz dot -Vdot -V正常会打印dot - graphviz version 2.x.x。这两个依赖到位后再装 PlantUML 本体sudo apt install -y plantuml plantuml -version如果你不想用 apt 版本有时偏旧也可以直接下载官方 jarwget -O plantuml.jar https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar java -jar plantuml.jar -version命令行方式适合 CI 里批量渲染日常写图还是靠编辑器插件更顺手。3. VS Code 插件接入与 settings.json 骨架在 VS Code 里搜两个插件安装PlantUML作者 jebbs和Graphviz Interactive Preview可选用于预览 dot 文件。装完后PlantUML 插件默认会去找系统 java但 Ubuntu 上多版本共存时经常找错所以要在 settings.json 里显式指定。打开命令面板CtrlShiftP输入Preferences: Open User Settings (JSON)把下面这段骨架贴进去。注意路径按你实际的 java 位置改which java可以查到。{ plantuml.server: https://www.plantuml.com/plantuml, plantuml.render: Local, plantuml.java: /usr/bin/java, plantuml.jar: /usr/share/plantuml/plantuml.jar, plantuml.commandArgs: [-Djava.awt.headlesstrue], plantuml.diagramsRoot: docs/diagrams, plantuml.exportOutDir: docs/diagrams/out, plantuml.exportFormat: png, plantuml.exportSubFolder: false, plantuml.previewAutoUpdate: true }几个关键项说明plantuml.render设为Local表示本地渲染不把图内容发到公共服务器plantuml.java和plantuml.jar是本地渲染的两个必需路径plantuml.commandArgs加 headless 参数避免在无图形界面的服务器上渲染时报 AWT 相关错误。如果你用 apt 装的 plantumljar 路径通常是/usr/share/plantuml/plantuml.jar用dpkg -L plantuml | grep jar可以确认。如果你希望把模型调用凭证也统一管理可以在同一份 settings.json 里加一段 TaoToken 的接入配置。TaoToken 提供统一的 API Key 入口把模型对话、编码辅助等调用收敛到一处避免每个项目各存一份。配置片段如下Key 从控制台生成后填入{ taotoken.apiBase: https://taotoken.net/api, taotoken.apiKey: sk-你的统一Key, taotoken.defaultModel: claude-sonnet, taotoken.timeoutMs: 60000 }这段配置本身不参与 PlantUML 渲染它的作用是让编辑器里的 AI 辅助、代码补全等能力走同一个 Key。生成 Key 的入口在控制台的 API Keys 页面接入细节可参考官方接入文档。这样团队协作时换人只需换一处 Key不用翻遍每个仓库的配置文件。4. 序列图核心语法逐段拆解序列图是 PlantUML 最常用的图型语法直观到几乎可以当伪代码读。下面按participant、activate、alt三个核心关键字逐段拆。4.1 participant 声明参与者最简单的序列图不声明参与者也能画箭头两端直接写名字即可startuml Alice - Bob: Authentication Request Bob -- Alice: Authentication Response enduml但一旦你想控制参与者顺序、改显示名、换图标形状就得用participant。声明顺序就是默认显示顺序as可以起别名startuml participant 前端 as FE participant 网关 as GW participant 用户服务 as US FE - GW: POST /login GW - US: verify(username, password) US -- GW: token GW -- FE: 200 OK enduml除了participant还有actor角色、boundary边界、control控制、entity实体、database数据库、collections集合、queue队列等关键字用来改变参与者的图形表示。比如画一个带数据库的登录流程startuml actor User participant API as API database MySQL as DB User - API: 提交登录 API - DB: SELECT * FROM users DB -- API: 用户记录 API -- User: 返回 token enduml4.2 activate/deactivate 表示生命周期activate和deactivate用来表示参与者在某段时间内处于活跃状态渲染出来是一条竖着的矩形条。配合destroy还能表示参与者生命线终结。startuml participant User participant 服务A as A participant 服务B as B User - A: DoWork activate A A - B: createRequest activate B B - B: 内部处理 B -- A: RequestCreated deactivate B A - User: Done deactivate A enduml这段里 A 被激活后一直保持活跃直到deactivate AB 在收到请求后激活处理完就退出。实际画接口调用链时这个机制能清晰表达谁在什么时候占用资源。4.3 alt/else 表达条件分支alt用于条件分支else是另一条分支end收尾。画登录成功/失败两条路径startuml participant User participant 认证服务 as Auth database 用户库 as DB User - Auth: 提交账号密码 activate Auth Auth - DB: 查询用户 activate DB DB -- Auth: 用户记录 deactivate DB alt 密码正确 Auth -- User: 返回 token else 密码错误 Auth -- User: 401 Unauthorized end deactivate Auth endumlalt还可以嵌套loop比如最多重试 3 次的场景startuml participant Client participant Server Client - Server: 请求 loop 重试次数 3 Server -- Client: 失败 Client - Server: 重试 end Server -- Client: 成功 enduml4.4 消息编号与注释autonumber自动给消息编号note left/right加注释title加标题header/footer加页眉页脚。这几个组合起来图的可读性会明显提升startuml title 订单创建序列图 autonumber participant 客户端 as C participant 订单服务 as O participant 库存服务 as S C - O: 创建订单 note right: 校验参数 O - S: 扣减库存 alt 库存充足 S -- O: 扣减成功 O -- C: 订单号 else 库存不足 S -- O: 扣减失败 O -- C: 下单失败 end endumlautonumber还支持autonumber 1.1.1这种多级编号以及autonumber inc A递增某一位适合画复杂的分层流程。5. 渲染验证与成功结果配置和语法都就位后验证分两步命令行渲染和编辑器预览。命令行方式最直接把上面的序列图存成login.puml然后plantuml -tpng login.puml如果用的是 jarjava -jar plantuml.jar -tpng login.puml执行后同目录会生成login.png。如果没报错且图片能打开说明 Java、Graphviz、PlantUML 三者链路通了。批量渲染整个目录plantuml -tpng docs/diagrams/*.puml编辑器里则是打开.puml文件后按AltD右侧会弹出预览面板。预览面板上方有一排小工具鼠标悬停会显示功能其中复制图标可以把当前图复制到剪贴板。如果预览一直转圈或报错先看 VS Code 的输出面板选PlantUML通道里面会打印实际调用的 java 命令和错误堆栈。成功渲染的序列图应该能看到参与者方框、带箭头的消息线、激活条和 alt 分支框。如果图出来了但布局很乱多半是 Graphviz 没装或版本太旧dot -V确认一下。6. 本篇常见报错排查清单下面这些是我在 Ubuntu 上实际遇到过的报错按出现频率排序。报错一Cannot find java或java: command not found插件找不到 java。先which java确认路径然后在 settings.json 里把plantuml.java写成绝对路径。如果系统有多个 JDK用update-alternatives --config java切换默认版本。报错二Dot executable does not existGraphviz 没装或不在 PATH。执行sudo apt install -y graphviz再用dot -V验证。如果装了还报错检查plantuml.commandArgs里是否误加了-DGRAPHVIZ_DOT之类的参数。报错三java.awt.HeadlessException在无图形界面的服务器上渲染时报这个。在plantuml.commandArgs里加-Djava.awt.headlesstrue或者命令行加-Djava.awt.headlesstrue参数。报错四预览面板空白但命令行能渲染多半是插件配置的 jar 路径不对。用dpkg -L plantuml | grep jar找到真实路径填到plantuml.jar。如果用的是手动下载的 jar路径要指向你下载的位置。报错五Error line 1: Syntax Error语法错误。常见原因是startuml和enduml不配对或者箭头写成了中文全角。检查每一行的箭头符号必须是半角-、--、-、--。报错六中文显示成方框系统缺中文字体。装一下sudo apt install -y fonts-noto-cjk然后重启 VS Code。如果还不行在 puml 文件里加skinparam defaultFontName Noto Sans CJK SC。报错七渲染超时图太大或服务器响应慢。本地渲染一般不会超时如果用的是远程 server 模式把plantuml.server换回本地或者调大plantuml.previewAutoUpdate的延迟。排查顺序建议先java -version再dot -V再plantuml -version最后看 VS Code 输出面板的 PlantUML 日志。这三条命令能覆盖 90% 的环境问题。7. 统一 Key 与后续接入PlantUML 这条链路本身不依赖外部服务但如果你在同一个编辑器里还跑 AI 辅助编码、模型对话把 Key 统一管理会省很多事。TaoToken 的接入入口有三个常用位置模型对话用于验证模型连通性Coding Plan 适合长期编码和 Agent 场景API Keys 页面用于生成和管理凭证。配置骨架上面已经给过核心就是apiBase指向https://taotoken.net/apiKey 从控制台生成后填入。接入文档里有各语言 SDK 的调用示例如果你要在 CI 里做 PlantUML 渲染的同时调用模型做图描述生成可以参考文档里的请求格式。实际用下来统一 Key 最大的好处是换项目不用重新配团队里换人也不用挨个仓库改配置。最后留一个实用技巧把docs/diagrams目录纳入 Git.puml源文件和渲染出的.png一起提交review 时直接看 diff 就能知道图改了什么。PlantUML 的文本特性让图形变更变得可追溯这是它相比拖拽式绘图工具最大的优势。