# spring-image-gen

**Repository Path**: alenzhai/spring-image-gen

## Basic Information

- **Project Name**: spring-image-gen
- **Description**: 商品图片生成程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Images Gen

一个基于 Spring Boot 的电商图片生成工具，支持登录认证、用户管理和火山引擎图片生成接口调用。页面可填写商品场景、横幅文字、主标题、卖点标签，并上传参考图生成电商主图。

## 功能特性

- 电商图片生成
  - 支持上传一张或多张参考图
  - 支持填写产品/场景描述
  - 支持配置顶部横幅文字、主标题和卖点图标文案
  - 生成结果按 3:4 比例展示
  - 参考图按原始比例预览
- 登录认证
  - 用户注册、登录、退出
  - 未登录用户不可调用图片生成接口
- 用户管理
  - 管理员可查看、更新、重置密码和删除用户
  - 防止删除、禁用或降级最后一个管理员
- 数据持久化
  - 使用 H2 文件数据库保存认证用户信息
- Docker 部署
  - 已提供多阶段构建 Dockerfile

## 技术栈

- Java 17
- Spring Boot 3.5.14
- Spring Security
- Spring JDBC
- H2 Database
- Volcengine Ark Runtime SDK
- Maven Wrapper

## 目录结构

```text
src/main/java/com/images/gen
├── common      # 通用响应、提示词构造、图片工具
├── config      # 安全配置、火山引擎配置、初始化配置
├── controller  # 认证、图片生成、用户管理接口
├── dto         # 请求/响应 DTO
└── service     # 业务服务

src/main/resources
├── application.yml
└── static
    ├── index.html   # 图片生成页面
    └── admin.html   # 用户管理页面
```

## 环境要求

- JDK 17+
- Maven 可选，项目已包含 `mvnw`
- 火山引擎图片生成 API Key

## 本地运行

### 1. 配置环境变量

至少需要配置火山引擎 API Key：

```bash
export VOLCENGINE_API_KEY=你的火山引擎APIKey
```

Windows PowerShell：

```powershell
$env:VOLCENGINE_API_KEY="你的火山引擎APIKey"
```

可选配置：

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `VOLCENGINE_API_KEY` | 空 | 火山引擎 API Key |
| `VOLCENGINE_MODEL` | `doubao-seedream-5-0-260128` | 图片生成模型 |
| `IMAGE_AUTH_USERNAME` | `admin` | 初始化管理员用户名 |
| `IMAGE_AUTH_PASSWORD` | `admin123` | 初始化管理员密码 |
| `AUTH_DB_URL` | `jdbc:h2:file:./data/auth-db` | H2 数据库地址 |
| `AUTH_DB_USERNAME` | `sa` | 数据库用户名 |
| `AUTH_DB_PASSWORD` | 空 | 数据库密码 |

### 2. 启动服务

```bash
./mvnw spring-boot:run
```

访问：

```text
http://localhost:8080
```

默认管理员账号：

```text
用户名：admin
密码：admin123
```

## 构建运行

```bash
./mvnw package -DskipTests
java -jar target/spring-images-gen-0.0.1-SNAPSHOT.jar
```

## Docker 部署

### 构建镜像

```bash
docker build -t spring-images-gen@latest .
```

### 运行容器

```bash
docker run -p 8080:8080 \
  -e VOLCENGINE_API_KEY=你的火山引擎APIKey \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config
  spring-images-gen@latest
```

Windows PowerShell：

```powershell
docker run -p 8080:8080 `
  -e VOLCENGINE_API_KEY=你的火山引擎APIKey `
  -v ${PWD}/data:/app/data `
  -v ${PWD}/config:/app/config `
  spring-images-gen
```

挂载 `data` 目录后，H2 用户数据库会持久化到宿主机。

## 接口说明

### 图片生成

```http
POST /api/image/generate
Content-Type: application/json
```

请求示例：

```json
{
  "scene": "一款太阳能户外壁灯，适合花园庭院场景",
  "bannerText": "САДОВЫЙ ФОНАРЬ",
  "titleText": "СОЛНЕЧНЫЙ СВЕТ",
  "iconLabels": ["1200mA", "ВОДОНЕПРОНИЦАЕМЫЙ"],
  "images": ["data:image/jpeg;base64,..."]
}
```

说明：该接口需要登录后访问。

### 认证接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/api/auth/register` | 注册用户 |
| `POST` | `/api/auth/login` | 登录 |
| `POST` | `/api/auth/logout` | 退出登录 |
| `GET` | `/api/auth/me` | 查询当前登录状态 |

### 管理员接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/admin/users` | 获取用户列表 |
| `PUT` | `/api/admin/users/{username}` | 更新用户状态/角色 |
| `PUT` | `/api/admin/users/{username}/password` | 重置用户密码 |
| `DELETE` | `/api/admin/users/{username}` | 删除用户 |

## 测试

```bash
./mvnw test
```

如果未配置 `VOLCENGINE_API_KEY`，直接调用真实图片生成接口的测试会自动跳过。

## 使用建议

- 参考图尽量选择主体清晰、背景干净、角度明确的图片。
- 如果需要稳定保留商品外观，建议只上传一张主参考图。
- 图片模型生成文字存在不确定性，如需 100% 准确文字，建议后续改为后端或前端叠加文字。