企业官网建设流程全解析

1. 项目概述：这不是又一个画图工具，而是一套“架构意图翻译器”

你有没有过这样的经历：在技术评审会上，刚说完“我们用微服务拆分订单模块，网关层做鉴权，库存服务走 gRPC，订单状态机用状态模式驱动”，白板上只留下几个歪歪扭扭的方块和几根断掉的箭头？会后同事问：“那个库存服务到底和哪个数据库连？是直连还是通过中间件？”你一时语塞——因为那张图根本没画出数据流向细节。archify 就是为解决这个“说得出、画不出、传不真”的顽疾而生的。它不是让你拖拽节点、手动连线的 GUI 架构图软件，而是一个AI 代理技能模块，核心能力是把一段自然语言描述（比如“用户下单触发事件总线，订单服务消费后调用库存服务扣减，失败则发消息到死信队列”）自动解析、推理、结构化，最终生成一份可交互、可展开、带语义注释的 HTML 架构图。关键词里反复出现的HTML不是偶然，而是 archify 的设计哲学：不依赖任何客户端安装，不绑定特定渲染引擎，一张.html文件双击就能打开，点击节点能弹出接口定义、环境变量、部署拓扑等上下文，右键还能导出 SVG 或 PlantUML。它面向的不是 PPT 美工，而是每天要写 RFC、做 CR、给新同学讲系统边界的工程师。我试过用它处理芋道系统的架构描述，5 分钟内生成的 HTML 图里，每个 Spring Boot 模块都自动标注了@RestController路径和@FeignClient服务名，比我自己手动画的 Visio 图信息密度高出三倍。如果你还在用 draw.io 拖着矩形框改来改去，或者靠 Mermaid 代码硬背语法，archify 提供的是一条从“人话”直达“可执行架构文档”的新路径。

2. 核心设计思路：为什么是 AI 代理 + HTML，而不是传统建模工具？

2.1 放弃 UML，拥抱“意图优先”的建模范式

传统架构图工具（如 Enterprise Architect、Lucidchart）失败的根本原因，在于它们把建模过程强行塞进一套预设的符号体系里。你得先决定画“组件图”还是“部署图”，再纠结“容器”该用圆角矩形还是云朵图标，最后还要手动维护图例说明。archify 的设计者很清醒：工程师脑子里根本没有“UML 组件图”这个概念，只有“这个服务要连 Redis”、“那个 API 要加 JWT 鉴权”、“前端静态资源走 CDN”。所以 archify 的第一层设计是语义解析层，它不识别“矩形=服务”，而是训练模型理解“调用”、“依赖”、“通过”、“部署在”这些动词和介词背后的拓扑关系。比如输入句子：“支付服务通过 OpenFeign 调用风控服务，风控服务连接 MySQL 主库和 Redis 缓存”，archify 的 NLP 模块会提取出三元组：(支付服务, 调用, 风控服务)、(风控服务, 连接, MySQL)、(风控服务, 连接, Redis)，并自动推断出MySQL和Redis是并列依赖而非嵌套关系。这背后用的是轻量级的 spaCy + 自定义规则引擎，而非大语言模型全量推理——实测下来，对 200 字以内的架构描述，解析耗时稳定在 300ms 内，比调用一次 GPT-4 API 快一个数量级，也避免了敏感业务描述上传云端的风险。

2.2 HTML 作为终极交付物：一次生成，多端复用

为什么所有热词里HTML出现频率最高？因为 archify 把 HTML 当作架构图的“通用二进制格式”。它生成的不是一张 PNG 图片，而是一个自包含的.html文件：所有 CSS 样式内联，JavaScript 逻辑打包进单个<script>标签，SVG 矢量图直接嵌入 DOM。这意味着什么？意味着你可以把它丢进 Git 仓库，和代码一起做版本管理；可以放在 Jenkins 构建产物里，每次发布自动生成最新架构快照；甚至能用python -m http.server在本地起个服务，让测试同学直接访问http://localhost:8000/architecture.html查看实时架构。我见过最狠的用法，是把 archify 输出的 HTML 嵌入 Grafana 的 Text Panel，配合 Prometheus 查询结果，实现“架构图随服务健康度变色”——CPU 使用率超 80% 的节点自动标红。这种灵活性，是任何桌面端架构图软件永远做不到的。有人问为什么不输出 PDF？PDF 是静态快照，而 archify 的 HTML 是活的：点击“订单服务”节点，弹窗里显示的不仅是它的端口和 JVM 参数，还有最近 3 次 CI 构建的 commit hash 和 SonarQube 代码质量评分，这些数据都是构建时动态注入的。<!doctype html><html lang="zh-cn">这行声明不是摆设，它确保中文字符正确渲染，meta 标签里的charset="utf-8"更是避免了架构图里出现“乱码数据库名”的尴尬现场。

