ShiZhui
de0b5d22a8
All checks were successful
Build and Deploy / build-deploy (push) Successful in 26s
6.5 KiB
6.5 KiB
在线内容管理方案：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规则，需用户确认授权后执行。
阶段一：基础设施
- 服务器初始化：Nginx、防火墙（见
docs/DEPLOY.md）。✅ - 安装 Gitea（二进制或 docker），数据目录规划，配置
git.shizhui.xyz。✅ - Nginx 反向代理 Gitea，申请 HTTPS 证书（含 git 子域名）。✅
- 创建管理员账号，建立本项目仓库，推送现有代码。✅
已完成的 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 自动部署（已完成）✅
- 安装并注册 Gitea Actions Runner。✅
- act_runner 0.6.1，host 模式（不依赖 Docker，省内存）
- systemd 服务
act_runner，labels: ubuntu-latest:host - 服务器已装 Node 20 供构建
- 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 连接层。 - 排查手段（下次继续）：
- 已在服务器临时部署最小化 config.yml 用于隔离（只含 title/pubDate/body）。
- 需从浏览器 F12 控制台读取 Sveltia 打印的具体校验错误（最直接）。
- 若最小配置可用，则逐项加回字段定位；若仍报错，排查 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
- 在站点加入
/admin（Sveltia CMS 页面 +config.yml）。 - 在 Gitea 注册 OAuth 应用，把 client_id 配到 CMS。
- 配置内容模型（collections）：blog、projects，字段对齐现有 frontmatter。
- 配置媒体上传目录、视频嵌入支持。
阶段四：验证
- 登录 /admin → 新建测试文章 → 发布 → 确认自动构建并上线。
- 移交维护文档（如何写文章、加项目、插图插视频）。
6. 待确认 / 前置条件
- 用户授权 SSH 连接服务器执行安装（提供临时密码或 SSH 密钥，勿用长期密码）
- 确认服务器配置（内存/CPU）足以同时运行 Gitea + 构建
- 确认 git 子域名方案（git.shizhui.xyz）并添加 DNS 解析
- 是否需要多个维护账号 / 权限分级
7. 备注
- 当前阶段网站已可用，内容用 Markdown 文件维护；CMS 为平滑叠加，不推翻现有结构。
- 凭据不写入仓库与文档。