shizhui_website/docs/CMS.md

在线内容管理方案：Gitea + Sveltia CMS

目标：让维护人员通过网页在线编辑博客/项目，富文本写作、上传图片、插入视频， 发布后自动构建上线。全部自托管，数据在自己服务器。

1. 方案概述

采用 Gitea（自托管 Git）+ Sveltia CMS（在线写作后台）+ Gitea Actions（自动部署）。

• Sveltia CMS 是 Decap CMS（原 Netlify CMS）的现代继任者，原生支持 Gitea 后端， 通过 Gitea OAuth 登录鉴权，无需额外搭建鉴权中转服务。
• 内容仍以 Markdown 形式存放在 Gitea 仓库，结构化、可版本管理、可回滚。
• 站点保持静态，安全、运维轻。

2. 架构

维护人员浏览器
  │
  ├─► https://shizhui.xyz/admin     Sveltia CMS 后台（写作/上传/发布）
  │        │  Gitea OAuth 登录
  │        ▼
  └─► https://git.shizhui.xyz       自托管 Gitea（内容 .md + 代码仓库）
           │  提交触发 Gitea Actions
           ▼
       npm run build  →  /var/www/shizhui  →  Nginx  →  https://shizhui.xyz

3. 组件角色

组件	作用	访问地址
Astro 站点	内容展示（已完成）	shizhui.xyz
Gitea	自托管 Git、内容存储、CI（Actions）	git.shizhui.xyz
Sveltia CMS	在线写作后台（静态页面，挂在站点 /admin）	shizhui.xyz/admin
Gitea Actions Runner	监听提交，自动构建并发布	服务器内部
Nginx	托管静态站 + 反向代理 Gitea	—

4. 编辑能力

• 富文本 + Markdown 双模式：标题、加粗、列表、链接、代码块、引用等。
• 图片：拖拽上传，自动存入仓库 public/ 或指定媒体目录。
• 视频：
  • 推荐嵌入式（B站 / YouTube），文章中粘贴嵌入；不占服务器带宽。
  • 也可自托管：上传视频文件，用 HTML5 <video> 播放（需注意带宽/存储）。
  • 视频渲染能力由 Astro 站点模板提供，CMS 负责录入。

5. 落地步骤（待用户授权 SSH 后执行）

以下涉及服务器操作，按 .kiro/steering/commands.md 规则，需用户确认授权后执行。

阶段一：基础设施

1. 服务器初始化：Nginx、防火墙（见 docs/DEPLOY.md）。
2. 安装 Gitea（二进制或 docker），数据目录规划，配置 git.shizhui.xyz。
3. Nginx 反向代理 Gitea，申请 HTTPS 证书（含 git 子域名）。
4. 创建管理员账号，建立本项目仓库，推送现有代码。

阶段二：CI 自动部署

5. 安装并注册 Gitea Actions Runner。
6. 编写 workflow：push 到主分支 → npm ci && npm run build → 发布到 /var/www/shizhui。

阶段三：接入 CMS

7. 在站点加入 /admin（Sveltia CMS 页面 + config.yml）。
8. 在 Gitea 注册 OAuth 应用，把 client_id 配到 CMS。
9. 配置内容模型（collections）：blog、projects，字段对齐现有 frontmatter。
10. 配置媒体上传目录、视频嵌入支持。

阶段四：验证

11. 登录 /admin → 新建测试文章 → 发布 → 确认自动构建并上线。
12. 移交维护文档（如何写文章、加项目、插图插视频）。

6. 待确认 / 前置条件

• 用户授权 SSH 连接服务器执行安装（提供临时密码或 SSH 密钥，勿用长期密码）
• 确认服务器配置（内存/CPU）足以同时运行 Gitea + 构建
• 确认 git 子域名方案（git.shizhui.xyz）并添加 DNS 解析
• 是否需要多个维护账号 / 权限分级

7. 备注

• 当前阶段网站已可用，内容用 Markdown 文件维护；CMS 为平滑叠加，不推翻现有结构。
• 凭据不写入仓库与文档。