📦 文件分享系统 · 技术总结

基于 NestJS + React + MinIO 的企业级安全分享平台

✅ 全面支持 HTTPS · 大文件强制下载 · 密码保护 · 邮件通知 · 分享管理

🔧 技术栈

🖥️ 后端

NestJS, TypeORM, PostgreSQL, Redis, JWT, Nodemailer, Bull (队列), MinIO SDK

🎨 前端

React, Vite, React Router, Axios, Tailwind CSS, React Hot Toast, date-fns

📦 存储

MinIO (纠删码模式, 8节点), PostgreSQL, Redis (缓存/令牌)

🌐 代理

Nginx (SSL termination, 负载均衡, 端口转发)

✨ 核心功能

创建分享 – 支持设置有效期(1~30天/永久)、提取码、下载次数限制
密码验证 – 失败次数限制与临时锁定(防暴力破解)
强制下载 – 所有文件类型均弹出下载框(通过 response-content-disposition=attachment)
分享结果页 – 显示文件名、链接、提取码，支持“复制链接+密码”一键分享
分享管理 – 列表查看、延长有效期、撤销/删除分享
邮件通知 – 分享创建、被访问时实时邮件提醒
自定义短链 – 允许用户自定义分享码(4-20位字母数字)
用户资料 – JWT身份验证，获取个人资料接口

⚙️ 关键挑战与解决方案

🔐 1. HTTPS 混合内容与证书问题

Nginx 前端 :5173 使用 HTTPS，后端 :3000 也使用 HTTPS，但 MinIO 代理地址 :9002 为 HTTPS。通过统一环境变量 FRONTEND_URL=https://www.fox360.cn:5173 及后端强制生成 https 预签名 URL，解决混合内容报错。

📤 2. 大文件下载无响应 / 500 错误

根源：bandwidth_used 字段累加时出现字符串拼接，导致超出 bigint 范围。解决方案：在 recordDownload 和实体 recordDownload 方法中强制使用数值运算，并添加 try/catch 保证下载流程不受影响。

🔑 3. 密码验证流程 (PASSWORD_REQUIRED vs ACCESS_DENIED)

后端统一使用 ForbiddenException 携带 code 字段 (PASSWORD_REQUIRED, INVALID_PASSWORD, PASSWORD_LOCKED)，前端根据 errorCode 显示对应密码框或错误提示。同时引入临时标记 __passwordVerified 避免重复验证。

📧 4. 邮件通知链接错误 (出现 undefined 或后端地址)

修复：在 share.service 调用邮件服务时，必须传递 shareCode；email.service 中从环境变量 FRONTEND_URL 读取前端地址拼接 /s/${shareCode}。同时清理 .env 中重复/错误的 FRONTEND_URL 配置。

🧠 5. 模块依赖与循环注入

通过 forwardRef 处理 ShareModule 与 UserModule 的相互依赖，并确保 UserService 正确导出，解决 UnknownDependenciesException。

🏗️ 系统架构简图

客户端 (HTTPS) → Nginx (端口 5173/3000/9002)
        ↓
    ├─ 前端静态资源 (5173) → React 应用
    ├─ 后端 API (3000)     → NestJS 服务 (连接 PostgreSQL, Redis)
    └─ MinIO 代理 (9002)   → MinIO 集群 (8节点, 纠删码)

所有对外服务均通过 Nginx 代理并启用 SSL，内部服务使用 HTTP 通信。

📁 重要配置文件

.env – 后端环境变量 (数据库、Redis、MinIO、邮件、JWT)
nginx.conf – 反向代理、SSL、负载均衡、客户端限流
docker-compose.yml – 8节点 MinIO 集群 + Nginx 容器编排
share.entity.ts – 分享实体（包含密码哈希、访问控制、统计字段）
share.service.ts – 核心业务逻辑（创建、访问、下载、邮件）

🚀 部署要点

生成 SSL 证书并配置 Nginx (将域名 www.fox360.cn 指向服务器)
确保服务器开放端口 5173(前端), 3000(后端), 9002(MinIO代理)
MinIO 集群需保证所有节点数据目录权限正确 (uid=1000)
邮件服务需开启 SMTP 并填写正确的授权码 (QQ邮箱示例)
前端构建时使用 npm run build，并将产物部署到 Nginx 静态目录或单独托管

🔮 未来展望

📊 分享统计图表（浏览量、下载量、地理分布）
🖼️ 文件在线预览（图片、视频、PDF）
🔗 自定义短链增强（支持过期时间、自定义别名）
📱 移动端适配与 PWA 支持
🤖 分享二维码生成与分享海报

🙏 致谢

感谢整个开发过程中严谨的调试与优化，最终交付了一个稳定、安全、用户体验优秀的分享系统。特别鸣谢所有参与测试的小伙伴们～