张翔
10404dbb36
同步工作区剩余变更，主要包括： - 营销页面组件与布局持续优化（about/news/services/solutions/team 等） - 详情页四层叙事组件、布局组件、UI 组件调整 - CMS 数据模型、API 路由、权限、工作流、站内通知、媒体管理扩展 - 新增/补充单元测试与 E2E 测试（cms-workflow.spec.ts 等） - ESLint 9 迁移、jest/tsconfig 配置更新、依赖调整 - 新增 ADR、CMS 评估文档、Release Review / Acceptance 报告 - 移除水墨装饰组件与大体积未使用字体文件
69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
# ADR 0007: 从纯静态导出迁移到混合渲染（SSR/ISR）以支撑 CMS
|
||
|
||
## 状态
|
||
|
||
已接受
|
||
|
||
## 上下文
|
||
|
||
Novalon 网站早期采用 Next.js 纯静态导出（`output: 'export'`）部署，营销页内容来自 `src/lib/constants/*.ts` 中的 TypeScript 常量。随着 CMS 数据层（`src/lib/cms/`）和 API 路由（`/api/admin/*`、`/api/cms/*`）逐步建立，纯静态导出开始与以下需求冲突：
|
||
|
||
1. **CMS 实时预览**：静态导出下，草稿和预览需要构建时注入环境变量或维护独立预览站点。
|
||
2. **一键发布**：静态导出要求每次内容变更后触发全站构建与部署，无法做到“发布即生效”。
|
||
3. **动态内容增长**：联系表单、CMS 管理后台、未来可能的搜索/过滤功能都需要服务端能力。
|
||
4. **现有基础设施**：`next.config.mjs` 已移除 `output: 'export'`，`/api/cms/revalidate` 与 `/api/cms/draft/*` 路由已存在，说明项目已经朝混合渲染方向过渡，但文档与口头描述仍存在“纯静态网站”的遗留口径。
|
||
|
||
需要正式决定部署模式，以统一团队认知并指导 CMS 实现。
|
||
|
||
## 决策
|
||
|
||
采用**混合渲染（Hybrid Rendering）**：以静态生成（SSG）为主，对需要实时内容或动态能力的页面/路由使用 SSR 或 ISR。
|
||
|
||
具体规则：
|
||
|
||
- 营销展示页面（首页、产品/方案/服务列表与详情、关于、新闻等）默认使用 SSG + ISR，CMS 内容发布后通过 `/api/cms/revalidate` 刷新缓存。
|
||
- 管理后台（`/admin/*`）、认证（`/api/auth/*`）、CMS API（`/api/admin/*`、`/api/cms/*`）、联系表单（`/api/contact/*`）使用 SSR/API Routes。
|
||
- 草稿预览通过 `/api/cms/draft/enable` 启用 draft 模式，从 CMS 实时拉取未发布内容。
|
||
|
||
## 理由
|
||
|
||
### 为什么不继续纯静态导出？
|
||
|
||
1. **CMS 价值被削弱**：静态导出下，CMS 的“发布”操作退化为“触发 CI/CD 全量构建”，无法提供运营人员期望的即时反馈。
|
||
2. **预览成本高**：草稿预览需要为每个内容状态维护独立构建产物或复杂的环境变量注入。
|
||
3. **与现有代码方向矛盾**：`output: 'export'` 已从 `next.config.mjs` 移除，`/api/cms/revalidate` 和 `/api/cms/draft/*` 已假设存在服务端运行时。
|
||
|
||
### 为什么不全面 SSR？
|
||
|
||
1. **性能与成本**：营销页内容变更不频繁，SSG + ISR 能在保证性能的同时减少服务端负载。
|
||
2. **SEO 与托管**：静态页面更易于 Nginx/CDN 缓存和部署，SSR 仅保留在真正需要动态能力的部分。
|
||
3. **渐进过渡**：团队已有 SSG 基础，混合渲染允许逐页、逐路由迁移，风险可控。
|
||
|
||
## 后果
|
||
|
||
### 正面
|
||
|
||
- CMS 发布、草稿预览、版本回滚可以实时生效，无需等待全量构建。
|
||
- 可以充分利用 Next.js App Router 的 `fetch(revalidate)`、`generateStaticParams` 和 Draft Mode。
|
||
- 为未来的搜索、个性化、用户登录等动态功能保留扩展空间。
|
||
|
||
### 负面
|
||
|
||
- 需要长期运行 Next.js 服务（而非仅部署静态文件），部署和监控复杂度略有上升。
|
||
- Nginx 反向代理配置需要更新，以正确路由 SSR/API 请求到 Next.js 服务。
|
||
- 需要为 ISR 缓存失效策略和 revalidation 失败场景制定回退方案。
|
||
|
||
### 风险与缓解
|
||
|
||
| 风险 | 缓解措施 |
|
||
|------|---------|
|
||
| Nginx 配置错误导致 SSR 路由 404 | 更新 `nginx-static-production.conf`，为 `/api/*`、`/admin/*` 及动态路由配置正确 upstream |
|
||
| ISR revalidate 失败导致内容陈旧 | 在管理后台显示“最后刷新时间”，支持手动 revalidate；关键发布后可触发全量构建兜底 |
|
||
| SQLite 写入并发瓶颈 | 当前后台管理并发低，可接受；未来若增长，平滑迁移至 PostgreSQL |
|
||
|
||
## 相关决策
|
||
|
||
- ADR-0001：重构路径选择——混合方案而非全站 web-design-engineer 替换
|
||
- ADR-0005：全局布局由 CMS 管理
|
||
- docs/cms-evaluation.md：CMS 内容管理系统集成评估
|