企业官网建设流程全解析

1. Ubuntu 上 PlantUML 到底解决什么问题

PlantUML 是一个用纯文本描述图表的工具，你写几行类似伪代码的语句，它就能渲染出序列图、用例图、类图、活动图、组件图、状态图等十几种 UML 图，还支持 JSON、YAML、网络拓扑、甘特图、思维导图等非 UML 图形。它适合谁？后端开发写接口时序、架构师画组件依赖、测试同学梳理用例流程、技术文档作者维护图文同步——只要你想让"图"和"代码"一样能进 Git、能 diff、能 review，PlantUML 就是那个把图形变成文本的桥梁。

在 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 -V

dot -V正常会打印dot - graphviz version 2.x.x。这两个依赖到位后，再装 PlantUML 本体：

sudo apt install -y plantuml plantuml -version

如果你不想用 apt 版本（有时偏旧），也可以直接下载官方 jar：

wget -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 里显式指定。

打开命令面板Ctrl+Shift+P，输入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.headless=true"], "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 装的 plantuml，jar 路径通常是/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 @enduml

4.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 A；B 在收到请求后激活，处理完就退出。实际画接口调用链时，这个机制能清晰表达"谁在什么时候占用资源"。

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 @enduml

alt还可以嵌套loop，比如"最多重试 3 次"的场景：

@startuml participant Client participant Server Client -> Server: 请求 loop 重试次数 < 3 Server --> Client: 失败 Client -> Server: 重试 end Server --> Client: 成功 @enduml

4.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 @enduml

autonumber还支持autonumber 1.1.1这种多级编号，以及autonumber inc A递增某一位，适合画复杂的分层流程。

5. 渲染验证与成功结果

配置和语法都就位后，验证分两步：命令行渲染和编辑器预览。

命令行方式最直接，把上面的序列图存成login.puml，然后：

plantuml -tpng login.puml

如果用的是 jar：

java -jar plantuml.jar -tpng login.puml

执行后同目录会生成login.png。如果没报错且图片能打开，说明 Java、Graphviz、PlantUML 三者链路通了。批量渲染整个目录：

plantuml -tpng "docs/diagrams/*.puml"

编辑器里则是打开.puml文件后按Alt+D，右侧会弹出预览面板。预览面板上方有一排小工具，鼠标悬停会显示功能，其中复制图标可以把当前图复制到剪贴板。如果预览一直转圈或报错，先看 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 exist

Graphviz 没装或不在 PATH。执行sudo apt install -y graphviz，再用dot -V验证。如果装了还报错，检查plantuml.commandArgs里是否误加了-DGRAPHVIZ_DOT之类的参数。

报错三：java.awt.HeadlessException

在无图形界面的服务器上渲染时报这个。在plantuml.commandArgs里加-Djava.awt.headless=true，或者命令行加-Djava.awt.headless=true参数。

报错四：预览面板空白，但命令行能渲染

多半是插件配置的 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/api，Key 从控制台生成后填入。

接入文档里有各语言 SDK 的调用示例，如果你要在 CI 里做 PlantUML 渲染的同时调用模型做图描述生成，可以参考文档里的请求格式。实际用下来，统一 Key 最大的好处是换项目不用重新配，团队里换人也不用挨个仓库改配置。

最后留一个实用技巧：把docs/diagrams目录纳入 Git，.puml源文件和渲染出的.png一起提交，review 时直接看 diff 就能知道图改了什么。PlantUML 的文本特性让图形变更变得可追溯，这是它相比拖拽式绘图工具最大的优势。