好图秀 AI Design 是一个面向商业设计场景的 AI 图片生成系统。仓库采用 Go + React monorepo 结构，包含 H5 创作端、Admin 运营端、HTTP API、异步任务 worker、MySQL/JSON 状态存储、Redis Streams 队列、OSS/本地资产存储、支付回调和 SEO 内容发布链路。

在线体验：设计师 AI 商业设计图生成工作台 | 好图秀

仓库地址: https://gitee.com/hfqf1234/figo-generate-images-website

项目效果

核心功能

• 行业工作台：基于 industryId、sceneId、语义字段和参考图槽位生成结构化生图请求。

• 模板系统：workbench_templates 保存 configSnapshotJson、generationParamsJson、封面图和发布状态，支持一键应用。

• 生图任务：/api/images/generate 支持同步执行和 taskId 异步轮询，异步模式由 Redis Streams 与 figo-worker 消费。

• 资产服务：AssetStorage 抽象本地目录和阿里云 OSS，统一返回 asset.url、asset.path、contentType、size。

• 用户与钱包：支持邮箱验证码、会话 Cookie、积分余额、冻结、扣减、释放、流水和作品归属。

• 支付域：封装订单创建、支付发起、支付宝/微信回调验签、mock 支付和对账入口。

• 运营管理：Admin API 覆盖用户、订单、生成任务、上游池、模板、资产、队列状态、死信、审计日志和代理商。

• 内容与 SEO：提供首页、行业页、案例页、产品页、手册页、工具页、sitemap.xml、robots.txt 和公开 Markdown 文章接口。

技术栈

• 后端：Go 1.22、标准库 net/http

• 前台：React 19、TypeScript、Vite、Tailwind CSS、lucide-react

• 管理端：React 19、TypeScript、Vite

• 存储：本地 JSON、MySQL

• 队列：本地队列、Redis Streams

• 资产：本地目录、阿里云 OSS

• 支付：支付宝、微信支付、mock 支付

• 验证码：noop、SMTP、阿里云短信

技术方案

系统按“展示层、接入层、领域层、适配层、持久层、运行层”拆分。领域服务只依赖接口契约，外部生图上游、资产存储、队列、支付、验证码和持久化实现通过适配层注入。H5 与 Admin 不直接访问基础设施，只通过 HTTP API 与服务端交互。

技术架构图

矢量图由 fireworks-tech-graph 生成，按系统总览、业务流程、模块边界拆分，避免单图压缩过多信息。

系统架构总览：

生图任务业务流程：

代码模块划分与依赖边界：

分层职责

层级	主要目录	职责
展示层	codes/h5、codes/admin、web/templates	用户创作、运营控制台、SEO 页面和静态资源展示
接入层	internal/server	注册路由、解析请求、会话校验、调用领域服务并返回 JSON/HTML
领域层	internal/generation、internal/wallet、internal/billing、internal/admin、internal/auth	承载核心业务规则，避免把计费、任务、用户、运营逻辑散落在 Handler 中
适配层	internal/favor、internal/assets、internal/payment、internal/queue、internal/vectorize	对接外部 AI、OSS、本地文件、支付、Redis 等可替换能力
持久层	internal/store、internal/store/mysqlstore、migrations	提供 JSON 与 MySQL 两套状态存储，便于本地开发和生产部署切换
运行层	cmd/server、cmd/worker、cmd/migrate、cmd/payment-reconcile	按职责拆分服务进程、异步任务进程、迁移和对账工具

关键设计点

• Handler 只负责协议适配和服务编排，核心规则下沉到领域服务，便于测试和替换入口。

• 生图服务通过 ImageGenerator、AssetStorage、Queue、Wallet 等接口依赖外部能力，保持依赖倒置，符合 SOLID 的开闭原则和单一职责原则。

• 本地开发可使用 JSON、本地资产目录、mock 生图和 noop 验证码；生产可切换为 MySQL、Redis、OSS、真实上游、SMTP/短信和真实支付。

• 异步模式下 server 只创建任务并入队，worker 独立消费，避免长时间生图请求占用 HTTP 连接。

• 管理端可查看运行健康、队列、死信、上游、资产、用户和订单，方便定位生产问题。

项目内置 Skills

