企业官网建设流程全解析

做AI应用架构师这几年，我最烦的事有两件：一是架构评审前发现PPT里的架构图和线上代码已经对不上，二是给新同事讲系统时，面对一张画得潦草的手绘图，连自己都得先盯着脑补半天。后来我花了大半年时间，把“画架构图”这件事直接从工作流里摘了出去——靠自动化转换工具让架构图自动生成。这篇文章就是我折腾出来的完整方法论，适合那些既要做AI应用设计、又要负责方案落地、还不想整天泡在绘图工具里的架构师同行。

1. 架构图在AI应用项目里为什么是刚需

1.1 一个典型AI应用的架构到底有多复杂

先别急着聊工具，得先认清架构图对我们的意义。AI应用和传统CRUD系统最大的区别在于依赖链路特别长，一个稍微像样点的AI产品，背后通常站着这样一串组件：前端负责交互采集，API网关负责鉴权和路由，应用服务层负责业务编排，向量数据库负责相似度检索，模型推理服务负责跑模型，对象存储负责存原始素材，消息队列负责异步任务，再加上缓存、日志、监控。这些组件之间还有不同的通信协议，HTTP、WebSocket、gRPC、消息订阅，画出来完全是网状结构。

我在跟算法团队对方案的时候感受特别深。算法同学关心的是一条数据从输入到推理结果返回全链路是否畅通，工程同学关心的是服务边界和容灾，运维同学关心的是部署形态和资源消耗，产品经理关心的则是哪些环节会影响响应延迟。同一套系统，每个人看到的视角都不同。没有一张清晰的架构图，评审会就会变成各说各话的混沌现场。

这也是为什么我一直认为，AI应用架构师的核心交付物之一就是架构图。它不只是给别人看的文档，更是你自己梳理系统边界、识别单点风险和依赖环的工具。画图的过程，本质上是逼着自己把“系统到底怎么转”这件事想清楚。所以架构图不是锦上添花，是刚需。

1.2 手绘架构图的三个致命问题

既然架构图这么重要，为什么很多架构师反而越来越不爱画？因为我踩过坑，手绘架构图这条路走不通，主要有三个原因。

第一个是时间成本高得离谱。一张像样的分层架构图，手绘至少要小半天。如果是AI应用这种节点多、关系乱的系统，光是对齐图标、调布局、配颜色就能消耗一个下午。而且画完不一定对，还要反复改。

第二个是文档必然腐化。架构图最怕的不是画得丑，而是和代码脱节。AI项目迭代速度有多快，大家都清楚，今天加了向量检索，明天换了推理框架，后天把消息队列从RabbitMQ换成Kafka。代码改完，图往往没跟上，过了两周再打开那张图，跟实际系统已经完全是两个世界了。

第三个是信息失真。手工画图时为了美观，很容易隐去关键信息。比如某个服务依赖了外部接口，为了版面好看就省略了；某个调用关系存在超时重试，为了简化就没标注。这些被“优化”掉的细节，恰恰是线上故障时最致命的信息。

所以我的结论很简单：架构图必须跟着代码走，必须可追溯、可验证、可自动更新。这正是自动化转换工具最核心的价值。下面的内容，我就围绕“如何让架构图自动生成”这件事展开。

2. 自动化转换工具选型：四条路线怎么选

2.1 四种主流自动化生成路线对比

市面上的架构图自动生成方案，归根结底是四种路线。我踩过不少坑，把它们的适用场景整理成一张表，方便大家根据自己项目的状态选型。

这四条路线不是互斥的，实际项目中往往是组合使用。比如我这边，部署阶段用配置文件解析路线，接口梳理阶段用代码逆向路线，而评审和沉淀阶段用文本描述路线。关键在于，你要清楚每一条路线解决的是哪个生命周期的问题。

2.2 我的选型原则：文本即图，图即代码

我个人的选型原则可以总结成一句话：文本即图，图即代码。原因很简单，AI应用架构师也是工程师，工程界最可靠的资产就是代码。如果架构图本身只是一张PNG图片，那它很难进入版本控制、代码评审和自动化的体系。但如果架构图是由一段文本描述渲染出来的，那这段文本就可以放进Git仓库，可以被diff，可以被review，可以接进CI/CD流水线自动更新。

这就是我为什么最终把重心放在Mermaid这套语法上。它的表达能力覆盖流程图、时序图、类图、状态图，基本上架构师日常需要画的图都能搞定。而且生态成熟，GitHub官方渲染、VS Code插件、Mermaid CLI、各类在线编辑器都有，团队协作成本降得很低。

