# CloudNest

CloudNest 是一个基于 Clean Architecture（整洁架构）的云存储后端服务，提供用户认证和文件管理功能。

## 技术栈

- **语言**: Go 1.25+
- **框架**: Gin 1.10
- **数据库**: MySQL 8.0 + GORM
- **缓存**: Redis 7
- **对象存储**: MinIO
- **认证**: JWT (github.com/golang-jwt/jwt/v5)
- **依赖注入**: Uber Dig
- **配置管理**: Viper（YAML + 环境变量）
- **日志**: Go 标准库 log/slog（JSON 格式）

## 架构设计

项目采用 **Clean Architecture（整洁架构）**，遵循依赖倒置原则（DIP），确保核心业务逻辑独立于框架、UI 和外部依赖。

```
┌─────────────────────────────────────────────────────────────┐
│                     Interface Layer                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Handler   │  │   Routes    │  │    Middleware       │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
└─────────┼────────────────┼─────────────────────┼─────────────┘
          │                │                     │
┌─────────▼────────────────▼─────────────────────▼─────────────┐
│                     Application Layer                       │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              AuthService       │        FileService     │ │
│  │  - Register()                 │  - Upload()            │ │
│  │  - Login()                    │  - List()              │ │
│  │                               │  - PresignDownload()   │ │
│  │                               │  - Delete()            │ │
│  └──────────────┬────────────────┴───────────────┬─────────┘ │
└─────────────────┼────────────────────────────────┼─────────────┘
                  │                                │
┌─────────────────▼────────────────────────────────▼─────────────┐
│                      Domain Layer                            │
│  ┌──────────────────┐         ┌──────────────────┐          │
│  │     Entity       │         │    Repository    │          │
│  │  - User          │         │  - Interface     │          │
│  │  - FileMeta      │         │  - (DIP)         │          │
│  └──────────────────┘         └──────────────────┘          │
└─────────────────────────────────────────────────────────────┘
                  │                                │
┌─────────────────▼────────────────────────────────▼─────────────┐
│                  Infrastructure Layer                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │  MySQL   │  │  Redis   │  │  MinIO   │  │ Repository   │  │
│  └──────────┘  └──────────┘  └──────────┘  │ Implementation│  │
│                                             └──────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## 目录结构

```
cloudnest/
├── cmd/                          # 启动入口 / Entry points
│   ├── auth-service/             # 认证服务
│   │   ├── main.go               # 服务入口（含端口检测、优雅关闭）
│   │   └── embed.go              # 静态文件嵌入
│   └── file-service/             # 文件服务
│       └── main.go               # 服务入口（含端口检测、优雅关闭）
├── configs/                      # 配置文件 / Configuration files
│   ├── config.yaml               # 基础默认配置
│   ├── config.dev.yaml           # 开发环境配置
│   ├── config.prod.yaml          # 生产环境配置
│   └── config.test.yaml          # 测试环境配置
├── deployments/                  # 部署配置 / Deployment configs
│   ├── docker/                   # Dockerfile
│   └── k8s/                      # Kubernetes 配置
├── internal/
│   ├── application/              # 应用层 / Application Layer
│   │   ├── auth/                 # 认证应用服务
│   │   │   ├── dto.go            # 请求/响应 DTO
│   │   │   └── service.go        # 业务逻辑
│   │   └── file/                 # 文件应用服务
│   │       ├── dto.go
│   │       └── service.go
│   ├── config/                   # 配置管理 / Configuration
│   │   └── config.go             # YAML + 环境变量加载
│   ├── di/                       # 依赖注入 / Dependency Injection
│   │   └── container.go          # Uber Dig 容器配置
│   ├── domain/                   # 领域层 / Domain Layer
│   │   ├── auth/                 # 认证领域
│   │   │   ├── entity/           # 实体定义
│   │   │   └── repository/       # 仓储接口（DIP）
│   │   └── file/                 # 文件领域
│   │       ├── entity/
│   │       └── repository/
│   ├── infrastructure/           # 基础设施层 / Infrastructure
│   │   ├── database/             # 数据库连接（MySQL、Redis）
│   │   ├── repository/           # 仓储实现（GORM、MinIO）
│   │   └── storage/              # 对象存储（MinIO 客户端）
│   ├── interface/                # 接口层 / Interface Layer
│   │   └── http/
│   │       ├── handler/          # HTTP Handler
│   │       └── routes/           # 路由定义
│   ├── middleware/               # 中间件 / Middleware
│   │   ├── cors.go               # 跨域处理
│   │   ├── error_handler.go      # 错误恢复与处理
│   │   └── jwt.go                # JWT 认证
│   └── pkg/                      # 工具包 / Utilities
│       ├── crypto/               # 密码加密（bcrypt）
│       ├── errors/               # 应用错误类型
│       ├── jwt/                  # JWT 生成与解析
│       ├── logger/               # 结构化日志（log/slog）
│       ├── response/             # 统一响应格式
│       └── validator/            # 参数校验
├── docker-compose.infra.yml      # 基础设施 Docker Compose
├── start-local.ps1               # Windows PowerShell 启动脚本
├── start-local.bat               # Windows CMD 启动脚本
├── deploy-all.sh                 # Kubernetes 一键部署脚本
├── go.mod
└── go.sum
```

## 环境要求

- **Go**: 1.25+
- **MySQL**: 8.0+
- **Redis**: 7.0+
- **MinIO**: Latest
- **Docker**: 20.10+（用于本地基础设施）

## 配置管理

项目使用 **分层配置加载** 机制，支持 YAML 文件 + 环境变量覆盖：

### 加载顺序（后面的覆盖前面的）

1. `configs/config.yaml` —— 基础默认值
2. `configs/config.{env}.yaml` —— 环境特定配置
3. **环境变量** —— 最高优先级

### 环境切换

通过 `CLOUDNEST_ENV` 环境变量选择配置环境：

```bash
# 开发环境（默认）
export CLOUDNEST_ENV=dev

