sunct/cloudnest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

首次提交：初始化项目代码

Browse Source
This commit is contained in:
sunct
2026-07-31 15:24:14 +08:00
commit 8d3c97bd01
73 changed files with 11720 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+432
View File
@@ -0,0 +1,432 @@
# 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