# chees_images

**Repository Path**: chees_cn/chees_images

## Basic Information

- **Project Name**: chees_images
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧀 Chees Images H5

<p align="center">
  <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js Version">
  <img src="https://img.shields.io/badge/yarn-%3E%3D4.0.0-blue" alt="Yarn Version">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
</p>

<p align="center">
  <b>基于积分系统的 AI 图片生成与管理平台</b>
</p>

[English Documentation](README.en.md) | 中文文档

---

## 📖 项目介绍

Chees Images H5 是一个面向用户的 AI 图片生成服务平台，采用积分制管理模式。用户可以通过卡密充值积分，使用积分生成和编辑图片。系统包含用户端 H5 页面和管理后台，支持完整的用户管理、积分管理、卡密管理和任务日志功能。

### ✨ 核心功能

- **用户系统**: 自主注册、JWT 认证、角色权限控制
- **积分系统**: 积分充值、消费、余额查询
- **卡密系统**: 批量生成、安全兑换、并发控制
- **AI 图片**: 文生图、图生图、任务记录
- **管理后台**: 用户管理、卡密管理、模型配置、日志查看

---

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                        前端层                               │
├─────────────────────┬───────────────────────────────────────┤
│   Web-Client (H5)   │           Web-Admin                   │
│   Vue 3 + Vite      │        Vue 3 + Vite                   │
│   移动端用户界面     │      管理后台界面                      │
└──────────┬──────────┴──────────────────┬────────────────────┘
           │                             │
           └──────────────┬──────────────┘
                          │
┌─────────────────────────▼──────────────────────────────────┐
│                      API 层                                │
│              NestJS + TypeScript                           │
│  - JWT 认证                                               │
│  - 权限控制 (RolesGuard)                                  │
│  - 输入验证 (ValidationPipe)                              │
│  - Swagger API 文档                                        │
└─────────────────────────┬──────────────────────────────────┘
                          │
┌─────────────────────────▼──────────────────────────────────┐
│                    数据层                                  │
│              JSON 文件数据库                                │
│  - 内存缓存 + 防抖持久化                                   │
│  - 崩溃安全写入 (临时文件+原子替换)                         │
│  - 并发控制 (临界区保护)                                    │
└────────────────────────────────────────────────────────────┘
```

---

## 🚀 快速开始

### 环境要求

- **Node.js**: >= 18.0.0
- **Yarn**: >= 4.0.0
- **Git**: 任意版本

### 安装步骤

1. **克隆仓库**

```bash
git clone <repository-url>
cd chees_images
```

2. **安装依赖**

```bash
# 启用 Yarn 4
yarn install
```

3. **配置环境变量**

```bash
# 复制环境变量模板
cp server/.env.example server/.env

# 编辑 server/.env 文件，设置以下必需变量:
# - JWT_SECRET: JWT 密钥 (建议 32 位随机字符串)
# - ADMIN_USERNAME: 管理员用户名
# - ADMIN_PASSWORD: 管理员密码
# - IMAGE_API_KEY: AI 图片服务 API 密钥 (可选)
# - IMAGE_API_URL: AI 图片服务地址 (可选)
```

4. **启动开发服务器**

```bash
# 启动后端服务
cd server
yarn dev

# 启动用户端 H5 (新终端)
cd web-client
yarn dev

# 启动管理后台 (新终端)
cd web-admin
yarn dev
```

5. **访问应用**

- 后端 API: http://localhost:3000/api
- API 文档: http://localhost:3000/api/docs
- 用户端 H5: http://localhost:5173
- 管理后台: http://localhost:5174

---

## 📚 项目结构

```
chees_images/
├── 📁 server/                 # 后端服务 (NestJS)
│   ├── src/
│   │   ├── auth/             # 认证模块
│   │   ├── user/             # 用户模块
│   │   ├── card-key/         # 卡密模块
│   │   ├── image/            # 图片生成模块
│   │   ├── model-config/     # 模型配置模块
│   │   ├── task-log/         # 任务日志模块
│   │   ├── db/               # 数据库服务
│   │   └── common/           # 通用组件
│   ├── test/                 # E2E 测试
│   └── database.json         # 数据库文件
│
├── 📁 web-client/            # 用户端 H5 (Vue 3)
│   ├── src/
│   │   ├── views/            # 页面视图
│   │   ├── components/       # 组件
│   │   ├── api/              # API 接口
│   │   ├── stores/           # Pinia 状态管理
│   │   └── router/           # 路由配置
│   └── package.json
│
├── 📁 web-admin/             # 管理后台 (Vue 3)
│   ├── src/
│   │   ├── views/            # 管理页面
│   │   ├── components/       # 管理组件
│   │   ├── api/              # API 接口
│   │   ├── stores/           # Pinia 状态管理
│   │   └── router/           # 路由配置
│   └── package.json
│
└── package.json              # 根配置 (Yarn Workspaces)
```

---

## 🧪 测试

### 运行测试

```bash
# 运行所有单元测试
yarn test

# 运行后端单元测试
cd server
yarn test

# 运行 E2E 测试
cd server
yarn test:e2e

