🏗 双模式架构总览
- rsSites 同时支持 SSR 和 SPA 两种子站渲染模式：一套后端代码，两种前端交付方式，覆盖从内容展示到富交互应用的全部场景
- 后台可自由切换：每个子站独立选择渲染模式，无需修改代码，一键切换。SSR 和 SPA 子站可以并存于同一个站群中
- 同一套后端服务：两种模式共享同一套数据模型、业务逻辑、权限体系、工作流——后端只写一次，两种前端模式全部复用
- 适用场景清晰：SSR 适合面向公众的展示型站点（官网、新闻站、博客），SPA 适合需要富交互的管理后台或应用型站点
- 路由层面统一：无论哪种模式，URL 路由规则一致，切换模式对访客完全无感，不会出现链接失效或跳转异常
📤 SSR 服务端渲染
- 请求到达：HTTP 请求进入 Axum 路由系统，开始完整的 SSR 渲染流程
- 路由匹配：按站点 + 栏目进行路由匹配，精确找到对应的模板和内容资源
- 模板查找：从模板目录中加载对应站点的 Tera 模板文件，支持模板继承和多级覆盖
- 上下文组装：系统自动注入站点信息、导航菜单、内容卡片、栏目区块、友情链接、SEO 配置等全部数据到渲染上下文
- 渲染输出：Tera 引擎将上下文与模板编译为完整 HTML，直接返回浏览器——无需客户端 JavaScript 即可呈现完整页面
- SSR 优势：SEO 友好（搜索引擎直接抓取 HTML 内容）、首屏秒开（无需等待 JS 加载和执行）、低端设备兼容（服务端承担渲染压力）、对爬虫和社交分享（OG 标签）完美支持
🎨 Tera 模板引擎
- 类 Jinja2 语法：学习成本极低，有 Python / Jinja2 经验的开发者可直接上手，`{% if %}`, `{% for %}`, `{{ variable }}` 等语法完全一致
- extends 继承：子模板通过 `{% extends "base.html" %}` 继承父模板布局，只覆写变化部分，避免重复代码，基础布局集中管理
- include 包含：公共组件（页头、页脚、导航栏、侧边栏）抽取为独立文件，通过 `{% include %}` 复用，修改一处全局生效
- macro 宏定义：可复用的 UI 片段（如卡片、按钮、列表），支持参数化调用，实现真正的组件化模板开发
- 组件化建站：导航菜单 + 内容组件 + 聚合页三件套，覆盖大部分常见的建站需求，无需从零编写模板
- 模板三态管理：草稿（编辑中）→ 发布（正式上线）→ 归档（历史保留），每一步状态流转均可记录操作元数据（操作人、时间、变更说明）
- 静态资源路径规范：`/statics/{site}/` 统一结构，天然适配 CDN 加速，资源版本化管理
- Rust 原生编译：Tera 是 Rust 原生编译的模板引擎，解析速度快于 Jinja2、Pug 等解释型引擎，模板错误在编译期即可发现
草稿态
编辑中，不影响线上
发布态
正式对外服务
归档态
历史版本保留，可回溯
每一步状态流转均可记录元数据（操作人、时间、变更说明），支持随时回溯到任意历史版本
💻 SPA 单页应用模式
- 支持任意前端框架：不限于 React，Vue、Angular、Svelte、Solid 等任何可构建为静态文件的 SPA 框架均支持——rsSites 不绑定任何前端技术栈
- Dist 运行环境：rsSites 提供静态文件托管服务，只需将 SPA 构建产物（dist 目录）部署到指定路径，系统自动托管，无需额外配置 Nginx 或 CDN
- 完整的 API 支持：rsSites 提供完整的 RESTful API，SPA 可通过 API 获取所有数据——内容、栏目、导航、搜索、站点配置等，全部通过标准 HTTP 接口交互
- 共享系统能力：SPA 子站可共享 rsSites 的全部后端能力——权限校验、审核工作流、内容管理、定时发布、中文分词搜索等后端逻辑全部复用，SPA 只需关注前端呈现
- 路由模式：SPA 子站可使用 Hash 路由（`#/page`）或 History 路由（`/page`），rsSites 自动处理 History 路由的后端回退，确保刷新页面不会出现 404
- API 认证：SPA 子站通过 Token 认证机制调用 API，权限体系与 SSR 子站完全一致，同一个用户在不同子站中拥有相同的权限
🎯 SSR 最适合的场景
- 需要 SEO 的站点：官网、新闻站、博客、落地页——搜索引擎可直接抓取完整 HTML 内容
- 首屏加载速度要求高的场景：服务端直出 HTML，无需等待 JavaScript 下载、解析、执行
- 面向公众访问的内容展示型站点：以内容阅读和浏览为主的页面，交互需求较低
- 需要支持低端设备和老旧浏览器：渲染压力在服务端，客户端只需解析 HTML，兼容性极佳
- 社交分享需要 OG 标签的场景：服务端直接输出完整的 Open Graph 标签，微信、Twitter、Facebook 分享预览完美呈现
⚡ SPA 最适合的场景
- 管理后台、数据看板：需要频繁操作、数据实时更新的内部管理系统
- 需要富交互的应用型页面：拖拽排序、实时预览、内联编辑、批量操作等复杂交互
- 需要离线能力的 PWA 应用：Service Worker 缓存、离线访问、消息推送等原生能力
- 团队已有成熟的前端框架技术栈：React、Vue、Angular 等团队可直接复用现有经验和组件库
- 需要复杂前端路由和状态管理的场景：多步骤表单、嵌套路由、全局状态共享等
🤝 两种模式共享的能力
SSR 和 SPA 两种模式共享同一套后端基础设施，以下能力在两种模式下均可使用，只是数据获取方式不同：
| 能力 | SSR 模式 | SPA 模式 |
|---|---|---|
| 内容管理 | 服务端直出 | API 获取 |
| 权限校验 | 服务端校验 | API Token 校验 |
| 审核工作流 | 服务端处理 | API 驱动 |
| 站内搜索 | 服务端渲染 | API 调用 |
| 中文分词 | 后端分词 | 后端分词 |
| SEO | 原生支持 | 需 SSR 或预渲染 |
| 模板系统 | Tera 渲染 | 前端框架自由选择 |
| 部署方式 | 无需构建 | 上传 dist 目录 |
💻 在线可视化编辑器
- Monaco 在线 IDE：浏览器里就是完整 IDE——语法高亮、自动补全、实时预览，无需安装任何本地工具
- Git 双向同步：本地用熟悉的编辑器开发模板，改动可推回变成草稿数据，正式版本只能走后台发布流程，Git 推送不绕过
- 发布前自动校验：语法错误、引用的公共片段文件是否存在，发布前自动跑一遍检查，只提醒不阻止操作
- 默认兜底渲染：子站缺少某类页面的专属模板时，平台级默认模板自动兜底，保证页面始终可访问
🎨 多主题配色
- 主题预设可配置：模板设计时固定可选范围，运行时不支持任意新增
- 浅色/深色一键切换：访客可自主切换（可关闭），选择记忆在本地
- 前后台风格统一：主题变量跟后台管理界面共用同一套设计语言
🧩 可视化组装 + 现成模板市场
- 菜单/卡片/聚合页可视化配置：导航菜单树形拖拽排序，内容卡片数据来源灵活配置（按栏目/手动挑选/全站最新/全站最热），首页和聚合页勾选使用哪些组件，不用碰代码
- Banner 和友情链接：多分类管理，手动添加或内容关联两种来源，按分类配置裁切比例
- 模板市场一键安装：系统自带丰富的现成模板可选，平台管理员下载进共享库，子站管理员也能直接下载到自己的草稿区，新版本可用会有提醒
- 模板库沉淀复用：某个子站已发布的模板可以收编回模板库，供其它子站复用，减少重复设计