# Cloud Service

一个高性能、可扩展的个人云服务，基于 gRPC 和 HTTP Gateway 架构，提供文件管理、相册管理、笔记系统、书签收藏、私人数据和文件分享等完整的云存储解决方案。

## 🚀 特性

- **📁 文件管理**: 完整的文件夹目录结构，支持文件上传、下载、移动、复制、搜索
- **📸 相册管理**: 专业的照片管理，支持相册创建、照片上传、分类整理、封面设置
- **📝 笔记系统**: 强大的知识管理，支持 Markdown、附件上传、分类标签、置顶功能
- **🔗 书签收藏**: 便捷的网址收藏管理，支持多浏览器导入、分类整理
- **🔒 私人数据**: 加密存储的私人信息管理，支持数据类型的灵活分类
- **📤 文件分享**: 安全的文件分享系统，支持密码保护、访问统计、过期控制
- **💾 空间管理**: 统一的云空间管理，支持多用户空间隔离
- **⚡ 高性能**: Redis缓存 + PostgreSQL 数据库优化
- **🐳 容器化**: 完整的Docker支持
- **📊 监控**: 健康检查和APM集成
- **🔐 安全**: 完善的错误处理和输入验证

## 📋 目录

- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [核心功能](#-核心功能)
- [API文档](#-api文档)
- [开发指南](#-开发指南)
- [部署说明](#-部署说明)
- [性能优化](#-性能优化)
- [故障排除](#-故障排除)

## 🚀 快速开始

### 环境要求

- **Go**: 1.24.6+
- **PostgreSQL**: 12+
- **Redis**: 6+
- **Docker**: 20.10+ (可选)
- **Protocol Buffers**: 3.15+ (开发需要)

### 快速安装

```bash
# 克隆项目
git clone bsm/full/module/base/cloud.git
cd cloud

# 安装依赖
make deps

# 生成代码
make proto

# 构建应用
make build

# 运行服务
make run
```

### Docker 快速启动

```bash
# 启动完整服务栈
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f cloud-service
```

## 📁 项目结构

```
cloud/
├── 📁 cmd/                     # 应用程序入口
│   ├── 📁 main/               # 主服务入口
│   └── 📁 cli/                # 命令行工具
├── 📁 internal/               # 内部包
│   ├── 📁 config/             # 配置管理
│   ├── 📁 impl/               # 实现层
│   ├── 📁 logic/              # 业务逻辑
│   │   ├── 📁 album/          # 相册相关逻辑
│   │   ├── 📁 bookmark/       # 书签相关逻辑
│   │   ├── 📁 disk/           # 文件系统逻辑
│   │   ├── 📁 note/           # 笔记相关逻辑
│   │   ├── 📁 private/        # 私人数据逻辑
│   │   ├── 📁 share/          # 分享相关逻辑
│   │   └── 📁 space/          # 空间管理逻辑
│   ├── 📁 models/             # 数据模型
│   └── 📁 server/             # 服务器实现
├── 📁 pb/                     # Protocol.Buffers 生成代码
├── 📁 proto/                  # Protocol.Buffers 定义文件
├── 📁 swagger/                # API 文档
├── 📁 scripts/                # 脚本和SQL文件
├── 📁 test/                   # 测试文件
├── 📁 etc/                    # 配置文件
├── 🐳 Dockerfile              # Docker 镜像构建
├── 🐳 docker-compose.yml      # Docker 编排
├── 🔧 Makefile               # 构建脚本
└── 📖 README.md              # 项目文档
```

## 🔧 核心功能

### 1. 文件管理服务 (Disk Service)

#### 📁 目录管理
```protobuf
rpc CreateDir(CreateDirRequest) returns (StatusReply)
rpc GetDir(IdentRequest) returns (CloudDiskDirItem)
rpc UpdateDir(CloudDiskDirItem) returns (StatusReply)
rpc DeleteDir(IdentRequest) returns (StatusReply)
rpc ListDirs(FetchRequest) returns (ListDirsResponse)
rpc GetDirTree(IdentRequest) returns (CloudDiskDirItem)
rpc MoveDir(MoveDirRequest) returns (StatusReply)
```
- **功能**: 完整的文件系统目录管理
- **特性**: 
  - 支持嵌套目录结构
  - 完整的CRUD操作
  - 目录树形结构展示
  - 路径管理

#### 📄 文件管理
```protobuf
rpc UploadFile(CloudDiskFileRequest) returns (StatusReply)
rpc GetFile(IdentRequest) returns (CloudDiskFileItem)
rpc UpdateFile(CloudDiskFileItem) returns (StatusReply)
rpc DeleteFile(IdentRequest) returns (StatusReply)
rpc ListFiles(FetchRequest) returns (ListFilesResponse)
rpc MoveFile(MoveFileRequest) returns (StatusReply)
rpc CopyFile(CopyFileRequest) returns (StatusReply)
rpc SearchFiles(FetchRequest) returns (ListFilesResponse)
```
- **功能**: 文件上传、管理和操作
- **特性**:
  - 支持多种文件类型
  - 文件哈希去重
  - 文件移动和复制
  - 全文搜索功能
  - MIME类型自动识别

### 2. 相册管理服务 (Album Service)

#### 📸 相册管理
```protobuf
rpc CreateAlbum(CreateAlbumRequest) returns (StatusReply)
rpc GetAlbum(IdentRequest) returns (CloudAlbumItem)
rpc UpdateAlbum(CloudAlbumItem) returns (StatusReply)
rpc DeleteAlbum(IdentRequest) returns (StatusReply)
rpc ListAlbums(FetchRequest) returns (ListAlbumsResponse)
rpc SetCoverPhoto(SetCoverPhotoRequest) returns (StatusReply)
```
- **功能**: 相册创建、管理和分类
- **特性**: 私有/公开相册、封面设置

#### 🖼️ 照片管理
```protobuf
rpc UploadPhoto(CloudPhotoItem) returns (StatusReply)
rpc GetPhoto(IdentRequest) returns (CloudPhotoItem)
rpc UpdatePhoto(CloudPhotoItem) returns (StatusReply)
rpc DeletePhoto(IdentRequest) returns (StatusReply)
rpc ListPhotos(FetchRequest) returns (ListPhotosResponse)
rpc MovePhoto(MovePhotoRequest) returns (StatusReply)
```
- **功能**: 照片上传、管理和元数据处理
- **特性**:
  - EXIF 信息提取
  - 照片尺寸、拍摄时间
  - 地理位置信息
  - 标签管理

### 3. 笔记服务 (Note Service)

#### 📝 笔记管理
```protobuf
rpc CreateNote(CreateNoteRequest) returns (StatusReply)
rpc GetNote(IdentRequest) returns (CloudNoteItem)
rpc UpdateNote(CloudNoteItem) returns (StatusReply)
rpc DeleteNote(IdentRequest) returns (StatusReply)
rpc ListNotes(FetchRequest) returns (ListNotesResponse)
rpc TogglePin(TogglePinRequest) returns (StatusReply)
rpc IncrementViews(IdentRequest) returns (StatusReply)
rpc SearchNotes(FetchRequest) returns (ListNotesResponse)
```
- **功能**: 知识管理和笔记系统
- **特性**:
  - Markdown 支持
  - 分类和标签管理
  - 置顶功能
  - 浏览次数统计
  - 全文搜索

#### 📎 附件管理
```protobuf
rpc InsertAttachment(NoteAttachmentItem) returns (StatusReply)
rpc DeleteAttachment(IdentRequest) returns (StatusReply)
```
- **功能**: 笔记附件管理
- **特性**: 多种文件类型附件支持

### 4. 书签服务 (Bookmark Service)

#### 🔗 书签管理
```protobuf
rpc CreateBookmark(CreateBookmarkRequest) returns (StatusReply)
rpc GetBookmark(IDRequest) returns (CloudBookmarkItem)
rpc UpdateBookmark(CloudBookmarkItem) returns (StatusReply)
rpc DeleteBookmark(IDRequest) returns (StatusReply)
rpc ListBookmarks(FetchRequest) returns (ListBookmarksResponse)
rpc ImportBookmarks(ImportBookmarksRequest) returns (StatusReply)
```
- **功能**: 网址收藏管理
- **特性**:
  - 多浏览器导入支持
  - 分类和标签管理
  - 网站图标缓存
  - 私有/公开收藏

### 5. 私人数据服务 (Private Service)

#### 🔒 数据管理
```protobuf
rpc CreatePrivateData(CreatePrivateDataRequest) returns (StatusReply)
rpc GetPrivateData(IdentRequest) returns (CloudPrivateItem)
rpc UpdatePrivateData(CloudPrivateItem) returns (StatusReply)
rpc DeletePrivateData(IdentRequest) returns (StatusReply)
rpc ListPrivateData(FetchRequest) returns (ListPrivateResponse)
rpc GetPrivateDataByType(GetPrivateDataByTypeRequest) returns (ListPrivateResponse)
rpc SearchPrivateData(FetchRequest) returns (ListPrivateResponse)
```
- **功能**: 加密私人数据存储
- **特性**: 
  - 数据加密存储
  - 类型化数据管理
  - 搜索和统计
  - 解密数据查询

#### 🔐 加密解密
```protobuf
rpc EncryptData(EncryptDataRequest) returns (EncryptDataReply)
rpc DecryptData(DecryptDataRequest) returns (DecryptDataReply)
```
- **功能**: 数据加密和解密操作
- **特性**: 安全的加密算法

### 6. 分享服务 (Share Service)

#### 📤 分享管理
```protobuf
rpc CreateShare(CreateShareRequest) returns (StatusReply)
rpc GetShare(IdentRequest) returns (CloudShareItem)
rpc DeleteShare(IdentRequest) returns (StatusReply)
rpc ListShares(FetchRequest) returns (ListSharesResponse)
rpc ValidateSharePassword(ValidateSharePasswordRequest) returns (StatusReply)
```
- **功能**: 文件分享和管理
- **特性**:
  - 多种资源类型分享
  - 密码保护
  - 过期时间控制
  - 访问统计
  - 公开/私有分享

### 7. 空间管理服务 (Space Service)

#### 💾 空间管理
```protobuf
rpc GetSpace(IdentRequest) returns (CloudSpaceItem)
rpc GetSpaceByKeyIdentifier(GetSpaceByKeyIdentifierRequest) returns (CloudSpaceItem)
```
- **功能**: 用户云空间管理
- **特性**: 多用户空间隔离和管理

## 📚 API文档

### gRPC 服务

| 服务 | 方法 | 描述 | 端口 |
|------|------|------|------|
| Disk | CreateDir | 创建目录 | 12206 |
| Disk | UploadFile | 上传文件 | 12206 |
| Disk | ListFiles | 文件列表 | 12206 |
| Album | CreateAlbum | 创建相册 | 12206 |
| Album | UploadPhoto | 上传照片 | 12206 |
| Note | CreateNote | 创建笔记 | 12206 |
| Note | SearchNotes | 搜索笔记 | 12206 |
| Bookmark | CreateBookmark | 创建书签 | 12206 |
| Bookmark | ImportBookmarks | 导入书签 | 12206 |
| Private | CreatePrivateData | 创建私人数据 | 12206 |
| Share | CreateShare | 创建分享 | 12206 |
| Space | GetSpace | 获取空间 | 12206 |

### HTTP Gateway

| 端点 | 方法 | 描述 |
|------|------|------|
| `/cloud.Disk/CreateDir` | POST | 创建目录 |
| `/cloud.Disk/UploadFile` | POST | 上传文件 |
| `/cloud.Album/CreateAlbum` | POST | 创建相册 |
| `/cloud.Album/UploadPhoto` | POST | 上传照片 |
| `/cloud.Note/CreateNote` | POST | 创建笔记 |
| `/cloud.Bookmark/CreateBookmark` | POST | 创建书签 |
| `/cloud.Share/CreateShare` | POST | 创建分享 |

### Swagger 文档

- **本地**: http://localhost:12102/cloud.swagger.json
- **在线**: 通过 HTTP Gateway 访问完整的 API 文档

##  🛠️ 开发指南

### 开发环境设置

```bash
# 安装开发工具
make install-tools

# 设置Git钩子
git config core.hooksPath .githooks

# 启动开发模式
make dev
```

### 代码生成

```bash
# 生成 protobuf 代码
make proto

# 生成 Swagger 文档
make swagger
```

### 测试

```bash
# 运行所有测试
make test

# 测试覆盖率
make test-coverage

# gRPC 功能测试
make test-grpc

# 代码检查
make lint

# 安全扫描
make security
```

### 数据库管理

```bash
# 初始化数据库
make init-db

# 备份数据库
make backup-db
```

## 🚀 部署说明

### Docker 部署

```bash
# 构建镜像
make docker-build

# 启动服务栈
make docker-compose-up

# 查看日志
make docker-compose-logs

# 停止服务
make docker-compose-down
```

### 生产环境部署

1. **环境准备**
   ```bash
   # 创建生产配置
   cp etc/cloud_dev.yaml etc/cloud_prod.yaml
   # 编辑生产配置...
   ```

2. **数据库初始化**
   ```bash
   # 创建数据库表结构
   # 根据 models 自动迁移
   ```

3. **服务启动**
   ```bash
   # 构建生产版本
   make build-linux
   
   # 启动服务
   ./build/cloud-linux-amd64
   ```

### Kubernetes 部署

```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cloud-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: cloud-service
  template:
    metadata:
      labels:
        app: cloud-service
    spec:
      containers:
      - name: cloud-service
        image: cloud:latest
        ports:
        - containerPort: 12206
        - containerPort: 12102
        env:
        - name: SERVICE_ENV
          value: "production"
```

## ⚡ 性能优化

### 缓存策略

| 数据类型 | 缓存时间 | 策略 |
|----------|----------|------|
| 文件元数据 | 30分钟 | 按目录缓存 |
| 相册信息 | 1小时 | 按用户缓存 |
| 笔记内容 | 10分钟 | 按关键词缓存 |
| 书签数据 | 6小时 | 全量缓存 |
| 分享信息 | 15分钟 | 按ID缓存 |

### 数据库优化

- **索引优化**: 关键字段建立复合索引
- **查询优化**: 文件路径、用户ID等关键查询优化
- **分页策略**: 大数据量查询使用游标分页
- **连接池**: 配置合适的连接池大小

### 监控指标

```bash
# 服务健康检查
curl http://localhost:12102/health

# 性能指标
curl http://localhost:12102/metrics
```

## 🔧 配置说明

### 环境配置文件

```yaml
# etc/cloud_prod.yaml
Service: cloud
Port: 12206

# 数据库配置
Databases:
  Driver: postgres
  Source:
    - host=db-host user=postgres password=*** dbname=cloud_db port=5432 sslmode=require

# 缓存配置
Cache: redis://username:password@redis-host:6379/0

# 网关配置
Gateway:
  Enable: true
  Port: 12102
  
# 微服务配置
MicroService:
  Enable: true
  Registry: etcd://etcd-cluster:2379

# APM监控
APM:
  Platform: elasticAPM
  Endpoint: http://apm-server:8200
```

### 环境变量

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `SERVICE_ENV` | 运行环境 | `development` |
| `CONFIG_FILE` | 配置文件路径 | `etc/cloud_dev.yaml` |
| `LOG_LEVEL` | 日志级别 | `info` |
| `TZ` | 时区设置 | `Asia/Shanghai` |

## 🐛 故障排除

### 常见问题

1. **服务启动失败**
   ```bash
   # 检查端口占用
   netstat -tlnp | grep :12206
   
   # 检查配置文件
   make lint
   ```

2. **文件上传失败**
   ```bash
   # 检查存储目录权限
   ls -la /var/lib/cloud/storage
   
   # 检查磁盘空间
   df -h
   ```

3. **数据库连接失败**
   ```bash
   # 测试数据库连接
   psql -h your-db-host -U postgres -d cloud_db -c "SELECT 1;"
   ```

### 日志分析

```bash
# 查看服务日志
tail -f logs/cloud.log

# 查看错误日志
grep ERROR logs/cloud.log

# 查看文件操作日志
grep "upload\|download" logs/cloud.log
```

## 📊 数据模型

### 核心表结构

#### cloud_disk_dir - 目录表
```sql
CREATE TABLE cloud_disk_dir (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    parent_id BIGINT DEFAULT 0,
    name VARCHAR(255) NOT NULL,
    path TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### cloud_disk_file - 文件表
```sql
CREATE TABLE-cloud_disk_file (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    directory_id BIGINT NOT NULL,
    name VARCHAR(255) NOT NULL,
    original_name VARCHAR(255)NOT NULL,
    size BIGINT NOT NULL,
    mime_type VARCHAR(100),
    storage_path TEXT NOT NULL,
    hash VARCHAR(64),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### cloud_album - 相册表
```sql
CREATE TABLE cloud_album (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    cover_photo TEXT,
    is_private BOOLEAN DEFAULT false,
    cloud_id BIGINT NOT NULL,
    cloud_identity VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### cloud_note - 笔记表
```sql
CREATE TABLE cloud_note (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    category VARCHAR(100),
    tags TEXT,
    is_markdown BOOLEAN DEFAULT false,
    is_pinned BOOLEAN DEFAULT false,
    is_private BOOLEAN DEFAULT false,
    views INTEGER DEFAULT 0,
    cloud_id BIGINT NOT NULL,
    cloud_identity VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## 🤝 贡献指南

### 开发流程

1. **Fork 项目**
2. **创建特性分支**: `git checkout -b feature/amazing-feature`
3. **提交更改**: `git commit -m 'Add amazing feature'`
4. **推送分支**: `git push origin feature/amazing-feature`
5. **创建 Pull Request**

### 代码规范

- 遵循 Go 官方代码规范
- 使用 `gofmt` 格式化代码
- 添加必要的注释和文档
- 编写单元测试

### 提交规范

```
type(scope): description

[optional body]

[optional footer]
```

类型:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建过程或辅助工具的变动

## 📄 许可证

本项目采用内部许可证，仅供 BSM 内部使用。

## 👥 团队

- **作者**: David Yan (david.yan@qq.com)
- **维护者**: BSM 开发团队
- **项目地址**: [bsm/full/module/base/cloud](https://bsm/full/module/base/cloud)

## 🔗 相关链接

- [BSM SDK](https://git.apinb.com/bsm-sdk)
- [API 文档](https://docs.apinb.com/cloud)
- [问题反馈](https://bsm/full/module/base/cloud/issues)

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请输入标！**

Made with ❤️ by BSM Team

</div>