# generate-image

**Repository Path**: junweizhou/generate-image

## Basic Information

- **Project Name**: generate-image
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Image Playground

基于 Next.js 的图片生成应用，参考 `https://image.huasan.xyz/generate`。

## 当前功能

- `/generate`：输入提示词、选择尺寸、选择生成数量、发布到画廊、预览和下载。
- `/edit`：上传本地图片或选择历史图片，通过提示词进行修图；上传原图会持久化保存。
- `/history`：查看当前登录用户的生成历史。
- `/gallery`：查看公开发布到画廊的图片。
- `/api/*`：认证、积分、签到、图片生成、第三方生图、历史记录、画廊等接口。
- `src/server/image/*`：图片生成服务适配层。
- `src/server/services/*`：后端业务逻辑层。

PostgreSQL 是主要持久化存储。接口会通过 `src/server/repositories/postgresRepository.ts` 访问数据库。

## 后端配置

复制 `.env.example` 为 `.env.local`：

```bash
cp .env.example .env.local
```

初始化 PostgreSQL 表结构：

```bash
npm run db:init
```

将用户提升为管理员：

```sql
update users set role = 'admin' where username = 'your_username';
```

`IMAGE_PROVIDER=inline-preview` 表示使用内置预览图，不需要外部图片服务。

`IMAGE_PROVIDER=openai-compatible` 表示调用兼容 OpenAI 的 `/images/generations` 图片生成接口：

```env
IMAGE_PROVIDER=openai-compatible
IMAGE_API_BASE_URL=https://api.openai.com/v1
IMAGE_API_KEY=your_key
IMAGE_MODEL=gpt-image-2
```

注册使用邮箱作为账号。邮箱验证码默认关闭；管理员可以在 `/console` 控制台在线填写 SMTP 主机、端口、账号、密码、发件人，并开启“邮箱注册验证”。开启后，新用户注册必须输入邮件验证码。

## 本地开发

```bash
npm install
npm run dev
```

## Docker 部署

构建并启动应用和 PostgreSQL：

```bash
docker compose up -d --build
```

Compose 默认把应用映射到宿主机 `18014` 端口：

```text
http://localhost:18014
http://<server-ip>:18014
```

可以通过 `APP_PORT` 修改宿主机访问端口：

```env
APP_PORT=18014
```

PostgreSQL 会在 `postgres-data` 卷第一次创建时，自动执行 `db/schema.sql` 初始化表结构。

默认图片服务是 `inline-preview`，所以 Docker 部署时即使没有外部图片 API，也能跑起来。

## 图片本地存储

默认使用本地文件存储生成图片和修图上传的原图：

```env
IMAGE_STORE=filesystem
IMAGE_UPLOAD_DIR=./uploads
IMAGE_PUBLIC_BASE_PATH=/api/assets
```

本地开发建议使用 `./uploads`。Docker 部署会通过 `docker-compose.yml` 默认覆盖为 `/app/uploads`。

生成后的图片不会再以 base64 形式直接塞进数据库。

当前数据流是：

```text
图片服务返回 base64
-> 服务端写入 uploads/YYYY/MM/DD/result-xxxx.png
-> 数据库只保存 /api/assets/YYYY/MM/DD/result-xxxx.png
-> 前端通过 imageUrl 正常展示图片
```

修图数据流是：

```text
本地上传图或历史图
-> 服务端转 PNG 并自动 resize 到 1024x1024 / 1792x1024 / 1024x1792 中最接近的尺寸
-> 原图写入 uploads/YYYY/MM/DD/source-xxxx.png
-> 调用图片编辑接口 /images/edits
-> 结果图写入 uploads/YYYY/MM/DD/result-xxxx.png
-> 数据库记录 sourceImageUrl 与 imageUrl
```

Docker 存储关系：

```text
postgres-data  -> db 容器:  /var/lib/postgresql/data
uploads-data   -> app 容器: /app/uploads
```

数据库里保存的图片地址类似：

```text
/api/assets/2026/05/28/xxxx.png
```

图片真实文件保存在 `uploads-data` Docker volume 里。查看宿主机真实路径：

```bash
docker volume inspect generate-image_uploads-data
```

如果 `docker volume ls` 里还没有看到 `generate-image_uploads-data`，说明新版容器还没有重新创建。执行：

```bash
docker compose up -d --build --force-recreate app
```

然后再查看：

```bash
docker volume ls | grep generate-image
```

如果希望图片直接保存到项目目录，例如 `./uploads`，可以把 `docker-compose.yml` 里的 app volume 从：

```yaml
- uploads-data:/app/uploads
```

改成：

```yaml
- ./uploads:/app/uploads
```

这样新生成的图片会直接写入项目下的 `uploads/` 目录。

## 第三方指定用户生图 API

服务端可以开放 `POST /api/external/generate` 给可信第三方系统调用。这个接口不依赖网页登录 cookie，而是通过 `EXTERNAL_API_TOKEN` 鉴权。

先生成一个第三方调用密钥：

```bash
openssl rand -hex 32
```

写入环境变量：

```env
EXTERNAL_API_TOKEN=your-generated-token
APP_PUBLIC_BASE_URL=https://your-domain.com
```

`APP_PUBLIC_BASE_URL` 用来把数据库里的 `/api/assets/...` 相对图片地址转换成第三方可直接访问的完整链接。

第三方调用示例：

```bash
curl -X POST "https://your-domain.com/api/external/generate" \
  -H "Authorization: Bearer your-generated-token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "prompt": "一只赛博朋克风格的橘猫",
    "size": "1024x1024",
    "n": 1,
    "publishToGallery": false
  }'
```

也可以用 `userId` 指定目标用户，`userId` 和 `email` 二选一：

```json
{
  "userId": "目标用户 ID",
  "prompt": "一张未来城市海报",
  "size": "1024x1024",
  "n": 1
}
```

请求成功后，会扣除目标用户积分，生成记录会进入该用户的历史记录。返回的 `records[].imageUrl` 是可直接访问的完整图片链接。

## 使用外部图片 API

如果要使用兼容 OpenAI 的图片接口，可以在启动 Compose 时传入环境变量：

```bash
IMAGE_PROVIDER=openai-compatible IMAGE_API_KEY=your_key docker compose up -d --build
```

或者写入 `.env.local`：

```env
IMAGE_PROVIDER=openai-compatible
IMAGE_API_BASE_URL=https://api.openai.com/v1
IMAGE_API_KEY=your_key
IMAGE_MODEL=gpt-image-2
```

## 常用命令

```bash
docker compose logs -f app
docker compose down
docker compose down -v
```

注意：`docker compose down -v` 会删除 Compose 管理的 volume，包括数据库数据和本地图片数据。执行前请确认已经备份。