433 lines
14 KiB
Markdown
433 lines
14 KiB
Markdown
# 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
|