345 lines
12 KiB
Markdown
345 lines
12 KiB
Markdown
# 慧愈科技官网｜一期架构决策与精简开发计划 V1.2
|
||
|
||
> 决策日期：2026-08-10
|
||
> 决策目标：按“主要供访客浏览、低并发、少运营人员、单服务器”的真实场景，采用简单、稳定、可恢复的实现，不为二期需求提前堆复杂架构。
|
||
|
||
## 1. 已直接确定的架构
|
||
|
||
### 1.1 应用形态
|
||
|
||
采用**一个 Nuxt（Vue）全栈应用**：
|
||
|
||
```text
|
||
Nuxt 应用
|
||
├── 官网前台：SSR / 混合渲染
|
||
├── 管理后台：/admin
|
||
├── 服务端 API：/api
|
||
├── SQLite
|
||
└── 本地素材目录
|
||
```
|
||
|
||
理由：
|
||
|
||
- Vue 生态成熟，设计图也适合组件化实现；
|
||
- 官网需要 SEO，不采用纯 Vue SPA，改用基于 Vue 的 Nuxt 服务端渲染；
|
||
- 前台、后台、API 使用同一套 TypeScript，减少服务数量和交接成本；
|
||
- 一期不再单独引入 FastAPI，避免同时维护 Node 和 Python 两套运行环境。
|
||
|
||
### 1.2 技术基线
|
||
|
||
```text
|
||
语言：TypeScript
|
||
前台与后台：Vue + Nuxt
|
||
样式：CSS Variables + SCSS（建立品牌设计令牌）
|
||
数据校验：统一 Schema 校验
|
||
数据库：SQLite
|
||
素材：服务器本地磁盘
|
||
入口与 HTTPS：Nginx
|
||
进程与部署：Docker Compose，使用预构建镜像
|
||
测试：单元测试 + API 集成测试 + 核心流程端到端测试
|
||
```
|
||
|
||
不固定未经验证的具体小版本；实现时使用当时仍在维护的稳定版本并锁定依赖。
|
||
|
||
## 2. 服务器决策
|
||
|
||
一期接受：
|
||
|
||
```text
|
||
CPU：2 核
|
||
内存：2 GB
|
||
系统盘：建议至少 40—80 GB SSD
|
||
Swap：1—2 GB，仅作为突发保护，不作为正常内存使用
|
||
实例数：1
|
||
```
|
||
|
||
使用限制：
|
||
|
||
- 不在生产服务器上执行重型前端构建；在本地或 CI 构建后部署制品/镜像；
|
||
- Nuxt 只启动一个应用实例，避免多个进程同时写 SQLite；
|
||
- Nginx、Nuxt 和定时备份是主要常驻服务；
|
||
- 设置 CPU、内存、磁盘和错误率告警；
|
||
- 磁盘使用达到 70% 时预警，达到 80% 前必须扩容或清理。
|
||
|
||
## 3. SQLite 决策
|
||
|
||
一期采用 SQLite，符合低写入、单应用服务器的官网场景。
|
||
|
||
必须遵守：
|
||
|
||
- 数据库文件与应用代码分离，固定挂载到 `/data/db/`；
|
||
- 不把 SQLite 放到 NFS、SMB 等网络文件系统；
|
||
- 开启 WAL、外键约束和合理的 `busy_timeout`；
|
||
- 写事务保持短小，不在事务中执行图片处理或外部网络请求；
|
||
- 数据库迁移必须有版本号；
|
||
- 发布前自动备份，迁移失败停止发布；
|
||
- 只能有一个负责写入的应用实例。
|
||
|
||
暂不使用 PostgreSQL。出现以下任一条件时再迁移：
|
||
|
||
- 需要多台应用服务器；
|
||
- 多名运营人员频繁同时写入并出现锁等待；
|
||
- 日志持续出现数据库锁超时；
|
||
- 需要复杂报表、数据分析或外部系统直接访问数据库；
|
||
- 单机已经无法满足可用性要求。
|
||
|
||
数据访问层不得散落手写 SQL，集中在 repository/service 层，便于二期迁移 PostgreSQL。
|
||
|
||
## 4. 本地素材决策
|
||
|
||
一期图片、PDF 和少量视频直接保存在服务器本地：
|
||
|
||
```text
|
||
/data/uploads/original/
|
||
/data/uploads/derived/
|
||
/data/uploads/trash/
|
||
```
|
||
|
||
必须实现：
|
||
|
||
- 文件名随机化，原始文件名只保存为元数据；
|
||
- 文件头、MIME、扩展名、大小和图片像素校验；
|
||
- 生成 WebP/缩略图，保留原图；
|
||
- 保存宽高、ALT、来源、版权和授权状态；
|
||
- 素材引用保护；
|
||
- 删除先进入回收站，延迟物理删除；
|
||
- Nginx 直接提供静态资源并设置缓存头；
|
||
- 上传目录不允许执行脚本。
|
||
|
||
暂不使用对象存储和 CDN。出现以下情况再迁移：
|
||
|
||
- 素材量达到约 20 GB 或磁盘增长明显加快；
|
||
- 访客跨地域访问图片明显缓慢；
|
||
- 需要多服务器部署；
|
||
- 图片流量成为服务器主要带宽开销；
|
||
- 需要更强的素材版本、权限或防盗链能力。
|
||
|
||
数据库只保存相对路径和素材 ID，不把域名写死，确保将来迁移对象存储时不用改业务数据。
|
||
|
||
## 5. 备份是一期 P0，不延后
|
||
|
||
本地存储足够使用，但**本地存储不等于备份**。服务器磁盘损坏、误删除、系统重装或云主机被释放时，数据库和图片可能同时消失。
|
||
|
||
一期最低备份策略：
|
||
|
||
- 每天使用 SQLite 在线备份生成一致性数据库副本；
|
||
- 每天增量备份上传素材；
|
||
- 数据库备份和素材备份必须复制到另一台机器或低成本云存储；
|
||
- 保留 7 个每日备份、4 个每周备份、6 个每月备份；
|
||
- 备份文件加密；
|
||
- 每月执行一次自动校验；
|
||
- 上线前和重大迁移前执行一次完整备份；
|
||
- 至少完成一次从空服务器恢复数据库和素材的演练。
|
||
|
||
目标：
|
||
|
||
```text
|
||
RPO：最多丢失 24 小时数据
|
||
RTO：故障后 4 小时内恢复官网
|
||
```
|
||
|
||
## 6. 一期功能范围
|
||
|
||
### 6.1 官网前台
|
||
|
||
- 沉浸式长滚动首页；
|
||
- 关于慧愈；
|
||
- 卢慧老师人物页；
|
||
- 课程与产品列表、详情；
|
||
- 品牌动态、官方声明列表和详情；
|
||
- 陪伴团队；
|
||
- 官方渠道与联系方式；
|
||
- 隐私政策、服务条款、版权和备案信息；
|
||
- Sitemap、Canonical、Open Graph、robots 和基础 JSON-LD；
|
||
- 响应式布局、无障碍基础和减少动态效果支持。
|
||
|
||
### 6.2 管理后台
|
||
|
||
- 一个超级管理员账号；
|
||
- 登录、退出、修改密码和登录限流；
|
||
- 首页固定模块的内容、排序和显隐；
|
||
- 卢慧老师、公司品牌、课程产品、文章声明、团队和官方渠道维护；
|
||
- 素材上传、选择、替换、引用保护和回收站；
|
||
- 草稿、预览、发布、下线；
|
||
- 最近 20 个关键内容版本，恢复版本时生成草稿；
|
||
- 基础操作日志；
|
||
- 网站和 SEO 基础配置。
|
||
|
||
### 6.3 一期明确不做
|
||
|
||
- 多级角色和复杂权限矩阵；
|
||
- 编辑提交、审核员审批的多人审核流；
|
||
- 定时发布；
|
||
- Redis、消息队列和后台任务集群；
|
||
- PostgreSQL；
|
||
- 对象存储和 CDN；
|
||
- 后台全局搜索；
|
||
- 复杂访问统计；
|
||
- AI 标准信息管理和内容监测；
|
||
- 字段级版本差异对比；
|
||
- 多语言、支付、CRM、学习系统和用户注册。
|
||
|
||
## 7. 一期仍然不能省的生产要求
|
||
|
||
- HTTPS；
|
||
- 密码安全哈希；
|
||
- HttpOnly/Secure/SameSite Cookie；
|
||
- 登录限流和统一失败提示；
|
||
- 后端权限校验；
|
||
- XSS、CSRF、上传和路径穿越防护；
|
||
- 数据库迁移与迁移前备份；
|
||
- 异机备份和恢复演练；
|
||
- 健康检查、结构化日志和错误告警；
|
||
- 部署制品有版本号并可回滚；
|
||
- 密钥不进入代码仓库；
|
||
- 图片和人物资料上线前完成版权、肖像和事实核验。
|
||
|
||
## 8. 精简开发计划
|
||
|
||
### 阶段 0：内容与页面冻结（2—3 个工作日）
|
||
|
||
- 确定页面、锚点和详情路由；
|
||
- 确定后台需要支持的内容字段和校验规则；
|
||
- 用明确标注的演示数据跑通人物、课程、渠道和法律信息页面；
|
||
- 建立素材授权状态字段和上线检查规则；
|
||
- 域名、DNS、服务器权限和异机备份目标不阻塞开发，在部署阶段提供。
|
||
|
||
### 阶段 1：工程和部署骨架（4—6 个工作日）
|
||
|
||
- 初始化 Nuxt 全栈工程；
|
||
- 建立模块边界、设计令牌和代码规范；
|
||
- 接入 SQLite、迁移、日志和测试；
|
||
- 完成 Docker Compose、Nginx、HTTPS、健康检查和备份脚本；
|
||
- 建立测试环境。
|
||
|
||
### 阶段 2：后台数据与登录（7—10 个工作日）
|
||
|
||
- 超级管理员登录和安全策略；
|
||
- 公司、品牌、人物、课程、文章、团队、渠道和首页模块数据模型；
|
||
- 素材上传和衍生图；
|
||
- 草稿、发布快照、下线、版本恢复和操作日志。
|
||
|
||
### 阶段 3：管理后台页面（8—12 个工作日）
|
||
|
||
- 首页管理；
|
||
- 人物和品牌资料；
|
||
- 课程、文章、声明、团队和渠道；
|
||
- 素材中心；
|
||
- 预览、发布和版本历史；
|
||
- 网站与 SEO 配置。
|
||
|
||
### 阶段 4：官网前台与动效（10—15 个工作日）
|
||
|
||
- 按设计图实现长滚动首页；
|
||
- 完成人物、课程、文章、声明和团队详情；
|
||
- 完成视差、渐显、遮罩、数字动画及移动端降级；
|
||
- 完成 SEO、结构化数据和响应式图片。
|
||
|
||
### 阶段 5：联调和生产验收（7—10 个工作日）
|
||
|
||
- API、权限、发布、上传和版本测试；
|
||
- 浏览器、移动端、横向滚动和视觉对比检查；
|
||
- XSS、CSRF、登录限流和上传安全测试；
|
||
- 性能检查；
|
||
- 备份恢复和应用回滚演练；
|
||
- 内容、链接、二维码、备案和法律信息验收；
|
||
- 编写部署、运营和故障恢复手册。
|
||
|
||
## 9. 工期判断
|
||
|
||
精简后粗略工作量：**38—56 人日**，不包含备案等待、大量文案创作和重新拍摄图片。
|
||
|
||
- 1 名全栈开发：约 9—12 周；
|
||
- 2 名开发合理分工：约 6—8 周；
|
||
- 如果真实内容、素材和授权不能及时提供，开发完成也不能直接上线。
|
||
|
||
## 10. 我方可以直接决策的事项
|
||
|
||
以下事项无需反复确认，按本文件执行：
|
||
|
||
- Vue/Nuxt + TypeScript；
|
||
- 单体全栈应用；
|
||
- SQLite + WAL；
|
||
- 本地素材 + 相对路径；
|
||
- 单服务器、单应用实例；
|
||
- Docker Compose + Nginx；
|
||
- 前台 SSR，后台客户端交互；
|
||
- 固定首页模块，不做低代码；
|
||
- 一期单超级管理员，不做复杂审核；
|
||
- 草稿、发布快照和最近 20 个历史版本；
|
||
- 基础 SEO、日志、安全、备份和回滚属于一期；
|
||
- 代码模块化、接口校验、测试和中文交接文档。
|
||
|
||
## 11. 只需用户提供的外部信息
|
||
|
||
### 11.1 开发阶段不需要用户提供
|
||
|
||
以下信息不阻塞开发，统一到部署阶段再提供：
|
||
|
||
- 域名及备案现状；
|
||
- DNS 管理权限；
|
||
- 服务器登录权限；
|
||
- 生产服务器系统与最终磁盘容量；
|
||
- 异机备份目标和备份账号；
|
||
- HTTPS 证书相关信息。
|
||
|
||
### 11.2 必须做成后台可配置的内容
|
||
|
||
以下内容不能写死在代码或环境变量中，全部通过后台维护：
|
||
|
||
- 官网名称、品牌名称、Logo、favicon 和品牌简介；
|
||
- 公司主体、统一社会信用代码、电话、邮箱和地址；
|
||
- ICP 备案号、公安备案号、页脚版权；
|
||
- 卢慧老师介绍、经历、成果、标签、照片和外部权威链接；
|
||
- 课程与产品；
|
||
- 团队成员；
|
||
- 官方渠道、账号、链接和二维码；
|
||
- 品牌动态、官方声明和媒体报道；
|
||
- 隐私政策、服务条款和版权说明；
|
||
- 首页标题、文案、图片、按钮、模块顺序和显隐；
|
||
- 默认 SEO、页面 SEO、Open Graph 图片和结构化信息所需字段；
|
||
- 素材来源、版权状态、授权状态和 ALT 文本。
|
||
|
||
开发和测试阶段使用演示数据。演示数据必须带有明显的“演示/待替换”标记，生产发布前由后台替换并通过上线检查。
|
||
|
||
### 11.3 不能放进普通后台配置的敏感信息
|
||
|
||
以下信息只允许通过服务器环境变量、只读配置文件或密钥管理方式注入：
|
||
|
||
- 数据库和会话密钥；
|
||
- 管理员初始密码；
|
||
- 备份账号和密钥；
|
||
- 邮件、短信或第三方服务密钥；
|
||
- DNS、服务器和部署平台凭证；
|
||
- 错误监控和统计平台的服务端密钥。
|
||
|
||
后台可以显示这些能力是否已配置，但不得读取或回显完整密钥。
|
||
|
||
### 11.4 生产上线前检查
|
||
|
||
真实内容可以在开发完成后由运营人员通过后台录入，但生产上线前必须完成：
|
||
|
||
- 演示数据清零；
|
||
- 公司、人物、课程和渠道信息审核；
|
||
- 图片版权与肖像授权确认；
|
||
- 电话、邮箱、链接和二维码逐项点击验证；
|
||
- 备案与法律文本确认；
|
||
- 最终内容审核人签字确认。
|
||
|
||
## 12. 后台网站配置字段范围
|
||
|
||
后台“网站配置”按职责拆分，避免一个页面堆放所有信息：
|
||
|
||
```text
|
||
网站配置
|
||
├── 品牌与站点
|
||
├── 公司主体与备案
|
||
├── 联系方式
|
||
├── 页脚与法律页面
|
||
├── 默认 SEO
|
||
├── 首页模块
|
||
└── 功能开关
|
||
```
|
||
|
||
配置修改同样保留草稿和发布快照。已发布配置由前台读取，编辑中的草稿不会直接影响线上官网。
|