# 运行 Playwright E2E 测试
yarn test:e2e
```

### 测试覆盖

- **单元测试**: 211 个测试用例
- **E2E 测试**: 80 个测试用例
- **总覆盖率**: 291 个测试用例，全部通过 ✅

---

## 🔐 安全配置

### 已实现的安全特性

- ✅ **密码安全**: bcrypt 哈希，成本因子 10
- ✅ **JWT 安全**: 最小 payload，7 天过期
- ✅ **API 安全**: 受保护端点需 Bearer Token
- ✅ **权限控制**: AdminGuard 保护管理员接口
- ✅ **并发安全**: 临界区保护卡密兑换
- ✅ **数据安全**: 崩溃安全的数据库写入
- ✅ **XSS 防护**: 输入验证和输出转义

### 环境变量说明

| 变量名           | 必需 | 说明                      |
| ---------------- | ---- | ------------------------- |
| `JWT_SECRET`     | ✅   | JWT 签名密钥              |
| `ADMIN_USERNAME` | ✅   | 管理员用户名              |
| `ADMIN_PASSWORD` | ✅   | 管理员密码                |
| `DATA_DIR`       | ❌   | 数据目录 (默认: ./data)   |
| `JWT_EXPIRES_IN` | ❌   | Token 过期时间 (默认: 7d) |
| `IMAGE_API_KEY`  | ❌   | AI 图片服务 API 密钥      |
| `IMAGE_API_URL`  | ❌   | AI 图片服务地址           |

---

## 📡 API 接口

### 认证接口

| 方法 | 路径               | 说明         |
| ---- | ------------------ | ------------ |
| POST | /api/auth/register | 用户注册     |
| POST | /api/auth/login    | 用户登录     |
| GET  | /api/auth/me       | 获取当前用户 |

### 用户接口

| 方法 | 路径                 | 说明     | 权限 |
| ---- | -------------------- | -------- | ---- |
| GET  | /api/users/me/points | 查询积分 | 用户 |

### 卡密接口

| 方法 | 路径                          | 说明     | 权限   |
| ---- | ----------------------------- | -------- | ------ |
| POST | /api/card-keys/redeem         | 兑换卡密 | 用户   |
| POST | /api/admin/card-keys/generate | 生成卡密 | 管理员 |
| GET  | /api/admin/card-keys          | 卡密列表 | 管理员 |

### 图片接口

| 方法 | 路径                 | 说明     | 权限 |
| ---- | -------------------- | -------- | ---- |
| POST | /api/images/generate | 生成图片 | 用户 |
| POST | /api/images/edit     | 编辑图片 | 用户 |
| GET  | /api/tasks           | 任务列表 | 用户 |

### 管理接口

| 方法           | 路径                                | 说明     |
| -------------- | ----------------------------------- | -------- |
| GET            | /api/admin/users                    | 用户列表 |
| POST           | /api/admin/users/:id/reset-password | 重置密码 |
| GET/POST/PATCH | /api/admin/models                   | 模型管理 |
| GET            | /api/admin/tasks                    | 所有任务 |

---

## 🛠️ 技术栈

### 后端

- **框架**: [NestJS](https://nestjs.com/) - 企业级 Node.js 框架
- **语言**: TypeScript 5.x
- **数据库**: JSON 文件 + 内存缓存
- **认证**: JWT + Passport
- **文档**: Swagger/OpenAPI
- **测试**: Jest + Supertest

### 前端

- **框架**: [Vue 3](https://vuejs.org/) - 渐进式 JavaScript 框架
- **构建**: [Vite](https://vitejs.dev/) - 下一代前端工具链
- **状态**: [Pinia](https://pinia.vuejs.org/) - Vue 官方状态管理
- **路由**: Vue Router 4
- **HTTP**: Axios
- **样式**: 原生 CSS + 移动优先响应式设计

### 工具链

- **包管理**: Yarn 4 (Workspaces)
- **代码规范**: ESLint 9 + Prettier
- **E2E 测试**: Playwright
- **版本控制**: Git

---

## 📦 部署

### Docker Compose 部署 (推荐)

一键部署所有服务（后端 + 用户端 + 管理后台）：

```bash
# 1. 克隆仓库
git clone <repository-url>
cd chees_images

# 2. 配置环境变量
cp .env.docker.example .env
# 编辑 .env 文件，设置必需的变量

# 3. 启动所有服务
docker-compose up -d

# 4. 查看服务状态
docker-compose ps

# 5. 查看日志
docker-compose logs -f
```

**服务访问地址：**

- 用户端 H5: http://localhost
- 管理后台: http://localhost:8080
- 后端 API: http://localhost:3000/api
- API 文档: http://localhost:3000/api/docs

**常用命令：**

```bash
# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 重新构建并启动
docker-compose up -d --build

# 查看特定服务日志
docker-compose logs -f server
```

### Docker 单容器部署

仅部署后端服务：

```bash
# 构建镜像
docker build -t chees-images ./server

# 运行容器
docker run -d \
  -p 3000:3000 \
  -e JWT_SECRET=your-secret \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=admin123 \
  -v ./data:/app/data \
  --name chees-images-server \
  chees-images
```

### 生产环境部署

```bash
# 构建生产版本
yarn build

# 启动生产服务
cd server
yarn start:prod
```

---

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

---

## 📄 许可证

[MIT](LICENSE) © Chees Images Team

---

## 💬 支持

如有问题或建议，欢迎提交 Issue 或联系开发团队。

---

<p align="center">
  Made with ❤️ by Chees Images Team
</p>