ShiZhui
de0b5d22a8
All checks were successful
Build and Deploy / build-deploy (push) Successful in 26s
129 lines
6.5 KiB
Markdown
129 lines
6.5 KiB
Markdown
# 在线内容管理方案：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 为平滑叠加，不推翻现有结构。
|
||
- 凭据不写入仓库与文档。
|