ShiZhui
db90280989
All checks were successful
Build and Deploy / build-deploy (push) Successful in 46s
100 lines
4.5 KiB
Markdown
100 lines
4.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。
|
||
6. workflow：push 主分支 → 构建 → 发布到 `/var/www/shizhui`。
|
||
|
||
### 测试访问地址（备案完成前）
|
||
- 网站：http://8.137.165.96:8080
|
||
- Gitea：需在本地 hosts 绑定，或经 SSH 隧道访问（域名直连会被劫持）
|
||
|
||
### 阶段三：接入 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 为平滑叠加，不推翻现有结构。
|
||
- 凭据不写入仓库与文档。
|