front-deploy-platform/SETUP.md

项目设置指南

环境要求

• Node.js >= 16
• pnpm >= 8

安装步骤

1. 安装所有依赖

pnpm install:all

或者分别安装：

# 根目录
pnpm install

# 后端
cd backend
pnpm install

# 前端
cd ../frontend
pnpm install

2. 初始化数据库

cd backend
pnpm run migrate

这将创建所有必要的数据库表并插入默认设置。

3. 启动开发服务器

在项目根目录运行：

pnpm dev

这将同时启动：

• 后端服务：http://localhost:3000
• 前端服务：http://localhost:5173

或者分别启动：

# 后端
pnpm dev:backend

# 前端（新终端）
pnpm dev:frontend

项目结构

just-demo/
├── backend/              # 后端服务
│   ├── src/
│   │   ├── controllers/  # 控制器
│   │   ├── models/       # 数据模型
│   │   ├── routes/       # 路由
│   │   ├── middleware/   # 中间件
│   │   ├── utils/        # 工具函数
│   │   ├── config/       # 配置文件
│   │   └── migrations/   # 数据库迁移
│   ├── uploads/          # 上传文件存储
│   └── package.json
├── frontend/             # 前端应用
│   ├── src/
│   │   ├── views/        # 页面组件
│   │   ├── components/   # 通用组件
│   │   ├── router/       # 路由配置
│   │   ├── store/        # 状态管理
│   │   ├── api/          # API接口
│   │   └── utils/        # 工具函数
│   └── package.json
├── database/             # 数据库文件
└── package.json          # 根配置

功能特性

已实现功能

1. 用户认证系统

   • 用户注册（第一个注册的为超级管理员）
   • 用户登录（JWT token认证）
   • 用户信息获取

2. 项目管理

   • 上传单个HTML文件或ZIP压缩包
   • 项目列表展示（网格布局）
   • 项目筛选（分类、标签）
   • 项目搜索
   • 项目详情查看
   • 项目删除（仅创建者或管理员）

3. 文件管理

   • 附件上传和下载
   • Markdown文档上传和查看
   • 静态资源服务

4. 预览功能

   • iframe沙盒预览
   • 项目信息抽屉
   • 文档查看器

5. 系统设置

   • 允许/禁止注册
   • 允许/禁止上传
   • 仅超级管理员可修改

6. 安全措施

   • 文件类型验证
   • 文件大小限制
   • 路径遍历防护
   • XSS防护（CSP头）
   • JWT认证
   • 密码加密（bcrypt）
   • 权限验证

API端点

认证

• POST /api/auth/register - 注册
• POST /api/auth/login - 登录
• POST /api/auth/logout - 登出
• GET /api/auth/me - 获取当前用户信息

项目

• GET /api/projects - 获取项目列表
• GET /api/projects/:id - 获取项目详情
• POST /api/projects - 上传项目（需要登录）
• DELETE /api/projects/:id - 删除项目（需要登录）
• GET /api/projects/:id/preview - 预览项目

文件

• GET /api/files/:projectId/* - 获取项目文件
• GET /api/files/attachment/:id - 下载附件
• GET /api/files/document/:id - 获取文档

设置

• GET /api/settings - 获取所有设置（需要管理员权限）
• PUT /api/settings/:key - 更新设置（需要超级管理员权限）

数据库表结构

• users - 用户表
• projects - 项目表
• attachments - 附件表
• documents - 文档表
• settings - 设置表

注意事项

1. 首次注册的用户自动成为超级管理员
2. 上传的文件存储在 backend/uploads/ 目录
3. 数据库文件存储在 database/ 目录
4. 生产环境请修改 backend/src/config/config.ts 中的 jwtSecret
5. 文件大小限制：单个HTML文件10MB，ZIP文件50MB

开发说明

• 后端使用 TypeScript + Koa3
• 前端使用 TypeScript + Vue3 + Vite
• 数据库使用 SQLite + Knex.js
• 包管理使用 pnpm