skills/ 目录定义项目级自动化协议，用于约束 AI Agent 或人工批处理任务的输入、输出、文件位置、字段契约和发布校验。该目录不参与运行时依赖，定位为内容生产、数据初始化和运营发布的工程规范。

Skill	文件	解决的问题	设计要点
好图秀工作台模版生图	skills/generate-models/SKILL.md	批量生成热门模版效果图，并写入可一键应用的工作台模版记录	固定行业/场景枚举；限制 fields[].key 为前端可识别语义字段；coverUrl 必须是永久 URL；status=enabled；同场景最多保留 10 个差异化模版
好图秀 GEO Markdown 软文	skills/geo-markdown/SKILL.md	生成可被 /showcase 消费的公开 Markdown 内容和结构化元数据	Markdown 固定落在 web/public/showcase/articles；元数据入库；图片使用永久 URL；禁止写入 H5 源码和构建目录；正文不包含 frontmatter

通过 skill 固化数据生产约束，可以降低批量模版、案例文章和图片资产在多轮生成中的漂移风险。核心约束包括：枚举不自造、字段不泛化、图片不使用临时 URL、内容不写入构建产物、元数据与正文分离。

工程化设计取舍

设计点	实现方式	工程收益
Prompt 结构化	行业、场景、语义字段、参考图槽位和 configSnapshotJson	降低纯文本 Prompt 的不可控性，提高模板复用能力
生图任务可追踪	GenerationTask 记录状态、进度、计费状态、上游任务 ID、超时和失败原因	支持刷新后继续轮询、失败复盘、运营补偿和死信处理
计费与任务解耦	钱包服务提供冻结、提交、释放和流水记录	避免生成失败导致积分状态不一致
上游可替换	favor.WeightedClient 基于上游池、权重和 token cursor 选择 endpoint	支持多线路、4K 模型、编辑接口和 fallback 配置
资产 URL 稳定	生成结果落本地目录或 OSS，再写入 Asset 记录	避免上游临时 URL 过期影响作品历史和内容页
开发/生产配置分层	JSON/local/mock/noop 用于本地，MySQL/Redis/OSS/真实支付用于生产	降低本地启动成本，同时保留生产扩展路径
内容资产服务端化	Markdown 存放于 web/public，列表和 SEO 元数据走数据库	避免内容硬编码进 H5 bundle，便于运营筛选、发布和回滚

整体设计目标是保持模块边界稳定：前台负责交互状态，Admin 负责运营与排障，Handler 负责协议转换，领域服务负责业务不变量，适配层负责外部系统差异。新增能力优先通过接口扩展或领域服务扩展实现，避免把支付、队列、上游、生图和资产逻辑耦合到同一个处理函数中。

目录结构

.
├── cmd/                    # server、worker、migrate、payment-reconcile 入口
├── internal/               # 后端领域服务、配置、存储、支付、生成、管理端 API
├── web/                    # Go embed 的静态资源、模板、H5/Admin 构建产物
├── codes/h5/               # 前台 H5 React/Vite 源码
├── codes/admin/            # 管理端 React/Vite 源码
├── migrations/             # MySQL 初始化与迁移 SQL
├── scripts/                # 本地验证、云端部署、对账脚本
├── docs/                   # 中文部署、进度、方案文档
├── shots/                  # README 项目效果截图
└── skills/                 # 项目内辅助技能说明

快速启动

1. 准备环境

需要安装：

• Go 1.22 或更高版本

• Node.js 22 或兼容版本

• npm

2. 初始化配置

cp .env.local.example .env.local

本地默认配置建议：

FIGO_STORE_DRIVER=json
FIGO_MOCK_FAVOR=1
FIGO_GENERATION_MODE=sync
FIGO_STORAGE_DRIVER=local
FIGO_VERIFICATION_PROVIDER=noop

接入真实生图上游时，设置 FAVOR_API_KEY，并将 FIGO_MOCK_FAVOR=0。

3. 启动后端

scripts/deploy-local.sh --run

默认路由：

• 首页：http://localhost:8080/

• 创作工作台：http://localhost:8080/workbench

• 管理端：http://localhost:8080/admin

4. 单独开发前台

cd codes/h5
npm ci
npm run dev

H5 Vite dev server 默认监听 http://localhost:3000。

5. 单独开发管理端

cd codes/admin
npm ci
npm run dev

Admin Vite dev server 默认监听 http://localhost:3001。

常用命令