2.3 “AI 代理”定位：技能模块，而非独立应用

标题里强调“AI 代理”和“技能模块”，这是 archify 区别于同类工具的关键。它不提供自己的 Web UI，也不打包成 Docker 镜像。你看到的 GitHub 仓库shihabal3amri/diplay（注意：diplay是项目代号，非拼写错误），本质是一个 Python CLI 工具 + 一套 JSON Schema 定义。它的标准工作流是：

1. 工程师在ARCHITECTURE.md里用 Markdown 写架构描述；
2. 运行archify generate --input ARCHITECTURE.md --output docs/arch.html；
3. CI 流水线自动提交生成的 HTML 到docs/目录。
   这个设计让 archify 天然融入现有工程流程。你可以把它当做一个 Git Hook，在git commit -m "feat: add payment service"后自动更新架构图；也可以集成进 Confluence，用宏指令{archify:source=ARCHITECTURE.md}实时渲染。所谓“AI 代理”，指的是它能在不同上下文中扮演不同角色：在本地开发时，它是你的“架构草稿助手”；在 CI 环境中，它是“架构合规检查员”（自动校验“所有外部 API 调用必须有熔断配置”这类规则）；在生产监控里，它又能变成“拓扑感知探针”（把 Prometheus 的服务发现数据注入 HTML，让节点大小反映 QPS）。这种模块化、可插拔的设计，正是它被称作“技能模块”的原因——它不取代你的工作流，而是悄悄增强它。

3. 核心功能实现：从一句话到可交互 HTML 的完整链路

3.1 输入解析：如何把“人话”变成机器可懂的拓扑关系？

archify 的输入解析不是黑箱。它采用三级流水线：
第一级：领域词典匹配。内置了 200+ 架构领域专有名词映射表，比如将“网关”、“API Gateway”、“Kong”、“Spring Cloud Gateway”统一归为gateway类型；把“Redis”、“缓存”、“cache”、“内存数据库”映射到redis实体。这个词典不是静态的，支持通过--dict custom_dict.json参数动态加载团队私有术语。我给一个真实案例：我们内部把 Kafka Topic 叫“消息通道”，把 Flink Job 叫“实时计算单元”，只需在custom_dict.json里添加"消息通道": "kafka_topic"和"实时计算单元": "flink_job"，后续所有描述里出现这两个词，都会被正确识别。
第二级：依存句法分析。用 spaCy 对句子做语法树解析，重点捕获主谓宾结构。例如句子：“用户服务通过 RESTful API 调用认证服务，认证服务验证 JWT 并返回用户信息”，解析后得到：主语用户服务，谓语调用，宾语认证服务，方式状语通过 RESTful API。这里的关键技巧是，archify 会忽略“RESTful API”这种泛化描述，转而从上下文推断协议——如果前文提到“所有服务间通信使用 HTTP/2”，它就会给这条连线打上protocol: http2标签。
第三级：规则引擎推理。这是最体现工程经验的部分。比如检测到“订单服务写 MySQL，读操作走 Elasticsearch”，archify 不会简单画两条平行线，而是根据预设规则if write_db and read_db then is_cqrs_pattern = true，自动在图中添加 CQRS 模式标识，并在节点旁显示小图标。更绝的是对“失败处理”的推理：当输入“调用库存服务失败，则降级返回兜底数据”，archify 会生成一条虚线箭头指向“兜底服务”，并在线上标注fallback: true。这套规则引擎用的是开源的jsonpath-ng库，所有规则都写在rules/目录下，你可以随时新增circuit_breaker.json或retry_policy.json，让 archify 学会识别你团队特有的容错模式。

3.2 图形生成：HTML 里藏着多少“可交互”的小心思？

生成的 HTML 不是简单地把 SVG 塞进去。它的 DOM 结构经过精心设计，每个关键元素都有语义化 class 和 data 属性：

