项目名称:CloudDrive
项目定位:基于 GoZero 的微服务网盘系统
项目目标:从一个可以运行的基础网盘,逐步演进为具备文件管理、可靠存储、并发控制、权限管理、可观测性和自动化部署能力的工程项目。本文档定义项目的最终目标和验收标准,不代表所有功能必须一次性实现。每个阶段都应该交付一个可以运行、可以测试、可以解释的版本。
CloudDrive 是一个支持用户注册登录、文件上传下载、文件夹管理、文件分享和文件版本管理的个人云盘系统。
用户可以通过 HTTP API 或 Web 前端使用系统。后端采用 GoZero 微服务架构,MySQL 保存用户、文件元数据和业务状态,MinIO 或其他对象存储保存实际文件内容。
系统不仅要能正常工作,还应该能够处理常见的异常情况:
- 用户上传过程中网络中断,可以继续上传或安全重试。
- 用户重复提交上传请求,不会产生重复的业务记录或错误的文件状态。
- 多个用户并发上传和下载时,系统能够维持正确的状态和权限。
- 文件上传成功后,元数据与实际存储对象保持一致。
- 服务发生异常时,可以通过日志、指标和错误信息定位问题。
- 服务可以通过 Docker 部署,并逐步支持 Kubernetes 部署。
- 每个核心模块都有测试、文档和清晰的设计理由。
最终,我希望 CloudDrive 不仅是一个功能演示项目,更是一个能够展示 Go 后端开发、网络编程、数据库设计、分布式系统基础和工程实践能力的项目。
第一阶段优先保证数据正确性、接口语义、权限控制和异常处理。
在没有基准测试之前,不盲目引入缓存、消息队列或复杂的分布式组件。
每个服务负责自己的业务和数据,不允许为了方便而随意跨服务修改数据库。
一个功能不能仅仅因为生成了代码就算完成。
至少需要明确:
- 正常情况下如何工作。
- 输入错误时如何处理。
- 并发情况下是否正确。
- 发生故障时如何恢复。
- 如何通过测试验证结果。
先实现同步业务流程,再根据真实需求引入异步任务、消息队列、缓存和分布式部署。
技术选型必须解决实际问题,而不是给项目增加名词。
| 领域 | 技术选择 | 主要用途 |
|---|---|---|
| 编程语言 | Go | 核心业务开发 |
| 微服务框架 | GoZero | HTTP API、RPC、服务治理 |
| HTTP 接口 | RESTful API | 面向客户端提供服务 |
| 服务间通信 | gRPC / Protobuf | 内部 RPC 调用 |
| 关系型数据库 | MySQL 8.x | 用户、文件元数据、业务状态 |
| 对象存储 | MinIO | 保存实际文件内容 |
| 缓存 | Redis | 缓存、限流辅助、短期状态管理 |
| 消息队列 | Kafka,可选进阶 | 异步任务与事件处理 |
| API 测试 | Go testing、集成测试 | 验证业务正确性 |
| 接口调试 | curl、Postman 等 | 调试 HTTP API |
| 容器化 | Docker | 构建和运行服务 |
| 编排 | Docker Compose、Kubernetes | 本地及集群部署 |
| 监控 | Prometheus + Grafana | 指标采集与可视化 |
| 日志 | 结构化日志 | 故障定位和请求追踪 |
| 自动化 | GitHub Actions 等 CI 工具 | 自动构建和测试 |
技术栈可以随项目演进调整,但任何新增依赖都必须说明用途、收益和维护成本。
Client / Web UI
|
v
HTTP API Layer
|
+--------------+--------------+
| | |
v v v
User Service File Service Storage Service
| | |
v v v
User DB File DB Storage DB
|
v
Object Storage
MinIO
Internal communication: gRPC / Protobuf
Optional infrastructure:
Redis / Kafka / Prometheus / Grafana
这是逻辑架构。初期可以将多个服务和数据库部署在同一台机器上,不需要为了画出微服务架构图而提前购买一整套分布式基础设施。
负责用户身份和用户账户相关能力。
主要功能:
- 用户注册。
- 用户登录与身份验证。
- Access Token 和 Refresh Token 管理。
- Token 刷新与退出登录。
- 用户基本信息查询。
- 用户存储配额查询。
- 用户账户状态管理。
- 为其他服务提供内部用户信息查询能力。
核心要求:
- 密码使用适当的密码哈希算法保存,禁止明文存储。
- Token 设置有效期,校验签名、过期时间和必要的身份信息。
- Refresh Token 具备失效与撤销机制。
- 登录、注册等敏感接口具备基本的限流和错误处理。
- 不向客户端泄露密码哈希、Token 密钥等敏感信息。
负责文件元数据和文件管理业务。
主要功能:
- 创建、重命名和删除文件夹。
- 查询文件夹内容。
- 文件列表分页。
- 文件元数据查询。
- 文件移动与重命名。
- 文件删除和恢复策略。
- 文件分享链接创建、查询、撤销。
- 文件版本管理。
- 文件归属、权限与配额相关业务校验。
核心要求:
- 文件元数据和实际文件内容分离。
- 文件夹结构具有明确的父子关系。
- 用户只能访问有权限的文件和文件夹。
- 文件移动时检查目标目录权限、循环引用和重名策略。
- 删除文件时正确处理版本、分享链接和存储对象的生命周期。
- 文件列表支持分页,避免一次性加载大量数据。
- 对重要业务操作使用事务保证本地数据库状态一致。
负责文件内容的存储、上传和下载。
主要功能:
- 初始化上传任务。
- 上传小文件。
- 分片上传大文件。
- 查询上传进度。
- 完成分片合并或对象提交。
- 取消上传任务。
- 下载文件。
- 断点续传。
- 文件大小和内容校验。
- 文件存储元数据管理。
- 失败任务清理。
- 存储对象完整性检查。
核心要求:
- 实际文件内容保存在对象存储中,不直接以 MySQL 保存文件二进制内容。
- 上传任务具有明确的状态机。
- 文件上传未完成时,不应被当作正常可下载文件。
- 文件大小、分片编号和分片内容都需要校验。
- 同一个上传请求重试时,不应重复创建错误的业务状态。
- 下载前检查用户身份和文件访问权限。
- 对象存储操作失败时,记录足够的信息以便重试和排查。
- 不允许仅凭客户端传入的对象 Key 直接访问任意存储对象。
最终流程:
- 客户端提交注册信息。
- User Service 校验输入并检查账户是否已存在。
- 对密码进行安全哈希。
- 将用户信息写入数据库。
- 登录时验证密码并签发 Token。
- 客户端携带 Token 访问受保护的接口。
- 服务端验证身份和权限后处理请求。
验收标准:
- 重复注册会得到明确错误。
- 错误密码不会获得有效 Token。
- 过期 Token 无法访问受保护接口。
- 用户退出或撤销会话后,相关凭证按照设计失效。
- 不同用户之间不存在身份越权。
最终流程:
- 客户端请求创建上传任务。
- 服务端验证用户身份、文件名、文件大小和配额。
- Storage Service 创建上传任务并返回任务 ID。
- 客户端上传文件内容或多个分片。
- 服务端校验分片和上传进度。
- 服务端完成对象提交,并验证必要的完整性信息。
- 系统更新文件元数据与上传任务状态。
- 客户端获得明确的上传结果。
验收标准:
- 小文件能够正常上传。
- 大文件可以分片上传。
- 分片支持安全重试。
- 重复完成请求不会造成重复提交。
- 中断的上传任务可以查询状态并继续。
- 文件超过配额时拒绝上传。
- 上传失败不会产生可正常下载的半成品文件。
- 数据库与对象存储之间的异常能够被发现和恢复。
注意:MySQL 事务无法直接覆盖 MinIO 的对象操作。必须明确设计跨资源失败后的补偿、重试和清理流程,不能假装两个系统会自动保持原子性。
最终流程:
- 客户端请求下载文件。
- 系统验证用户身份和访问权限。
- File Service 查询文件元数据。
- Storage Service 获取对应对象。
- 服务端返回文件流或受控的临时下载地址。
- 客户端完成下载。
验收标准:
- 只能下载有权访问的文件。
- 不存在的文件返回明确错误。
- 文件内容与上传内容一致。
- 大文件下载不要求将整个文件一次性加载到内存。
- 网络中断时能够按照设计支持重试或断点续传。
- 下载地址和对象 Key 不会绕过授权检查。
最终流程:
- 验证用户身份和文件操作权限。
- 标记文件为删除状态,或执行设计好的逻辑删除。
- 按规则处理分享链接和历史版本。
- 确认没有其他有效引用需要保留对象。
- 清理不再使用的实际存储对象。
- 记录失败的清理任务并支持重试。
验收标准:
- 用户不能删除其他用户无权管理的文件。
- 删除失败不会静默丢失必要的业务信息。
- 重复删除请求具有明确的行为。
- 历史版本、分享链接和存储对象之间的生命周期关系清晰。
- 对象清理失败时能够发现并恢复。
最终流程:
- 文件所有者创建分享链接。
- 系统生成不可预测的分享标识。
- 根据需要设置密码、有效期和访问次数。
- 访问者通过分享链接获取文件。
- 系统校验分享状态和访问条件。
- 所有者可以撤销分享。
验收标准:
- 失效或撤销的分享链接无法继续访问。
- 受密码保护的分享需要验证密码。
- 分享访问不能绕过文件本身的存储安全机制。
- 分享链接不暴露内部存储路径和敏感凭证。
每个服务负责自己的业务数据:
- User Service:用户、配额、会话或刷新令牌。
- File Service:文件夹、文件元数据、文件版本、分享信息。
- Storage Service:上传任务、分片状态、存储对象记录。
在开发阶段可以使用同一个 MySQL 实例,但逻辑上必须明确各服务的数据归属。
- 主键、唯一约束和必要的外键或业务校验明确。
- 查询字段建立合理索引。
- 所有表都有清晰的字段语义。
- 时间字段统一使用 UTC 或明确的统一时区约定。
- 金额或配额等字段使用合适的数据类型。
- 删除、更新和状态迁移具有明确语义。
- SQL 变更可追踪、可复现。
- 不依赖客户端提供的数据来决定关键业务状态。
系统必须明确区分:
- 单个服务内部的数据库事务。
- 多个服务之间的业务一致性。
- MySQL 与对象存储之间的一致性。
跨服务操作不能简单依赖一个数据库事务解决。
最终应具有:
- 明确的状态迁移规则。
- 幂等的关键操作。
- 失败任务重试机制。
- 对象与元数据对账机制。
- 异常状态的监控和排查手段。
最终系统需要考虑以下场景:
对创建上传任务、提交上传、创建分享等关键操作,设计适当的幂等机制。
要求:
- 重复请求有明确的处理结果。
- 并发请求不会产生互相矛盾的状态。
- 幂等记录具有合理的生命周期。
- 所有跨服务调用设置合理的超时。
- 只对适合重试的错误进行重试。
- 对有副作用的操作先保证幂等,再考虑重试。
- 重试次数和退避策略有明确限制。
- 避免服务之间互相重试导致请求风暴。
- 对共享状态进行正确的同步。
- 避免数据竞争。
- 对配额扣减、上传完成、文件移动等关键业务考虑并发冲突。
- 使用数据库约束、事务或适当的锁实现一致性。
- 使用 Go race detector 检查可检测的数据竞争。
- 限制上传文件大小。
- 限制并发上传任务数量。
- 限制请求体大小和超时。
- 合理管理 goroutine、连接池和缓冲区。
- 避免大文件处理导致内存无限增长。
安全功能不是最后一天才贴上的装饰品。
最终必须满足:
- 密码安全哈希存储。
- Token 验证和过期控制。
- 用户级别的访问控制。
- 文件和文件夹级别的权限校验。
- 上传大小和类型校验。
- SQL 参数化查询。
- 敏感配置通过环境变量或受控配置注入。
- 日志不记录密码、完整 Token 或其他敏感凭证。
- 对象存储不允许未经授权的任意访问。
- 分享链接具备过期和撤销能力。
- 错误响应不暴露内部堆栈、数据库凭证等信息。
- 对重要接口进行基本的滥用和限流防护。
最终系统应该能够回答:
- 哪个接口最慢?
- 哪个服务的错误率最高?
- 文件上传失败的主要原因是什么?
- 当前有多少未完成的上传任务?
- 哪些对象清理任务长期失败?
- 请求在多个服务之间花了多少时间?
采用结构化日志,至少记录:
- 时间。
- 日志级别。
- 服务名称。
- 请求 ID 或 Trace ID。
- 关键业务操作。
- 错误类型和错误原因。
至少采集:
- HTTP 请求总量。
- 请求延迟分布。
- 请求错误率。
- RPC 调用延迟和错误数。
- 活跃上传任务数。
- 上传失败数。
- 上传与下载的字节数。
- 数据库连接池使用情况。
- 关键后台任务失败数。
进阶阶段使用 OpenTelemetry 等工具追踪跨服务请求,能够查看一次上传请求经过哪些服务,以及时间消耗在哪里。
至少提供:
- 服务不可用告警。
- 错误率异常告警。
- 请求延迟异常告警。
- 上传任务长期滞留告警。
- 对象存储清理失败告警。
最终项目必须具有自动化测试,而不只是开发者手动点过几次接口。
覆盖:
- 参数校验。
- 业务规则。
- 权限判断。
- 状态迁移。
- 配额计算。
- 幂等逻辑。
- 文件和上传任务相关的边界条件。
验证:
- 数据库读写。
- HTTP API 调用。
- RPC 调用。
- 对象存储操作。
- 上传和下载完整流程。
- 数据库与对象存储异常时的恢复行为。
至少覆盖:
- 注册、登录和访问鉴权。
- 上传文件并下载后验证内容一致。
- 上传中断后继续上传。
- 重复提交上传完成请求。
- 用户配额不足时拒绝上传。
- 用户 A 无法访问用户 B 的私有文件。
- 文件夹移动和重命名。
- 分享链接过期或撤销。
- 文件删除和对象清理。
- 服务异常后任务状态仍可恢复或明确报告失败。
建立可重复的测试环境,测量:
- 普通 API 的吞吐量和延迟。
- 文件上传和下载吞吐量。
- 不同文件大小下的资源消耗。
- 并发请求下的错误率。
- CPU、内存和数据库连接池使用情况。
性能指标必须来自真实测试结果,不能在 README 里凭空写一个漂亮的 QPS。数字会骗人,测试报告通常没那么配合。
通过清晰的启动步骤,可以在一台 Linux 机器或开发环境中启动:
- User Service。
- File Service。
- Storage Service。
- MySQL。
- MinIO。
Redis、Kafka、Prometheus 和 Grafana 按对应阶段启用。
最终要求:
- 每个服务可以构建 Docker 镜像。
- 镜像尽可能精简。
- 容器使用明确的配置和环境变量。
- 提供健康检查。
- 数据通过持久化卷保存。
- 服务启动顺序和依赖关系清晰。
- 提供 Docker Compose 配置。
- 不把密码和密钥硬编码进镜像。
进阶目标:
- 每个服务具有 Deployment 和 Service。
- 配置与密钥分离。
- 设置 readinessProbe 和 livenessProbe。
- 设置合理的 CPU、内存 requests 和 limits。
- 支持滚动更新。
- 能够通过日志和监控定位 Pod 故障。
- 能够验证服务重启和部分实例不可用时的行为。
每次提交或 Pull Request 至少执行:
- 代码格式检查。
- Go 静态检查。
- 单元测试。
- 构建检查。
- 可运行的集成测试。
- 必要的安全与依赖检查。
不预先承诺没有测试支撑的性能数字。
最终应建立一份性能报告,明确:
- 测试机器配置。
- Go 版本和依赖版本。
- MySQL 与对象存储配置。
- 文件大小分布。
- 并发用户数。
- 请求类型与比例。
- 吞吐量、延迟分位数和错误率。
- CPU、内存、网络和磁盘使用情况。
- 性能瓶颈与优化前后对比。
优化应基于测量结果,例如:
- 优化 SQL 和索引。
- 调整连接池。
- 减少不必要的内存复制。
- 使用流式文件处理。
- 调整并发控制。
- 在确有必要时引入缓存或异步处理。
每次优化都应说明问题、原因、方案和验证结果。
最终仓库至少包含:
CloudDrive/
├── README.md
├── target.md
├── docs/
│ ├── architecture.md
│ ├── database.md
│ ├── api.md
│ ├── upload-design.md
│ ├── consistency.md
│ ├── security.md
│ ├── testing.md
│ ├── performance.md
│ └── troubleshooting.md
├── deploy/
│ ├── docker/
│ └── kubernetes/
├── scripts/
├── user/
├── file/
└── storage/
实际目录以当前仓库结构为准,不必为了符合示例而重构所有文件。
文档应说明:
- 项目解决什么问题。
- 为什么采用当前架构。
- 每个服务负责什么。
- 数据库表之间是什么关系。
- 核心业务流程如何运行。
- 如何启动、测试和部署。
- 如何复现和定位常见故障。
- 已知限制是什么。
- 下一阶段准备解决什么问题。
重要的架构决策应记录在 ADR(Architecture Decision Record)中,尤其是服务边界、存储一致性、异步处理和部署方式。
目标:确认项目结构和基础设施可用。
- 审查现有目录结构。
- 检查三个服务的 API 定义。
- 检查 Protobuf 与 RPC 定义。
- 检查 SQL DDL。
- 确认 goctl 生成代码可以编译。
- 整理各服务的配置和启动方式。
- 明确服务之间的调用关系。
- 建立统一的错误处理和日志规范。
验收:项目能够编译,各服务职责清晰,生成代码与手写代码的边界明确。
目标:实现最小可用网盘。
- 用户注册和登录。
- Token 鉴权。
- 文件夹创建与查询。
- 小文件上传。
- 文件列表查询。
- 文件下载。
- 文件删除。
- 基础配额检查。
- MySQL 和 MinIO 本地部署。
- 核心业务单元测试和集成测试。
验收:一个用户可以注册、登录、上传文件、查看文件并下载原始内容;其他用户无法越权访问。
目标:让核心业务能够应对常见错误。
- 文件重命名和移动。
- 文件夹删除规则。
- 大文件分片上传。
- 上传进度查询。
- 断点续传。
- 幂等提交。
- 文件内容校验。
- 上传失败清理。
- 对象与元数据一致性检查。
- 文件分享和撤销。
- 文件版本管理。
验收:重复请求、网络中断和部分失败不会导致系统进入无法解释的状态。
目标:达到可以稳定交付的后端项目水平。
- 完善参数校验。
- 完善权限控制。
- 统一错误码和响应结构。
- 配置请求超时和 RPC 超时。
- 检查并发安全。
- 添加关键路径集成测试。
- 添加 Docker 镜像。
- 提供 Docker Compose。
- 添加 CI 流程。
- 完善配置和密钥管理。
- 编写故障排查文档。
验收:新开发者可以按照 README 启动项目、执行测试并验证核心业务。
目标:可以解释系统的运行状态和性能瓶颈。
- 统一结构化日志。
- 采集 HTTP 和 RPC 指标。
- 集成 Prometheus。
- 创建 Grafana 仪表盘。
- 接入链路追踪。
- 编写性能测试。
- 记录性能基线。
- 分析 SQL、网络和内存瓶颈。
- 完成至少一次有数据支撑的性能优化。
验收:能够通过日志、指标和追踪定位一次失败请求,并用测试数据证明优化是否有效。
目标:在已有可靠业务基础上增加异步处理和服务治理能力。
- 为耗时任务设计异步执行机制。
- 在适合的场景引入 Kafka。
- 设计事件格式和版本兼容策略。
- 处理消息重复投递。
- 处理消息消费失败和重试。
- 设计死信或失败任务处理流程。
- 根据需要引入 Redis。
- 验证服务重启、重复消费和部分故障。
- 明确事件最终一致性的边界。
可选的异步任务包括大文件处理、对象清理、过期分享清理和数据对账。
验收:异步任务在重复执行、消费失败和服务重启时不会静默丢失,系统可以发现并处理失败任务。
目标:让系统能够在容器化环境中部署、观察和恢复。
- 完善镜像构建。
- 完善 Docker Compose 环境。
- 编写 Kubernetes 部署清单。
- 配置健康检查。
- 配置资源 requests 和 limits。
- 验证滚动更新。
- 验证服务重启与故障恢复。
- 配置监控和告警。
- 编写部署、升级和回滚文档。
- 完成最终验收报告。
验收:能够按照文档部署系统,模拟常见故障,观察故障并验证恢复结果。
项目只有在以下核心目标得到实际验证后,才能称为完成。
- 用户注册、登录和鉴权正常。
- 文件夹管理正常。
- 小文件上传和下载正常。
- 大文件分片上传和恢复正常。
- 文件分享与撤销正常。
- 文件版本管理正常。
- 删除和对象清理行为明确。
- 关键操作具备幂等性。
- 网络中断和服务重启场景得到测试。
- 跨服务调用具备超时和明确的错误处理。
- 对象存储与数据库不一致时可以发现问题。
- 失败任务可以重试或被明确报告。
- 关键并发场景经过测试。
- 不同用户之间不存在未授权的数据访问。
- 文件下载经过权限验证。
- 敏感凭证不写入日志。
- 上传和分享接口具备必要的输入校验。
- 密钥和数据库凭证没有硬编码在仓库中。
- 核心业务具有自动化测试。
- CI 可以自动执行构建和测试。
- Docker 环境可以启动系统。
- 监控可以展示核心请求指标。
- README 和架构文档能够指导其他人运行项目。
- 有可复现的性能测试报告。
- 有至少一次完整的故障分析与修复记录。
- 能画出系统架构图并解释每个服务的职责。
- 能解释为什么采用当前的数据模型。
- 能独立定位并修复至少一类真实故障。
- 能解释上传幂等性和跨资源一致性设计。
- 能展示测试、监控和性能分析的实际结果。
- 能清楚说明一个重要技术决策的替代方案和取舍。
- 能通过一个完整业务流程讲清楚请求从客户端到数据库和对象存储的全过程。
第一阶段不追求:
- 自研分布式文件系统。
- 自研对象存储。
- 自研 RPC 框架。
- 自研消息队列。
- 一开始就部署完整 Kubernetes 集群。
- 为每个 CRUD 操作引入 Kafka。
- 为了展示技术栈而同时引入大量中间件。
- 在没有性能数据的情况下追求极限 QPS。
- 一开始就实现多地域容灾和复杂分布式事务。
如果现有方案已经能可靠地解决问题,就没有必要为了看起来高级而重新造一遍轮子。
CloudDrive 最终应当具备四种可以展示的成果:
- 一个可以运行的系统:能够完成真实的文件上传、下载、管理和分享。
- 一套可靠的工程实现:有测试、错误处理、权限控制和异常恢复机制。
- 一份可信的技术证据:有架构图、设计文档、性能数据、测试结果和故障分析记录。
- 一段能够清楚讲述的工程经历:能够说明遇到的问题、分析过程、设计选择、实现方式和验证结果。
最终目标不是把所有技术都塞进项目,而是让每一项技术都有明确的用途,让每一个重要设计都经得起追问。
完成定义:功能能够运行,错误能够处理,结果能够验证,设计能够解释,项目能够被其他开发者复现。