Spaces:
Running
Running
| # 网页PPT后端系统需求文档 | |
| ## 项目概述 | |
| 本项目为网页PPT前端系统配套的后端服务，主要功能包括用户认证、PPT数据管理、分享功能、历史记录管理等。系统设计为部署在Hugging Face Space上，使用Docker容器化部署。 | |
| ## 技术架构 | |
| ### 部署环境 | |
| - **平台**: Hugging Face Space | |
| - **容器化**: Docker | |
| - **运行时**: Node.js 18 Alpine | |
| - **端口**: 7860 | |
| ### 技术栈 | |
| - **后端框架**: Express.js + TypeScript | |
| - **数据存储**: | |
| - 临时数据库：内存存储（最大12GB） | |
| - 永久数据库：GitHub仓库 | |
| - **图片处理**: Sharp | |
| - **定时任务**: node-cron | |
| - **安全**: Helmet, bcryptjs, express-rate-limit | |
| ## 功能需求 | |
| ### 1. 用户认证系统 | |
| #### 1.1 内置账户 | |
| 系统不支持公开注册，仅提供4个预配置账户： | |
| | 用户名 | 密码 | 角色 | | |
| |--------|------|------| | |
| | PS01 | admin_cybercity2025 | admin | | |
| | PS02 | cybercity2025 | user | | |
| | PS03 | cybercity2025 | user | | |
| | PS04 | cybercity2025 | user | | |
| #### 1.2 认证功能 | |
| - JWT token认证 | |
| - 登录失败锁定机制（5次失败锁定30分钟） | |
| - 密码加密存储（bcrypt） | |
| - 会话管理 | |
| ### 2. 数据存储架构 | |
| #### 2.1 临时数据库（内存） | |
| - **存储介质**: Hugging Face Space内存 | |
| - **容量限制**: 最大12GB | |
| - **数据类型**: | |
| - 用户信息 | |
| - PPT编辑数据 | |
| - 导出的PPT页面截图 | |
| - 分享链接数据 | |
| - **自动保存**: 每10分钟自动保存修改的数据 | |
| #### 2.2 永久数据库（GitHub） | |
| - **存储介质**: GitHub仓库 | |
| - **同步策略**: 每天03:00自动同步修改的数据 | |
| - **配置方式**: Space环境变量 | |
| - `GITHUB_TOKEN`: GitHub访问令牌 | |
| - `GITHUB_REPO`: 仓库地址（格式：owner/repo） | |
| - **数据恢复**: Space重启时自动从GitHub同步数据 | |
| #### 2.3 数据同步规则 | |
| - **增量同步**: 仅同步修改的数据，未修改数据不同步 | |
| - **容量控制**: 同步数据量超过7GB时，仅同步最近的数据 | |
| - **按需加载**: 用户访问早期数据时，临时从GitHub拉取 | |
| ### 3. PPT分享功能 | |
| #### 3.1 分享机制 | |
| - 在前端PPT页面缩略图上添加分享按钮 | |
| - 点击按钮调用前端导出图片功能 | |
| - 导出JPEG格式截图 | |
| - 保存到内存临时数据库 | |
| - 生成永久唯一公网链接 | |
| #### 3.2 链接管理 | |
| - 链接是长期有效并且唯一的 | |
| - 链接格式：`/api/sharelink/{PPT的slideID}` | |
| - 外网可通过链接直接访问图片 | |
| - 如果ppt修改，保存后将自动更新图片并按同样的流程上传内存数据库替换旧图片，外界通过这个链接读取更新的图片 | |
| - 访问日志记录 | |
| #### 3.3 自动更新 | |
| - PPT页面修改后，用户保存数据时自动重新生成截图 | |
| - 覆盖内存中的原截图 | |
| - 公网链接保持不变 | |
| - 外网访问获得更新后的页面 | |
| ### 4. 历史PPT管理 | |
| #### 4.1 管理界面 | |
| - 前端页面顶部添加历史PPT管理按钮 | |
| - 弹出历史PPT管理界面 | |
| - 支持分页显示（默认20条/页） | |
| - 支持搜索和筛选功能 | |
| #### 4.2 数据加载策略 | |
| - 优先从内存数据库读取 | |
| - 内存中不存在需要的数据再从GitHub仓库拉取，这部分数据编辑后保存自动同步回内存数据库 | |
| - 支持按需加载早期数据 | |
| - 提供加载状态指示 | |
| #### 4.3 管理功能 | |
| - 查看PPT列表 | |
| - 打开历史PPT | |
| - 复制PPT | |
| - 删除PPT | |
| - 导出PPT | |
| ### 5. API接口设计 | |
| #### 5.1 认证接口 | |
| ``` | |
| POST /api/auth/login # 用户登录 | |
| GET /api/auth/verify # 验证token | |
| POST /api/auth/logout # 用户登出 | |
| GET /api/auth/me # 获取用户信息 | |
| ``` | |
| #### 5.2 PPT管理接口 | |
| ``` | |
| POST /api/ppt/save # 保存PPT | |
| PUT /api/ppt/:id # 更新PPT | |
| GET /api/ppt/:id # 获取PPT详情 | |
| DELETE /api/ppt/:id # 删除PPT | |
| GET /api/ppt # 获取PPT列表 | |
| POST /api/ppt/:id/copy # 复制PPT | |
| ``` | |
| #### 5.3 分享接口 | |
| ``` | |
| POST /api/share/slide # 分享幻灯片 | |
| GET /api/share/view/:shareId # 查看分享截图 | |
| GET /api/share/info/:shareId # 获取分享信息 | |
| GET /api/share/my-shares # 获取我的分享 | |
| DELETE /api/share/:shareId # 删除分享 | |
| ``` | |
| #### 5.4 历史管理接口 | |
| ``` | |
| GET /api/history/ppts # 获取历史PPT列表 | |
| GET /api/history/ppts/:id/from-github # 从GitHub获取PPT | |
| POST /api/history/search # 搜索历史PPT | |
| GET /api/history/stats # 获取统计信息 | |
| ``` | |
| ### 6. 安全要求 | |
| #### 6.1 认证安全 | |
| - JWT token过期时间：24小时 | |
| - 密码加密：bcrypt（12轮） | |
| - 登录失败锁定：5次失败锁定30分钟 | |
| #### 6.2 API安全 | |
| - 请求频率限制：100请求/15分钟 | |
| - CORS配置 | |
| - Helmet安全头 | |
| - 输入验证和清理 | |
| #### 6.3 数据安全 | |
| - 用户数据隔离 | |
| - 敏感信息不记录日志 | |
| - GitHub token安全存储 | |
| ### 7. 性能要求 | |
| #### 7.1 响应时间 | |
| - API响应时间 < 500ms | |
| - 图片加载时间 < 2s | |
| - PPT列表加载 < 1s | |
| #### 7.2 并发处理 | |
| - 支持同时100个用户在线 | |
| - 数据库操作异步处理 | |
| - 图片压缩优化 | |
| #### 7.3 内存管理 | |
| - 内存使用监控 | |
| - 自动清理过期数据 | |
| - 数据压缩存储 | |
| ### 8. 监控和日志 | |
| #### 8.1 日志记录 | |
| - 用户操作日志 | |
| - 系统错误日志 | |
| - 性能监控日志 | |
| - GitHub同步日志 | |
| #### 8.2 健康检查 | |
| - 服务健康状态检查 | |
| - 数据库连接状态 | |
| - GitHub连接状态 | |
| - 内存使用情况 | |
| ### 9. 部署配置 | |
| #### 9.1 环境变量 | |
| ```bash | |
| # 基础配置 | |
| PORT=5000 | |
| NODE_ENV=production | |
| # GitHub配置 | |
| GITHUB_TOKEN=your-github-token | |
| GITHUB_REPO=owner/repo-name | |
| GITHUB_BRANCH=main | |
| # 可选配置 | |
| MAX_MEMORY_GB=7 | |
| AUTO_SAVE_INTERVAL=10 | |
| SYNC_HOUR=0 | |
| ``` | |
| #### 9.2 Docker配置 | |
| - 基础镜像：node:18-alpine | |
| - 工作目录：/app | |
| - 数据目录：/app/data | |
| - 健康检查：GET /health | |
| ### 10. 维护和扩展 | |
| #### 10.1 数据备份 | |
| - 自动GitHub同步 | |
| - 手动备份功能 | |
| - 数据恢复机制 | |
| #### 10.2 系统维护 | |
| - 日志轮转 | |
| - 内存清理 | |
| - 性能优化 | |
| #### 10.3 功能扩展 | |
| - 支持更多用户 | |
| - 增加协作功能 | |
| - 优化存储策略 | |
| ## 项目结构 | |
| ``` | |
| backend/ | |
| ├── src/ | |
| │ ├── config/ # 配置文件 | |
| │ ├── middleware/ # 中间件 | |
| │ ├── routes/ # 路由 | |
| │ ├── services/ # 服务层 | |
| │ ├── types/ # 类型定义 | |
| │ ├── utils/ # 工具函数 | |
| │ └── index.ts # 入口文件 | |
| ├── data/ # 数据目录 | |
| ├── Dockerfile # Docker配置 | |
| ├── package.json # 依赖配置 | |
| ├── tsconfig.json # TypeScript配置 | |
| └── requirements.md # 需求文档 | |
| ``` | |
| ## 开发和测试 | |
| ### 开发环境 | |
| ```bash | |
| npm install | |
| npm run dev | |
| ``` | |
| ### 生产构建 | |
| ```bash | |
| npm run build | |
| npm start | |
| ``` | |
| ### 测试 | |
| ```bash | |
| npm test | |
| ``` | |
| ## 总结 | |
| 本后端系统为网页PPT应用提供完整的数据管理、用户认证、分享功能和历史记录管理。通过内存+GitHub的双重存储策略，确保数据的可靠性和访问性能。系统设计考虑了Hugging Face Space的特点和限制，提供了完整的解决方案。 |