# 赛博世界服务端

**Repository Path**: beizhan/cyber-server

## Basic Information

- **Project Name**: 赛博世界服务端
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2025-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cyber Server

一个基于 Golang 和 Gin 框架的 Web 服务器项目。

## 功能特性

- RESTful API 支持
- 健康检查端点
- 用户中心模块（注册、登录）
- 邮箱验证码验证
- JWT 认证
- 密码加密存储
- MySQL 数据库存储（使用 GORM）
- 自动数据库迁移
- 模块化项目结构

## 项目结构

```
.
├── main.go              # 应用入口
├── go.mod               # Go 模块定义
├── handlers/            # 请求处理器
│   ├── handlers.go      # 通用处理器
│   └── auth_handler.go  # 认证相关处理器
├── routes/              # 路由配置
│   └── routes.go
├── models/              # 数据模型
│   ├── user.go          # 用户模型
│   └── verification_code.go  # 验证码模型
├── services/            # 业务逻辑层
│   ├── user_service.go  # 用户服务
│   ├── code_service.go  # 验证码服务
│   └── email_service.go # 邮件服务
├── config/              # 配置
│   └── database.go      # 数据库配置和连接
└── middleware/          # 中间件
    └── auth_middleware.go  # JWT 认证中间件
```

## 快速开始

### 前置要求

- Go 1.21 或更高版本
- MySQL 5.7 或更高版本
- Redis 6.0 或更高版本（用于存储验证码）

### 安装依赖

```bash
go mod download
```

### 数据库配置

1. 创建 MySQL 数据库：
```sql
CREATE DATABASE cyber_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

2. 配置数据库连接（推荐使用 `.env` 文件）：

**方式一：使用 .env 文件（推荐，不会污染系统环境变量）**

复制 `.env.example` 为 `.env` 并修改配置：
```bash
cp .env.example .env
```

编辑 `.env` 文件：
```bash
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=cyber_db

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
```

**方式二：使用系统环境变量**

```bash
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=root
export DB_PASSWORD=your_password
export DB_NAME=cyber_db
```

**优先级说明**：
- 如果存在 `.env` 文件，会优先从 `.env` 文件加载
- 如果 `.env` 文件不存在，会使用系统环境变量
- 如果都不存在，会使用默认值

### 运行项目

```bash
go run main.go
```

服务器将在 `http://localhost:8080` 启动。

**注意**：首次运行时会自动创建数据库表结构（users 表）。验证码存储在 Redis 中，无需数据库表。

### 构建项目

```bash
go build -o server main.go
```

## API 端点

### 健康检查
- `GET /health` - 检查服务器状态

### API v1
- `GET /api/v1/ping` - Ping 测试
- `GET /api/v1/users` - 获取用户列表
- `POST /api/v1/users` - 创建新用户

### 用户中心 API

#### 发送验证码
```bash
POST /api/v1/auth/send-code
Content-Type: application/json

{
  "email": "user@example.com"
}
```

#### 用户注册
```bash
POST /api/v1/auth/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "user@example.com",
  "password": "password123",
  "code": "123456"
}
```