# Go 全量测试
go test ./...

# 构建后端二进制
go build -o bin/figo-server ./cmd/server
go build -o bin/figo-worker ./cmd/worker

# 前台检查与构建
cd codes/h5
npm run lint
npm run build

# 管理端检查与构建
cd codes/admin
npm run lint
npm run build

H5 前台默认构建到 codes/h5/dist，发布时同步到 web/h5；管理端构建到 web/admin。web/ 下的静态资源会由 Go embed 打包进服务端二进制。

生产部署

推荐生产拓扑：

浏览器
  -> HTTPS / Nginx
  -> figo-server
  -> MySQL
  -> Redis Streams
  -> figo-worker
  -> AI 生图上游
  -> OSS

关键运行参数：

• FIGO_STORE_DRIVER=mysql

• FIGO_GENERATION_MODE=queue

• FIGO_QUEUE_DRIVER=redis

• FIGO_STORAGE_DRIVER=oss

• FIGO_SESSION_COOKIE_SECURE=1

• FIGO_VERIFICATION_PROVIDER=smtp 或 aliyun_sms

• FIGO_PAYMENT_PROVIDER=alipay、wechat 或按配置自动选择

可参考：

• 阿里云部署手册

• 管理端进度手册

• 成本测算与定价方案

一键部署脚本入口：

bash scripts/one-click-deploy.sh --env-file .env.production

环境变量说明

常用配置分组如下，完整变量见 .env.local.example 和 .env.production.example。

分组	关键变量	说明
服务	PORT	HTTP 服务端口
管理端	FIGO_ADMIN_EMAIL、FIGO_ADMIN_PASSWORD	管理员初始化登录信息
存储	FIGO_STORE_DRIVER、FIGO_MYSQL_DSN、FIGO_DATA_PATH	MySQL 或本地 JSON 状态存储
生图	FAVOR_API_KEY、FAVOR_BASE_URL、FAVOR_IMAGE_MODEL、FIGO_MOCK_FAVOR	AI 生图上游与 mock 开关
队列	FIGO_GENERATION_MODE、FIGO_QUEUE_DRIVER、FIGO_REDIS_ADDR	同步模式或 Redis 异步队列
资产	FIGO_STORAGE_DRIVER、FIGO_LOCAL_ASSET_DIR、ALIYUN_OSS_*	本地或 OSS 图片存储
验证码	FIGO_VERIFICATION_PROVIDER、FIGO_SMTP_*、ALIYUN_SMS_*	邮件、短信或本地 noop
支付	FIGO_PAYMENT_PROVIDER、ALIPAY_*、WECHAT_PAY_*	支付渠道与回调配置
会话	FIGO_SESSION_COOKIE_SECURE、FIGO_SESSION_SAME_SITE、FIGO_SESSION_DOMAIN	登录 Cookie 安全配置

开源前安全检查

• 不要提交 .env.local、.env.production、数据库备份、私钥、支付证书和真实用户数据。

• 如果历史提交或示例文件曾出现真实密钥，应立即在对应云平台、支付平台、邮件服务中轮换。

• .env.*.example 只保留占位值或明显无效的示例值。

• 生产环境不要开启 FIGO_MOCK_FAVOR、FIGO_MOCK_PAYMENT。

• 管理端密码必须使用强密码，并建议通过反向代理、网络 ACL 或二次认证加强保护。

• OSS、RDS、Redis、短信服务建议使用最小权限账号。

开发约定

• 后端模块按领域边界拆分，新增能力优先通过接口和服务组合扩展。

• 前台与管理端 API 调用集中在各自 api.ts，组件层避免直接耦合请求细节。

• 影响计费、任务状态、队列、支付和资产持久化的变更必须补充自动化测试。

• 文档统一使用中文；部署、运维和方案细节放入 docs/，README 保持索引和架构说明职责。

贡献方式

欢迎提交 Issue 或 Pull Request。建议在提交前完成：

go test ./...
cd codes/h5 && npm run lint
cd ../admin && npm run lint

涉及前台或管理端页面时，请同时更新截图、文档或测试，方便后续维护者理解变更影响。

当前项目已按开源方式整理。上线或公开部署前，请务必检查 .env.*、云厂商密钥、支付密钥、短信/邮件凭证是否已经替换、脱敏并轮换。

许可证

本项目使用 MIT License 开源。