• 服务节点是<div class="service-node"><script> fetch('/api/build-info') .then(r => r.json()) .then(data => { document.querySelector('.build-footer').textContent = `Last updated: ${data.timestamp} | Commit: ${data.sha.slice(0,7)}`; }); </script>

  配合 Nginx 配置location /api/build-info { alias /var/www/build-info.json; }，每次 Jenkins 构建成功，就往/var/www/build-info.json写入当前构建信息，HTML 页面就能实时显示“最后更新于 2024-06-15 14:23:01 | Commit: a1b2c3d”。这种“活文档”能力，让架构图不再是过期的 PPT 附件，而是和代码一样具有时效性的第一手资料。另外，--output-format参数支持html、svg、plantuml三种输出。PlantUML 输出特别适合老派工程师——生成的.puml文件可以直接用 VS Code 的 PlantUML 插件实时预览，还能提交到 Git 做文字 diff，一眼看出“这次重构删掉了库存服务对 MongoDB 的依赖”。

  4. 实操指南：从零开始跑通第一个可交互架构图

  4.1 环境准备与最小可行配置

  archify 对环境要求极低，这是它能在 Ubuntu 的 HTML 编辑器里直接运行的原因。我推荐两种安装方式：
  方式一：pip 全局安装（适合个人开发）

  # 确保 Python >= 3.8 python3 -m venv archify-env source archify-env/bin/activate pip install archify-cli # 验证安装 archify --version # 应输出 0.4.2+

  方式二：Docker 运行（适合 CI/CD）

  # Dockerfile.archify FROM python:3.9-slim RUN pip install archify-cli COPY ./ARCHITECTURE.md /workspace/ WORKDIR /workspace CMD ["archify", "generate", "--input", "ARCHITECTURE.md", "--output", "arch.html"]

  然后docker build -f Dockerfile.archify -t archify-builder . && docker run --rm -v $(pwd):/output archify-builder cp arch.html /output/。这种方式彻底隔离依赖，避免“在我机器上能跑”的问题。

  最小可行输入文件ARCHITECTURE.md只需三行：

  # 系统架构概览 用户通过 Web 前端访问订单服务，订单服务调用库存服务扣减库存。 所有服务部署在 Kubernetes 集群，使用 Istio 做服务网格。

  运行archify generate --input ARCHITECTURE.md --output quickstart.html，双击quickstart.html，你会看到一个包含三个节点（Web 前端、订单服务、库存服务）和两条连线的图，节点下方标注着env: kubernetes和mesh: istio。这就是 archify 的“Hello World”。注意：不要试图在输入里写复杂逻辑，比如“如果库存不足则触发补偿事务”，archify 0.4 版本还无法解析条件分支，它专注做好一件事：把确定性的架构描述，变成确定性的可视化表达。

  4.2 进阶配置：注入真实元数据，让架构图“活”起来

  真正的价值在于注入运行时数据。创建config.yaml：

  services: order-service: language: java framework: spring-boot port: 8080 jvm_args: "-Xmx2g" dependencies: - inventory-service - redis-cache inventory-service: language: go framework: gin port: 8081 health_check: "/actuator/health" databases: mysql-master: type: mysql version: "8.0" host: "mysql-primary.default.svc.cluster.local" port: 3306 redis-cache: type: redis version: "7.0" host: "redis.default.svc.cluster.local" port: 6379

  然后运行：

  archify generate \ --input ARCHITECTURE.md \ --config config.yaml \ --output architecture.html \ --template templates/corporate.html.j2

  生成的 HTML 里，“订单服务”节点会显示 Java 图标和8080端口，“库存服务”节点显示 Go 语言图标和健康检查路径。更妙的是，当你把鼠标悬停在“redis-cache”节点上，状态栏会显示完整的 Kubernetes Service 地址。这个config.yaml文件应该和代码一起提交到 Git，成为团队共享的架构真相源。我建议把它放在项目根目录的/infra/config/下，CI 脚本在构建时自动读取，确保架构图永远和实际部署一致。

  4.3 与现有工具链集成：让它成为你工作流的“隐形齿轮”

  archify 最强大的地方，在于它不抢戏，而是默默增强现有工具。以下是三个真实场景的集成方案：
  场景一：Git Hooks 自动更新
  在.git/hooks/pre-commit里添加：

  #!/bin/bash if git diff --cached --quiet ARCHITECTURE.md; then echo "ARCHITECTURE.md changed, regenerating diagram..." archify generate --input ARCHITECTURE.md --output docs/architecture.html git add docs/architecture.html fi

  这样，每次提交架构变更，HTML 图自动更新并纳入本次 commit。
  场景二：VS Code 实时预览
  安装 VS Code 扩展Markdown Preview Enhanced，在settings.json中添加：

  "markdown-preview-enhanced.previewTheme": "github.css", "markdown-preview-enhanced.enableScriptExecution": true, "markdown-preview-enhanced.codeBlockTheme": "github.css"

  然后在ARCHITECTURE.md底部添加：

  <script> // 自动在预览窗口嵌入架构图 fetch('docs/architecture.html') .then(r => r.text()) .then(html => { document.querySelector('.markdown-preview').innerHTML = html; }); </script>

  写完架构描述，实时预览区就显示可交互图，效率翻倍。
  场景三：Jenkins 构建产物归档
  在 Jenkinsfile 里：

  stage('Generate Architecture Diagram') { steps { sh 'archify generate --input ARCHITECTURE.md --output architecture.html' archiveArtifacts artifacts: 'architecture.html', fingerprint: true } }

  构建完成后，Jenkins 的“构建产物”里就能下载到最新架构图，QA 同学测试前必看。这三个集成点，覆盖了从编码、预览到发布的全生命周期，archify 就像一个沉默的架构管家，不打扰你，但总在你需要时递上最准确的图纸。

  5. 常见问题与避坑指南：那些官方文档不会告诉你的事

  5.1 输入文本的“黄金写法”：工程师该怎么写才不被 archify 误解？

  archify 不是万能的，它对输入文本的结构有隐式要求。我踩过的最大坑，是早期用长段落描述：“订单服务是一个基于 Spring Boot 的 Java 应用，暴露 /order/create 接口，它需要调用库存服务的 /inventory/deduct 接口，库存服务用 Go 写，连接 MySQL 和 Redis，MySQL 是主从架构……” 这段话 archify 解析出了 7 个实体，但连线全是错的。后来我发现，最佳实践是“主谓宾短句 + 换行分隔”：

  订单服务暴露 /order/create REST API。 订单服务调用库存服务的 /inventory/deduct 接口。 库存服务用 Go 语言编写。 库存服务连接 MySQL 主库。 库存服务连接 Redis 缓存。

  每行一个明确关系，archify 的解析准确率从 62% 提升到 98%。另一个关键是避免模糊动词。“使用”、“依赖”、“涉及”这类词 archify 无法推理出方向性。必须用“调用”、“写入”、“读取”、“监听”等有明确流向的动词。比如“订单服务使用 Redis”会被忽略，而“订单服务写入 Redis 缓存”就能生成正确的连线。最后，数字和符号要空格隔开：“服务A调用服务B(超时5s)” 会被解析为服务B(超时5s)这个整体实体，正确写法是“服务A 调用 服务B (超时 5s)”。这些细节，是 archify 开发者在 issue 里透露的，但从未写进文档。

  5.2 输出 HTML 的兼容性陷阱：为什么你的架构图在某些浏览器里“失灵”？

  archify 生成的 HTML 在 Chrome/Firefox/Edge 上完美运行，但在 Safari 15 以下版本会出现交互失效。根本原因是 Safari 对<dialog>元素的支持不完整，而 archify 的节点详情弹窗用了原生<dialog>。解决方案有两个：
  方案一（推荐）：降级为 div 弹窗
  修改模板templates/default.html.j2，把：

  <dialog id="detail-dialog"> <form method="dialog"> <p id="dialog-content"></p> <button>Close</button> </form> </dialog>

  替换成：

  <div id="detail-dialog" class="modal" style="display:none;"> <div class="modal-content"> <span class="close">&times;</span> <p id="dialog-content"></p> </div> </div>

  并补充对应 CSS。这个改动让 archify 兼容所有现代浏览器，包括 iOS 的 Safari。
  方案二：强制启用实验特性
  在 HTML 的<head>里添加：

  <script> if (!window.HTMLDialogElement) { document.write('<script src="https://unpkg.com/dialog-polyfill@0.4.14/dialog-polyfill.js"><\/script>'); document.write('<link rel="stylesheet" href="https://unpkg.com/dialog-polyfill@0.4.14/dialog-polyfill.css">'); } </script>

  但 polyfill 会增加 120KB 加载，不如方案一轻量。另一个常见问题是中文乱码，根源在于ARCHITECTURE.md文件保存时用了 GBK 编码。archify 默认按 UTF-8 读取，所以务必在 VS Code 或 Sublime Text 里，用“文件 -> 重新用编码打开 -> UTF-8”转换，否则生成的 HTML 里会出现“??????”代替服务名。

  5.3 性能调优实战：当架构描述超过 500 行时，如何避免生成卡死？

  在处理大型单体应用的架构描述时（比如把整个芋道系统的 200+ 模块描述写进去），archify generate会卡在 12 秒以上。性能瓶颈不在 NLP 解析，而在 HTML 渲染阶段——DOM 节点过多导致浏览器重排重绘。我的优化方案是：
  第一步：启用增量渲染
  在命令中添加--chunk-size 50，archify 会把 200 个节点分成 4 批，每批渲染后插入setTimeout(() => {}, 0)让浏览器喘口气。
  第二步：简化默认样式
  复制archify/templates/default.css到本地，注释掉所有box-shadow、transition、animation相关 CSS，这些视觉效果在大型图里毫无意义，却消耗 40% 的渲染时间。
  第三步：禁用非必要交互
  运行时加参数--disable-hover-details，关闭悬停详情，只保留点击钻取。实测下来，200 节点的图生成时间从 12.3s 降到 1.8s，文件体积从 4.2MB 压缩到 1.1MB。最后提醒一句：archify 不是替代专业架构治理工具，当你的系统拓扑复杂到需要自动检测循环依赖、计算服务耦合度时，该上 ArchUnit 或 Structure101 了。archify 的定位很清晰——把工程师脑子里的架构认知，快速、准确、低成本地变成一张大家都能看懂的图。它解决的是“沟通成本”，而不是“架构治理深度”。

  6. 生态扩展与未来可能：从技能模块到架构协作平台

  archify 的 GitHub 仓库里，examples/目录藏着几个被低估的宝藏。其中openclaw+ros示例展示了如何把 archify 和机器人操作系统（ROS）结合：输入“机械臂控制节点订阅 /camera/image_raw 主题，发布 /arm/move_cmd 命令”，生成的 HTML 图里，节点自动标注 ROS 版本、消息类型（sensor_msgs/Image）、QoS 策略。这证明 archify 的解析引擎是领域无关的，只要提供对应领域的词典和规则，它就能成为任何技术栈的架构翻译器。另一个ubuntu-html-editor示例，演示了如何在 GNOME 的 HTML 编辑器里，用右键菜单直接调用 archify 生成图——这暗示了它的终极形态：不是一个命令行工具，而是一个嵌入式架构服务。想象一下，你在 VS Code 里写完一段 Spring Boot 配置，光标悬停在@FeignClient("inventory-service")上，右键出现“Show in Architecture Diagram”，点击后自动高亮架构图中对应的节点和连线。这已经不是工具，而是 IDE 的一部分。

  目前社区正在推进两个重要扩展：
  扩展一：archify-export插件
  这是一个 VS Code 插件，能自动扫描项目中的application.yml、pom.xml、Dockerfile，提取服务名、端口、依赖关系，生成初始ARCHITECTURE.md。我试过对一个 50 个模块的项目运行，它生成了 83% 的基础拓扑，剩下 17% 是业务逻辑连线，需要人工补充。这相当于把 archify 的输入门槛，从“写架构描述”降到了“确认生成结果”。
  扩展二：archify-collab服务
  这是一个轻量级 Node.js 服务，允许多人同时编辑同一份ARCHITECTURE.md，所有修改实时同步到共享的 HTML 图。它用的是 ShareDB 库，冲突解决策略很简单：后提交者胜出。虽然不如 Google Docs 优雅，但在小团队内部，它让架构图评审从“发邮件传 PPT”变成了“围在一台电脑前实时改图”。

  我个人在实际使用中发现，archify 最大的价值不是生成图，而是倒逼团队建立架构描述规范。以前大家写 RFC，架构部分随意堆砌文字；现在必须按 archify 的“主谓宾短句”格式写，无形中提升了描述的精确性。有次我们发现，两个工程师对“订单服务是否直连 MySQL”的描述不一致，archify 生成的图出现了矛盾连线，当场就暴露了设计分歧。这让我想起一句话：最好的架构工具，不是帮你画出完美的图，而是帮你发现哪里还没想清楚。archify 正是这样一面镜子——它不创造架构，它只忠实地反射出你已有的认知。当你对着生成的 HTML 图皱眉时，那不是工具的 bug，而是你架构设计的 warning。