CloudPicturePlatform - 云图片协作平台

简介

CloudPicturePlatform 是一个基于 Spring Boot 4.0.1 + Java 21 构建的企业级云图片管理与协作平台。采用领域驱动设计（DDD）分层架构，提供公开画廊、私人图库、团队空间三大使用场景，内置内容审核工作流、AI 辅助标签生成与多级缓存体系，支持本地存储与腾讯云 COS 双存储后端。

🎯 核心优势

• ✨ 多场景支持 — 公开画廊 / 私人图库 / 团队协作空间，满足个人与企业需求
• 🔐 开箱即用的安全体系 — JWT 无状态认证，RBAC 角色权限，平台角色与空间角色双维度管控
• 🏷️ AI 智能标签 — 上传时自动调用 AI 服务生成标签，支持多提供商（OpenAI / Google Vision / AWS Rekognition）
• ⚡ 高性能缓存 — Caffeine（L1）+ Redis（L2）两级缓存，Redis 不可用时自动降级
• 🗄️ 弹性存储 — 一键切换本地文件系统与腾讯云 COS，接口统一无感迁移
• 📋 完整审计链路 — 内容审核工作流、成员操作事件、标签变更全量审计
• ☁️ 云原生就绪 — Docker 友好，环境变量配置，Flyway 数据库版本管理

核心功能

🔒 身份与访问控制

