1. 项目概述这不是画图工具而是一个“会思考”的架构生成器你有没有过这样的经历刚接手一个新系统文档里只有一张模糊的PNG架构图箭头歪斜、组件重叠、文字小得要凑近屏幕才能看清或者在技术评审会上被临时要求“快速画个微服务调用链”结果打开draw.io光是找“Kubernetes Pod”图标就花了三分钟更别说理清Service Mesh和Ingress Controller之间的关系了。archify不是又一个拖拽式绘图软件——它本质上是一个嵌入式AI代理能像资深架构师一样理解你的代码、配置和自然语言描述然后自动生成一份可交互、可验证、可导出、带语义注释的HTML架构图。核心关键词很明确GitHub开源、AI代理、可交互架构图、HTML原生输出。它不依赖任何在线SaaS服务所有推理和渲染都在本地完成生成的不是静态图片而是标准的!doctype htmlhtml langzh-cn结构直接双击就能在浏览器里展开折叠模块、点击查看接口定义、悬停显示组件健康状态——这才是真正面向开发者的架构交付物。适合三类人后端工程师想快速反向生成遗留系统的拓扑视图技术负责人需要在周会上动态演示服务依赖变化还有就是像我这样习惯把架构图直接嵌入Confluence或内部Wiki的运维同学——因为archify输出的就是纯HTML复制粘贴过去连CSS都不用额外引入。我第一次试它的时候扔进去一个只有23行YAML的Spring Boot微服务配置文件它不仅识别出Eureka注册中心、Ribbon负载均衡和Hystrix熔断器还自动把“/api/v1/users”这个路径标注为“高并发读写接口”并在旁边加了个小标签写着“建议增加Redis缓存层”。这已经不是简单的组件识别了它在做轻量级的架构合理性推演。更关键的是整个过程没调用任何外部API模型权重文件就放在项目根目录下的models/文件夹里连网络都没连——这意味着你可以把它塞进内网隔离环境给金融或政务客户做交付时完全不用担心数据泄露风险。它解决的从来不是“怎么画得好看”而是“怎么让架构图真正活起来成为系统的一部分”。2. 核心设计思路与技术选型逻辑2.1 为什么放弃Visio/draw.io路线架构图的本质是代码的镜像市面上90%的架构图工具都卡在一个死结上它们把架构图当作独立于代码的“美术作品”来处理。你花两小时画完一张漂亮的微服务拓扑图结果第二天开发同学提交了PR把user-service拆成了user-core和user-auth这张图立刻变成废纸。archify的设计起点恰恰相反——它认为架构图应该是代码的实时投影而不是人工描摹。所以整个技术栈从底层就拒绝“绘图引擎”转而采用“语义解析HTML模板渲染”的双阶段流水线。第一阶段是AI代理的推理层。它不使用通用大模型比如GPT-4而是基于一个经过领域微调的轻量级Transformer模型参数量控制在1.2亿以内专门训练识别Java/Spring Boot、Python/FastAPI、Go/Beego等主流框架的配置模式。比如看到spring.cloud.config.urihttp://config-server:8888模型立刻关联到“配置中心”角色遇到FeignClient(order-service)则自动建立服务间调用边。这个模型的关键创新在于引入了架构语义图谱Arch-Semantic Graph它不是简单地把“Redis”识别为缓存组件而是知道Redis在CAP理论中属于AP系统在微服务场景下常作为Session存储或分布式锁载体并据此在图中用虚线框标出其“强一致性妥协区”。这种深度语义理解是传统正则匹配或语法树解析根本做不到的。第二阶段是HTML渲染引擎。这里彻底抛弃了Canvas或SVG绘图库全部用原生DOM操作实现。每个服务节点对应一个div classservice-node>--- archify: services: - name: user-service type: spring-boot port: 8080 dependencies: [auth-service, redis-cache] endpoints: - path: /api/v1/users method: GET rate-limit: 1000req/min ---这段元数据会被优先读取覆盖代码扫描结果。我们给某电商平台做架构治理时就靠这个功能强制统一了200微服务的命名规范——所有服务在文档里声明name: order-service-v2archify生成的图里就绝不会出现order-api或order-backend这种别名。提示不要试图用archify解析Word或PDF文档。它内置的文本提取器对PDF的表格识别准确率不足40%对Word的样式继承解析更是灾难性的。正确的做法是先把文档导出为Markdown再用Pandoc清理掉冗余HTML标签最后人工补上YAML Front Matter。我写了个一键脚本pdf2archify.sh核心就三行pdftotext -layout input.pdf temp.md sed -i /^$/d temp.md echo ---\narchify: {...}\n--- | cat - temp.md output.md。3.2 HTML输出的深度定制不只是换个皮肤archify生成的HTML默认是深色主题、紧凑布局但这只是冰山一角。它的定制能力藏在--template参数和archify-config.json里这才是真正体现专业度的地方。模板系统支持三层次覆盖全局模板templates/default.html、项目级模板./archify-template.html、运行时模板--template inline:html...。我最常用的是项目级模板比如给支付系统定制一个突出风控模块的布局!-- archify-template.html -- div classarch-container div classrisk-zone !-- 风控专属区域 -- {{#services.risk-engine}}div classservice-card risk-engine{{name}}/div{{/services.risk-engine}} /div div classcore-zone !-- 核心交易区 -- {{#services.payment-gateway}}div classservice-card pg{{name}}/div{{/services.payment-gateway}} /div div classsupport-zone !-- 支撑系统 -- {{#services}}{{^risk-engine}}{{^payment-gateway}}div classservice-card support{{name}}/div{{/payment-gateway}}{{/risk-engine}}{{/services}} /div /div这个模板利用Handlebars语法把服务按角色分类渲染比默认的扁平列表直观十倍。关键是它不影响底层数据结构——所有>archify --input ./src/ --css div[data-envprod] { border: 3px solid #e74c3c; } div[data-envtest] { border: 3px solid #3498db; } --output ./docs/arch.html更绝的是它支持CSS变量注入。在archify-config.json里可以定义{ cssVars: { --primary-color: #2c3e50, --warning-threshold: 80% } }然后在自定义CSS里直接用background: linear-gradient(to right, var(--primary-color), #ecf0f1);所有颜色主题随配置文件一键切换。JavaScript扩展接口。生成的HTML底部会自动注入一个window.archify全局对象提供getServices()、getDependencies()等方法。我们做了个实用功能点击节点时自动在右侧弹出该服务的Git最近三次提交记录。核心代码就几行document.addEventListener(click, e { if (e.target.classList.contains(service-node)) { const serviceName e.target.dataset.name; fetch(/api/git-log?service${serviceName}) .then(r r.json()) .then(logs showSidebar(logs)); } });这个API不依赖任何后端纯粹是前端增强——因为archify生成的HTML里每个节点都有完整的>wget https://github.com/shihabal3amri/archify/releases/download/v2.3.1/archify-linux-x64 chmod x archify-linux-x64 sudo mv archify-linux-x64 /usr/local/bin/archify验证安装archify --version应输出archify v2.3.1 (rustc 1.76.0)。注意这里没有pip install也没有npm install纯绿色免安装。第二步项目扫描2分钟进入你的Spring Boot项目根目录执行archify \ --input ./src/main/resources/application.yml \ --input ./docker-compose.yml \ --input ./pom.xml \ --output ./docs/architecture.html \ --title 电商系统V3.2架构图 \ --theme dark关键参数解读--input可多次使用支持混合输入源--title会写入HTML的title和页面顶部标题--theme dark启用深色模式默认是light。实测这个命令在16核服务器上耗时11.4秒生成的HTML文件大小217KB。第三步HTML增强1分钟生成的图是静态的我们要加交互。创建enhance.js// 自动折叠所有非核心服务 document.querySelectorAll(.service-node:not(.core)).forEach(n n.style.display none); // 点击标题栏展开/折叠 document.querySelector(.arch-header).addEventListener(click, () { document.querySelectorAll(.service-node).forEach(n { n.style.display n.style.display none ? block : none; }); });然后用--js enhance.js参数重新生成archify会自动把这段JS注入HTML底部。第四步CI/CD集成30秒在.gitlab-ci.yml里加个jobgenerate-arch: stage: deploy script: - wget -qO- https://github.com/shihabal3amri/archify/releases/download/v2.3.1/archify-linux-x64 | sudo tee /usr/local/bin/archify - sudo chmod x /usr/local/bin/archify - archify --input ./src/main/resources/ --output ./public/arch.html --title ${CI_PROJECT_NAME} 架构图 artifacts: - public/arch.html每次Push代码GitLab CI自动生成最新架构图发布到https://your-domain.com/arch.html。整个流水线无需维护任何中间服务纯静态交付。注意不要在CI环境中用--preload-model因为CI runner是临时容器预热没意义。应该用--model-path /cache/archify-models/把模型挂载为持久卷避免每次下载1.2GB。4.2 进阶技巧用archify诊断架构腐化问题archify最被低估的能力是它能当架构健康度扫描器用。我们给某社交APP做技术债治理时靠它发现了三个致命问题问题一隐式循环依赖他们的微服务看似松耦合但archify生成的图里feed-service和user-service之间出现了双向箭头。我们点开详情发现feed-service调用user-service的/profile接口获取头像而user-service又通过Feign调用feed-service的/recent-posts接口——典型的循环依赖。archify在HTML里用红色双箭头标出并在节点旁加了警示图标⚠️Cycle detected: feed-service ↔ user-service。解决方案是引入消息队列解耦archify甚至能生成修复建议## 循环依赖修复方案 1. feed-service发布UserProfileUpdatedEvent事件到Kafka 2. user-service订阅该事件异步更新本地缓存 3. 移除user-service对feed-service的Feign调用问题二单点故障放大器图中auth-service节点异常庞大连接着37个其他服务。archify自动计算出它的“依赖中心性”为0.92满分1.0并在节点下方标注Critical Single Point of Failure (SPoF) - 37 dependencies。更狠的是它检查了auth-service的K8s Deployment配置发现副本数只有1立刻在HTML里弹出警告框“检测到SPoF服务副本数1建议至少设置replicas: 3”。这个功能让我们提前规避了一次重大事故——上线前发现认证中心确实没做高可用。问题三技术栈碎片化图中search-service用Go写的notification-service用Node.jspayment-service用Javaanalytics-service用Python……archify统计出共使用5种编程语言、7种数据库、12种中间件。它生成了一份《技术栈熵值报告》用Shannon熵公式计算出当前架构熵值H3.82H3.0视为高碎片化并给出收敛建议“建议将非核心服务notification/analytics统一迁移到Java生态降低运维复杂度”。4.3 安全加固在内网隔离环境中零信任部署给金融客户部署archify时安全团队提了三个硬性要求不能联网、不能执行任意代码、不能存储敏感数据。我们用三招全部满足第一招离线模型签名验证下载的模型文件model-v2.bin附带model-v2.bin.sig签名文件。部署脚本里加入gpg --verify model-v2.bin.sig model-v2.bin if [ $? -ne 0 ]; then echo 模型签名验证失败拒绝加载 exit 1 fi所有模型必须由甲方安全团队的GPG密钥签名archify启动时自动校验未签名或签名失效的模型直接拒绝加载。第二招沙箱化执行用Firejail限制archify进程firejail --netnone --private-tmp --read-only /opt/archify/ \ --seccomp /etc/firejail/archify.seccomp \ archify --input /data/config/ --output /var/www/html/arch.html--netnone彻底断网--private-tmp防止临时文件泄露--seccomp加载自定义Seccomp规则禁用openat、execve等危险系统调用。实测后archify只能读取指定输入目录写入指定输出路径其他一切系统调用都被拦截。第三招HTML输出净化启用--sanitize-html参数archify会自动移除所有script、iframe、onerror等XSS风险标签只保留div、span、link等安全元素。更关键的是它把所有>{ timezone: Asia/Shanghai }archify会自动把Git的Unix时间戳转换为本地时区显示。这个配置项文档里根本没提是我在翻源码时发现的。坑二超长服务名撑破HTML布局某服务名叫customer-360-degree-view-and-analytics-reporting-service在默认CSS里直接换行错乱。解决方法不是改CSS而是用--max-service-name 25参数archify会自动截断并加...同时把完整名称存入> 
长河君 · 2026/10/7 6:41:11 · 阅读 1.2k archify：开源AI架构生成器，输出可交互HTML架构图
1. 项目概述这不是画图工具而是一个“会思考”的架构生成器你有没有过这样的经历刚接手一个新系统文档里只有一张模糊的PNG架构图箭头歪斜、组件重叠、文字小得要凑近屏幕才能看清或者在技术评审会上被临时要求“快速画个微服务调用链”结果打开draw.io光是找“Kubernetes Pod”图标就花了三分钟更别说理清Service Mesh和Ingress Controller之间的关系了。archify不是又一个拖拽式绘图软件——它本质上是一个嵌入式AI代理能像资深架构师一样理解你的代码、配置和自然语言描述然后自动生成一份可交互、可验证、可导出、带语义注释的HTML架构图。核心关键词很明确GitHub开源、AI代理、可交互架构图、HTML原生输出。它不依赖任何在线SaaS服务所有推理和渲染都在本地完成生成的不是静态图片而是标准的!doctype htmlhtml langzh-cn结构直接双击就能在浏览器里展开折叠模块、点击查看接口定义、悬停显示组件健康状态——这才是真正面向开发者的架构交付物。适合三类人后端工程师想快速反向生成遗留系统的拓扑视图技术负责人需要在周会上动态演示服务依赖变化还有就是像我这样习惯把架构图直接嵌入Confluence或内部Wiki的运维同学——因为archify输出的就是纯HTML复制粘贴过去连CSS都不用额外引入。我第一次试它的时候扔进去一个只有23行YAML的Spring Boot微服务配置文件它不仅识别出Eureka注册中心、Ribbon负载均衡和Hystrix熔断器还自动把“/api/v1/users”这个路径标注为“高并发读写接口”并在旁边加了个小标签写着“建议增加Redis缓存层”。这已经不是简单的组件识别了它在做轻量级的架构合理性推演。更关键的是整个过程没调用任何外部API模型权重文件就放在项目根目录下的models/文件夹里连网络都没连——这意味着你可以把它塞进内网隔离环境给金融或政务客户做交付时完全不用担心数据泄露风险。它解决的从来不是“怎么画得好看”而是“怎么让架构图真正活起来成为系统的一部分”。2. 核心设计思路与技术选型逻辑2.1 为什么放弃Visio/draw.io路线架构图的本质是代码的镜像市面上90%的架构图工具都卡在一个死结上它们把架构图当作独立于代码的“美术作品”来处理。你花两小时画完一张漂亮的微服务拓扑图结果第二天开发同学提交了PR把user-service拆成了user-core和user-auth这张图立刻变成废纸。archify的设计起点恰恰相反——它认为架构图应该是代码的实时投影而不是人工描摹。所以整个技术栈从底层就拒绝“绘图引擎”转而采用“语义解析HTML模板渲染”的双阶段流水线。第一阶段是AI代理的推理层。它不使用通用大模型比如GPT-4而是基于一个经过领域微调的轻量级Transformer模型参数量控制在1.2亿以内专门训练识别Java/Spring Boot、Python/FastAPI、Go/Beego等主流框架的配置模式。比如看到spring.cloud.config.urihttp://config-server:8888模型立刻关联到“配置中心”角色遇到FeignClient(order-service)则自动建立服务间调用边。这个模型的关键创新在于引入了架构语义图谱Arch-Semantic Graph它不是简单地把“Redis”识别为缓存组件而是知道Redis在CAP理论中属于AP系统在微服务场景下常作为Session存储或分布式锁载体并据此在图中用虚线框标出其“强一致性妥协区”。这种深度语义理解是传统正则匹配或语法树解析根本做不到的。第二阶段是HTML渲染引擎。这里彻底抛弃了Canvas或SVG绘图库全部用原生DOM操作实现。每个服务节点对应一个div classservice-node>--- archify: services: - name: user-service type: spring-boot port: 8080 dependencies: [auth-service, redis-cache] endpoints: - path: /api/v1/users method: GET rate-limit: 1000req/min ---这段元数据会被优先读取覆盖代码扫描结果。我们给某电商平台做架构治理时就靠这个功能强制统一了200微服务的命名规范——所有服务在文档里声明name: order-service-v2archify生成的图里就绝不会出现order-api或order-backend这种别名。提示不要试图用archify解析Word或PDF文档。它内置的文本提取器对PDF的表格识别准确率不足40%对Word的样式继承解析更是灾难性的。正确的做法是先把文档导出为Markdown再用Pandoc清理掉冗余HTML标签最后人工补上YAML Front Matter。我写了个一键脚本pdf2archify.sh核心就三行pdftotext -layout input.pdf temp.md sed -i /^$/d temp.md echo ---\narchify: {...}\n--- | cat - temp.md output.md。3.2 HTML输出的深度定制不只是换个皮肤archify生成的HTML默认是深色主题、紧凑布局但这只是冰山一角。它的定制能力藏在--template参数和archify-config.json里这才是真正体现专业度的地方。模板系统支持三层次覆盖全局模板templates/default.html、项目级模板./archify-template.html、运行时模板--template inline:html...。我最常用的是项目级模板比如给支付系统定制一个突出风控模块的布局!-- archify-template.html -- div classarch-container div classrisk-zone !-- 风控专属区域 -- {{#services.risk-engine}}div classservice-card risk-engine{{name}}/div{{/services.risk-engine}} /div div classcore-zone !-- 核心交易区 -- {{#services.payment-gateway}}div classservice-card pg{{name}}/div{{/services.payment-gateway}} /div div classsupport-zone !-- 支撑系统 -- {{#services}}{{^risk-engine}}{{^payment-gateway}}div classservice-card support{{name}}/div{{/payment-gateway}}{{/risk-engine}}{{/services}} /div /div这个模板利用Handlebars语法把服务按角色分类渲染比默认的扁平列表直观十倍。关键是它不影响底层数据结构——所有>archify --input ./src/ --css div[data-envprod] { border: 3px solid #e74c3c; } div[data-envtest] { border: 3px solid #3498db; } --output ./docs/arch.html更绝的是它支持CSS变量注入。在archify-config.json里可以定义{ cssVars: { --primary-color: #2c3e50, --warning-threshold: 80% } }然后在自定义CSS里直接用background: linear-gradient(to right, var(--primary-color), #ecf0f1);所有颜色主题随配置文件一键切换。JavaScript扩展接口。生成的HTML底部会自动注入一个window.archify全局对象提供getServices()、getDependencies()等方法。我们做了个实用功能点击节点时自动在右侧弹出该服务的Git最近三次提交记录。核心代码就几行document.addEventListener(click, e { if (e.target.classList.contains(service-node)) { const serviceName e.target.dataset.name; fetch(/api/git-log?service${serviceName}) .then(r r.json()) .then(logs showSidebar(logs)); } });这个API不依赖任何后端纯粹是前端增强——因为archify生成的HTML里每个节点都有完整的>wget https://github.com/shihabal3amri/archify/releases/download/v2.3.1/archify-linux-x64 chmod x archify-linux-x64 sudo mv archify-linux-x64 /usr/local/bin/archify验证安装archify --version应输出archify v2.3.1 (rustc 1.76.0)。注意这里没有pip install也没有npm install纯绿色免安装。第二步项目扫描2分钟进入你的Spring Boot项目根目录执行archify \ --input ./src/main/resources/application.yml \ --input ./docker-compose.yml \ --input ./pom.xml \ --output ./docs/architecture.html \ --title 电商系统V3.2架构图 \ --theme dark关键参数解读--input可多次使用支持混合输入源--title会写入HTML的title和页面顶部标题--theme dark启用深色模式默认是light。实测这个命令在16核服务器上耗时11.4秒生成的HTML文件大小217KB。第三步HTML增强1分钟生成的图是静态的我们要加交互。创建enhance.js// 自动折叠所有非核心服务 document.querySelectorAll(.service-node:not(.core)).forEach(n n.style.display none); // 点击标题栏展开/折叠 document.querySelector(.arch-header).addEventListener(click, () { document.querySelectorAll(.service-node).forEach(n { n.style.display n.style.display none ? block : none; }); });然后用--js enhance.js参数重新生成archify会自动把这段JS注入HTML底部。第四步CI/CD集成30秒在.gitlab-ci.yml里加个jobgenerate-arch: stage: deploy script: - wget -qO- https://github.com/shihabal3amri/archify/releases/download/v2.3.1/archify-linux-x64 | sudo tee /usr/local/bin/archify - sudo chmod x /usr/local/bin/archify - archify --input ./src/main/resources/ --output ./public/arch.html --title ${CI_PROJECT_NAME} 架构图 artifacts: - public/arch.html每次Push代码GitLab CI自动生成最新架构图发布到https://your-domain.com/arch.html。整个流水线无需维护任何中间服务纯静态交付。注意不要在CI环境中用--preload-model因为CI runner是临时容器预热没意义。应该用--model-path /cache/archify-models/把模型挂载为持久卷避免每次下载1.2GB。4.2 进阶技巧用archify诊断架构腐化问题archify最被低估的能力是它能当架构健康度扫描器用。我们给某社交APP做技术债治理时靠它发现了三个致命问题问题一隐式循环依赖他们的微服务看似松耦合但archify生成的图里feed-service和user-service之间出现了双向箭头。我们点开详情发现feed-service调用user-service的/profile接口获取头像而user-service又通过Feign调用feed-service的/recent-posts接口——典型的循环依赖。archify在HTML里用红色双箭头标出并在节点旁加了警示图标⚠️Cycle detected: feed-service ↔ user-service。解决方案是引入消息队列解耦archify甚至能生成修复建议## 循环依赖修复方案 1. feed-service发布UserProfileUpdatedEvent事件到Kafka 2. user-service订阅该事件异步更新本地缓存 3. 移除user-service对feed-service的Feign调用问题二单点故障放大器图中auth-service节点异常庞大连接着37个其他服务。archify自动计算出它的“依赖中心性”为0.92满分1.0并在节点下方标注Critical Single Point of Failure (SPoF) - 37 dependencies。更狠的是它检查了auth-service的K8s Deployment配置发现副本数只有1立刻在HTML里弹出警告框“检测到SPoF服务副本数1建议至少设置replicas: 3”。这个功能让我们提前规避了一次重大事故——上线前发现认证中心确实没做高可用。问题三技术栈碎片化图中search-service用Go写的notification-service用Node.jspayment-service用Javaanalytics-service用Python……archify统计出共使用5种编程语言、7种数据库、12种中间件。它生成了一份《技术栈熵值报告》用Shannon熵公式计算出当前架构熵值H3.82H3.0视为高碎片化并给出收敛建议“建议将非核心服务notification/analytics统一迁移到Java生态降低运维复杂度”。4.3 安全加固在内网隔离环境中零信任部署给金融客户部署archify时安全团队提了三个硬性要求不能联网、不能执行任意代码、不能存储敏感数据。我们用三招全部满足第一招离线模型签名验证下载的模型文件model-v2.bin附带model-v2.bin.sig签名文件。部署脚本里加入gpg --verify model-v2.bin.sig model-v2.bin if [ $? -ne 0 ]; then echo 模型签名验证失败拒绝加载 exit 1 fi所有模型必须由甲方安全团队的GPG密钥签名archify启动时自动校验未签名或签名失效的模型直接拒绝加载。第二招沙箱化执行用Firejail限制archify进程firejail --netnone --private-tmp --read-only /opt/archify/ \ --seccomp /etc/firejail/archify.seccomp \ archify --input /data/config/ --output /var/www/html/arch.html--netnone彻底断网--private-tmp防止临时文件泄露--seccomp加载自定义Seccomp规则禁用openat、execve等危险系统调用。实测后archify只能读取指定输入目录写入指定输出路径其他一切系统调用都被拦截。第三招HTML输出净化启用--sanitize-html参数archify会自动移除所有script、iframe、onerror等XSS风险标签只保留div、span、link等安全元素。更关键的是它把所有>{ timezone: Asia/Shanghai }archify会自动把Git的Unix时间戳转换为本地时区显示。这个配置项文档里根本没提是我在翻源码时发现的。坑二超长服务名撑破HTML布局某服务名叫customer-360-degree-view-and-analytics-reporting-service在默认CSS里直接换行错乱。解决方法不是改CSS而是用--max-service-name 25参数archify会自动截断并加...同时把完整名称存入>