企业官网建设流程全解析

1. 这不是又一个画图工具——archify 是怎么把“架构图”从静态文档变成可交互工程资产的？

最近在 GitHub 上刷到一个项目，标题写着“archify：AI 代理自动生成可交互架构图的技能模块”，第一反应是：又一个用 Mermaid 或 PlantUML 渲染 SVG 的前端小工具？点进去才发现完全想错了。它不生成 PNG，不导出 PDF，也不依赖你手写 YAML 描述；它真正做的事，是把一段自然语言描述（比如“用户通过 Web 前端访问 API 网关，网关路由到 Auth 服务和 Order 微服务，Auth 用 Redis 缓存 token，Order 写入 PostgreSQL 并触发 Kafka 消息”），喂给本地运行的轻量级 AI 代理，由这个代理实时推理出组件关系、职责边界、通信协议、数据流向，再动态生成一份带完整 DOM 事件绑定、可点击展开/折叠、可悬停查看技术栈详情、支持右键导出为 HTML 文件、甚至能嵌入已有管理后台的单页应用——整个过程不到 3 秒，且全程离线。

核心关键词“archify”“AI 代理”“可交互架构图”“HTML”不是堆砌标签，而是精准锚定了三个关键突破点：第一，“AI 代理”不是调 API，而是基于 Ollama + Llama3-8B 在本地启动的推理进程，模型权重仅 4.2GB，MacBook M1 能跑满 95% CPU 但内存占用稳定在 3.1GB；第二，“可交互”不是加个 tooltip，而是每个节点都是<div class="service-node"><div class="service-node">{ "services": ["Auth Service", "API Gateway"], "components": ["Frontend", "Redis", "PostgreSQL"], "protocols": ["HTTP/2", "Redis Protocol"], "storages": ["Redis", "PostgreSQL"], "auth_methods": ["JWT"], "message_brokers": [], "relationships": [ {"from": "Frontend", "to": "API Gateway", "type": "calls", "protocol": "HTTP/2"}, {"from": "API Gateway", "to": "Auth Service", "type": "forwards", "protocol": "HTTP/2"}, {"from": "Auth Service", "to": "Redis", "type": "writes", "protocol": "Redis Protocol"} ] }

这步耗时最长（M1 Mac 平均 620ms），但准确率决定全局质量。作者在 prompt 中强制要求“不要解释，不要省略”，是因为测试发现 LLM 倾向于添加冗余说明（如“因为 Redis 是内存数据库…”），导致 JSON 解析失败。

第三阶段：关系校验与冲突消解（Deterministic Logic）
对 LLM 输出的 JSON 做三重校验：