当然，光有Mermaid还不够。自动化的关键在于，怎么把代码、配置、运行数据这些“事实来源”转换成Mermaid文本。这一步必须靠解析脚本和工具链来完成，不能靠人肉翻译。这也是“自动化转换工具”和“画图工具”最根本的区别：画图工具只是帮你把形状拖出来，转换工具是直接从源头生成图描述。

2.3 我的工具组合拳

我把自己的工具链分成三层，每层职责单一，组合起来就是一套完整的流水线。

第一层是“事实来源层”，也就是你的代码仓库、docker-compose.yml、Kubernetes配置、OpenAPI文档、运行时指标。这些是架构图的唯一事实依据，所有图都必须是它们推导出来的。

第二层是“转换层”，把配置和代码解析成中间结构。我常用的是Python脚本配合PyYAML、AST模块、json解析，必要时也用现成工具。这一层输出的不是最终的图，而是一个结构化的依赖关系集合。

第三层是“渲染层”，把中间的依赖关系拼装成Mermaid文本，再用Mermaid CLI渲染成SVG或PNG。渲染产物直接被文档系统引用，同时源文本进入Git仓库，形成闭环。

这套组合拳的好处是每一层都可以单独替换。今天换了K8s，我可以只改第一层的事实来源和解析脚本，渲染层完全不动；明天想在图上加一个“网络隔离域”的视觉表达，我只改渲染层的模板逻辑就行。

3. 实操：三套自动生成流水线，照着抄就能用

3.1 从docker-compose一键生成部署架构图

AI应用依赖的中间件太多了，Redis、PostgreSQL、RabbitMQ、Milvus、MinIO，几乎每个项目都是一堆容器编排。docker-compose.yml本身就是一份权威的部署拓扑描述，完全可以把它的YAML结构直接转换成架构图。

我写了一个很简短的Python脚本，核心思路是解析services块，把每个服务变成一个节点，把depends_on关系变成有向边。代码如下：

import yaml from pathlib import Path def compose_to_mermaid(compose_file: str) -> str: with open(compose_file, encoding="utf-8") as f: data = yaml.safe_load(f) lines = ["graph LR"] nodes = [] edges = [] for svc, conf in data.get("services", {}).items(): safe_name = svc.replace("-", "_").replace(".", "_") nodes.append(f' {safe_name}["{svc}"]') deps = conf.get("depends_on", []) if isinstance(deps, dict): deps = list(deps.keys()) for dep in deps: dep_safe = dep.replace("-", "_").replace(".", "_") edges.append(f" {safe_name} --> {dep_safe}") lines.extend(nodes) lines.extend(edges) return "\n".join(lines) if __name__ == "__main__": print(compose_to_mermaid("docker-compose.yml"))

用的时候，在项目根目录执行python scripts/compose_to_mermaid.py > docs/arch/deployment.md，整个部署拓扑就出现在Markdown里了。之后用Mermaid CLI或者VS Code插件渲染成SVG。

这里面有几个坑我必须提醒。第一个是depends_on的两种写法，老版本是数组，新版本支持对象形式带condition字段，脚本里必须都兼容，否则线上就会漏边。第二个是服务名里经常有中划线和下划线混用，Mermaid节点ID里不能留中划线，需要统一替换，否则渲染时会报错。第三个是Compose文件里的环境变量插值，比如${VAR:-default}，解析时不要直接在脚本里做替换，保持源文件原样，否则生成的图跟真实运行环境反而对不上。

3.2 从FastAPI自动生成接口与数据模型架构图

AI应用最常见的服务形态就是FastAPI，一套OpenAPI规范已经把接口路径、请求方法、标签、数据模型都定义好了。从OpenAPI生成架构图，等于把接口文档变成可视化拓扑，非常适合评审和目视检查。

解析OpenAPI的要点是先提取tags。FastAPI里我们会给每个路由打tag，比如user、rag、inference、admin，这些tag天然就是微服务视角下的服务边界。脚本逻辑是：每种tag生成一个“服务节点”，客户端作为源头，指向所有服务节点，边上标注方法和路径。

import json def openapi_to_mermaid(openapi_file: str) -> str: with open(openapi_file, encoding="utf-8") as f: spec = json.load(f) lines = ["graph LR", ' Client["客户端"]'] services = set() edges = [] for path, methods in spec.get("paths", {}).items(): for method, op in methods.items(): if method.lower() not in ("get", "post", "put", "delete", "patch"): continue tag = (op.get("tags") or ["default"])[0] services.add(tag) safe = tag.replace("-", "_").replace(" ", "_") edges.append(f" Client -->|{method.upper()}| S_{safe}") for tag in sorted(services): safe = tag.replace("-", "_").replace(" ", "_") lines.append(f' S_{safe}["{tag}服务"]') lines.extend(edges) return "\n".join(lines) + "\n"

