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. 创建管理员账号，建立本项目仓库，推送现有代码。✅

已完成的 Gitea 部署细节

• 版本：Gitea 1.25.5（二进制，SQLite 数据库，省内存）
• 运行：systemd 服务 gitea，监听 127.0.0.1:3000
• 反代：Nginx → https://git.shizhui.xyz（证书已含该子域名）
• 配置：/etc/gitea/app.ini（关闭开放注册、启用 Actions）
• 账号：
  • shizhui（管理员）
  • developer（普通用户 / 内容维护者）
  • 两账号密码已单独设置，不记录于文档；首次登录后请自行修改。
• 仓库：shizhui/shizhui_website（已推送全部代码）
• 推送方式：因域名未备案，经公网域名会被劫持，推送通过 SSH 端口转发 （本地 3000 → 服务器 127.0.0.1:3000）完成。

阶段二：CI 自动部署（已完成）✅

5. 安装并注册 Gitea Actions Runner。✅
   • act_runner 0.6.1，host 模式（不依赖 Docker，省内存）
   • systemd 服务 act_runner，labels: ubuntu-latest:host
   • 服务器已装 Node 20 供构建
6. workflow：push 主分支 → 构建 → 发布到 /var/www/shizhui。✅
   • 文件：.gitea/workflows/deploy.yml
   • 已实测：git push → Gitea → Runner → npm ci + build → 发布，全链路打通。

阶段三：接入 CMS（进行中）

• public/admin/ 已就绪（Sveltia CMS + config.yml，backend 指向 Gitea IP）
• Gitea 已注册 OAuth 应用（Sveltia CMS，公开客户端 + PKCE）
  • client_id 已写入 config.yml
  • redirect_uri: http://8.137.165.96:8080/admin/
• 待验证：浏览器登录 /admin 的 OAuth 流程能否纯前端跑通（Sveltia 对 Gitea 的 token 交换是否需要额外中转服务）。需先放行安全组 3000 端口。

测试访问地址（备案完成前）

• 网站：http://8.137.165.96:8080
• Gitea：http://8.137.165.96:3000 （需安全组放行 3000）
• CMS：http://8.137.165.96:8080/admin/

阶段三：接入 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 为平滑叠加，不推翻现有结构。
• 凭据不写入仓库与文档。