# 在线内容管理方案：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/
- ✅ 安全组已放行 3000，浏览器可访问 Gitea
- ⚠️ **待解决问题**：访问 /admin 时报
  "There is an error in the CMS configuration. Please solve the issue and try again."
  - 已排除：YAML 语法正确；已移除 local_backend 和无效的 locale 字段
  - 据 Sveltia 文档，该错误出现在登录屏，通常因 collection/field 的 name
    含非法字符（空格、`.`、`*`）或配置结构不被接受。本项目 name 均为合法英文，
    故疑点转向某个字段写法（datetime 的 format 组合 / value_type / summary 过滤器）
    或 backend 连接层。
  - 排查手段（下次继续）：
    1. 已在服务器临时部署最小化 config.yml 用于隔离（只含 title/pubDate/body）。
    2. 需从浏览器 F12 控制台读取 Sveltia 打印的具体校验错误（最直接）。
    3. 若最小配置可用，则逐项加回字段定位；若仍报错，排查 backend/CORS。
  - 相关：Sveltia 文档提到自托管 Gitea 需在 Gitea 配置启用 CORS
    （[server].CORS / cors 段），本项目 Gitea 尚未配置 CORS，登录后调用 API
    可能受影响（此项与"配置错误"不同阶段，但一并待处理）。
- 备注：CMS 在线编辑非阻塞项，静态站点 + CI 自动部署已可用；
  内容当前可用 Markdown 文件方式维护，CMS 调通后再切到在线编辑。

### 测试访问地址（备案完成前）
- 网站：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 为平滑叠加，不推翻现有结构。
- 凭据不写入仓库与文档。