同类的脚本还可以用来生成数据模型类图。OpenAPI的components.schemas本身就是完整的数据模型定义，转换成Mermaid的classDiagram非常顺手。代码很简单，遍历每个schema的properties，生成类和字段，再把$ref引用变成继承或关联关系。这样一张ER风格的数据模型图就自动出来了。

我常用的做法是这两个脚本一起跑，一个生成接口拓扑图，一个生成数据模型图，放进同一次评审文档里。效果相当好：接口图和模型图相互印证，架构评审时信息量直接翻倍，而且自动化生成的图永远不会出现“文档里的接口带已经不存在了”这种尴尬。

3.3 用大模型从需求描述生成架构图初稿

从代码和配置生成架构图很可靠，但有个前提——你得先有代码。在方案设计阶段，只有一段模糊的需求描述，这时候怎么快速得到一张架构图草案？我现在的方案是用大模型生成初稿，然后人工修正。这块我也踩过不少坑，最有价值的一条心得是：Prompt必须给足结构约束，否则大模型画出来的图只是一个“看起来很热闹”的分层，根本经不起推敲。

我常用的Prompt模板长这样：

你是资深AI应用架构师。请根据我提供的信息，生成架构方案图。 硬性要求： 1. 只输出一份Mermaid格式的流程图文本，不要输出任何解释文字。 2. 图类型只允许使用 graph LR。 3. 节点按层次组织，必须体现：客户端、接入层/网关、应用服务、数据层/外部依赖。 4. 边统一用 --> 表示调用关系，有必要的边要标注协议（HTTP/gRPC/WS）。 5. 节点总数控制在25个以内，聚焦核心链路，不要堆砌细节。 我的背景信息： [在这里粘贴：技术栈、模块列表、关键依赖、部署方式、用户场景]

把背景信息填进去之后，输出的文本虽然不一定一次就能渲染成功，但作为草稿完全够用。我拿到草稿之后会做三件事：第一，逐条检查节点是不是真的能在我的系统里找到对应模块，大模型偶尔会幻觉出一些不存在的组件；第二，检查边的方向是否跟真实调用方向一致，最离谱的一次是它把“用户请求”和“模型返回”画成了同一条双向边，信息量直接丢失；第三，把不满足“25个节点以内”要求的图剪枝。

大模型生成的图只能当底稿，不能当终稿。但它最大价值在于能把你的经验沉淀成一套“输入需求就产出架构草图”的模板，尤其是对AI这种组件高度标准化、模式相对固定的领域，草稿的可用度比我预期高很多。

4. 进阶玩法：让架构图随着代码变更自动更新

4.1 把架构图生成接入CI/CD流水线

架构图自动生成的核心价值，不是省一次画图的时间，而是让架构图和代码永远保持同步。想达到这个效果，必须把生成脚本接进CI/CD流水线。我的方案是：每当主干分支有代码或部署配置变更，CI任务自动重新生成架构图，然后自动提交回仓库。

下面是一个GitHub Actions的示例配置文件，我在多个项目里都这么用，稳定跑了很久：

name: auto-generate-architecture on: push: branches: - main paths: - "docker-compose.yml" - "app/**" - "docs/architecture/**" jobs: generate-arch: runs-on: ubuntu-latest steps: - name: 拉取代码 uses: actions/checkout@v4 - name: 安装依赖 run: | pip install pyyaml npm install -g @mermaid-js/mermaid-cli - name: 运行生成脚本 run: | python scripts/gen_arch.py - name: 提交自动生成的架构图 uses: stefanzweifel/git-auto-commit-action@v5 with: commit_message: "chore: auto update architecture diagrams"

这套流水线的好处是，架构图变成了代码仓库里的“一等公民”。评审代码的时候，顺带就能看到这次的改动是否影响了系统拓扑。我有一次排查一个性能问题，就是通过CI自动生成的架构diff，一眼发现某个服务突然多了一个对慢数据库的同步调用，这要是在以前，得靠人工盯代码才能发现。

需要特别注意的是触发路径。一开始我把触发条件写得很宽，任何文件变更都触发，结果一天提交了十几张完全一样的架构图，PR噪音大到队友直接找我投诉。后来收敛到了三个路径：部署描述文件、业务代码目录、文档目录。没有变的就不需要重复生成，节省CI时长也减少噪音。

4.2 不同粒度的架构图如何自动聚合

架构图不是只有一张，系统级、应用级、服务级、部署级粒度完全不同。团队里不同角色需要的粒度也不一样。技术委员会看的是系统上下文，开发看的是服务模块依赖，运维看的是部署资源。

