前端设计已完成

前端开发已完成

后端开发需求文档

———————————————— 10 大模块、42 个子项

1. 项目总体约束

1.1 技术栈：Node ≥ 18 + NestJS + TypeORM + MySQL 8.0 | PostgreSQL 14（二选一，需支持切换）。 1.2 接口风格：RESTful + JSON，统一前缀 /api/v1。 1.3 统一返回体 { code: number, message: string, data: any, traceId: string } 1.4 错误码规范：0=成功；1xxx=通用错误；2xxx=鉴权；3xxx=文件；4xxx=数据库。 1.5 部署：Docker + docker-compose 一键启动；提供官方镜像 ghcr.io/xxx/imgbed:latest。

2. 数据库与初始化 ✅

2.1 物理库：库名可自定义，默认 imgbed。 2.2 字符集：utf8mb4 / UTF-8。 2.3 表清单 users       用户表 settings      系统配置表（key-value） files        文件元数据表 folders       虚拟文件夹表（支持多级） file_folder     多对多关系 share_tokens    分享令牌表（可选，预留） 2.4 初始化流程 Step1 程序启动时检测 settings 中 install_status=done 与否。 Step2 若未安装，自动创建 install_lock 文件防止并发，弹出「安装向导」接口： POST /api/v1/install Body: {dbHost, dbPort, dbName, dbUser, dbPwd, adminName, adminPwd, storagePath} 响应：{code:0, data:{adminToken}} Step3 成功后写入 settings：install_status=done，并创建 admin 用户（role=admin）。 2.5 升级脚本：版本号记录在 settings.schema_version，TypeORM migration 自动执行。

3. 配置中心 ✅

3.1 支持运行时修改且立即生效的配置项（管理后台页面已留好）： • siteName     站点名称 • storagePath    资源物理存放根目录（可配绝对路径，容器内挂卷） • allowFileTypes   允许上传的扩展名数组 • maxFileSize    单文件最大体积（Byte） • maxStoragePerUser 单用户最大容量（Byte，0=不限） • jwtSecret / jwtExpires 登录密钥与过期时间（默认 30 天） 3.2 提供接口 GET /api/v1/admin/settings  获取 POST /api/v1/admin/settings  修改（需 admin 角色）

4. 用户 & 鉴权 ✅

4.1 字段 userId(pk)、nickname、loginName(unique)、passwordHash、email(unique)、role(admin|user)、status(active|disabled)、createdAt、updatedAt、lastLoginAt。 4.2 密码策略：bcrypt 10 轮；登录失败 5 次锁定 15 分钟。 4.3 JWT 结构 payload: {userId, role, iat, exp} 刷新机制：自动续期 7 天（滑动窗口）。 4.4 接口 POST /api/v1/auth/login  登录 POST /api/v1/auth/logout  登出（把 jti 加入 Redis 黑名单） GET /api/v1/auth/profile 获取个人信息 PUT /api/v1/auth/profile 修改昵称/邮箱/密码

5. 文件存储 ✅

5.1 物理目录规则 {storagePath}/{userId}/{year}/{month}/{uuid}.{ext} 例：/data/imgbed/1001/2025/11/a3d8f9.jpg 5.2 文件名冲突：使用 uuidv4 重命名，原文件名存入 files.originalName。 5.3 支持本地磁盘 / S3 协议（MinIO、AWS S3、阿里云 OSS）一键切换，配置项： storage.driver = local|s3 s3.* 相关密钥由管理后台填写，自动加密存储。 5.4 上传流程

1. 校验登录 → 2. 校验单文件大小 → 3. 校验用户剩余容量 → 4. 写入物理存储 → 5. 落库 files 表 → 6. 返回 JSON

6. 资源管理 ✅

6.1 多级虚拟文件夹 • 支持无限级目录；数据库 folders 表存储 materialized path 或 closure table。 • 同一文件可归属到多个文件夹（ManyToMany）。 6.2 文件/文件夹重命名 PUT /api/v1/file/{fileId}/rename PUT /api/v1/folder/{folderId}/rename 物理文件名不变，仅修改 files.logicalName；若修改扩展名给出警告。 6.3 移动 & 批量移动 POST /api/v1/file/move Body: {fileIds[], targetFolderId} 6.4 复制（仅数据库记录复制，物理文件硬链接） POST /api/v1/file/copy 6.5 递归统计 GET /api/v1/folder/{id}/stats 返回总文件数/总大小

7. 删除与回收站 ✅

7.1 两种策略可配置： A. 直接物理删除（默认） B. 软删除 + 回收站（保留 30 天） 7.2 软删除实现 files.status=trashed；定时任务每天 04:00 扫描超过 30 天的 trashed 文件真正删除。 7.3 接口 DELETE /api/v1/file/{id}  → 移入回收站或物理删除 DELETE /api/v1/file/force → 立即物理删除（admin） GET  /api/v1/trash   → 回收站列表 POST /api/v1/trash/restore

8. 浏览与预览 ✅

8.1 图片缩略图 • 本地驱动：使用 sharp 生成 300×300 webp，缓存到 {storagePath}/.thumb/ • S3 驱动：接入 Lambda@Edge 或 阿里云 OSS 图片处理参数 ?x-oss-process=style/thumb 8.2 文档、视频在线预览 • 文档：接入 OnlyOffice / Microsoft Viewer，返回预览 URL。 • 视频：返回 HLS 索引 .m3u8（转码任务异步，见第 10 章）。 8.3 私有文件签名 GET /api/v1/file/{id}/url?expire=3600 返回带签名的临时 URL（local 驱动走 nginx secure_link；s3 驱动走预签名）。

9. 分享功能（预留） ✅

9.1 用户可创建分享令牌 POST /api/v1/share Body: {fileIds[], password, expireDays} 返回：{token, url} 9.2 匿名访问 GET /s/{token} 输入密码后查看/打包下载。

10. 任务与日志 ✅

10.1 异步队列 使用 BullMQ + Redis，用于缩略图、视频转码、清理回收站。 10.2 管理员日志 admin_logs 表记录「谁、在什么时间、做了什么、IP、UA」。 10.3 用户操作日志（可选） user_logs 表记录上传/删除/下载。 10.4 监控接口 GET /api/v1/admin/metrics 返回 {userCount, fileCount, totalSize, trashSize, queueWaiting}