nvzhuang技术架构揭秘:GoFrame v2后端+纯静态前端的AI虚拟试穿全链路拆解

原创2026-11-01 23:55:132,292 阅读

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 套服装参考图库。

nvzhuang 中文模式界面截图:深色主题的 AI 女装参考图集网格与 AI 虚拟试穿入口

二、前端:一个 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 端口),试穿功能开箱即连,无需任何额外配置。

nvzhuang 关键词搜索界面:支持中文与英文双向检索的 AI 服装图集搜索框

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 中写死,先入先出):

  1. RequestID:为每个请求分配唯一 ID,贯穿日志与错误响应
  2. HandlerResponse:GoFrame 统一 JSON 响应包装
  3. CORS 精确白名单:非授权来源直接 403(ORIGIN_NOT_ALLOWED)
  4. BodyLimit:请求体超过 24 MiB 在 JSON 解析前就截断(413)
  5. Auth:Bearer Token 校验,服务端只存 SHA-256 摘要并恒定时间比对
  6. RateLimit:令牌桶限流,默认 10 次/分钟,超限返回 429 并附带 Retry-After

3.2 接口定义:一个结构体就是一个 API

GoFrame 的 API 定义写在结构体标签里,backend/api/tryon/v1/tryon.go 中 TryonReq 同时携带路由(POST /tryon)、校验规则与字段文档:人像照片(base64)、服装图(base64)、模型别名、输出尺寸、是否保留面部,以及一个关键的 ClientConfig 字段——用户在浏览器设置中心保存的个人模型配置,只随单次请求使用,后端不写入数据库、配置文件或业务日志。

nvzhuang 英文模式界面:English 切换后的 AI 服装参考图集与分类标签栏

四、多模型可插拔设计:换模型不改代码

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 后再拨号,防止公开后端被当作内网请求代理。

nvzhuang AI 虚拟试穿合成效果:保留模特五官发型,服装自然融合

五、公网部署安全:六层防护防止大模型账单被刷

/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 前端如何找到后端

前端按优先级从高到低识别后端地址:

  1. 设置中心保存的「后端 API 地址」(当前浏览器)
  2. window.AI_API_URL 全局变量(页面加载前注入)
  3. URL 参数:?tryon=http://localhost:8000
  4. 本地回退: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 虚拟试穿全链路就全部跑通了。

登录后查看全文
nvzhuang