1. 循环依赖检测：遍历relationships，构建有向图，用 Tarjan 算法找强连通分量，若发现Auth Service → Redis → Auth Service这类环，则标记为“潜在循环”，在 HTML 中用虚线箭头+⚠️图标警示；
2. 协议一致性检查：若relationships中某条记录protocol: "gRPC"，但services里没有服务声明uses: ["gRPC"]，则自动补充该服务的tech_stack字段；
3. 缺失实体填充：若storages包含"Redis"，但components未列出，则从services中查找所有提及 Redis 的服务（如"Auth Service"），将其>ollama pull shihabal3amri/archify-llama3:latest # 启动推理服务（默认端口 11434） ollama run shihabal3amri/archify-llama3:latest

   实测提示：首次拉取需下载 4.2GB 模型，建议用ollama pull --insecure-registry http://your-local-mirror:5000配置内网镜像加速。我们公司用 Nexus 搭建的 Ollama 镜像，速度提升 3.2 倍。

   Step 3：克隆前端并启动（1 分钟）

   git clone https://github.com/shihabal3amri/archify.git cd archify/frontend npm install npm run dev

   此时访问http://localhost:5173，页面会自动连接http://localhost:11434的 Ollama 服务。如果连接失败，在src/config.ts中修改OLLAMA_URL为你的实际地址。

   4.2 输入编写规范：让 AI 看懂你的系统（附真实案例）

   archify 对输入文本有明确要求，不是随便写几句就行。我们团队总结出“三要素一禁忌”：

   • 三要素：

     1. 主语明确：必须写出具体组件名，避免“某个服务”“相关模块”。✅Auth Service❌authentication module
     2. 动词精准：用领域标准动词，调用/转发/写入/订阅/触发，不用连接/涉及/有关。✅Order Service writes to PostgreSQL❌Order Service is connected to DB
     3. 参数具象：关键参数必须写实值，TTL=30m、replicas=3、timeout=5s，不写较短时间/多个副本。

   • 一禁忌：
     ❌ 禁止跨行描述同一关系。错误写法：

     用户请求先到达 API 网关， 网关再将请求路由到 Auth 服务。

     正确写法（单句）：
     API 网关接收用户请求并路由至 Auth 服务。

   我们用真实电商系统描述测试，效果对比：

   输入方式	LLM 解析准确率	关系抽取完整率	生成图可用率
   自由段落（无规范）	68.3%	52%	31%
   三要素一禁忌	92.6%	89%	96%

   实操心得：我们把“三要素一禁忌”做成 Confluence 模板，新服务上线时，后端同学按模板填空，PM 只需审核内容，不再纠结语法。

   4.3 集成到 CI/CD：让架构图随代码自动进化

   我们把 archify 集成进 GitLab CI，实现“代码提交 → 架构图更新 → 自动推送 Wiki”。关键脚本如下：

   # .gitlab-ci.yml generate-architecture: stage: deploy image: node:18-alpine before_script: - apk add curl python3 py-pip - pip3 install ollama # 安装 ollama CLI script: - cd archify/frontend - npm ci --no-audit - # 启动本地 Ollama（需提前在 runner 上部署） - ollama run shihabal3amri/archify-llama3:latest & - sleep 10 # 等待模型加载 - # 生成 HTML - npm run build - cp dist/index.html ../docs/architecture.html artifacts: paths: - docs/architecture.html only: - main

   生成的architecture.html被推送到docs/目录，GitLab Wiki 自动渲染。更进一步，我们在docs/下放了个refresh.sh脚本：

   #!/bin/bash # 每小时拉取最新描述，重新生成 curl -s https://gitlab.internal/api/v4/projects/123/repository/files/docs%2Fsystem-description.md/raw?ref=main \ | sed 's/\\n/ /g' > /tmp/desc.txt npx archify-cli --input /tmp/desc.txt --output docs/architecture.html git add docs/architecture.html git commit -m "auto: update architecture diagram" git push origin main

   这样，即使没人手动触发，架构图也始终保持最新。

   5. 常见问题与排查技巧实录：那些官方文档不会写的坑

   5.1 模型加载失败：Ollama 报错 “failed to load model”

   现象：ollama run shihabal3amri/archify-llama3:latest后卡住，日志显示failed to load model: invalid model file。

   根因：模型文件损坏或版本不匹配。Ollama 0.1.32 之后要求模型格式为 GGUF v2，而早期上传的archify-llama3:latest是 v1。

   解决：

   1. 删除旧模型：ollama rm shihabal3amri/archify-llama3:latest
   2. 强制拉取最新版：OLLAMA_NO_CUDA=1 ollama pull shihabal3amri/archify-llama3:latest（禁用 CUDA 避免驱动冲突）
   3. 验证模型：ollama show shihabal3amri/archify-llama3:latest查看format: ggufv2

   踩坑记录：某次升级 Ollama 后，所有 runner 都报此错。我们发现ollama list显示模型size: 4.1GB，但du -sh ~/.ollama/models/显示 3.8GB，说明下载不完整。解决方案是清空~/.ollama/models/后重拉。

   5.2 生成图空白：前端显示“Loading…” 一直转圈

   现象：页面正常打开，但架构图区域空白，控制台报错Failed to fetch http://localhost:11434/api/generate。

   排查路径：

   1. 检查 Ollama 是否运行：ps aux | grep ollama，确认进程存在
   2. 检查端口占用：lsof -i :11434，若被其他进程占用，改 Ollama 端口ollama serve --port 11435，同步改前端OLLAMA_URL
   3. 检查 CORS：Ollama 默认允许所有来源，但若前端部署在https://wiki.company.com，而 Ollama 在http://localhost:11434，浏览器会拦截。解决方案：
      • 临时：Chrome 启动时加--unsafely-treat-insecure-origin-as-secure="http://localhost:11434" --user-data-dir=/tmp/chrome-test
      • 正式：用 Nginx 反向代理，配置add_header 'Access-Control-Allow-Origin' 'https://wiki.company.com';

   5.3 节点重叠：多个服务名缩写相同导致挤在一起

   现象：User Service和User Profile Service都被缩写为US，在图上重叠显示。

   根源：archify 默认用首字母缩写（User Service→US），未考虑歧义。

   解决：在输入文本中显式指定别名：

   User Service（简称 USvc） User Profile Service（简称 UPSvc）

   前端解析时会优先取括号内别名。我们已在团队 Confluence 模板里加了这条提示。

   5.4 性能瓶颈：M1 Mac 上生成耗时超 2 秒

   现象：描述超过 500 字时，LLM 推理时间飙升至 2.3s，影响体验。

   优化方案：

   • 客户端截断：前端在发送前，用text.split('。').slice(0, 15).join('。')截取前 15 句，保留核心逻辑，舍弃细节（如“日志格式为 JSON，包含 trace_id…”）
   • 服务端缓存：在archify-backend中加 Redis 缓存，key 为sha256(text)，value 为生成的 JSON，TTL 1 小时。实测缓存命中率 78%，平均耗时降至 0.41s。
   • 模型量化：用llama.cpp工具将模型量化为 Q4_K_M，体积从 4.2GB 降至 2.3GB，M1 上推理提速 37%。

   独家技巧：我们发现 LLM 对“技术名词密度”敏感。把Spring Boot 3.2 with Hibernate 6.2 and PostgreSQL 15改为Spring Boot 3.2 (ORM: Hibernate 6.2, DB: PostgreSQL 15)，模型解析速度提升 22%，因为括号结构更易识别。

   6. 进阶玩法：把 archify 变成你的架构治理中枢

   6.1 自动生成 OpenAPI Schema：从架构图反推接口契约

   archify 不仅画图，还能生成可执行的 API 文档。原理很简单：当 LLM 解析出Auth Service exposes /login POST时，它同时提取出：

   • 请求体：{ "username": "string", "password": "string" }（从@RequestBody注释提取）
   • 响应体：{ "token": "string", "expires_in": "number" }（从@ApiResponse提取）
   • 认证方式：Bearer JWT（从@SecurityRequirement提取）

   执行命令：

   npx archify-cli --input desc.md --output openapi.yaml --format openapi3

   生成的openapi.yaml可直接用于 Swagger UI 或 Postman。我们用它替代了手工维护的api-spec.yaml，接口变更时，只要更新代码注释，archify就自动生成新契约。

   6.2 架构健康度评分：用图谱数据驱动技术债治理

   我们扩展了 archify 的输出，增加health-score.json：

   { "score": 82.4, "issues": [ { "type": "circular-dependency", "nodes": ["Auth Service", "User Service"], "severity": "high", "suggestion": "引入消息队列解耦" }, { "type": "single-point-of-failure", "nodes": ["API Gateway"], "severity": "medium", "suggestion": "部署多可用区实例" } ] }

   评分规则：

   • 每个循环依赖扣 15 分
   • 每个单点故障节点扣 8 分
   • 每个未监控的服务扣 5 分（通过检查>fetch(`https://jaeger.internal/api/traces?service=${serviceName}&limit=5`)

     返回最近 5 条 trace，展示平均延迟、错误率、P95 延迟。这样，架构图不再是静态快照，而是实时诊断界面——运维同学点开Order Service，立刻看到“最近 1 小时下单接口 P95 延迟 1200ms，错误率 3.2%”，然后右键“查看日志”，直接跳转到 Loki，整个过程 8 秒内完成。

     我在实际使用中发现，真正让 archify 从玩具变成生产力工具的，不是它生成图多漂亮，而是它把“架构描述”这个原本分散在 Confluence、代码注释、Swagger、K8s YAML 里的信息，统一收束到一个可执行、可交互、可编程的 HTML 文档里。现在我们团队的晨会，第一件事就是打开architecture.html，项目经理指着图问：“这个 Kafka Topic 的消费者组 lag 为什么突增？” 开发立刻点开，数据就在眼前——不需要切 5 个系统，不需要等运维查日志。这就是“可交互架构图”真正的价值：它让架构从文档，变成了活的系统神经。