nvzhuang技术架构揭秘:GoFrame v2后端+纯静态前端的AI虚拟试穿全链路拆解
nvzhuang技术架构揭秘:GoFrame v2后端+纯静态前端的AI虚拟试穿全链路拆解
nvzhuang 是一个开源的 AI 女装参考图集与虚拟试穿网站,收录 1407 张 AI 生成的服装图,支持中英文双向检索,并内置 AI 一键换装能力。它的前端是纯静态网站(无需构建、打开即用),后端则是基于 GoFrame v2 的 AI 试穿服务,支持 OpenAI Images、Gemini、豆包 Seedream 及本地 ComfyUI 四种模型协议。本文从前端结构、后端启动链路、多模型适配到公网安全防护,带你完整拆解这套 AI 虚拟试穿全链路架构。
一、架构总览:一个前端 + 一个后端,各管一段
nvzhuang 的架构刻意保持"极简分工":
| 层 | 技术 | 核心职责 |
|---|---|---|
| 静态前端 | index.html + data.js |
1407 张图集浏览、分类筛选、中英双语搜索、AI 试穿交互 |
| 动态后端 | GoFrame v2(backend/,可选) |
接收人像+服装图,代理调用生图大模型,返回换装结果 |
前端完全不依赖后端——浏览图集、搜索、下载全部本地完成;只有点击「AI 换装」时,才会把两张图片发给后端。这种设计让用户即使零部署,也能先体验 1407 套服装参考图库。
二、前端:一个 HTML 文件撑起整个静态站点
2.1 单文件 + 数据文件的设计
前端全部逻辑集中在两个文件里:
- index.html:页面结构、深色主题样式、双语字典、分类筛选、无限滚动、键盘 ←/→ 切换大图、AI 试穿搭配台,全部内联在这一个文件(约 2000 行),无任何构建步骤。
- data.js:1407 条服装记录,每条包含
id、分类、关键词、缩略图与展示图路径。数据保留原始日文字段名(如カテゴリ、キーワード),由前端自动本地化为中文或英文展示。
图片资源也做了双层缓存:assets/thumbs/ 放网格卡片用的缩略图,assets/img/ 放弹窗放大用的展示图,滚动加载时只拉小图,点击详情才加载大图,带宽和体感速度都更优。
2.2 三种方式打开,零门槛体验
# 方式一:Python 内置服务器(推荐端口 3000,与后端 8000 不冲突)
python3 -m http.server 3000
# 方式二:Node 简单服务器
npx serve -l 3000 .
# 方式三:直接用现代浏览器打开 index.html
启动后打开 http://localhost:3000 即可。若本地同时启动了后端(8000 端口),试穿功能开箱即连,无需任何额外配置。
2.3 URL 参数分享状态
前端还支持通过 URL 参数直接分享特定浏览状态,方便社群传播:
?lang=en初始切换到英文界面?q=lace预填搜索词?lang=en&q=white组合使用
三、后端启动链路:GoFrame v2 如何拉起整套服务
3.1 从 main.go 到路由绑定
后端入口 backend/main.go 非常克制:
func main() {
cmd.Main.Run(gctx.GetInitCtx())
}
真正的启动逻辑在 backend/internal/cmd/cmd.go:先初始化 security.InitService(鉴权、限流、配额、并发四件套),再创建 CORS、请求体限制、鉴权、限流四类中间件,最后通过 GoFrame 的 ghttp.RouterGroup 把 hello 和 tryon 两个控制器统一绑定到路由组,s.Run() 后服务监听在 :8000。
请求进来后依次穿过这条中间件链(顺序在 cmd.go 中写死,先入先出):
- RequestID:为每个请求分配唯一 ID,贯穿日志与错误响应
- HandlerResponse:GoFrame 统一 JSON 响应包装
- CORS 精确白名单:非授权来源直接 403(
ORIGIN_NOT_ALLOWED) - BodyLimit:请求体超过 24 MiB 在 JSON 解析前就截断(413)
- Auth:Bearer Token 校验,服务端只存 SHA-256 摘要并恒定时间比对
- RateLimit:令牌桶限流,默认 10 次/分钟,超限返回 429 并附带
Retry-After
3.2 接口定义:一个结构体就是一个 API
GoFrame 的 API 定义写在结构体标签里,backend/api/tryon/v1/tryon.go 中 TryonReq 同时携带路由(POST /tryon)、校验规则与字段文档:人像照片(base64)、服装图(base64)、模型别名、输出尺寸、是否保留面部,以及一个关键的 ClientConfig 字段——用户在浏览器设置中心保存的个人模型配置,只随单次请求使用,后端不写入数据库、配置文件或业务日志。
四、多模型可插拔设计:换模型不改代码
4.1 统一接口 + 协议适配
AI 试穿的核心抽象是 backend/internal/logic/tryon/generator.go 中的 ImageGenerator 接口(只有 Generate 和 Name 两个方法)。newGeneratorFromConfig 按 provider 字段路由到具体适配器:
| provider | 适配器 | 覆盖模型 |
|---|---|---|
openai(含 qwen/zhipu/siliconflow 别名) |
gpt_image.go | GPT Image 2、通义万相、智谱 CogView、硅基流动等一切 OpenAI 兼容服务 |
doubao |
doubao.go | 豆包 Seedream(火山方舟) |
gemini |
gemini.go | Nano Banana 2(gemini-3.1-flash-image) |
comfyui |
comfyui.go | 本地 Qwen-Image-Edit-2511 + Lightning LoRA,未就绪自动回退 MiniMax H3 |
默认模型是 Gemini:代码注释里写得很直白——GPT Image 系列对真人换装场景会被官方内容审核拦截,而 Gemini 无此限制。
4.2 配置即接入:加一个模型只需加一段 YAML
所有模型的 API Key、Base URL、模型名 都集中在 backend/manifest/config/config.example.yaml 的 llm.models 下:
llm:
models:
gpt-image:
provider: openai
envKey: "OPENAI_API_KEY" # 环境变量优先于 apiKey
baseURL: "https://api.openai.com/v1"
model: "gpt-image-2"
comfyui:
provider: comfyui
baseURL: "http://127.0.0.1:8188"
model: "qwen-image-edit-2511"
workflowPath: "workflows/comfyui_qwen_image_edit_2511_api.json"
loadModelConfig 按 llm.models.<别名> 读取配置,环境变量可覆盖 Key;旧版 llm.openai / llm.gemini 写法也有兼容回退。ComfyUI 工作流文件随仓库提供(见 backend/workflows/),固定节点映射只允许来自服务端配置,避免公网后端被诱导访问用户指定的内网地址。
4.3 换装全链路的执行顺序
一次 POST /tryon 的完整路径(backend/internal/logic/tryon/tryon.go):
参数校验 → base64 解码 → 选定模型适配器(服务端预设 or 浏览器个人配置)→ 按模型构建差异化提示词(GPT 用防封控安全提示词,Gemini 用稳定英文提示词)→ 调用生成 → 脱敏包装错误后返回 base64 结果图
个人配置模式还有一层 SSRF 防线:validateClientModelConfig 拒绝 Base URL 指向 localhost、内网与保留地址,且自定义 HTTP 客户端会先解析域名、逐个排除非公网 IP 后再拨号,防止公开后端被当作内网请求代理。
五、公网部署安全:六层防护防止大模型账单被刷
/tryon 接口直接消耗用户的模型配额,所以 backend/DEPLOY.md 把安全加固列为必读,防护层可归纳为六道:
| # | 防护 | 默认值 | 触发表现 |
|---|---|---|---|
| 1 | Bearer Token 鉴权(security.authRequired: true) |
服务端仅存 SHA-256 摘要 | 401 AUTH_REQUIRED |
| 2 | CORS 精确域名白名单(禁止 *) |
— | 403 ORIGIN_NOT_ALLOWED |
| 3 | 令牌桶限流 | 10 次/分,突发 3 次 | 429 RATE_LIMITED + Retry-After |
| 4 | UTC 自然日额度 | 每调用方 100 次/天 | 429 DAILY_QUOTA_EXCEEDED |
| 5 | 并发锁定 | 全局 2、单主体 1 | 429 CONCURRENCY_LIMITED(不排队) |
| 6 | 图片真实性与像素校验 | JPEG/PNG/WebP;单图 ≤8 MiB、双图 ≤16 MiB;256~8192 px;总像素 ≤2000 万 | 413/422 系列错误码 |
第 6 层值得单独说:backend/internal/imagevalidate/validate.go 用内容嗅探 + 图像解码器探测真实 MIME,伪造扩展名的 SVG、GIF 甚至可执行文件都过不了关;2000 万像素的总上限则是专门针对"解压像素炸弹"(小文件解包成超大位图拖垮内存)的防御。前端侧也配合做了自适应压缩——最长边缩到 2048 px 以内、WebP 优先阶梯压缩,手机实拍照基本无感上传。
六、快速上手:三条部署路径 + 前端对接顺序
6.1 后端三种启动方式
Docker Compose(推荐):
cd backend
cp .env.example .env # 填入你的模型 Key
docker compose up -d # 服务监听 http://localhost:8000
Docker Run 单命令:
docker build -f manifest/docker/Dockerfile -t costume-tryon .
docker run -d --name costume-tryon -p 8000:8000 \
-e ARK_API_KEY="你的豆包ArkKey" costume-tryon
无 Docker:cd backend && export ARK_API_KEY="你的Key" && go run main.go;Windows 用户可直接双击 backend/restart.bat 一键编译启动。
6.2 前端如何找到后端
前端按优先级从高到低识别后端地址:
- 设置中心保存的「后端 API 地址」(当前浏览器)
window.AI_API_URL全局变量(页面加载前注入)- URL 参数:
?tryon=http://localhost:8000 - 本地回退:
localhost/127.0.0.1访问时自动连http://127.0.0.1:8000
公网部署建议用 Nginx 反代到 https://api.你的域名(配置见 DEPLOY.md 第四节),前端加一行 window.AI_API_URL 即可,顺带解决跨域与明文 Key 问题。
6.3 一条 curl 验证部署
curl -X POST https://api.你的域名/tryon \
-H "Authorization: Bearer 你的Token" \
-H "Content-Type: application/json" -d '{}'
收到 The PersonImage field is required 这类参数校验错误,说明服务已正常,回到网页点「AI 换装」就能用了。
七、写在最后
nvzhuang 的架构给中小项目的参考点很明确:
- 前端静态化:把展示层做成零构建单文件站点,部署成本趋近于零,用户体验不受后端可用性影响;
- 后端只做一件事:一个
/tryon接口 + 多模型适配器,配置驱动接入新模型,代码零改动; - 安全前置:鉴权、限流、配额、并发、图片校验、SSRF 防护全部内建在中间件与业务层,公网部署开箱即防刷。
想动手体验,先 python3 -m http.server 3000 逛完图集,再按第六节拉起后端配一个 API Key,一条 curl 之后,AI 虚拟试穿全链路就全部跑通了。