我在实践里发现，最重要的是按“分层视图”组织生成任务，而不是把所有的信息塞进一张图。具体做法是固定三层视图：系统上下文图（System Context）、容器图（Container）、部署图（Deployment）。每一层都由不同的脚本独立生成，但都基于同一个事实来源。

举个例子，系统上下文图从docker-compose.yml提取“外部用户”和“核心服务”这两层，只画大逻辑不画细节；容器图从服务配置文件里提取更详细的内网依赖关系，比如某个服务调用了哪个Redis实例；部署图则从Kubernetes配置或Compose的resource定义里提取副本数、端口映射、网络域。三层图分开存到docs/arch/下的不同文件里，CI流水线每次更新全部三层。

这样下来，每个角色看一眼自己关心的那层图就够了，信息密度和准确度都高。总有人说“一张图看懂系统”是伪需求，确实，该做的是“一套图看懂系统”，每张图各司其职。

5. 常见问题与避坑指南实录

5.1 自动生成的图太乱了，根本没法看

这个问题几乎100%会碰到，尤其是第一次跑通代码解析脚本后，生成的图密密麻麻全是节点和边。原因很直接：脚本忠实还原了一切，但架构图不是源码map，图是要给人类看的，必须聚焦。

我的解决办法很简单，分三步走。第一步，设置节点阈值，超过40个节点就自动触发剪枝，优先剔除无依赖关系的叶子服务。第二步，使用subgraph按领域分组，把“数据层”“接入层”“应用服务”“基础设施”分别装进不同的视觉分组，Mermaid的subgraph会让整张图的结构清晰很多。第三步，过滤噪音边。比如健康检查接口的调用、监控指标上报这类边，对架构分析没有实际帮助，解析时直接在生成阶段丢掉，不必走到图里再手动整理。

这层逻辑最好下沉到转换脚本里，不要图生成之后再人工去改。脚本里的过滤规则就是你的架构规范，每个人提交代码后跑一遍CI，得到的图都遵循同样的过滤标准。图就不会因为不同的人画图风格不同而千奇百怪。

5.2 大模型生成的图语法报错怎么处理

用大模型生成图，最常遇到的就是Mermaid语法错误。节点ID里混入了中划线、中文括号、特殊字符，或者边和节点的定义顺序有问题，渲染时直接报错。第一次遇到这种情况，我以为是模型能力不行，后来把报错信息原样回传给大模型让它自己修，发现大多数时候它能修对。

更稳定的做法是在Prompt里限制语法子集，只允许用graph LR和基本的节点边定义，不要给它打开新特性的机会。同时，在CI里加一步Mermaid CLI的渲染校验，渲染失败直接让流水线失败，逼着提交者去处理问题。Mermaid CLI的用法很简单：

mmdc -i docs/arch/system.mmd -o docs/arch/system.svg

如果报错，输出的错误信息会明确指向第几行，配合大模型的修正能力，基本两三轮就能修好。我的经验是，跟大模型协作时要明确告诉它“根据这条报错信息修复，不要重构整个图的结构”，否则它会擅自把布局逻辑都改了，反而制造新的问题。

5.3 自动化生成和人工到底怎么分工

写了这么多自动化，但我要说句公道话：架构图里最宝贵的那层信息，自动化工具是生成不出来的，那就是架构决策和设计意图。

我现在的分工模式非常明确。自动化工具负责生成“事实层”的图，也就是系统当前实际状态的忠实描述，包括部署拓扑、服务依赖、接口关系这些硬信息。而“决策层”的图，比如目标架构图、演进路线图、故障容灾拓扑图，这些涉及未来规划和权衡取舍的，仍然需要架构师亲手斟酌。我也并不追求后者自动化，因为这类图的价值恰恰在于思考过程本身。

所以，最终的工作流是：事实图靠自动化流水线持续更新，保证永远和代码同步；规划图在事实图基础上手工加工，把架构决策的文字说明、待办标识、风险标记加进去。人工要做的是审图和决策，不用做“把节点从一个位置拖到另一个位置”的体力活。

写在最后

自动化转换工具让我最大的改变是，我再也不用因为画图占用太多时间而产生拖延和内疚感了。以前一想到要更新架构图就头疼，连续拖几周之后就彻底不碰了；现在架构图跟着代码自动刷新，评审的时候打开最新的SVG，所有人都看同一份“会动”的真实状态。对我来说，这就是AI应用架构师该有的工作方式：把重复劳动交出去，把时间花在判断和权衡上。

最后分享一个小技巧：把你项目里最常改动的那份架构图模板固定下来，沉淀到自己团队的标准模板库里。下次不管谁接手，只需要跑两条命令，就能在十分钟内拿到一套最新的、分层的、可评审的架构图资产。这套方法论不算复杂，但它真的能把你从画图员的身份里解放出来。