526 lines
11 KiB
Markdown
526 lines
11 KiB
Markdown
# Mizuki 内容分离完整指南
|
||
|
||
本指南详细说明如何在 Mizuki 中使用内容分离功能,包括基础配置、私有仓库、CI/CD 部署等所有场景。
|
||
|
||
## 📖 目录
|
||
|
||
- [快速开始](#-快速开始)
|
||
- [ENABLE_CONTENT_SYNC 控制开关](#-enable_content_sync-控制开关)
|
||
- [配置方式](#-配置方式)
|
||
- [私有仓库](#-私有仓库配置)
|
||
- [CI/CD 部署](#-cicd-部署)
|
||
- [常用命令](#-常用命令)
|
||
- [故障排查](#-故障排查)
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 新手推荐: 本地模式 (最简单)
|
||
|
||
**不需要任何配置**,直接开始使用:
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/matsuzaka-yuki/Mizuki.git
|
||
cd Mizuki
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 直接开发
|
||
pnpm dev
|
||
```
|
||
|
||
内容存放在 `src/content/` 和 `public/images/` 目录,与代码一起管理。
|
||
|
||
### 进阶: 启用内容分离
|
||
|
||
如果需要将内容独立管理(多人协作、私有内容、独立版本控制),按以下步骤配置:
|
||
|
||
```bash
|
||
# 1. 创建 .env 文件
|
||
cp .env.example .env
|
||
|
||
# 2. 编辑 .env,启用内容分离
|
||
ENABLE_CONTENT_SYNC=true
|
||
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
||
|
||
# 3. 同步内容
|
||
pnpm run sync-content
|
||
|
||
# 4. 启动开发
|
||
pnpm dev
|
||
```
|
||
|
||
---
|
||
|
||
## 🎛️ ENABLE_CONTENT_SYNC 控制开关
|
||
|
||
### 功能说明
|
||
|
||
`ENABLE_CONTENT_SYNC` 是一个一键开关,控制是否启用内容分离功能。
|
||
|
||
| 值 | 说明 | 适用场景 |
|
||
|---|---|---|
|
||
| `false` 或未设置 | **禁用内容分离** (默认) | 新手、个人博客、内容较少 |
|
||
| `true` | **启用内容分离** | 团队协作、私有内容、大量文章 |
|
||
|
||
### 配置位置
|
||
|
||
在项目根目录的 `.env` 文件中:
|
||
|
||
```bash
|
||
# 禁用内容分离 (使用本地内容)
|
||
ENABLE_CONTENT_SYNC=false
|
||
|
||
# 或启用内容分离 (从远程仓库同步)
|
||
ENABLE_CONTENT_SYNC=true
|
||
```
|
||
|
||
### 使用场景对比
|
||
|
||
#### 场景 1: 本地模式 (推荐新手)
|
||
|
||
**特点**:
|
||
- ✅ 无需额外配置
|
||
- ✅ 内容和代码一起管理
|
||
- ✅ 适合个人博客、小型项目
|
||
|
||
**配置**:
|
||
```bash
|
||
# .env (或不创建 .env 文件)
|
||
ENABLE_CONTENT_SYNC=false
|
||
```
|
||
|
||
**工作流程**:
|
||
```bash
|
||
# 直接编辑 src/content/ 下的文章
|
||
pnpm dev
|
||
|
||
# 提交时一起提交代码和内容
|
||
git add .
|
||
git commit -m "Update content"
|
||
git push
|
||
```
|
||
|
||
#### 场景 2: 独立仓库（分离）模式
|
||
|
||
**特点**:
|
||
- ✅ 内容独立仓库管理
|
||
- ✅ 支持私有内容仓库
|
||
- ✅ 多人协作方便
|
||
- ✅ 独立的内容版本控制
|
||
|
||
**配置**:
|
||
```bash
|
||
# .env
|
||
ENABLE_CONTENT_SYNC=true
|
||
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
||
```
|
||
|
||
**工作流程**:
|
||
```bash
|
||
# 自动同步内容后启动
|
||
pnpm dev
|
||
|
||
# 内容在独立仓库编辑
|
||
cd /path/to/Mizuki-Content
|
||
# 编辑文章
|
||
git add .
|
||
git commit -m "Update article"
|
||
git push
|
||
```
|
||
|
||
### 模式切换
|
||
|
||
#### 从本地切换到独立仓库
|
||
|
||
1. 创建内容仓库 (参考 [CONTENT_MIGRATION.md](./CONTENT_MIGRATION.md))
|
||
2. 编辑 `.env`:
|
||
```bash
|
||
ENABLE_CONTENT_SYNC=true
|
||
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
||
```
|
||
3. 同步内容: `pnpm run sync-content`
|
||
|
||
#### 从独立仓库切换回本地
|
||
|
||
1. 编辑 `.env`:
|
||
```bash
|
||
ENABLE_CONTENT_SYNC=false
|
||
```
|
||
2. 直接开发: `pnpm dev`
|
||
|
||
---
|
||
|
||
## ⚙️ 配置方式
|
||
|
||
### 环境变量说明
|
||
|
||
在 `.env` 文件中配置:
|
||
|
||
```bash
|
||
# ============================================
|
||
# 功能开关
|
||
# ============================================
|
||
|
||
# 是否启用内容分离功能
|
||
# false = 使用本地内容 (推荐新手)
|
||
# true = 从远程仓库同步内容
|
||
ENABLE_CONTENT_SYNC=false
|
||
|
||
# ============================================
|
||
# 内容仓库配置 (仅当 ENABLE_CONTENT_SYNC=true 时需要)
|
||
# ============================================
|
||
|
||
# 内容仓库地址
|
||
# 支持 HTTPS 和 SSH 方式
|
||
# 公开仓库: https://github.com/username/repo.git
|
||
# 私有仓库 (SSH): git@github.com:username/repo.git
|
||
# 私有仓库 (Token): https://TOKEN@github.com/username/repo.git
|
||
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
||
|
||
# 内容目录路径 (默认 ./content 一般无需改动)
|
||
CONTENT_DIR=./content
|
||
```
|
||
|
||
### 配置示例
|
||
|
||
#### 示例 1: 完全本地 (最简单)
|
||
|
||
```bash
|
||
# .env
|
||
ENABLE_CONTENT_SYNC=false
|
||
```
|
||
|
||
或者**不创建 `.env` 文件**,直接使用本地内容。
|
||
|
||
#### 示例 2: 公开仓库 (HTTPS)
|
||
|
||
```bash
|
||
# .env
|
||
ENABLE_CONTENT_SYNC=true
|
||
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
||
```
|
||
|
||
#### 示例 3: 私有仓库 (SSH)
|
||
|
||
```bash
|
||
# .env
|
||
ENABLE_CONTENT_SYNC=true
|
||
CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 自动构建触发 (内容更新时)
|
||
|
||
### 问题
|
||
|
||
启用内容分离后，默认只有代码仓库更新会触发部署，内容仓库更新**不会**自动触发。
|
||
|
||
### 解决方案
|
||
|
||
**推荐使用 Repository Dispatch**，5 步快速配置，适用所有部署平台。
|
||
|
||
详细步骤请查看:
|
||
- **[自动构建触发快速参考](./AUTO_BUILD_TRIGGER.md)** - 最简洁的配置指南 ⭐
|
||
- **[部署文档 - 完整说明](./DEPLOYMENT.md#内容仓库更新触发构建)** - 包含多种方案
|
||
- **[内容仓库配置指南](../Mizuki-Content/.github/workflows/README.md)** - 工作流详细说明
|
||
|
||
---
|
||
|
||
## 🔐 私有仓库配置
|
||
|
||
完全支持私有内容仓库! 推荐使用 SSH 方式,安全且方便。
|
||
|
||
### 方案 A: SSH 密钥 (推荐)
|
||
|
||
#### 1. 生成 SSH 密钥
|
||
|
||
```bash
|
||
# 推荐使用 Ed25519
|
||
ssh-keygen -t ed25519 -C "your_email@example.com"
|
||
|
||
# 或使用 RSA
|
||
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
|
||
```
|
||
|
||
按提示操作,默认保存到 `~/.ssh/id_ed25519`。
|
||
|
||
#### 2. 添加公钥到 Git 平台
|
||
|
||
```bash
|
||
# 查看公钥
|
||
cat ~/.ssh/id_ed25519.pub
|
||
|
||
# Windows PowerShell
|
||
Get-Content ~/.ssh/id_ed25519.pub
|
||
```
|
||
|
||
**GitHub**:
|
||
- Settings → SSH and GPG keys → New SSH key
|
||
- 粘贴公钥内容
|
||
|
||
**GitLab**:
|
||
- Preferences → SSH Keys → Add new key
|
||
|
||
**Gitee**:
|
||
- 设置 → SSH 公钥 → 添加公钥
|
||
|
||
#### 3. 配置 Mizuki
|
||
|
||
在 `.env` 文件中使用 SSH URL:
|
||
|
||
```bash
|
||
ENABLE_CONTENT_SYNC=true
|
||
CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git
|
||
```
|
||
|
||
#### 4. 测试连接
|
||
|
||
```bash
|
||
# 测试 GitHub 连接
|
||
ssh -T git@github.com
|
||
|
||
# 测试 GitLab 连接
|
||
ssh -T git@gitlab.com
|
||
|
||
# 同步内容
|
||
pnpm run sync-content
|
||
```
|
||
|
||
### 方案 B: HTTPS + Personal Access Token
|
||
|
||
#### 1. 生成 Token
|
||
|
||
**GitHub**:
|
||
- Settings → Developer settings → Personal access tokens → Generate new token
|
||
- 权限: 勾选 `repo` (完整访问)
|
||
|
||
**GitLab**:
|
||
- Preferences → Access Tokens
|
||
- Scopes: `read_repository`
|
||
|
||
**Gitee**:
|
||
- 设置 → 私人令牌 → 生成新令牌
|
||
- 权限: `projects` (读取)
|
||
|
||
#### 2. 配置 .env
|
||
|
||
```bash
|
||
ENABLE_CONTENT_SYNC=true
|
||
CONTENT_REPO_URL=https://YOUR_TOKEN@github.com/your-username/Mizuki-Content-Private.git
|
||
```
|
||
|
||
⚠️ **安全提示**:
|
||
- **不要将 `.env` 提交到 Git!** (已在 `.gitignore` 中)
|
||
- Token 具有完整权限,请妥善保管
|
||
|
||
---
|
||
|
||
## 🌐 CI/CD 部署
|
||
|
||
### 快速配置
|
||
|
||
所有部署平台都使用相同的自动同步机制:
|
||
- ✅ `pnpm build` 执行前自动运行 `prebuild` 钩子
|
||
- ✅ 根据 `ENABLE_CONTENT_SYNC` 决定是否同步内容
|
||
- ✅ 同步失败不会中断构建,回退到本地内容
|
||
|
||
**只需配置环境变量,无需修改构建命令!**
|
||
|
||
### 环境变量配置
|
||
|
||
在部署平台添加以下环境变量:
|
||
|
||
| 变量名 | 值 | 说明 |
|
||
|-------|---|------|
|
||
| `ENABLE_CONTENT_SYNC` | `true` | 启用内容分离 |
|
||
| `CONTENT_REPO_URL` | 仓库地址 | 内容仓库的 URL |
|
||
|
||
### 支持的平台
|
||
|
||
- ✅ **GitHub Pages** - 使用 GitHub Actions
|
||
- ✅ **Vercel** - 环境变量配置
|
||
- ✅ **Netlify** - 环境变量配置
|
||
- ✅ **Cloudflare Pages** - 环境变量配置
|
||
|
||
### 详细配置指南
|
||
|
||
不同平台的具体配置步骤、私有仓库认证、故障排查等详细信息，请查看：
|
||
|
||
📖 **[部署指南](./DEPLOYMENT.md)** - 完整的部署文档，包含：
|
||
- GitHub Pages 自动部署配置
|
||
- Vercel 部署详细步骤
|
||
- Netlify 部署配置
|
||
- Cloudflare Pages 部署
|
||
- 私有仓库认证配置
|
||
- 常见问题故障排查
|
||
|
||
---
|
||
|
||
## 📋 常用命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `pnpm run init-content` | 运行交互式初始化向导 |
|
||
| `pnpm run sync-content` | 手动同步内容仓库 |
|
||
| `pnpm run check-env` | 检查环境变量配置 |
|
||
| `pnpm dev` | 启动开发服务器 (自动同步) |
|
||
| `pnpm build` | 构建项目 (自动同步) |
|
||
|
||
### 自动同步时机
|
||
|
||
当 `ENABLE_CONTENT_SYNC=true` 时,以下命令会自动同步内容:
|
||
|
||
- `pnpm dev` - 开发前自动同步
|
||
- `pnpm build` - 构建前自动同步
|
||
|
||
同步失败不会中断开发,会显示警告并继续。
|
||
|
||
---
|
||
|
||
## 🔍 故障排查
|
||
|
||
### 问题 1: 提示 "未启用内容分离功能"
|
||
|
||
**原因**: `ENABLE_CONTENT_SYNC` 未设置或设置为 `false`。
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查 .env 文件
|
||
cat .env
|
||
|
||
# 确认有以下配置
|
||
ENABLE_CONTENT_SYNC=true
|
||
```
|
||
|
||
### 问题 2: 提示 "未设置 CONTENT_REPO_URL"
|
||
|
||
**原因**: 启用了内容分离但未配置仓库地址。
|
||
|
||
**解决**:
|
||
```bash
|
||
# 在 .env 中添加
|
||
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
||
```
|
||
|
||
### 问题 3: 私有仓库认证失败
|
||
|
||
**SSH 方式**:
|
||
```bash
|
||
# 测试 SSH 连接
|
||
ssh -T git@github.com
|
||
|
||
# 应该看到: Hi username! You've successfully authenticated...
|
||
```
|
||
|
||
如果失败,检查:
|
||
- SSH 密钥是否生成: `ls ~/.ssh/`
|
||
- 公钥是否添加到 GitHub
|
||
- SSH agent 是否运行: `ssh-add -l`
|
||
|
||
**HTTPS + Token 方式**:
|
||
- 检查 Token 是否有效
|
||
- 检查 Token 权限是否正确 (`repo` 权限)
|
||
- 确认 URL 格式: `https://TOKEN@github.com/user/repo.git`
|
||
|
||
### 问题 4: .env 文件不生效
|
||
|
||
**检查清单**:
|
||
|
||
1. 文件位置正确 (项目根目录)
|
||
```bash
|
||
ls -la .env # Linux/Mac
|
||
dir .env # Windows
|
||
```
|
||
|
||
2. 文件格式正确
|
||
```bash
|
||
# ✅ 正确
|
||
ENABLE_CONTENT_SYNC=true
|
||
|
||
# ❌ 错误 (多余空格)
|
||
ENABLE_CONTENT_SYNC = true
|
||
|
||
# ❌ 错误 (不需要引号,除非值中有空格)
|
||
ENABLE_CONTENT_SYNC="true"
|
||
```
|
||
|
||
3. 文件权限可读
|
||
```bash
|
||
chmod 644 .env # Linux/Mac
|
||
```
|
||
|
||
4. 运行检查命令
|
||
```bash
|
||
pnpm run check-env
|
||
```
|
||
|
||
### 问题 5: 内容同步失败
|
||
|
||
```bash
|
||
# 手动同步内容
|
||
pnpm run sync-content
|
||
|
||
# 检查内容目录
|
||
ls -la content/
|
||
|
||
# 手动克隆内容仓库
|
||
git clone https://github.com/your-username/Mizuki-Content.git content
|
||
```
|
||
|
||
### 问题 6: 部署时内容未同步
|
||
|
||
**Vercel/Netlify**:
|
||
- 确认环境变量已添加
|
||
- 检查构建日志,查看同步步骤是否执行
|
||
- 确认 Token 在部署环境有效
|
||
|
||
**GitHub Actions**:
|
||
- 检查工作流配置
|
||
- 查看 Actions 运行日志
|
||
- 确认 Secrets 已正确添加
|
||
|
||
---
|
||
|
||
## 💡 最佳实践
|
||
|
||
### 新手建议
|
||
|
||
1. **从本地模式开始** - 不需要额外配置,立即可用
|
||
2. **内容稳定后再分离** - 等内容积累到一定程度
|
||
3. **使用 SSH 方式** - 比 Token 更安全方便
|
||
|
||
### 进阶用户
|
||
|
||
1. **使用独立仓库模式** - 清晰的版本控制
|
||
2. **内容仓库添加 CI** - 自动检查文章格式、图片优化等
|
||
3. **分支管理** - main 分支用于生产,develop 用于预览
|
||
|
||
### 团队协作
|
||
|
||
1. **统一环境变量** - 团队成员使用相同的配置
|
||
2. **权限控制** - 内容仓库设置为私有,精细控制访问权限
|
||
3. **Git Hooks** - 提交前检查文章格式、图片大小等
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [内容迁移指南](./CONTENT_MIGRATION.md) - 如何从单仓库迁移到分离模式
|
||
- [内容仓库结构](./CONTENT_REPOSITORY.md) - 内容仓库的推荐结构
|
||
- [主 README](../README.zh.md) - 项目总体说明
|
||
|
||
---
|
||
|
||
## 🤝 需要帮助?
|
||
|
||
- 查看 [GitHub Issues](https://github.com/matsuzaka-yuki/Mizuki/issues)
|
||
- 阅读 [完整文档](../README.zh.md)
|
||
- 运行 `pnpm run check-env` 检查配置
|
||
|
||
祝你使用愉快! 🎉
|