From 4919bc6194b6815a87ab5759f234358712ea5843 Mon Sep 17 00:00:00 2001 From: Jiao77 Date: Tue, 21 Oct 2025 01:44:01 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=90=8E=E7=AB=AFtodo-list?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/DETAILED_TODOLIST.md | 791 +++++++++++++++++++ docs/SINGLE_VPS_DEPLOYMENT_PLAN.md | 1145 ++++++++++++++++++++++++++++ docs/WEBSITE_MODERNIZATION_PLAN.md | 681 +++++++++++++++++ 3 files changed, 2617 insertions(+) create mode 100644 docs/DETAILED_TODOLIST.md create mode 100644 docs/SINGLE_VPS_DEPLOYMENT_PLAN.md create mode 100644 docs/WEBSITE_MODERNIZATION_PLAN.md diff --git a/docs/DETAILED_TODOLIST.md b/docs/DETAILED_TODOLIST.md new file mode 100644 index 0000000..a77f14b --- /dev/null +++ b/docs/DETAILED_TODOLIST.md @@ -0,0 +1,791 @@ +# 🚀 网站现代化重构 - 详尽 TodoList + +**项目周期**：4-6 周 | **总任务数**：87 项 | **优先级分布**：P0(22) | P1(35) | P2(20) | P3(10) + +--- + +## 📋 任务约定 + +- 🔴 **P0 - 必须**：项目核心，必须完成 +- 🟠 **P1 - 重要**：功能完整性，应该完成 +- 🟡 **P2 - 优化**：用户体验，可选完成 +- 🟢 **P3 - 未来**：后续功能，后期实现 + +**状态说明**： +- ⬜ `not-started` - 未开始 +- 🟦 `in-progress` - 进行中 +- ✅ `completed` - 已完成 + +--- + +## 🎯 第一阶段：环境准备 & 项目规划（第 1 周） + +### 🔴 P0 任务：项目初始化 + +#### 1.1 后端项目创建 +- [ ] 创建 `/backend` 目录结构 + ``` + backend/ + ├── src/ + │ ├── server.ts + │ ├── config/ + │ ├── routes/ + │ ├── controllers/ + │ ├── middleware/ + │ ├── database/ + │ └── types/ + ├── tests/ + ├── .env.example + ├── package.json + └── tsconfig.json + ``` +- [ ] 初始化 Node.js 项目：`npm init -y` +- [ ] 安装基础依赖：`npm install express cors dotenv pg` +- [ ] 安装开发依赖：`npm install -D typescript @types/node @types/express ts-node nodemon` +- [ ] 创建 `.env` 和 `.env.example` 文件 +- [ ] 创建 `tsconfig.json` 配置文件 +- [ ] 创建 `package.json` 脚本配置 + +#### 1.2 前端项目升级 +- [ ] 升级 Astro 到最新版本：`npm install astro@latest` +- [ ] 安装 React 集成：`npm install @astrojs/react react react-dom` +- [ ] 安装 API 相关依赖：`npm install axios zod isomorphic-dompurify` +- [ ] 验证项目能正常构建 + +#### 1.3 数据库规划 +- [ ] 创建数据库初始化脚本目录 `backend/sql/` +- [ ] 制定数据库连接策略 +- [ ] 准备 PostgreSQL 本地开发环境 +- [ ] 创建数据库连接池配置 + +### 🟠 P1 任务：文档编写 + +#### 1.4 API 文档 +- [ ] 编写完整的 API 规范文档 +- [ ] 定义评论 API 端点 +- [ ] 定义统计 API 端点 +- [ ] 定义用户 API 端点 +- [ ] 定义错误响应格式 + +#### 1.5 架构文档 +- [ ] 绘制系统架构图 +- [ ] 编写数据流说明 +- [ ] 列出安全考虑点 +- [ ] 记录性能优化策略 + +### 🟡 P2 任务：设计文档 + +#### 1.6 UI/UX 设计 +- [ ] 设计评论区域样式 +- [ ] 设计统计卡片样式 +- [ ] 制定色系和排版规范 +- [ ] 创建组件设计稿 + +--- + +## 🎯 第二阶段：后端开发（第 2-3 周） + +### 🔴 P0 任务：核心基础设施 + +#### 2.1 Server 启动和基础配置 +- [ ] 创建 `src/server.ts` 主文件 +- [ ] 配置 Express 应用基础 +- [ ] 配置 CORS 中间件 +- [ ] 配置 JSON 解析中间件 +- [ ] 实现环境变量加载 +- [ ] 设置错误处理中间件 +- [ ] 实现 404 路由处理 +- [ ] 测试服务器启动成功 + +#### 2.2 数据库连接 +- [ ] 创建 `src/database/connection.ts` +- [ ] 配置 PostgreSQL 连接池 +- [ ] 实现连接错误处理 +- [ ] 实现连接超时处理 +- [ ] 添加连接测试函数 +- [ ] 验证连接可用性 + +#### 2.3 数据库 Schema +- [ ] 创建 `backend/sql/001_init_schema.sql` +- [ ] 定义 `comments` 表 + ```sql + - id: SERIAL PRIMARY KEY + - report_id: VARCHAR(100) + - author: VARCHAR(100) + - email: VARCHAR(100) + - content: TEXT + - status: VARCHAR(20) + - created_at: TIMESTAMP + - updated_at: TIMESTAMP + ``` +- [ ] 定义 `report_stats` 表 + ```sql + - id: SERIAL PRIMARY KEY + - report_id: VARCHAR(100) UNIQUE + - views: INTEGER + - comments: INTEGER + - likes: INTEGER + - shares: INTEGER + ``` +- [ ] 定义 `likes` 表 + ```sql + - id: SERIAL PRIMARY KEY + - report_id: VARCHAR(100) + - client_id: VARCHAR(100) + - created_at: TIMESTAMP + ``` +- [ ] 创建必要的索引 + - `idx_comments_report_id` + - `idx_stats_report_id` + - `idx_likes_report_id` +- [ ] 创建 `backend/sql/002_add_constraints.sql` (外键约束) +- [ ] 创建迁移脚本运行器 + +#### 2.4 TypeScript 类型定义 +- [ ] 创建 `src/types/comment.ts` +- [ ] 创建 `src/types/stats.ts` +- [ ] 创建 `src/types/like.ts` +- [ ] 创建 `src/types/error.ts` +- [ ] 创建 `src/types/api-response.ts` + +### 🔴 P0 任务：评论系统 API + +#### 2.5 评论模块 - 路由层 +- [ ] 创建 `src/routes/comments.ts` +- [ ] `GET /api/comments` - 获取评论列表 + - [ ] 支持分页（page, limit） + - [ ] 支持排序（created_at, likes） + - [ ] 支持过滤（status, reportId） +- [ ] `GET /api/comments/:id` - 获取单条评论 +- [ ] `POST /api/comments` - 创建评论 +- [ ] `PUT /api/comments/:id` - 更新评论（仅作者或管理员） +- [ ] `DELETE /api/comments/:id` - 删除评论（仅作者或管理员） + +#### 2.6 评论模块 - 控制器层 +- [ ] 创建 `src/controllers/commentController.ts` +- [ ] 实现 `getAllComments()` 逻辑 +- [ ] 实现 `getCommentById()` 逻辑 +- [ ] 实现 `createComment()` 逻辑 +- [ ] 实现 `updateComment()` 逻辑 +- [ ] 实现 `deleteComment()` 逻辑 +- [ ] 添加数据验证逻辑 +- [ ] 添加错误处理 + +#### 2.7 评论模块 - 数据库层 +- [ ] 创建 `src/database/commentQueries.ts` +- [ ] 实现 `fetchCommentsByReport()` +- [ ] 实现 `fetchCommentById()` +- [ ] 实现 `insertComment()` +- [ ] 实现 `updateComment()` +- [ ] 实现 `deleteComment()` +- [ ] 实现 `countCommentsByReport()` +- [ ] 添加事务处理 + +### 🔴 P0 任务：统计系统 API + +#### 2.8 统计模块 - 路由层 +- [ ] 创建 `src/routes/stats.ts` +- [ ] `GET /api/stats/:reportId` - 获取统计数据 +- [ ] `POST /api/stats/:reportId/view` - 记录浏览 +- [ ] `POST /api/stats/:reportId/like` - 点赞 +- [ ] `DELETE /api/stats/:reportId/like` - 取消点赞 +- [ ] `POST /api/stats/:reportId/share` - 记录分享 +- [ ] `GET /api/stats/trending` - 获取热门 + +#### 2.9 统计模块 - 控制器层 +- [ ] 创建 `src/controllers/statsController.ts` +- [ ] 实现 `getStats()` 逻辑 +- [ ] 实现 `recordView()` 逻辑 +- [ ] 实现 `recordLike()` 逻辑 +- [ ] 实现 `removeLike()` 逻辑 +- [ ] 实现 `recordShare()` 逻辑 +- [ ] 实现 `getTrending()` 逻辑 +- [ ] 添加重复检查 + +#### 2.10 统计模块 - 数据库层 +- [ ] 创建 `src/database/statsQueries.ts` +- [ ] 实现 `fetchStats()` +- [ ] 实现 `updateViews()` +- [ ] 实现 `addLike()` +- [ ] 实现 `removeLike()` +- [ ] 实现 `checkLikeExists()` +- [ ] 实现 `updateShares()` +- [ ] 实现 `fetchTrending()` + +### 🟠 P1 任务：中间件和工具 + +#### 2.11 验证中间件 +- [ ] 创建 `src/middleware/validation.ts` +- [ ] 实现评论数据验证 (Zod schema) +- [ ] 实现统计数据验证 +- [ ] 实现错误转换中间件 +- [ ] 添加日志中间件 + +#### 2.12 安全中间件 +- [ ] 创建 `src/middleware/security.ts` +- [ ] 实现速率限制（express-rate-limit） +- [ ] 实现 CSRF 保护 +- [ ] 实现 XSS 防护 (DOMPurify) +- [ ] 实现输入清理函数 + +#### 2.13 认证中间件（可选基础） +- [ ] 创建 `src/middleware/auth.ts` +- [ ] 实现 JWT 验证（预留） +- [ ] 实现权限检查函数 +- [ ] 实现管理员标识 + +### 🟡 P2 任务：辅助功能 + +#### 2.14 工具函数 +- [ ] 创建 `src/utils/helpers.ts` +- [ ] 实现分页计算函数 +- [ ] 实现日期格式化 +- [ ] 实现 ID 生成器 +- [ ] 实现数据转换函数 + +#### 2.15 缓存策略 +- [ ] 创建 `src/cache/cacheManager.ts`（预留 Redis） +- [ ] 实现内存缓存方案 +- [ ] 实现缓存失效策略 +- [ ] 实现缓存预热 + +#### 2.16 日志系统 +- [ ] 创建 `src/logger/logger.ts` +- [ ] 配置日志级别 +- [ ] 实现日志文件轮转 +- [ ] 实现错误日志记录 + +--- + +## 🎯 第三阶段：前端开发（第 3-4 周） + +### 🔴 P0 任务：Astro 混合渲染配置 + +#### 3.1 更新 Astro 配置 +- [ ] 修改 `astro.config.mjs` 启用混合渲染 + ```javascript + output: 'hybrid' + adapter: node({ mode: 'standalone' }) + ``` +- [ ] 配置 React 集成 +- [ ] 验证混合渲染配置正确 +- [ ] 测试静态和动态页面生成 + +#### 3.2 创建 API 客户端 +- [ ] 创建 `src/lib/api-client.ts` +- [ ] 实现 HTTP 请求拦截器 +- [ ] 实现错误处理 +- [ ] 实现请求重试逻辑 +- [ ] 配置 API 基础 URL + +#### 3.3 创建 React 上下文（可选） +- [ ] 创建 `src/contexts/ReportContext.tsx` +- [ ] 实现统计数据共享 +- [ ] 实现用户状态管理 +- [ ] 实现通知管理 + +### 🔴 P0 任务：评论组件开发 + +#### 3.4 评论列表组件 +- [ ] 创建 `src/components/comments/CommentList.tsx` +- [ ] 实现分页显示 +- [ ] 实现排序切换 +- [ ] 实现加载状态 +- [ ] 实现空状态提示 +- [ ] 实现错误状态提示 + +#### 3.5 评论表单组件 +- [ ] 创建 `src/components/comments/CommentForm.tsx` +- [ ] 实现表单输入验证 +- [ ] 实现字符计数 +- [ ] 实现提交加载状态 +- [ ] 实现成功/失败提示 +- [ ] 实现防重复提交 + +#### 3.6 单条评论组件 +- [ ] 创建 `src/components/comments/CommentItem.tsx` +- [ ] 实现用户信息展示 +- [ ] 实现时间格式化 +- [ ] 实现评论内容渲染（XSS 防护） +- [ ] 实现编辑/删除按钮（权限检查） +- [ ] 实现回复按钮（预留） + +#### 3.7 完整评论区域组件 +- [ ] 创建 `src/components/comments/CommentSection.tsx` +- [ ] 组合 List、Form、Item 组件 +- [ ] 实现数据获取逻辑 +- [ ] 实现实时更新 +- [ ] 实现错误边界 +- [ ] 实现加载骨架屏 + +### 🔴 P0 任务：统计组件开发 + +#### 3.8 统计卡片组件 +- [ ] 创建 `src/components/stats/StatCard.tsx` +- [ ] 实现数字动画展示 +- [ ] 实现图标展示 +- [ ] 实现趋势指示 +- [ ] 实现加载状态 + +#### 3.9 统计面板组件 +- [ ] 创建 `src/components/stats/StatsPanel.tsx` +- [ ] 组合多个 StatCard +- [ ] 实现数据获取 +- [ ] 实现自动刷新 +- [ ] 实现响应式布局 + +#### 3.10 点赞按钮组件 +- [ ] 创建 `src/components/interactions/LikeButton.tsx` +- [ ] 实现点赞/取消点赞逻辑 +- [ ] 实现动画效果 +- [ ] 实现重复点赞防护 +- [ ] 实现点赞数显示 + +#### 3.11 分享按钮组件 +- [ ] 创建 `src/components/interactions/ShareButton.tsx` +- [ ] 实现复制链接功能 +- [ ] 实现社交分享（可选） +- [ ] 实现分享统计 +- [ ] 实现分享提示 + +### 🟠 P1 任务：页面集成 + +#### 3.12 报告页面更新 +- [ ] 修改 `src/pages/report/ai-eda-paper-report/index.astro` +- [ ] 导入统计组件 +- [ ] 导入评论组件 +- [ ] 添加统计展示区域 +- [ ] 添加评论区域 +- [ ] 实现客户端加载指令 + +#### 3.13 其他报告页面 +- [ ] 为其他报告页面添加统计功能 +- [ ] 为其他报告页面添加评论功能 +- [ ] 统一样式风格 +- [ ] 验证功能一致性 + +### 🟡 P2 任务：交互优化 + +#### 3.14 加载状态 +- [ ] 创建 `src/components/common/Skeleton.tsx` (骨架屏) +- [ ] 创建 `src/components/common/LoadingSpinner.tsx` +- [ ] 创建 `src/components/common/ErrorBoundary.tsx` +- [ ] 应用到所有异步组件 + +#### 3.15 通知系统 +- [ ] 创建 `src/components/common/Toast.tsx` +- [ ] 实现成功提示 +- [ ] 实现错误提示 +- [ ] 实现警告提示 +- [ ] 实现通知队列 + +#### 3.16 动画效果 +- [ ] 实现数字动画库集成（可选） +- [ ] 添加评论出现动画 +- [ ] 添加统计数字动画 +- [ ] 添加过渡效果 + +--- + +## 🎯 第四阶段：集成与测试（第 4 周） + +### 🔴 P0 任务：后端测试 + +#### 4.1 单元测试 +- [ ] 安装测试框架：`npm install -D jest @types/jest ts-jest` +- [ ] 创建 `backend/tests/` 目录 +- [ ] 编写评论 API 单元测试 + - [ ] 测试 GET /api/comments + - [ ] 测试 POST /api/comments + - [ ] 测试数据验证 + - [ ] 测试错误处理 +- [ ] 编写统计 API 单元测试 + - [ ] 测试 GET /api/stats/:reportId + - [ ] 测试 POST /api/stats/:reportId/view + - [ ] 测试 POST /api/stats/:reportId/like +- [ ] 运行测试，确保覆盖率 > 80% + +#### 4.2 集成测试 +- [ ] 创建测试数据库配置 +- [ ] 编写评论完整流程测试 +- [ ] 编写统计完整流程测试 +- [ ] 编写并发场景测试 +- [ ] 验证所有 API 端点 + +#### 4.3 API 文档测试 +- [ ] 使用 Postman/Insomnia 测试所有端点 +- [ ] 验证请求/响应格式 +- [ ] 验证错误响应 +- [ ] 记录实际的 API 示例 + +### 🔴 P0 任务：前端测试 + +#### 4.4 组件测试 +- [ ] 安装测试库：`npm install -D vitest @testing-library/react` +- [ ] 编写 CommentForm 测试 + - [ ] 测试表单提交 + - [ ] 测试验证逻辑 + - [ ] 测试错误显示 +- [ ] 编写 StatsPanel 测试 + - [ ] 测试数据加载 + - [ ] 测试数据展示 +- [ ] 编写 LikeButton 测试 + - [ ] 测试点赞逻辑 + - [ ] 测试防重复点赞 + +#### 4.5 集成测试 +- [ ] 测试 Astro 页面 + React 组件集成 +- [ ] 测试客户端加载指令 +- [ ] 测试数据流 +- [ ] 测试错误恢复 + +### 🟠 P1 任务：E2E 测试 + +#### 4.6 用户场景测试 +- [ ] 安装 E2E 框架：`npm install -D playwright` +- [ ] 测试查看报告流程 +- [ ] 测试发布评论流程 +- [ ] 测试点赞流程 +- [ ] 测试分享流程 +- [ ] 测试移动端响应 + +#### 4.7 性能测试 +- [ ] 测试页面加载时间 +- [ ] 测试 API 响应时间 +- [ ] 测试并发用户压力 +- [ ] 记录性能基线 + +### 🟡 P2 任务：安全测试 + +#### 4.8 安全审查 +- [ ] 审查 XSS 防护 +- [ ] 审查 SQL 注入防护 +- [ ] 审查认证逻辑 +- [ ] 审查 CORS 配置 +- [ ] 测试速率限制 + +--- + +## 🎯 第五阶段：部署与优化（第 5 周） + +### 🔴 P0 任务：Docker 配置 + +#### 5.1 后端 Docker 化 +- [ ] 创建 `Dockerfile` +- [ ] 创建 `.dockerignore` +- [ ] 定义构建阶段 +- [ ] 定义运行阶段 +- [ ] 优化镜像大小 +- [ ] 本地测试 Docker 镜像 + +#### 5.2 前端 Docker 化 +- [ ] 为前端创建 `Dockerfile` +- [ ] 多阶段构建 +- [ ] 静态文件优化 +- [ ] 本地测试 + +#### 5.3 Docker Compose +- [ ] 创建 `docker-compose.yml` +- [ ] 配置后端服务 +- [ ] 配置前端服务 +- [ ] 配置数据库服务 +- [ ] 配置网络 +- [ ] 测试本地完整运行 + +#### 5.4 数据库容器 +- [ ] 配置 PostgreSQL 容器 +- [ ] 持久化数据卷 +- [ ] 初始化脚本 +- [ ] 备份策略 + +### 🔴 P0 任务：环境配置 + +#### 5.5 生产环境变量 +- [ ] 创建 `.env.production` +- [ ] 配置数据库 URL +- [ ] 配置 API 基础 URL +- [ ] 配置日志级别 +- [ ] 配置 CORS 源 +- [ ] 配置密钥 + +#### 5.6 环境管理 +- [ ] 创建环境配置管理器 +- [ ] 验证必需变量 +- [ ] 文档化所有变量 + +### 🟠 P1 任务：部署配置 + +#### 5.7 Nginx 反向代理 +- [ ] 创建 `nginx.conf` +- [ ] 配置前端路由 +- [ ] 配置后端 API 反向代理 +- [ ] 配置 Gzip 压缩 +- [ ] 配置缓存策略 +- [ ] 配置 SSL（可选） + +#### 5.8 PM2 进程管理 +- [ ] 创建 `ecosystem.config.js` +- [ ] 配置后端进程 +- [ ] 配置前端构建进程 +- [ ] 实现自动重启 +- [ ] 配置日志轮转 + +#### 5.9 部署脚本 +- [ ] 创建 `deploy.sh` 脚本 +- [ ] 拉取最新代码 +- [ ] 安装依赖 +- [ ] 构建项目 +- [ ] 运行数据库迁移 +- [ ] 重启服务 +- [ ] 健康检查 + +### 🟠 P1 任务：性能优化 + +#### 5.10 数据库优化 +- [ ] 分析查询性能 +- [ ] 添加必要的索引 +- [ ] 优化 N+1 查询 +- [ ] 实现查询缓存 +- [ ] 监控连接池 + +#### 5.11 API 优化 +- [ ] 实现 API 分页 +- [ ] 实现字段选择（select） +- [ ] 实现 API 压缩 +- [ ] 实现响应缓存 +- [ ] 实现 CDN 集成 + +#### 5.12 前端优化 +- [ ] 代码分割优化 +- [ ] 图片优化 +- [ ] 字体加载优化 +- [ ] 缓存策略 +- [ ] 预加载/预连接 + +### 🟡 P2 任务：监控与日志 + +#### 5.13 应用监控 +- [ ] 配置应用性能监控 (APM) +- [ ] 配置错误追踪 +- [ ] 配置日志聚合 +- [ ] 设置告警规则 + +#### 5.14 基础设施监控 +- [ ] 配置 CPU 监控 +- [ ] 配置内存监控 +- [ ] 配置磁盘监控 +- [ ] 配置网络监控 + +--- + +## 🎯 第六阶段：上线与维护（第 6 周） + +### 🔴 P0 任务：上线前准备 + +#### 6.1 最终检查清单 +- [ ] 所有测试通过 +- [ ] 代码审查完成 +- [ ] 文档完整 +- [ ] 安全审计通过 +- [ ] 性能测试通过 +- [ ] 备份策略就位 +- [ ] 回滚计划准备 + +#### 6.2 数据迁移 +- [ ] 备份现有数据 +- [ ] 准备数据迁移脚本 +- [ ] 测试数据迁移 +- [ ] 准备回滚方案 + +#### 6.3 DNS 配置 +- [ ] 配置域名解析 +- [ ] 配置 SSL 证书 +- [ ] 测试 HTTPS 连接 +- [ ] 配置 CDN（可选） + +### 🟠 P1 任务：灰度发布 + +#### 6.4 金丝雀发布 +- [ ] 发布到测试服务器 +- [ ] 在小部分用户中测试 +- [ ] 监控错误率 +- [ ] 逐步增加流量 +- [ ] 完整上线 + +#### 6.5 发布公告 +- [ ] 准备发布说明 +- [ ] 通知用户新功能 +- [ ] 准备常见问题解答 +- [ ] 监控用户反馈 + +### 🟠 P1 任务：上线后维护 + +#### 6.6 监控第一周 +- [ ] 日常监控指标 +- [ ] 应对用户反馈 +- [ ] 快速修复 bug +- [ ] 记录问题和解决方案 + +#### 6.7 长期维护计划 +- [ ] 建立定期备份 +- [ ] 定期安全更新 +- [ ] 定期依赖更新 +- [ ] 性能优化迭代 + +### 🟡 P2 任务：用户支持 + +#### 6.8 文档完善 +- [ ] 完善用户指南 +- [ ] 编写 FAQ +- [ ] 编写故障排查指南 +- [ ] 建立反馈渠道 + +#### 6.9 持续改进 +- [ ] 收集用户反馈 +- [ ] 分析使用数据 +- [ ] 规划功能迭代 +- [ ] 优化用户体验 + +--- + +## 🎯 可选增强功能（P3 任务） + +### 🟢 P3：用户系统 + +#### 7.1 用户认证 +- [ ] 实现用户注册 +- [ ] 实现用户登录 +- [ ] 实现密码重置 +- [ ] 实现社交登录 + +#### 7.2 用户资料 +- [ ] 用户头像上传 +- [ ] 用户信息编辑 +- [ ] 用户偏好设置 +- [ ] 用户隐私控制 + +### 🟢 P3：高级评论功能 + +#### 7.3 评论增强 +- [ ] 评论回复功能 +- [ ] 评论点赞功能 +- [ ] 评论举报功能 +- [ ] 评论标签功能 +- [ ] 评论搜索功能 + +### 🟢 P3：AI 增强 + +#### 7.4 智能功能 +- [ ] 评论内容审核（AI） +- [ ] 自动回复建议 +- [ ] 评论总结 +- [ ] 智能分类 + +### 🟢 P3：社区功能 + +#### 7.5 社区建设 +- [ ] 排行榜系统 +- [ ] 徽章系统 +- [ ] 积分系统 +- [ ] 社区讨论区 +- [ ] 用户关注 + +### 🟢 P3：数据分析 + +#### 7.6 深度分析 +- [ ] 用户行为分析 +- [ ] 评论情感分析 +- [ ] 内容热力分析 +- [ ] 用户转化分析 + +--- + +## 📊 时间和资源预估 + +### 时间分配 +``` +第一周：环境和规划 - 40 小时 +第二周：后端开发 - 60 小时 +第三周：前端开发 - 60 小时 +第四周：测试和集成 - 50 小时 +第五周：部署和优化 - 50 小时 +第六周：上线和维护 - 40 小时 + +总计：约 300 小时 ≈ 7-8 周（单人开发） +``` + +### 资源需求 +- **开发者**：1-2 人（可并行） +- **测试**：可通过自动化完成 +- **运维**：1 人（兼职） +- **服务器**： + - VPS：¥30-50/月 + - 数据库：¥10-20/月 + - 存储：¥5-10/月 + +--- + +## 🎯 优先级执行策略 + +### 如果时间紧张（2 周完成） +**优先完成 P0 任务**： +1. 后端基础 + 数据库 +2. 评论和统计 API +3. 前端组件集成 +4. 基础部署 + +**跳过**： +- 完整测试 → 手动测试即可 +- 性能优化 → 后期迭代 +- 用户系统 → 第二期实现 + +### 正常周期（4-6 周） +**完成所有 P0 + P1 任务**： +- 完整功能实现 +- 充分测试 +- 完善文档 +- 生产级部署 + +### 完全版本（8-12 周） +**完成所有任务**： +- 包含所有 P2 优化 +- 包含 P3 高级功能 +- 完整的监控和维护体系 + +--- + +## 📝 检查清单模板 + +### 每周完成检查 +- [ ] 所有 P0 任务完成 +- [ ] 代码审查通过 +- [ ] 测试覆盖率 > 80% +- [ ] 文档更新 +- [ ] 部署到测试环境 +- [ ] 演示给利益相关者 + +### 上线前最终检查 +- [ ] 所有单元测试通过 +- [ ] 所有集成测试通过 +- [ ] 所有 E2E 测试通过 +- [ ] 性能测试通过（<2s 加载） +- [ ] 安全审计通过 +- [ ] 备份和回滚计划准备好 +- [ ] 监控和告警配置完成 +- [ ] 团队培训完成 +- [ ] 用户文档完备 +- [ ] 发布公告准备好 + +--- + +## 🚀 下一步行动 + +现在可以开始执行这个 TodoList： + +1. **立即开始**：第一阶段任务（环境准备） +2. **并行进行**：后端和前端开发（第二、三阶段） +3. **定期检查**：每周检查进度和质量 +4. **灵活调整**：根据实际情况调整优先级 + +**建议**：建立一个项目管理工具（如 Trello、Notion、Linear）来追踪这些任务的进度。 + diff --git a/docs/SINGLE_VPS_DEPLOYMENT_PLAN.md b/docs/SINGLE_VPS_DEPLOYMENT_PLAN.md new file mode 100644 index 0000000..05130c0 --- /dev/null +++ b/docs/SINGLE_VPS_DEPLOYMENT_PLAN.md @@ -0,0 +1,1145 @@ +# 🚀 单机 VPS 部署方案 - 优化 TodoList + +**部署环境**：单机 VPS（公网 IP + 大带宽 + 100GB 存储） +**优化方向**：资源优化、单机部署、简化运维 +**项目周期**：4-5 周 | **总任务数**：72 项 | **优先级分布**：P0(20) | P1(30) | P2(15) | P3(7) + +--- + +## 📋 环境特点分析 + +### ✅ 优势 +- 单一公网 IP，简化网络配置 +- 大带宽支持高并发 +- 100GB 存储足够应用 + 数据库 + 备份 + +### ⚠️ 制约 +- 单机故障 = 全部服务宕机 +- 内存/CPU 有限（需要优化） +- 需要更严格的监控和备份 + +### 🎯 优化策略 +1. **容器精简** - 使用 Alpine 基础镜像 +2. **资源共享** - 数据库、应用、Web 服务器在同一机器 +3. **缓存优先** - Redis 缓存热数据 +4. **监控告警** - 及时发现问题 +5. **自动备份** - 防止数据丢失 + +--- + +## 🎯 第一阶段：环境准备与优化（第 1 周） + +### 🔴 P0 任务：VPS 环境初始化 + +#### 1.1 VPS 系统准备 +- [ ] SSH 连接 VPS，验证系统版本（建议 Ubuntu 20.04 LTS） +- [ ] 更新系统：`sudo apt update && apt upgrade -y` +- [ ] 安装基础工具：`sudo apt install -y curl wget git htop` +- [ ] 配置防火墙（UFW） + ```bash + sudo ufw enable + sudo ufw allow 22/tcp # SSH + sudo ufw allow 80/tcp # HTTP + sudo ufw allow 443/tcp # HTTPS + ``` +- [ ] 配置时区和 NTP +- [ ] 创建普通用户用于应用运行（非 root） + +#### 1.2 Docker 和 Docker Compose 安装 +- [ ] 安装 Docker：`curl -fsSL https://get.docker.com | sh` +- [ ] 配置 Docker 权限：添加用户到 docker 组 +- [ ] 安装 Docker Compose（最新版本） +- [ ] 验证 Docker 和 Compose 可用性 + +#### 1.3 域名和 SSL 配置 +- [ ] 配置域名 DNS 解析到公网 IP +- [ ] 申请 Let's Encrypt SSL 证书（使用 Certbot） +- [ ] 配置 SSL 证书自动续期 +- [ ] 测试 HTTPS 连接 + +#### 1.4 存储规划 +- [ ] 检查磁盘使用情况：`df -h` +- [ ] 规划存储分配（100GB） + ``` + 系统：20GB + 数据库：30GB + 应用：20GB + 备份：20GB + 日志：10GB + ``` +- [ ] 创建数据目录结构 + +### 🟠 P1 任务：后端项目创建 + +#### 1.5 创建后端项目 +- [ ] 在 VPS 上克隆项目：`git clone /home/app/backend` +- [ ] 创建 `/backend` 目录结构 + ``` + backend/ + ├── src/ + │ ├── server.ts + │ ├── config/ + │ ├── routes/ + │ ├── controllers/ + │ ├── middleware/ + │ ├── database/ + │ └── types/ + ├── docker/ + │ ├── Dockerfile + │ └── .dockerignore + ├── scripts/ + │ ├── db-init.sql + │ └── backup.sh + ├── package.json + ├── tsconfig.json + └── .env + ``` +- [ ] 本地初始化 Node.js 项目（npm init） +- [ ] 编写最小化 package.json（仅必需依赖） + +#### 1.6 依赖选择（针对单机优化） +- [ ] 后端依赖： + ```json + { + "express": "^4.18.2", + "pg": "^8.10.0", + "cors": "^2.8.5", + "dotenv": "^16.3.1", + "zod": "^3.22.4", + "pino": "^8.16.1" + } + ``` +- [ ] 开发依赖： + ```json + { + "typescript": "^5.2.2", + "ts-node": "^10.9.1", + "nodemon": "^3.0.1", + "@types/express": "^4.17.20", + "@types/node": "^20.8.0", + "jest": "^29.7.0", + "@types/jest": "^29.5.6" + } + ``` +- [ ] **移除不必要包**：@astrojs/node, 重量级 ORM 等 + +### 🟡 P2 任务：文档和规划 + +#### 1.7 部署文档编写 +- [ ] 编写 VPS 部署指南 +- [ ] 记录环境配置清单 +- [ ] 编写故障恢复流程 +- [ ] 编写备份和恢复步骤 + +--- + +## 🎯 第二阶段：后端开发（第 2 周） + +### 🔴 P0 任务：核心后端功能 + +#### 2.1 Server 基础配置（精简版） +- [ ] 创建 `src/server.ts` 主文件 +- [ ] 配置 Express 应用 + ```typescript + app.use(cors({ origin: process.env.FRONTEND_URL })); + app.use(express.json({ limit: '10mb' })); + app.use(compression()); // 启用 Gzip + ``` +- [ ] 配置错误处理中间件 +- [ ] 实现健康检查端点 `GET /health` +- [ ] 配置日志（使用 Pino，性能优于 Winston） + +#### 2.2 数据库配置（针对单机） +- [ ] 创建 PostgreSQL 容器配置 + ```yaml + postgres: + image: postgres:15-alpine # 使用 Alpine 减少镜像大小 + environment: + POSTGRES_DB: jiao77_db + POSTGRES_USER: app + POSTGRES_PASSWORD: ${DB_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + restart: always + ``` +- [ ] 创建连接池配置 + ```typescript + new Pool({ + max: 20, // 单机限制连接数 + idleTimeoutMillis: 30000, + connectionTimeoutMillis: 2000, + }) + ``` +- [ ] 实现连接池监控函数 + +#### 2.3 数据库 Schema（优化版） +- [ ] 创建 SQL 初始化脚本 + ```sql + -- 评论表（带分区考虑） + CREATE TABLE comments ( + id SERIAL PRIMARY KEY, + report_id VARCHAR(100) NOT NULL, + author VARCHAR(100) NOT NULL, + content TEXT NOT NULL CHECK (char_length(content) <= 5000), + status VARCHAR(20) DEFAULT 'pending', + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() + ); + + -- 索引优化 + CREATE INDEX CONCURRENTLY idx_comments_report_id + ON comments(report_id, created_at DESC); + CREATE INDEX CONCURRENTLY idx_comments_status + ON comments(status, created_at DESC); + + -- 统计表 + CREATE TABLE report_stats ( + id SERIAL PRIMARY KEY, + report_id VARCHAR(100) UNIQUE NOT NULL, + views INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + last_updated TIMESTAMP DEFAULT NOW() + ); + + -- 点赞表 + CREATE TABLE likes ( + id SERIAL PRIMARY KEY, + report_id VARCHAR(100) NOT NULL, + client_id VARCHAR(100) NOT NULL, + created_at TIMESTAMP DEFAULT NOW(), + UNIQUE(report_id, client_id) + ); + ``` +- [ ] 创建数据库初始化脚本 `scripts/db-init.sql` +- [ ] 准备数据库迁移工具（简单的 SQL 文件版本控制） + +#### 2.4 评论 API 实现（轻量级） +- [ ] `GET /api/comments?reportId=xxx&page=1&limit=20` - 分页获取 +- [ ] `POST /api/comments` - 创建评论（含速率限制） +- [ ] `DELETE /api/comments/:id` - 删除评论（仅作者或管理员） +- [ ] 实现数据验证（使用 Zod） +- [ ] 实现错误处理 + +#### 2.5 统计 API 实现（轻量级） +- [ ] `GET /api/stats/:reportId` - 获取统计数据（加缓存） +- [ ] `POST /api/stats/:reportId/view` - 记录浏览（批量处理） +- [ ] `POST /api/stats/:reportId/like` - 点赞 +- [ ] 实现请求去重（基于 IP + clientId） +- [ ] 实现缓存策略 + +#### 2.6 中间件实现（安全 + 性能） +- [ ] 速率限制中间件 + ```typescript + const rateLimit = require('express-rate-limit'); + const limiter = rateLimit({ + windowMs: 15 * 60 * 1000, // 15 分钟 + max: 100, // 单机限制请求数 + keyGenerator: (req) => req.ip, + skip: (req) => req.path === '/health' + }); + ``` +- [ ] 请求日志中间件（Pino） +- [ ] 数据验证中间件（Zod） +- [ ] 错误处理中间件 + +#### 2.7 本地测试 +- [ ] 运行 `npm run dev` 本地启动 +- [ ] 测试各个 API 端点 +- [ ] 测试数据库连接 +- [ ] 验证错误处理 + +### 🟠 P1 任务：后端测试 + +#### 2.8 单元测试（简化版） +- [ ] 编写 API 端点测试 +- [ ] 编写数据验证测试 +- [ ] 编写错误处理测试 +- [ ] 目标覆盖率 > 70%（单机优先功能质量） + +#### 2.9 集成测试 +- [ ] 测试完整的评论流程 +- [ ] 测试完整的统计流程 +- [ ] 测试异常场景 + +--- + +## 🎯 第三阶段：前端开发（第 2-3 周） + +### 🔴 P0 任务：前端集成 + +#### 3.1 Astro 混合渲染配置 +- [ ] 更新 `astro.config.mjs` + ```javascript + export default defineConfig({ + integrations: [react(), tailwind()], + output: 'hybrid', + adapter: node({ mode: 'standalone' }), + vite: { + ssr: { external: ['pg'] } + } + }); + ``` +- [ ] 本地测试混合渲染 + +#### 3.2 API 客户端库 +- [ ] 创建 `src/lib/api-client.ts` + ```typescript + const API_BASE = process.env.PUBLIC_API_URL || 'http://localhost:3000'; + + export async function fetchAPI( + path: string, + options?: RequestInit + ) { + const response = await fetch(`${API_BASE}${path}`, { + headers: { + 'Content-Type': 'application/json', + ...options?.headers, + }, + ...options, + }); + + if (!response.ok) { + throw new Error(`API Error: ${response.status}`); + } + return response.json(); + } + ``` +- [ ] 实现缓存策略 + +#### 3.3 React 组件开发（轻量级） +- [ ] 开发 `CommentSection` 组件 + ```typescript + export default function CommentSection({ + reportId + }: { + reportId: string + }) { + const [comments, setComments] = useState([]); + const [loading, setLoading] = useState(false); + + useEffect(() => { + setLoading(true); + fetchAPI(`/api/comments?reportId=${reportId}`) + .then(setComments) + .finally(() => setLoading(false)); + }, [reportId]); + + // ... 组件逻辑 + } + ``` +- [ ] 开发 `StatsPanel` 组件（简化版） + ```typescript + export default function StatsPanel({ reportId }: { reportId: string }) { + const [stats, setStats] = useState(null); + + useEffect(() => { + fetchAPI(`/api/stats/${reportId}`).then(setStats); + }, [reportId]); + + if (!stats) return ; + + return ( +
+ + + + +
+ ); + } + ``` +- [ ] 开发 `LikeButton` 组件 + +#### 3.4 页面集成 +- [ ] 在报告页面导入组件 +- [ ] 设置客户端加载指令 +- [ ] 样式适配 + +### 🟠 P1 任务：前端测试 + +#### 3.5 组件测试 +- [ ] 编写简单的组件测试（Vitest） +- [ ] 测试数据加载 +- [ ] 测试用户交互 + +--- + +## 🎯 第四阶段：单机容器化部署（第 3 周） + +### 🔴 P0 任务：Docker 化应用 + +#### 4.1 后端 Dockerfile（Alpine 优化） +- [ ] 创建 `backend/Dockerfile` + ```dockerfile + # 构建阶段 + FROM node:18-alpine AS builder + WORKDIR /app + COPY package*.json ./ + RUN npm ci --only=production && npm cache clean --force + + # 运行阶段 + FROM node:18-alpine + WORKDIR /app + RUN apk add --no-cache dumb-init + + COPY --from=builder /app/node_modules ./node_modules + COPY . . + + EXPOSE 3000 + ENTRYPOINT ["dumb-init", "--"] + CMD ["node", "dist/server.js"] + ``` +- [ ] 镜像大小目标：< 200MB + +#### 4.2 前端 Dockerfile（静态优化） +- [ ] 创建 `frontend/Dockerfile` + ```dockerfile + FROM node:18-alpine AS builder + WORKDIR /app + COPY package*.json ./ + RUN npm ci + COPY . . + RUN npm run build + + FROM node:18-alpine + WORKDIR /app + COPY --from=builder /app/dist ./dist + EXPOSE 3000 + CMD ["node", "./dist/server/entry.mjs"] + ``` + +#### 4.3 Docker Compose 配置（单机专用） +- [ ] 创建 `docker-compose.yml` + ```yaml + version: '3.8' + + services: + postgres: + image: postgres:15-alpine + container_name: jiao77_postgres + environment: + POSTGRES_DB: ${DB_NAME} + POSTGRES_USER: ${DB_USER} + POSTGRES_PASSWORD: ${DB_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + - ./scripts/db-init.sql:/docker-entrypoint-initdb.d/init.sql + restart: unless-stopped + # 资源限制 + deploy: + resources: + limits: + cpus: '1' + memory: 1G + reservations: + cpus: '0.5' + memory: 512M + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"] + interval: 10s + timeout: 5s + retries: 5 + + redis: + image: redis:7-alpine + container_name: jiao77_redis + restart: unless-stopped + deploy: + resources: + limits: + cpus: '0.5' + memory: 512M + volumes: + - redis_data:/data + + api: + build: + context: ./backend + dockerfile: Dockerfile + container_name: jiao77_api + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_started + environment: + NODE_ENV: production + DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME} + REDIS_URL: redis://redis:6379 + PORT: 3000 + ports: + - "3000:3000" + restart: unless-stopped + deploy: + resources: + limits: + cpus: '1' + memory: 1G + reservations: + cpus: '0.5' + memory: 512M + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3000/health"] + interval: 30s + timeout: 10s + retries: 3 + + web: + build: + context: ./frontend + dockerfile: Dockerfile + container_name: jiao77_web + depends_on: + - api + environment: + PUBLIC_API_URL: http://api:3000 + ports: + - "3001:3000" + restart: unless-stopped + deploy: + resources: + limits: + cpus: '0.5' + memory: 512M + + nginx: + image: nginx:alpine + container_name: jiao77_nginx + ports: + - "80:80" + - "443:443" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro + - ./ssl:/etc/nginx/ssl:ro + - nginx_cache:/var/cache/nginx + depends_on: + - web + - api + restart: unless-stopped + deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + + volumes: + postgres_data: + redis_data: + nginx_cache: + ``` +- [ ] 本地测试 Docker Compose + +#### 4.4 Nginx 配置（单机反向代理） +- [ ] 创建 `nginx.conf` + ```nginx + user nginx; + worker_processes auto; + error_log /var/log/nginx/error.log warn; + pid /var/run/nginx.pid; + + events { + worker_connections 2048; + use epoll; + } + + http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + # 性能优化 + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + + # 日志格式 + log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for"'; + access_log /var/log/nginx/access.log main; + + # 缓存配置 + proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=http_cache:10m + max_size=1g inactive=60m use_temp_path=off; + + gzip on; + gzip_vary on; + gzip_proxied any; + gzip_comp_level 6; + gzip_types text/plain text/css text/xml text/javascript + application/json application/javascript application/xml+rss; + + upstream api { + server api:3000; + } + + upstream web { + server web:3000; + } + + server { + listen 80; + server_name _; + return 301 https://$host$request_uri; + } + + server { + listen 443 ssl http2; + server_name jiao77.cn www.jiao77.cn; + + ssl_certificate /etc/nginx/ssl/cert.pem; + ssl_certificate_key /etc/nginx/ssl/key.pem; + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + # 静态文件 + location ~* \.(js|css|png|jpg|jpeg|gif|ico|woff|woff2)$ { + proxy_pass http://web; + proxy_cache http_cache; + proxy_cache_valid 200 30d; + expires 30d; + add_header Cache-Control "public, immutable"; + } + + # API 接口 + location /api/ { + proxy_pass http://api; + proxy_cache http_cache; + proxy_cache_valid 200 10m; + proxy_cache_key "$scheme$request_method$host$request_uri"; + 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; + } + + # 健康检查 + location /health { + access_log off; + proxy_pass http://api; + } + + # 前端 + location / { + proxy_pass http://web; + 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; + } + } + } + ``` + +#### 4.5 环境配置 +- [ ] 创建 `.env` 模板 + ```bash + NODE_ENV=production + + # 数据库 + DB_NAME=jiao77_db + DB_USER=app + DB_PASSWORD= + + # Redis + REDIS_URL=redis://redis:6379 + + # 应用 + PORT=3000 + FRONTEND_URL=https://jiao77.cn + API_BASE=https://jiao77.cn/api + + # 日志 + LOG_LEVEL=info + ``` + +#### 4.6 启动脚本 +- [ ] 创建 `scripts/start.sh` + ```bash + #!/bin/bash + set -e + + echo "🚀 启动应用..." + + # 拉取最新代码 + git pull origin main + + # 构建镜像 + docker-compose build --no-cache + + # 启动服务 + docker-compose up -d + + # 等待数据库启动 + sleep 10 + + # 运行数据库迁移 + docker-compose exec -T api npm run migrate + + # 健康检查 + echo "✅ 等待服务健康..." + for i in {1..30}; do + if curl -f http://localhost:3000/health > /dev/null 2>&1; then + echo "✅ 应用已启动" + exit 0 + fi + echo "⏳ 尝试 $i/30..." + sleep 1 + done + + echo "❌ 启动失败" + exit 1 + ``` +- [ ] 创建 `scripts/stop.sh` - 优雅关闭 +- [ ] 创建 `scripts/backup.sh` - 数据备份 + +### 🟠 P1 任务：性能优化 + +#### 4.7 数据库优化（单机） +- [ ] 优化 PostgreSQL 配置 + ```yaml + environment: + POSTGRES_INITDB_ARGS: | + -c shared_buffers=256MB + -c effective_cache_size=1GB + -c maintenance_work_mem=64MB + -c work_mem=16MB + ``` +- [ ] 创建必要的数据库索引 +- [ ] 配置连接池大小 + +#### 4.8 API 性能优化 +- [ ] 实现 API 分页（20 条/页） +- [ ] 实现查询结果缓存（Redis） +- [ ] 实现请求压缩（Gzip） +- [ ] 实现 HTTP 缓存头 + +#### 4.9 前端性能优化 +- [ ] Astro 静态生成优化 +- [ ] 图片优化和懒加载 +- [ ] 代码分割 +- [ ] 浏览器缓存配置 + +--- + +## 🎯 第五阶段：监控与备份（第 4 周） + +### 🔴 P0 任务：核心监控 + +#### 5.1 应用健康监控 +- [ ] 配置 `/health` 端点 +- [ ] 配置 `/metrics` 端点（Prometheus 格式） +- [ ] 编写简单的监控脚本 + ```bash + #!/bin/bash + # 定期检查服务状态 + curl -f http://localhost:3000/health || { + echo "❌ API 宕机" | mail -s "告警" admin@jiao77.cn + docker-compose restart api + } + ``` + +#### 5.2 数据库监控 +- [ ] 监控数据库连接数 +- [ ] 监控磁盘使用率 +- [ ] 监控查询缓慢日志 + +#### 5.3 系统监控 +- [ ] 监控 CPU 使用率（< 70%） +- [ ] 监控内存使用率（< 80%） +- [ ] 监控磁盘使用率（< 80%） +- [ ] 配置告警规则 + +#### 5.4 日志管理 +- [ ] 配置 Docker 日志驱动（json-file + 轮转） + ```yaml + logging: + driver: "json-file" + options: + max-size: "100m" + max-file: "3" + ``` +- [ ] 实现日志聚合（可选：ELK Stack 精简版） + +### 🔴 P0 任务：备份策略 + +#### 5.5 数据库备份 +- [ ] 创建自动备份脚本 + ```bash + #!/bin/bash + BACKUP_DIR="/backup/postgresql" + TIMESTAMP=$(date +%Y%m%d_%H%M%S) + + docker-compose exec -T postgres pg_dump \ + -U app jiao77_db | gzip > $BACKUP_DIR/backup_$TIMESTAMP.sql.gz + + # 保留最近 7 天的备份 + find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +7 -delete + ``` +- [ ] 配置每日凌晨 2 点自动备份（crontab） +- [ ] 测试备份恢复流程 + +#### 5.6 应用备份 +- [ ] 备份应用代码（Git） +- [ ] 备份配置文件 +- [ ] 备份日志文件（定期轮转） + +#### 5.7 存储规划 +- [ ] 本地备份：30GB（7 天备份） +- [ ] 云存储备份：20GB（使用 Aliyun OSS 或 COS） +- [ ] 监控备份完成状态 + +### 🟠 P1 任务：故障恢复 + +#### 5.8 故障恢复流程 +- [ ] 编写数据库恢复脚本 + ```bash + #!/bin/bash + # 恢复数据库 + docker-compose exec -T postgres psql -U app jiao77_db < backup.sql + ``` +- [ ] 编写服务重启脚本 +- [ ] 编写完整的应急响应手册 + +#### 5.9 测试和演练 +- [ ] 测试备份恢复（月度） +- [ ] 测试服务重启（周度） +- [ ] 演练故障场景（季度） + +--- + +## 🎯 第六阶段：上线和运维（第 5 周） + +### 🔴 P0 任务：上线前准备 + +#### 6.1 最终检查清单 +- [ ] 所有功能测试通过 +- [ ] 性能基线建立 +- [ ] 安全审计完成 +- [ ] 备份策略验证 +- [ ] 文档完备 +- [ ] 监控告警配置 +- [ ] 回滚计划准备 + +#### 6.2 SSL 证书配置 +- [ ] 使用 Certbot 申请证书 + ```bash + sudo certbot certonly --standalone -d jiao77.cn -d www.jiao77.cn + ``` +- [ ] 配置自动续期 + ```bash + sudo systemctl enable certbot.timer + ``` +- [ ] 配置 Nginx 使用证书 + +#### 6.3 域名配置 +- [ ] 配置 A 记录指向公网 IP +- [ ] 配置 CNAME（www） +- [ ] 配置 MX 记录（邮件，可选） +- [ ] 测试 DNS 解析 + +#### 6.4 上线检查 +- [ ] SSH 配置（禁用密码登录） +- [ ] 防火墙规则验证 +- [ ] 资源使用率基线 +- [ ] 日志系统就位 + +### 🔴 P0 任务：正式部署 + +#### 6.5 发布到 VPS +- [ ] 登录 VPS +- [ ] 执行部署脚本：`bash scripts/start.sh` +- [ ] 验证所有服务正常运行 +- [ ] 验证 HTTPS 连接 +- [ ] 验证所有功能可用 + +#### 6.6 上线后验证 +- [ ] 访问前端页面 +- [ ] 测试评论功能 +- [ ] 测试统计功能 +- [ ] 检查日志无错误 + +#### 6.7 持续监控（上线后 24h） +- [ ] 监控 CPU、内存、磁盘 +- [ ] 监控应用日志 +- [ ] 监控用户反馈 +- [ ] 记录性能数据 + +### 🟠 P1 任务：运维自动化 + +#### 6.8 Cron 任务设置 +- [ ] 每日 02:00 - 数据库备份 +- [ ] 每周日 03:00 - 系统备份 +- [ ] 每小时 - 健康检查 +- [ ] 每 10 分钟 - 监控检查 + +#### 6.9 日常运维任务 +- [ ] 周度备份验证 +- [ ] 月度性能分析 +- [ ] 季度灾难恢复演练 +- [ ] 定期安全更新 + +#### 6.10 长期维护计划 +- [ ] Docker 镜像定期更新 +- [ ] 依赖包定期更新 +- [ ] PostgreSQL 大版本升级计划 +- [ ] 磁盘空间管理计划 + +### 🟠 P1 任务：文档和培训 + +#### 6.11 运维文档 +- [ ] 部署操作手册 +- [ ] 故障排查指南 +- [ ] 备份恢复流程 +- [ ] 监控告警规则 + +#### 6.12 应急响应 +- [ ] 编写应急响应计划 +- [ ] 列出主要故障场景 +- [ ] 编写恢复步骤 + +--- + +## 🎯 可选优化（P2 任务） + +### 🟡 P2 任务：性能优化 + +#### 7.1 查询优化 +- [ ] 数据库慢查询分析 +- [ ] 添加查询索引 +- [ ] 优化 N+1 查询 +- [ ] 实现查询结果缓存 + +#### 7.2 缓存优化 +- [ ] Redis 缓存热数据 +- [ ] 实现缓存预热 +- [ ] 实现缓存失效策略 + +#### 7.3 API 优化 +- [ ] 减少 API 响应大小 +- [ ] 实现字段选择 +- [ ] 实现 API 聚合 + +--- + +## 🎯 后续扩展（P3 任务） + +### 🟢 P3 任务：功能扩展 + +#### 8.1 用户系统 +- [ ] 用户认证 +- [ ] 用户资料 +- [ ] 权限管理 + +#### 8.2 社区功能 +- [ ] 评论回复 +- [ ] 用户关注 +- [ ] 排行榜 + +#### 8.3 数据分析 +- [ ] 用户行为分析 +- [ ] 内容热力分析 + +--- + +## 📊 单机配置资源预算 + +### VPS 规格建议 +``` +配置：4核 CPU、8GB 内存、100GB SSD +操作系统：Ubuntu 20.04 LTS +带宽：大带宽（>10 Mbps） +``` + +### 容器资源分配 +``` +PostgreSQL： + - CPU limit: 1 核 + - Memory limit: 1GB + - 实际使用：0.5 核、500MB + +Redis： + - CPU limit: 0.5 核 + - Memory limit: 512MB + - 实际使用：0.2 核、256MB + +API (Node.js)： + - CPU limit: 1 核 + - Memory limit: 1GB + - 实际使用：0.3 核、300MB + +Web (Astro)： + - CPU limit: 0.5 核 + - Memory limit: 512MB + - 实际使用：0.1 核、100MB + +Nginx： + - CPU limit: 0.5 核 + - Memory limit: 256MB + - 实际使用：0.05 核、50MB + +总计峰值：3 核、3.5GB +实际使用：1.15 核、1.2GB（预留安全边际） +``` + +### 存储分配（100GB） +``` +系统和 Docker：20GB +PostgreSQL 数据：30GB +Redis 数据：2GB +应用代码：5GB +日志文件：3GB +备份文件：30GB +缓冲区：10GB +``` + +--- + +## ⏱️ 时间表（针对单机优化） + +``` +第1周 - VPS 准备 + 后端开发 60 小时 +第2周 - 前端开发 + 集成 50 小时 +第3周 - Docker 化 + 部署 40 小时 +第4周 - 监控 + 备份 + 测试 40 小时 +第5周 - 上线 + 优化 30 小时 +────────────────────────────────── +总计：220 小时 ≈ 5-6 周（单人开发） + ≈ 3-4 周（双人开发） +``` + +--- + +## 🚀 快速开始指南 + +### 立即开始（第 1 天） +```bash +# 1. SSH 登录 VPS +ssh root@ + +# 2. 安装 Docker 和 Compose +curl -fsSL https://get.docker.com | sh +sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose +sudo chmod +x /usr/local/bin/docker-compose + +# 3. 克隆项目 +git clone /home/app + +# 4. 配置环境 +cd /home/app +cp .env.example .env +# 编辑 .env，配置数据库密码等 + +# 5. 启动应用 +docker-compose up -d + +# 6. 验证 +curl http://localhost:3000/health +``` + +### 配置 SSL（第 2 天） +```bash +# 使用 Certbot +sudo apt install certbot +sudo certbot certonly --standalone -d jiao77.cn -d www.jiao77.cn + +# 在 docker-compose.yml 中配置证书路径 +# 重启 Nginx +docker-compose restart nginx +``` + +### 配置备份（第 3 天） +```bash +# 添加 cron 任务 +crontab -e + +# 添加备份命令 +0 2 * * * cd /home/app && bash scripts/backup.sh +``` + +--- + +## 💡 单机部署最佳实践 + +### ✅ DO（应该做） +- ✅ 定期备份数据库 +- ✅ 监控资源使用率 +- ✅ 设置告警规则 +- ✅ 使用 Alpine 镜像减少内存 +- ✅ 配置资源限制 +- ✅ 日志轮转 +- ✅ 定期更新依赖 + +### ❌ DON'T（不应该做） +- ❌ 不使用 root 运行容器 +- ❌ 不在生产用开发镜像 +- ❌ 不忽视监控告警 +- ❌ 不手动管理依赖版本 +- ❌ 不连续部署到生产（需要测试） + +--- + +## 🔧 常见问题排查 + +### 问题 1：内存不足 +```bash +# 检查内存使用 +docker stats + +# 解决方案： +# 1. 减少 PostgreSQL 缓冲区 +# 2. 减少 Redis 最大内存 +# 3. 优化 Node.js 堆大小 +``` + +### 问题 2：磁盘满 +```bash +# 检查磁盘 +df -h + +# 清理 Docker 镜像 +docker image prune -a + +# 清理 Docker 容器 +docker container prune +``` + +### 问题 3：性能下降 +```bash +# 检查慢查询 +docker-compose logs api | grep "SLOW" + +# 检查数据库连接 +docker-compose exec postgres psql -c "SELECT count(*) FROM pg_stat_activity;" +``` + +--- + +## 📈 性能指标目标 + +| 指标 | 目标 | 说明 | +|-----|------|------| +| 页面加载时间 | < 2s | 首次加载 | +| API 响应时间 | < 200ms | 平均响应 | +| 数据库查询 | < 100ms | 95 分位 | +| CPU 使用率 | < 60% | 平均 | +| 内存使用率 | < 75% | 峰值 | +| 磁盘使用率 | < 80% | 实时 | +| 可用性 | 99.5% | 月度 | + +--- + +## 🎯 总结 + +这个方案针对**单机 VPS 环境**进行了全面优化： + +1. **资源优化** - 使用 Alpine 镜像、资源限制、连接池优化 +2. **部署简化** - Docker Compose 单文件部署、Nginx 反向代理 +3. **监控自动化** - 健康检查、告警规则、自动重启 +4. **备份完善** - 每日备份、7 天保留、恢复流程 +5. **成本低** - 无需复杂基础设施、单机成本 ~¥100/月 + +**建议**：从 P0 任务开始，按阶段稳步推进，确保每个阶段的质量。 + diff --git a/docs/WEBSITE_MODERNIZATION_PLAN.md b/docs/WEBSITE_MODERNIZATION_PLAN.md new file mode 100644 index 0000000..d805052 --- /dev/null +++ b/docs/WEBSITE_MODERNIZATION_PLAN.md @@ -0,0 +1,681 @@ +# 🎯 网站现代化重构方案 + +**目标**：将静态 Astro 网站升级为具有评论系统、数据统计、用户交互的动态网站 + +--- + +## 📊 方案对比 + +### 方案 A：Astro + Node.js 后端（推荐）⭐⭐⭐⭐⭐ + +**最适合当前项目！** + +#### 技术栈 +- **前端**：Astro + React/Vue 组件（动态部分） +- **后端**：Node.js + Express/Fastify +- **数据库**：PostgreSQL / MongoDB +- **缓存**：Redis +- **API**：REST / GraphQL +- **部署**：Docker + PM2 + +#### 优势 +✅ 前后端分离，灵活可维护 +✅ Astro 保留静态生成的性能优势 +✅ 支持实时数据更新 +✅ 可扩展性强 +✅ 成熟的技术生态 + +#### 架构图 +``` +┌─────────────────────────────────────┐ +│ 用户浏览器 (静态部分) │ +├─────────────────────────────────────┤ +│ Astro 静态生成 │ +│ - 首页、报告页面 │ +│ - SEO 优化 │ +└────────────────┬────────────────────┘ + │ + ┌────────▼────────┐ + │ 动态组件加载 │ + │ (React/Vue) │ + ├─────────────────┤ + │ - 评论系统 │ + │ - 数据统计 │ + │ - 用户互动 │ + └────────┬────────┘ + │ API 调用 + ┌────────▼────────┐ + │ Node.js 后端 │ + ├─────────────────┤ + │ - 用户管理 │ + │ - 评论处理 │ + │ - 数据分析 │ + │ - 权限控制 │ + └────────┬────────┘ + │ + ┌────────▼────────┐ + │ 数据库 │ + ├─────────────────┤ + │ - PostgreSQL │ + │ - Redis Cache │ + └─────────────────┘ +``` + +--- + +### 方案 B：Astro + 第三方服务（快速启动）⭐⭐⭐⭐ + +**无需后端维护，快速上线** + +#### 技术栈 +- **前端**：Astro（保持不变） +- **评论**：Disqus / Giscus / Utterances +- **数据统计**：Google Analytics / Plausible +- **用户系统**：Supabase / Firebase +- **内容管理**：Contentful / Sanity +- **部署**：Vercel / Netlify + +#### 优势 +✅ 零后端维护 +✅ 快速集成 +✅ 自动扩展 +✅ 成本低 +✅ 部署简单 + +#### 缺点 +❌ 功能受限 +❌ 数据隐私性 +❌ 成本可能增加 + +--- + +### 方案 C：Astro + Hybrid Rendering（终极方案）⭐⭐⭐⭐⭐ + +**Astro 4.0+ 的新特性：静态和动态混合** + +#### 技术栈 +- **Astro Hybrid SSR**：部分页面服务端渲染 +- **后端**：Node.js +- **数据库**：PostgreSQL +- **实时**：WebSocket +- **部署**：自托管或 Vercel + +#### 优势 +✅ 性能最优 +✅ SEO 完美 +✅ 实时交互 +✅ 完全控制 + +--- + +## 🏗️ 推荐方案详细实现 + +### 方案 A：完整实现步骤 + +#### 第一阶段：前端重构（1-2周） + +**1. 更新 Astro 配置支持混合渲染** + +```javascript +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import react from '@astrojs/react'; +import tailwind from '@astrojs/tailwind'; +import node from '@astrojs/node'; + +export default defineConfig({ + integrations: [ + react(), + tailwind(), + ], + // 启用混合渲染 + output: 'hybrid', + adapter: node({ + mode: 'standalone' + }), + vite: { + define: { + 'process.env.NODE_ENV': JSON.stringify('production') + } + } +}); +``` + +**2. 创建动态 React 组件** + +```typescript +// src/components/comments/CommentSection.tsx +import React, { useState, useEffect } from 'react'; +import type { Comment } from '../../types/comment'; + +export default function CommentSection({ reportId }: { reportId: string }) { + const [comments, setComments] = useState([]); + const [newComment, setNewComment] = useState(''); + const [loading, setLoading] = useState(false); + + useEffect(() => { + fetchComments(); + }, [reportId]); + + const fetchComments = async () => { + try { + const response = await fetch(`/api/comments?reportId=${reportId}`); + const data = await response.json(); + setComments(data); + } catch (error) { + console.error('Failed to fetch comments:', error); + } + }; + + const handleSubmit = async (e: React.FormEvent) => { + e.preventDefault(); + setLoading(true); + try { + const response = await fetch('/api/comments', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + reportId, + content: newComment, + author: 'Anonymous', // 需要用户系统 + }) + }); + const comment = await response.json(); + setComments([...comments, comment]); + setNewComment(''); + } catch (error) { + console.error('Failed to post comment:', error); + } finally { + setLoading(false); + } + }; + + return ( +
+

评论 ({comments.length})

+ + {/* 评论列表 */} +
+ {comments.map((comment) => ( +
+
+ {comment.author} + +
+

{comment.content}

+
+ ))} +
+ + {/* 评论表单 */} +
+