# 测试环境
export CLOUDNEST_ENV=test

# 生产环境
export CLOUDNEST_ENV=prod
```

### 配置文件说明

| 文件 | 用途 | 注意 |
|------|------|------|
| `config.yaml` | 所有环境的默认配置 | 不要在此存放敏感信息 |
| `config.dev.yaml` | 本地开发环境 | 使用 localhost 连接 |
| `config.test.yaml` | 自动化测试环境 | 使用独立的测试数据库 |
| `config.prod.yaml` | 生产环境 | 敏感信息通过环境变量注入 |

### 环境变量映射

以下环境变量会自动映射到配置项（优先级最高）：

```bash
# 应用 / Application
APP_NAME=cloudnest
APP_LOG_LEVEL=debug

# 服务器 / Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# 数据库 / Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=yourpassword
DB_NAME=cloudnest

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=cloudnest-files

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=720
```

## 快速开始

### 1. 安装依赖

```bash
go mod tidy
```

### 2. 启动基础设施

使用 Docker Compose 启动 MySQL、Redis 和 MinIO：

```bash
docker compose -f docker-compose.infra.yml up -d
```

### 3. 启动服务（Windows）

**PowerShell 方式（推荐）：**

```powershell
# 使用 dev 配置启动（默认）
.\start-local.ps1

# 使用 test 配置启动
$env:CLOUDNEST_ENV="test"; .\start-local.ps1
```

**CMD 方式：**

```cmd
start-local.bat
```

### 4. 手动启动服务（跨平台）

```bash
# 设置环境并启动认证服务
export CLOUDNEST_ENV=dev
go run ./cmd/auth-service

# 另开终端启动文件服务
export CLOUDNEST_ENV=dev
go run ./cmd/file-service
```

### 5. 访问服务

| 服务 | 地址 | 说明 |
|------|------|------|
| **Auth Service** | `http://localhost:8081` | 认证服务，处理注册/登录 |
| **File Service** | `http://localhost:8082` | 文件服务，处理上传/下载 |
| **MinIO Console** | `http://localhost:9001` | 对象存储管理界面 (minioadmin / minioadmin) |
| **健康检查** | `GET /healthz` | 服务健康状态 |

> **注意**: 开发模式下如果端口被占用，服务会自动检测并切换到下一个可用端口。生产环境使用配置文件中指定的固定端口。

## API 文档

### 认证接口

#### 注册

```bash
POST /api/v1/auth/register
Content-Type: application/json

{
  "username": "string (3-50 chars)",
  "password": "string (min 6 chars)"
}
```

**响应：**

```json
{
  "code": 0,
  "message": "注册成功"
}
```

#### 登录

```bash
POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "string",
  "password": "string"
}
```

**响应：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "token": "jwt-token"
  }
}
```

### 文件接口

所有文件接口需要在 Header 中携带 JWT Token：

```bash
Authorization: Bearer <jwt-token>
```

#### 上传文件

```bash
POST /api/v1/files/upload
Content-Type: multipart/form-data

file: <file>
```

**响应：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "上传成功",
    "file": "username/filename",
    "size": 1024
  }
}
```

#### 列出文件

```bash
GET /api/v1/files
```

**响应：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "files": ["username/file1.txt", "username/file2.jpg"]
  }
}
```

#### 获取下载链接

```bash
GET /api/v1/files/download/:name
```

**响应：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "download_url": "https://minio.example.com/..."
  }
}
```

#### 删除文件

```bash
DELETE /api/v1/files/:name
```

**响应：**

```json
{
  "code": 0,
  "message": "删除成功"
}
```

## 项目特性

- **分层架构**: 清晰的 Clean Architecture 层次划分，高内聚低耦合
- **依赖注入**: 使用 Uber Dig 实现依赖管理，便于测试和替换实现
- **配置管理**: YAML 文件 + 环境变量分层覆盖，支持多环境切换
- **端口自动检测**: 开发模式下自动检测并切换被占用的端口
- **优雅关闭**: 支持 SIGINT/SIGTERM 信号处理，确保请求完成后再关闭
- **错误处理**: 统一的错误响应格式，支持错误码和 HTTP 状态码
- **日志记录**: JSON 格式结构化日志，支持 Debug/Info/Warn/Error/Fatal 级别
- **参数校验**: 使用 go-playground/validator 进行请求参数校验
- **CORS 支持**: 跨域请求处理中间件
- **JWT 认证**: 基于 Token 的无状态认证机制

## 开发规范

- **包命名**: 小写，使用单数形式（如 `entity`、`repository`）
- **文件命名**: 使用 snake_case（如 `auth_handler.go`）
- **接口命名**: 以 `Repository` 结尾（如 `UserRepository`）
- **服务命名**: 以 `Service` 结尾（如 `AuthService`）
- **Handler 命名**: 以 `Handler` 结尾（如 `AuthHandler`）
- **注释规范**: 中英文双语注释，包含功能说明、参数、返回值和注意事项

## 部署

### Docker

```bash
docker build -t cloudnest/auth-service -f deployments/docker/auth-service.Dockerfile .
docker build -t cloudnest/file-service -f deployments/docker/file-service.Dockerfile .
```

### Kubernetes

```bash
# 一键部署
CLOUDNEST_ENV=prod ./deploy-all.sh

# 或手动部署
kubectl apply -f deployments/k8s/
```

## License

MIT