• JWT 认证 — 无状态令牌，2小时有效期，Spring Security 集成
• RBAC 权限模型 — 平台角色（USER / ADMIN）+ 空间角色（OWNER / ADMIN / MEMBER）
• 细粒度鉴权 — 上传、审核、编辑、导出各操作独立权限控制
• 管理端隔离 — /api/admin/** 端点强制 ADMIN 角色，网关层拦截

🖼️ 图片资产管理

• 上传管道 — 文件校验 → 存储 → MD5 校验和 → 图像尺寸提取 → 搜索索引
• 多可见性模式 — PUBLIC（公开）/ PRIVATE（私有）/ TEAM（团队可见）
• 元数据提取 — 分辨率、文件大小、格式、校验和自动记录
• 空间配额管理 — 每个用户/团队拥有独立 Space，实时追踪 usedBytes

🏷️ 标签与搜索

• 标签目录 — 全局 Tag 目录，支持创建、改名（级联更新所有关联）、删除（使用中禁止）
• 图片标签关联 — PictureTag 记录置信度评分与 AI 提供商信息
• 多维搜索 — 关键词、标签、可见性、审核状态、拥有者、空间、日期范围、图片方向
• 搜索索引 — PictureSearchDocument 异步维护，支持后台全量重建

👥 团队协作

• 团队生命周期 — 创建自动生成 TEAM 类型空间和 OWNER 成员记录
• 邀请工作流 — 发送邀请 → 接受 / 拒绝 → 状态流转，支持取消和移除
• 角色管理 — OWNER / ADMIN / MEMBER 三级角色，权限分级控制
• 成员事件审计 — JOINED / INVITED / LEFT / MEMBER_REMOVED / TEAM_UPDATED 全量事件日志

📋 内容审核

• 审核工作流 — 公开图片上传后进入 PENDING 状态，等待管理员审批
• 审核操作 — APPROVE / REJECT，支持附加原因说明
• 审核历史 — ModerationRecord 记录完整审核链路，支持分页查询与 CSV 导出
• 批量操作 — 管理员批量处理待审图片

⚡ 性能与缓存

• 两级缓存 — Caffeine 本地缓存（L1）+ Redis 分布式缓存（L2）
• 降级容错 — FallbackCacheManager 在 Redis 不可用时自动降级到纯 Caffeine
• 缓存命名 — publicGallery、pictureSearch、adminPending、moderationHistory、tagCatalog
• 缓存失效 — 写操作自动驱逐相关缓存，保证数据一致性

🗄️ 存储抽象

• 统一接口 — StorageService 接口屏蔽底层差异，业务代码零修改切换存储后端
• 本地存储 — 开发/测试环境使用，文件写入 data/uploads/
• 腾讯云 COS — 生产环境推荐，支持多区域、自定义 Endpoint 和 CDN 前缀
• 切换方式 — 仅需修改 app.storage.provider 配置项

技术栈

核心框架

中间件与存储

安全与认证

可观测性

快速开始

前置需求

• JDK 21+
• Maven 3.8+
• Redis（可选，不可用时自动降级）
• PostgreSQL（生产环境）/ H2（开发默认）

本地开发启动

# 1. 克隆仓库
git clone https://github.com/dengxingzhi000/cloud-picture-platform.git
cd cloud-picture-platform

# 2. 启动（默认使用 H2 内存数据库，无需额外配置）
./mvnw spring-boot:run

# 3. 验证启动
curl http://localhost:8080/actuator/health

注册与登录

# 注册用户（自动创建个人空间）
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","email":"demo@example.com","password":"Demo@1234"}'

# 登录获取 JWT 令牌
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"Demo@1234"}'

上传图片

curl -X POST http://localhost:8080/api/pictures \
  -H "Authorization: Bearer <your-jwt-token>" \
  -F "file=@/path/to/image.jpg" \
  -F "visibility=PUBLIC"

切换生产数据库（PostgreSQL）

在 application.yml 中修改：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/cloud_picture
    username: your_user
    password: your_password
    driver-class-name: org.postgresql.Driver

启用腾讯云 COS 存储

app:
  storage:
    provider: cos
    cos:
      secret-id: ${COS_SECRET_ID}
      secret-key: ${COS_SECRET_KEY}
      region: ap-guangzhou
      bucket: your-bucket-name

关键配置说明

项目结构

cloud-picture-platform/
├── src/main/java/com/cn/cloudpictureplatform/
│   ├── domain/                    # 领域层：实体与枚举（DDD核心）
│   │   ├── user/                  # AppUser, UserRole, UserStatus
│   │   ├── picture/               # PictureAsset, Tag, PictureTag, Visibility, ReviewStatus
│   │   ├── space/                 # Space, SpaceType
│   │   ├── team/                  # Team, TeamMember, TeamMemberEvent, TeamRole
│   │   ├── audit/                 # ModerationRecord
│   │   ├── search/                # PictureSearchDocument
│   │   ├── storage/               # StorageService 接口, StorageResult
│   │   └── ai/                    # AI 域（预留）
│   │
│   ├── application/               # 应用层：用例服务（业务编排）
│   │   ├── auth/                  # AuthService（注册/登录/JWT签发）
│   │   ├── picture/               # PictureService（上传/搜索/审核）
│   │   ├── tag/                   # TagService（标签目录管理）
│   │   ├── team/                  # TeamService（团队/成员/邀请）
│   │   └── search/                # SearchIndexService + SearchMaintenanceService
│   │
│   ├── infrastructure/            # 基础设施层：技术实现
│   │   ├── persistence/           # JPA Repository（10个）
│   │   ├── security/              # JWT过滤器, UserDetails, Principal
│   │   └── storage/               # LocalStorageService, CosStorageService
│   │
│   ├── interfaces/                # 接口层：REST控制器与DTO
│   │   ├── auth/                  # AuthController
│   │   ├── picture/               # PictureController
│   │   ├── tag/                   # TagController
│   │   ├── team/                  # TeamController
│   │   └── admin/                 # AdminPictureController, SearchAdminController
│   │
│   ├── common/                    # 公共工具
│   │   ├── model/                 # BaseEntity（UUID主键 + 审计时间戳）
│   │   ├── web/                   # ApiResponse, PageResponse, ApiErrorCode
│   │   └── exception/             # ApiException, GlobalExceptionHandler
│   │
│   └── config/                    # Spring 配置
│       ├── SecurityConfig.java    # JWT安全策略
│       ├── CacheConfig.java       # 两级缓存配置
│       ├── cache/                 # FallbackCache, FallbackCacheManager
│       └── StorageProperties.java # 存储提供商配置
│
├── src/main/resources/
│   ├── application.yml            # 应用配置
│   └── db/migration/              # Flyway 迁移脚本（V1~V9）
│
└── docs/
    ├── requirements.md            # 需求文档
    ├── plan.md                    # 项目路线图
    └── er.md                      # ER 数据模型图

数据库迁移

项目使用 Flyway 进行数据库版本管理，启动时自动执行。

注意： 永远不要修改已提交的迁移脚本。新的 Schema 变更请创建 V10__xxx.sql。

路线图

贡献指南

我们欢迎任何形式的贡献！

提交流程

1. Fork 项目
2. 创建特性分支（git checkout -b feat/your-feature-#issue）
3. 提交更改（遵循约定式提交，使用中文）
4. 推送到分支（git push origin feat/your-feature-#issue）
5. 创建 Pull Request

Commit 格式

feat(picture.service): 添加图片相似度搜索功能

- 实现基于向量的相似度计算
- 添加相关 REST API 端点
- 补充单元测试

Closes #42

代码规范

• Java 21，Spring Boot 4，Lombok
• 4 空格缩进，类名 PascalCase，DTO 以 Request / Response 结尾
• DDD 分层：业务逻辑只进 application/，domain/ 不依赖 Spring
• Schema 变更必须新增 Flyway 迁移脚本，禁止修改已有迁移
• 新功能需要配套单元测试（JUnit 5 + Spring Boot Test）

常用命令

./mvnw test                      # 运行所有测试
./mvnw test -Dtest=TagServiceTests  # 运行单个测试类
./mvnw compile                   # 编译检查
./mvnw checkstyle:check          # 代码风格检查

许可证

本项目采用 Apache License 2.0 许可证。详见 LICENSE 文件。

联系方式

• 📧 Email: dengxingzhi2015@gmail.com
• 🐛 Issue: 提交问题
• 💬 Discussion: 参与讨论