响应示例：
```json
{
  "message": "注册成功",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### 用户登录
```bash
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}
```

响应示例：
```json
{
  "message": "登录成功",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 使用认证 Token

在需要认证的请求中，需要在 Header 中添加：
```
Authorization: Bearer <your-token>
```

### 示例请求

#### 1. 发送验证码
```bash
curl -X POST http://localhost:8080/api/v1/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
```

**注意**：开发环境下，验证码会在服务器控制台输出。

#### 2. 用户注册
```bash
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "user@example.com",
    "password": "password123",
    "code": "123456"
  }'
```

#### 3. 用户登录
```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'
```

## 开发

### 技术栈

- **框架**: Gin Web Framework
- **数据库**: MySQL (使用 GORM ORM)
- **认证**: JWT (JSON Web Token)
- **密码加密**: bcrypt
- **验证码**: 6位数字验证码，有效期5分钟

### 安全说明

1. **密码存储**: 使用 bcrypt 进行密码哈希加密
2. **JWT Secret**: 当前使用硬编码密钥，生产环境应使用环境变量
3. **验证码**: 验证码有效期为5分钟，验证后自动删除
4. **邮件服务**: 当前为开发模式，验证码输出到控制台。生产环境需要配置真实的 SMTP 服务

### 配置邮件服务

编辑 `services/email_service.go`，取消注释 SMTP 相关代码并配置：
- SMTP 服务器地址
- 发件人邮箱和密码
- 端口号（通常为 587 或 465）

### 添加新的路由

1. 在 `handlers/` 目录下添加新的处理函数
2. 在 `routes/routes.go` 中注册新路由
3. 如需认证，使用 `middleware.AuthMiddleware()` 中间件

### 添加新的模型

在 `models/` 目录下创建新的模型文件。

### 数据库

项目使用 **MySQL** 数据库和 **GORM** ORM 框架。

#### 数据库表结构

**users 表**：
- `id`: 主键，自增
- `name`: 用户名，varchar(100)，非空
- `email`: 邮箱，varchar(255)，唯一索引，非空
- `password`: 密码（加密），varchar(255)，非空
- `created_at`: 创建时间
- `updated_at`: 更新时间

**注意**：验证码存储在 Redis 中，不在 MySQL 数据库中。

#### 自动迁移

项目启动时会自动执行数据库迁移，创建或更新表结构。无需手动执行 SQL 脚本。

#### 数据库连接池配置

- 最大空闲连接数：10
- 最大打开连接数：100
- 连接最大生存时间：1小时

### Redis

项目使用 **Redis** 存储验证码等临时数据。

#### Redis 存储说明

- **验证码存储**：验证码存储在 Redis 中，key 格式为 `code:verification:{email}`
- **自动过期**：验证码自动设置 5 分钟过期时间，无需手动清理
- **高性能**：Redis 提供快速读写，适合存储临时数据
- **Key 管理**：所有 Redis key 统一在 `config/redis_keys.go` 中管理，方便扩展和维护

#### Redis 配置

在 `.env` 文件中配置 Redis 连接：

```bash
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=        # 如果 Redis 设置了密码，填写密码
REDIS_DB=0            # Redis 数据库编号，默认 0
```

#### Redis 优势

- **自动过期**：利用 Redis 的 TTL 功能，验证码自动过期，无需手动管理
- **高性能**：内存存储，读写速度快
- **简化代码**：不需要手动检查过期时间，Redis 自动处理

### 环境变量

#### 使用 .env 文件（推荐）

项目支持使用 `.env` 文件来管理环境变量，这样不会污染系统环境变量。

1. **复制模板文件**：
```bash
cp .env.example .env
```

2. **编辑 `.env` 文件**，填入你的配置：
```bash
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=cyber_db
```

3. **启动项目**，`.env` 文件会自动加载：
```bash
go run main.go
```

**注意**：`.env` 文件已添加到 `.gitignore`，不会被提交到 Git。

#### 环境变量列表

可以通过环境变量配置数据库连接：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `DB_HOST` | 数据库主机 | `localhost` |
| `DB_PORT` | 数据库端口 | `3306` |
| `DB_USER` | 数据库用户名 | `root` |
| `DB_PASSWORD` | 数据库密码 | 空 |
| `DB_NAME` | 数据库名称 | `cyber_db` |
| `REDIS_HOST` | Redis 主机 | `localhost` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `REDIS_PASSWORD` | Redis 密码 | 空 |
| `REDIS_DB` | Redis 数据库编号 | `0` |
| `GIN_MODE` | Gin 运行模式 | 根据 `APP_ENV` 自动判断 |
| `APP_ENV` | 应用环境 | `development`（开发环境） |

#### Gin 模式说明

Gin 框架支持三种运行模式：

- **debug**：开发模式
  - 输出详细的请求日志
  - 显示完整的错误堆栈信息
  - 适合开发和调试
  
- **release**：生产模式
  - 性能优化，不输出详细日志
  - 错误信息简化
  - 适合生产环境
  
- **test**：测试模式
  - 用于单元测试

**模式选择逻辑**：
1. 如果设置了 `GIN_MODE` 环境变量，直接使用该值
2. 如果没有设置 `GIN_MODE`，根据 `APP_ENV` 判断：
   - `APP_ENV=production` 或 `APP_ENV=prod` → 使用 `release` 模式
   - 其他情况 → 使用 `debug` 模式（开发环境默认）

**推荐配置**：
- 开发环境：`.env` 文件中设置 `GIN_MODE=debug` 或 `APP_ENV=development`
- 生产环境：设置 `GIN_MODE=release` 或 `APP_ENV=production`

#### 环境变量优先级

1. `.env` 文件（如果存在）
2. 系统环境变量
3. 默认值

#### 命令行方式设置环境变量

如果不想使用 `.env` 文件，也可以在启动时通过命令行设置：

```bash
# Linux/macOS
DB_HOST=localhost DB_PORT=3306 DB_USER=root DB_PASSWORD=password DB_NAME=cyber_db go run main.go

# 或者先导出
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=root
export DB_PASSWORD=password
export DB_NAME=cyber_db
go run main.go
```

## 许可证

MIT