Sharely — 技术文档

版本： 1.0.0 · 许可证： MIT · Node.js： ≥ 18

目录

1. 项目概述

2. 架构

3. 技术栈

4. 目录结构

5. 配置与环境变量

6. 数据模型

7. REST API

8. WebSocket API

9. 文件服务路由

10. 身份验证与安全

11. 上传系统

12. 缩略图生成

13. 邮件与SMTP

14. 国际化

15. 前端（React SPA）

16. 管理后台

17. GDPR / 隐私保护

18. 后台任务

19. 部署

20. 开发环境

21. 迁移与脚本

22. 端到端测试

1. 项目概述

Sharely 是一个自托管文件共享平台，提供简洁的 Web 界面、ShareX 集成和 API 访问。用户可上传截图、文件和媒体，并通过短链接即时分享。

核心功能

2. 架构

┌─────────────────────────────────────────────────────────────┐
│                        Browser / Client                      │
│            React 18 SPA  ·  Vite  ·  Tailwind CSS           │
│   ┌──────────────────────────────────────────────────────┐   │
│   │  HTTP REST (/api/*)            WebSocket (/ws)       │   │
│   └──────────────────────────────────────────────────────┘   │
└───────────────────────────┬────────────────────┬─────────────┘
                            │ HTTP               │ WS
┌───────────────────────────▼────────────────────▼─────────────┐
│                    Express.js (app.js)                        │
│                                                               │
│  ┌──────────────┐  ┌───────────┐  ┌──────────┐  ┌────────┐  │
│  │  /api/auth   │  │  /api/*   │  │   /f/*   │  │  /s/*  │  │
│  │  /api/install│  │  routes   │  │  files   │  │ shares │  │
│  └──────────────┘  └───────────┘  └──────────┘  └────────┘  │
│                                                               │
│  Middleware: session · rate-limit · CSRF · CSP · auth        │
│                                                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  multer  │  │  ws.js   │  │  mailer  │  │ retention  │  │
│  │  upload  │  │ WebSocket│  │ nodemailer│  │  cleanup   │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
└───────────────────────────┬───────────────────────────────────┘
                            │
┌───────────────────────────▼───────────────────────────────────┐
│                      MongoDB (Mongoose)                        │
│  User · File · Collection · ShareLink · SiteSettings          │
│  AuditLog                                                      │
└───────────────────────────────────────────────────────────────┘
                            │
              ┌─────────────▼───────────────┐
              │     Dateisystem (uploads/)   │
              │  {folderName}/  ·  .chunks/  │
              │  .thumbnails/   ·  .avatars/ │
              └─────────────────────────────┘

数据流：标准上传

Browser → POST /api/web-upload (multipart/form-data)
       → multer: Datei in uploads/{folderName}/
       → File.createUnique() → MongoDB
       → generateThumbnail() (async, non-blocking)
       → logAudit()
       → broadcast('file:uploaded') via WebSocket
       ← JSON: { files: [...] }

数据流：ShareX 上传

ShareX → POST /upload (token im Formular-Body)
       → multer: Datei temporär in uploads/
       → requireApiKey: Token-Lookup → User
       → fs.renameSync → uploads/{folderName}/
       → File.create() → MongoDB
       ← JSON: { url, delete_url }

3. 技术栈

4. 目录结构

sharely/
├── app.js                          # Express 入口点，启动序列
├── package.json
├── .env.example                    # 所有环境变量的模板
├── Dockerfile
├── docker-compose.yml
│
├── src/
│   ├── config/
│   │   └── db.js                   # MongoDB 连接（Mongoose）
│   ├── middleware/
│   │   ├── auth.js                 # requireLogin / requireAdmin / requireApiKey
│   │   └── upload.js               # Multer 配置，黑名单
│   ├── models/
│   │   ├── AuditLog.js             # 审计事件（TTL 90 天）
│   │   ├── Collection.js           # 文件集合
│   │   ├── File.js                 # 文件元数据
│   │   ├── ShareLink.js            # 文件专属分享链接
│   │   ├── SiteSettings.js         # 单例：运营者设置
│   │   └── User.js                 # 用户账户 + API 密钥
│   ├── routes/
│   │   ├── api.js                  # 主 API（上传、相册、管理等）
│   │   ├── auth.js                 # 登录 / 注册 / 密码重置
│   │   ├── files.js                # 文件服务、OG 嵌入、Range 请求
│   │   ├── import.js               # XBackBone 迁移
│   │   ├── install.js              # 初始安装端点
│   │   └── shares.js               # 分享链接文件服务
│   ├── jobs/
│   │   └── retentionCleanup.js     # 每日删除过期文件
│   ├── migrations/
│   │   ├── migrateApiKeyHashes.js  # 一次性：明文 → SHA-256 哈希
│   │   └── migrateUserFolders.js   # 一次性：将文件移入用户文件夹
│   ├── utils/
│   │   ├── audit.js                # logAudit() 辅助函数
│   │   ├── generateThumbnail.js    # ffmpeg / ghostscript 集成
│   │   ├── mailer.js               # Nodemailer 封装 + i18n 邮件模板
│   │   └── sanitizeFilename.js     # 文件名净化
│   └── ws.js                       # WebSocket 服务器 + 动作调度器
│
├── client/                         # React 前端
│   ├── index.html
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   └── src/
│       ├── main.jsx                # React 入口点
│       ├── App.jsx                 # 路由配置
│       ├── index.css               # 全局样式
│       ├── context/
│       │   └── AuthContext.jsx     # 全局认证状态
│       ├── hooks/
│       │   ├── use-toast.js        # Toast 通知 Hook
│       │   └── useWebSocket.js     # WS 连接 + 事件处理器
│       ├── components/
│       │   ├── Layout.jsx          # 应用外壳（导航栏、侧边栏）
│       │   ├── ProtectedRoute.jsx  # 认证守卫
│       │   ├── ShareLinkDialog.jsx # 分享链接创建对话框
│       │   ├── AddToCollectionDialog.jsx
│       │   ├── CookieBanner.jsx
│       │   ├── LanguageSelector.jsx
│       │   ├── RequireEmailDialog.jsx
│       │   ├── UserAvatar.jsx
│       │   └── ui/                 # shadcn/ui 基础组件
│       ├── pages/
│       │   ├── Upload.jsx          # 上传页面
│       │   ├── Gallery.jsx         # 文件相册
│       │   ├── FileView.jsx        # 文件详情视图
│       │   ├── Collections.jsx     # 集合概览
│       │   ├── CollectionView.jsx  # 单个集合
│       │   ├── ShareView.jsx       # 公开分享链接页面
│       │   ├── Settings.jsx        # 用户设置
│       │   ├── Login.jsx
│       │   ├── Register.jsx
│       │   ├── ForgotPassword.jsx
│       │   ├── ResetPassword.jsx
│       │   ├── Install.jsx         # 初始安装
│       │   ├── PrivacyPolicy.jsx
│       │   ├── TermsOfService.jsx
│       │   └── admin/
│       │       ├── Dashboard.jsx   # 管理员首页
│       │       ├── Users.jsx       # 用户管理
│       │       ├── Files.jsx       # 文件管理
│       │       ├── AuditLog.jsx    # 审计日志视图
│       │       ├── SiteSettings.jsx# 运营者设置
│       │       └── Import.jsx      # XBackBone 导入
│       ├── i18n/
│       │   ├── index.js            # i18next 配置
│       │   └── locales/
│       │       ├── de.json
│       │       ├── en.json
│       │       ├── es.json
│       │       ├── fr.json
│       │       ├── it.json
│       │       ├── ja.json
│       │       ├── pt.json
│       │       └── zh.json
│       └── lib/
│           └── utils.js            # Tailwind 工具函数（cn()）
│
├── scripts/
│   ├── setup-db.js
│   ├── mongo-init.js               # MongoDB 初始化脚本
│   ├── migrate-uploads-to-user-folders.js
│   └── generate-missing-thumbnails.js
│
├── e2e/                            # Playwright 测试
│   ├── admin.spec.js
│   ├── bulk-actions-fixes.spec.js
│   ├── gallery.spec.js
│   ├── sharelink.spec.js
│   ├── tags.spec.js
│   ├── upload.spec.js
│   ├── helpers.js
│   └── global-setup.js
│
├── uploads/                        # 文件上传（运行时）
│   ├── .thumbnails/
│   ├── .avatars/
│   └── .chunks/                    # 临时分块
│
└── docs/assets/                    # 截图和 Logo

5. 配置与环境变量

所有变量均从 .env 文件加载（通过 dotenv）。.env.example 文件包含完整模板。

必填字段

所有环境变量

6. 数据模型

User（src/models/User.js）

{
  username:                    String（3–32，唯一，字母数字 + _-）
  password:                    String（bcrypt，12 轮）
  role:                        'admin' | 'user'
  apiKey:                      String（遗留，迁移后为空）
  apiKeyHash:                  String（SHA-256，唯一，sparse）
  apiKeyPrefix:                String（明文的前 8 个字符）
  folderName:                  String（唯一，sparse，最大 64）
  avatarExt:                   String | null（.jpg/.png/.gif/.webp）
  embedMode:                   'embed' | 'raw'
  isActive:                    Boolean
  email:                       String（小写，唯一，sparse）
  emailVerified:               Boolean
  emailVerificationToken:      String | null（明文的 SHA-256 哈希）
  emailVerificationExpires:    Date | null
  passwordResetToken:          String | null（SHA-256 哈希）
  passwordResetExpires:        Date | null
  language:                    'en'|'de'|'fr'|'es'|'it'|'pt'|'ja'|'zh'
  predefinedTags:              [String]（最多 100 个标签 × 50 个字符）
  createdAt:                   Date
}

重要方法：

• user.comparePassword(candidate) — bcrypt 比较
• user.regenerateApiKey() — 生成新明文，存储哈希，返回明文（仅显示一次）
• User.findByApiKey(plaintext) — 通过 SHA-256 哈希查找，仅限活跃用户

File（src/models/File.js）

{
  shortId:      String（8 个十六进制字符：6 位时间戳 + 2 位随机，唯一）
  deleteToken:  String（32 个十六进制字符，唯一）
  originalName: String（已净化）
  storedName:   String（相对路径："folderName/8hex.ext"）
  mimeType:     String
  size:         Number（字节）
  uploader:     ObjectId → User
  views:        Number
  tags:         [String]（最多 20 × 50 个字符）
  createdAt:    Date
}

虚拟属性：

• sizeHuman — 人类可读的大小（B / KB / MB / GB）
• displayType — 分类：image|video|audio|pdf|code|text|file

Short ID 算法：

shortId = hex(seconds_since_2024-01-01, 6 chars) + randomBytes(2).hex()

Collection（src/models/Collection.js）

{
  shortId:     String（8 位十六进制，唯一）
  name:        String（最大 100）
  description: String（最大 500）
  owner:       ObjectId → User
  files:       [ObjectId → File]
  password:    String | null（bcrypt）
  expiresAt:   Date | null
  createdAt:   Date
}

过期的集合将在到期后 7 天由 MongoDB TTL 索引自动删除。

ShareLink（src/models/ShareLink.js）

{
  token:         String（32 位十六进制，唯一）
  file:          ObjectId → File
  createdBy:     ObjectId → User
  label:         String（最大 100）
  password:      String | null（bcrypt）
  expiresAt:     Date | null
  downloadLimit: Number（-1 = 无限制）
  downloadCount: Number
  createdAt:     Date
}

与集合相同：通过 TTL 索引在过期后享有 7 天宽限期。

SiteSettings（src/models/SiteSettings.js）

单例文档（_id: 'singleton'）：

{
  operatorName:        String
  operatorAddress:     String
  operatorEmail:       String
  cloudflareAnalytics: Boolean
  fileRetentionDays:   Number（0 = 禁用）
  encryptionAtRest:    Boolean
  sessionDurationDays: Number（默认：7）
  allowRegistration:   Boolean
}

AuditLog（src/models/AuditLog.js）

{
  timestamp: Date（TTL 索引：90 天）
  userId:    ObjectId → User | null
  username:  String | null
  action:    String
  ip:        String | null
  meta:      Mixed（特定于操作的元数据）
}

7. REST API

基础 URL：/api

所有 JSON 端点均返回 Content-Type: application/json。错误格式：{ "error": "消息" }。

认证（/api/auth）

登录请求：

POST /api/auth/login
{ "username": "max", "password": "meinPasswort123" }

登录响应：

{
  "user": {
    "id": "...", "username": "max", "role": "user",
    "avatarUrl": null, "email": "[email protected]",
    "emailVerified": true, "language": "de"
  }
}

文件上传

API 上传响应：

{
  "url": "https://example.com/f/a1b2c3d4",
  "raw": "https://example.com/f/a1b2c3d4/raw",
  "delete_url": "https://example.com/api/delete/a1b2c3d4",
  "short_id": "a1b2c3d4",
  "filename": "screenshot.png",
  "size": 102400
}

分块上传流程

1. POST /api/chunk/init → { uploadId: "32hex" }

2. POST /api/chunk/:uploadId（Body：chunkIndex=N，文件：chunk）→ { received: N }

并行上传 3–5 个分块

3. POST /api/chunk/:uploadId/complete → { files: [fileObject] }

文件管理

相册查询参数：

• q — 在文件名中搜索（正则表达式安全）
• type — all|image|video|audio|pdf|code
• tag — 精确标签筛选
• page — 页码（默认：1）

用户设置

分享链接

创建分享链接：

POST /api/file/a1b2c3d4/share-links
{
  "label": "给同事用",
  "password": "密码",
  "expiresAt": "2025-12-31T23:59:59Z",
  "downloadLimit": 10
}

集合

管理员端点

站点设置（公开）

GET /api/site-settings
{
  "operatorName": "Musterfirma GmbH",
  "operatorAddress": "Musterstr. 1, 12345 Musterstadt",
  "operatorEmail": "[email protected]",
  "cloudflareAnalytics": false,
  "fileRetentionDays": 365,
  "encryptionAtRest": false,
  "sessionDurationDays": 7
}

8. WebSocket API

连接： wss://example.com/ws（仅限已登录用户，需要会话 Cookie）

协议

客户端 → 服务器（请求）：

{ "id": "req-abc123", "action": "file:list", "payload": { "type": "image", "page": 1 } }

服务器 → 客户端（响应）：

{ "id": "req-abc123", "data": { ... } }

服务器 → 客户端（错误）：

{ "id": "req-abc123", "error": "Forbidden", "status": 403 }

服务器 → 客户端（广播）：

{ "event": "file:uploaded", "data": { "shortId": "a1b2c3d4", "uploaderId": "..." } }

可用操作

广播事件

9. 文件服务路由

/f/:shortId — 文件查看器

• 浏览器请求： 转发到 React SPA（index.html）— SPA 渲染查看器。
• 社交媒体机器人（Discord、Telegram、Twitter 等）：返回带有 Open Graph / Twitter Card 元标签的最小 HTML 页面。

- embedMode = 'embed'：带重定向的 OG HTML

- embedMode = 'raw' + 图片/视频/音频：HTTP 302 → /f/:shortId/raw

/f/:shortId/raw — 直接访问

以 HTTP 响应的形式提供文件，支持 Range 请求（206 Partial Content）。图片/视频/音频：Content-Disposition: inline，其他：attachment。

/f/:shortId/download — 强制下载

与 /raw 相同，但始终使用 Content-Disposition: attachment。

/f/:shortId/thumb — 缩略图

返回 JPEG 缩略图（适用于视频和 PDF）。Cache-Control: public, max-age=86400。

/f/:shortId/delete/:token — ShareX 删除

通过唯一删除令牌无需会话即可删除文件。

/s/:token — 分享链接文件服务（src/routes/shares.js）

验证密码（通过会话标志）、过期日期和下载限制，然后提供文件。

10. 身份验证与安全

会话认证

• 带 MongoDB 存储的 Express 会话（connect-mongo）
• 会话 Cookie：httpOnly: true、sameSite: 'strict'，生产环境下 secure: true
• 会话时长：通过 SiteSettings.sessionDurationDays 配置（默认：7 天），实时缓存 60 秒

API 密钥认证

• API 密钥以 SHA-256 哈希形式存储，从不以明文存储
• 前 8 个字符作为 apiKeyPrefix 存储（用于展示）
• 查找：User.findByApiKey(plaintext) 计算哈希并在 apiKeyHash 中搜索
• 下载 ShareX 配置时密钥会被重新生成 — 明文仅在那一刻可见

中间件链（src/middleware/auth.js）

requireLogin    → 检查 req.session.user → 未登录返回 401
requireAdmin    → 类似 requireLogin，额外要求 role === 'admin' → 403
requireApiKey   → 检查 Authorization 请求头或 req.body.token

CSRF 防护

app.js 中的 requireSameOrigin() 对所有 API 路由比较 Origin 请求头与 Host 请求头。配合 sameSite: 'strict' Cookie 共同防护。

内容安全策略

default-src 'self';
script-src 'self' 'unsafe-inline' https://static.cloudflareinsights.com;
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;
media-src 'self' blob:;
connect-src 'self' https://cloudflareinsights.com;
frame-ancestors 'self';

安全响应头

• X-Frame-Options: SAMEORIGIN
• X-Content-Type-Options: nosniff

限流

文件黑名单

以下 MIME 类型和扩展名在上传时将被拒绝：

被阻止的 MIME 类型： application/x-executable、application/x-sh、application/x-csh、application/x-bat

被阻止的扩展名： .bat、.cmd、.com、.ps1、.psm1、.psd1、.sh、.bash、.csh、.zsh、.fish、.vbs、.vbe、.jse、.scr、.pif、.application、.gadget、.hta、.php、.php3–5、.phtml、.asp、.aspx、.jsp、.jspx、.cfm

路径遍历防护

所有通过 resolveUploadPath() 的文件访问都会验证解析路径是否位于 UPLOAD_DIR 内。

11. 上传系统

标准上传（Multer）

• 存储方式： multer.diskStorage → uploads/{folderName}/{8hex}{.ext}
• 文件名： crypto.randomBytes(4).hex() + 原始扩展名
• 限制： MAX_FILE_SIZE_MB（默认：100 MB）
• 存储位置： 用户专属文件夹（user.folderName）

分块上传（>250 MB）

前端客户端会自动为大文件切换到分块模式。

服务器端目录结构：

uploads/.chunks/{uploadId}/
  meta.json          { filename, mimeType, totalSize, totalChunks, userId, createdAt }
  chunk-0
  chunk-1
  ...
  chunk-N

分块大小： 10–20 MB（向后兼容最多接受 51 MB）

并发数： 3–5 个分块同时上传

合并方式： 基于流（不在 RAM 中完全加载）

头像上传

• 存储方式： multer.memoryStorage()（无磁盘缓冲）
• 存储位置： uploads/.avatars/{userId}{.ext}
• 限制： 2 MB
• 格式： JPEG、PNG、GIF、WebP

12. 缩略图生成

缩略图在上传后异步生成（.catch(() => {}) — 错误会被静默忽略）。

视频缩略图（ffmpeg）

ffmpeg -y -i <file> -ss 00:00:01 -vframes 1 \
  -vf "scale=320:320:force_original_aspect_ratio=increase,crop=320:320" \
  -q:v 3 uploads/.thumbnails/<shortId>.jpg

PDF 缩略图（Ghostscript）

gs -dNOPAUSE -dBATCH -dSAFER \
  -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 \
  -r72 -dJPEGQ=85 \
  -sOutputFile=uploads/.thumbnails/<shortId>.jpg \
  <file>

超时： 每次缩略图生成 30 秒

回退： 如果 ffmpeg/ghostscript 不可用，生成将静默跳过。

补充生成脚本

npm run migrate:thumbnails
# 或在容器中：
docker exec -it <container> npm run migrate:thumbnails

13. 邮件与 SMTP

配置

设置 SMTP_HOST 后 SMTP 即被激活。mailer.isConfigured() 检查该值。

邮件模板

所有邮件均以用户的语言发送（8 种语言）。模板内嵌于 src/utils/mailer.js。

发送的邮件类型：

令牌安全

• 令牌：crypto.randomBytes(32).hex()（64 个十六进制字符）
• 存储形式：令牌的 SHA-256 哈希
• 邮件中包含明文令牌作为 URL 参数
• 验证方式：将收到令牌的哈希与存储的哈希进行比较

14. 国际化

库： i18next + react-i18next + i18next-browser-languagedetector

支持的语言：

语言选择：

1. 浏览器语言检测（自动）

2. 数据库中的用户偏好（user.language）

3. 通过 PATCH /api/user/language 持久化

翻译文件：client/src/i18n/locales/{code}.json

15. 前端（React SPA）

路由配置（client/src/App.jsx）

认证上下文（client/src/context/AuthContext.jsx）

已登录用户的全局状态。应用启动时通过 GET /api/auth/me 初始化。

WebSocket Hook（client/src/hooks/useWebSocket.js）

管理持久化的 WS 连接。提供 sendMessage() 和事件处理器注册。连接断开时的重连逻辑。

UI 组件

基于 shadcn/ui（Radix UI Primitives + Tailwind CSS）：

• Dialog、AlertDialog、DropdownMenu、ContextMenu、Popover
• Select、Checkbox、Input、Textarea、Label
• Card、Badge、Button、Separator、Tabs、Table
• Toast / Toaster 用于通知
• Calendar / DateTimePicker 用于选择过期日期
• Pagination 用于分页列表
• ScrollArea、Tooltip

16. 管理后台

管理后台（/admin/*）仅限 role: 'admin' 的用户访问。

仪表板（/admin）

• 用户总数、文件数、存储使用量
• 最近上传的 10 个文件
• 通过 WebSocket 实时更新（stats:invalidate）

用户管理（/admin/users）

• 所有用户及其文件数量和存储使用量
• 创建用户、启用/禁用、修改角色
• 重置密码、重新生成 API 密钥
• 修改文件夹名称（物理文件在服务器上移动）
• 删除用户（所有文件将被删除）

文件管理（/admin/files）

• 所有用户的所有文件，分页显示
• 按文件名搜索
• 删除文件

审计日志（/admin/audit-log）

• 所有操作的分页日志（50 条/页）
• 按用户名和操作类型筛选
• CSV 导出（用于合规目的）

站点设置（/admin/site-settings）

• 运营者信息（名称、地址、邮箱）
• 启用 Cloudflare Analytics
• 文件保留时长
• 会话时长
• 启用/禁用用户注册

XBackBone 导入（/admin/import）

• 从 XBackBone SQLite 数据库预览并导入
• 按用户名匹配用户
• 幂等性（已导入的文件将被跳过）

17. GDPR / 隐私保护

GDPR 删除流程

删除账户时（user:delete-account / DELETE /api/user/account）：

1. 用户的所有文件从磁盘删除

2. 缩略图被删除

3. 头像被删除

4. 审计日志条目被匿名化（username: '[deleted]'、ip: null、userId: null）

5. 用户文档被删除

6. 会话被销毁

18. 后台任务

保留期清理（src/jobs/retentionCleanup.js）

• 执行时机： 启动时以及之后每天执行（setInterval(runRetentionCleanup, 24h)）
• 操作： 若 SiteSettings.fileRetentionDays > 0，则删除超过该天数的文件
• 删除内容：磁盘上的文件、缩略图、MongoDB 文档
• 向管理员广播 stats:invalidate

MongoDB TTL 索引（自动）

19. 部署

Docker（推荐）

git clone https://github.com/Christianoooooo/sharely.git
cd sharely
cp .env.example .env
# 编辑 .env（SESSION_SECRET、MONGO 密码、BASE_URL）
docker compose up -d

服务：

• app — Node.js 应用（端口 3000）
• mongo — MongoDB 7（端口 127.0.0.1:27017，外部不可访问）

数据卷：

• uploads — 持久文件存储
• mongo_data — MongoDB 数据

健康检查： 应用检查 / 是否返回 HTTP 200，MongoDB 检查 db.adminCommand('ping')。

Nginx 反向代理

server {
    listen 443 ssl;
    server_name files.example.com;

    client_max_body_size 2100M;  # 至少要大于最大分块大小加缓冲

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

.env 中的 BASE_URL 必须与公开域名一致。

首次启动

第一个注册的用户将自动获得 admin 角色（User.countDocuments() === 0）。

20. 开发环境

前提条件

• Node.js ≥ 18
• MongoDB（本地或通过 Docker）
• 可选：ffmpeg、ghostscript（用于缩略图）

搭建环境

# 后端
npm install
cp .env.example .env
# 编辑 .env

# 前端
cd client
npm install

启动

# 后端（端口 3000，使用 nodemon）
npm run dev

# 前端（端口 5173，另开终端）
cd client
npm run dev

Vite 开发服务器会自动将 API 请求代理到 localhost:3000。

构建

npm run build   # 构建 client/dist/，后端不变
npm start       # 启动生产环境 Express 服务器

21. 迁移与脚本

自动迁移（每次启动时）

这些迁移在 app.js 启动时运行，具有幂等性：

手动脚本

# 为已有文件生成缩略图
npm run migrate:thumbnails
# 或：
node scripts/generate-missing-thumbnails.js

# 将上传文件移动到用户文件夹（手动）
npm run migrate:user-folders
# 或：
node scripts/migrate-uploads-to-user-folders.js

数据库初始化（Docker）

scripts/mongo-init.js 在 MongoDB 容器首次启动时执行，以正确权限创建应用用户。

22. 端到端测试

框架： Playwright（@playwright/test）

测试文件

运行测试

# 所有测试
npm run test:e2e

# 带 UI 界面
npm run test:e2e:ui

Playwright 配置： playwright.config.js

全局初始化： e2e/global-setup.js（创建测试用户、管理员等）

辅助函数： e2e/helpers.js（共享辅助函数）

附录：审计日志操作列表

*本文档由 sharely v1.0.0 源代码生成*