14 KiB
14 KiB
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 文件 + 环境变量覆盖：
加载顺序（后面的覆盖前面的）
configs/config.yaml—— 基础默认值configs/config.{env}.yaml—— 环境特定配置- 环境变量 —— 最高优先级
环境切换
通过 CLOUDNEST_ENV 环境变量选择配置环境：
# 开发环境（默认）
export CLOUDNEST_ENV=dev
# 测试环境
export CLOUDNEST_ENV=test
# 生产环境
export CLOUDNEST_ENV=prod
配置文件说明
| 文件 | 用途 | 注意 |
|---|---|---|
config.yaml |
所有环境的默认配置 | 不要在此存放敏感信息 |
config.dev.yaml |
本地开发环境 | 使用 localhost 连接 |
config.test.yaml |
自动化测试环境 | 使用独立的测试数据库 |
config.prod.yaml |
生产环境 | 敏感信息通过环境变量注入 |
环境变量映射
以下环境变量会自动映射到配置项（优先级最高）：
# 应用 / 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. 安装依赖
go mod tidy
2. 启动基础设施
使用 Docker Compose 启动 MySQL、Redis 和 MinIO：
docker compose -f docker-compose.infra.yml up -d
3. 启动服务（Windows）
PowerShell 方式（推荐）：
# 使用 dev 配置启动（默认）
.\start-local.ps1
# 使用 test 配置启动
$env:CLOUDNEST_ENV="test"; .\start-local.ps1
CMD 方式：
start-local.bat
4. 手动启动服务（跨平台）
# 设置环境并启动认证服务
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 文档
认证接口
注册
POST /api/v1/auth/register
Content-Type: application/json
{
"username": "string (3-50 chars)",
"password": "string (min 6 chars)"
}
响应：
{
"code": 0,
"message": "注册成功"
}
登录
POST /api/v1/auth/login
Content-Type: application/json
{
"username": "string",
"password": "string"
}
响应：
{
"code": 0,
"message": "success",
"data": {
"token": "jwt-token"
}
}
文件接口
所有文件接口需要在 Header 中携带 JWT Token：
Authorization: Bearer <jwt-token>
上传文件
POST /api/v1/files/upload
Content-Type: multipart/form-data
file: <file>
响应：
{
"code": 0,
"message": "success",
"data": {
"message": "上传成功",
"file": "username/filename",
"size": 1024
}
}
列出文件
GET /api/v1/files
响应：
{
"code": 0,
"message": "success",
"data": {
"files": ["username/file1.txt", "username/file2.jpg"]
}
}
获取下载链接
GET /api/v1/files/download/:name
响应：
{
"code": 0,
"message": "success",
"data": {
"download_url": "https://minio.example.com/..."
}
}
删除文件
DELETE /api/v1/files/:name
响应：
{
"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
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
# 一键部署
CLOUDNEST_ENV=prod ./deploy-all.sh
# 或手动部署
kubectl apply -f deployments/k8s/
License
MIT