98 lines
3.8 KiB
Markdown
98 lines
3.8 KiB
Markdown
# BlogFlare
|
||
|
||
BlogFlare 是一个基于 **SvelteKit** 和 **Cloudflare D1** 构建的现代化、轻量级博客系统。它的设计灵感来源于 Typecho 的经典主题 VOID，旨在提供极速的访问体验和极低的托管成本。
|
||
|
||
## ✨ 特性
|
||
|
||
- ⚡️ **极速体验**: 采用 SvelteKit 框架，提供极致的页面加载速度和流畅的交互体验。
|
||
- ☁️ **边缘计算架构**: 完全依托于 Cloudflare 强大的全球网络。使用 Cloudflare Pages 进行前端托管，D1 数据库进行数据存储，实现真正的零运维与超低成本。
|
||
- 📝 **强大的 Markdown 支持**: 内置 Markdown 渲染引擎（结合了 `marked` 和 `highlight.js` 等），并支持代码高亮与 DoIt 风格的提示块（Admonition）。
|
||
- 🎨 **优雅的设计**: 界面灵感源自广受好评的 VOID 主题，排版舒适，注重纯粹的阅读体验。
|
||
- 🏷️ **完善的内容管理**: 包含文章发布、标签系统及用户认证的基础数据结构支持。
|
||
|
||
## 🚀 快速开始
|
||
|
||
> [!IMPORTANT]
|
||
> 本项目强制使用 `pnpm` 作为包管理器，请勿使用 `npm` 或 `yarn`。
|
||
|
||
### 1. 克隆项目与安装依赖
|
||
|
||
```bash
|
||
git clone git@git.seahi.me:seahi/blogflare.git
|
||
cd blogflare
|
||
pnpm install
|
||
```
|
||
|
||
### 2. 初始化与同步数据库迁移
|
||
|
||
本项目全面采用 Cloudflare D1 规范化迁移链体系。不管是初次安装还是升级扩展，只需应用增量迁移（`0000_initial.sql`、`0001_add_series.sql` 等）即可自动实现幂等同步：
|
||
|
||
`0000_initial.sql` 同时兼容空数据库和旧版 `schema.sql` 已初始化的数据库。生产升级前仍应先创建 D1 备份；不要再对生产库执行已移除的破坏性 `schema.sql`。
|
||
|
||
#### 本地开发环境同步：
|
||
|
||
```bash
|
||
pnpm run db:migrate:local
|
||
# 或直接运行 wrangler: pnpm exec wrangler d1 migrations apply blogflare-db --local
|
||
```
|
||
|
||
如果需要强制清空本地开发数据库并重新从初始状态加载迁移数据，可以运行：
|
||
|
||
```bash
|
||
pnpm run db:reset:local
|
||
```
|
||
|
||
#### 部署与生产远端库同步：
|
||
|
||
部署更新或正式发布之前，请将完整的迁移链条应用到云端 D1 远端数据库中：
|
||
|
||
```bash
|
||
pnpm run db:migrate:remote
|
||
# 或直接运行 wrangler: pnpm exec wrangler d1 migrations apply blogflare-db --remote
|
||
```
|
||
|
||
### 3. 启动本地开发服务器
|
||
|
||
```bash
|
||
pnpm run dev
|
||
|
||
# 或者启动服务器并在浏览器中自动打开
|
||
pnpm run dev -- --open
|
||
```
|
||
|
||
### 4. 配置后台认证
|
||
|
||
生产环境的 `/admin` 路由强制验证 Cloudflare Access JWT。请在 Cloudflare Pages 项目的设置页面中配置以下两个加密变量，也可以使用 `pnpm exec wrangler pages secret put <变量名> --project-name=blogflare` 交互式写入。Pages 不支持在 `wrangler.jsonc` 中声明 secrets；缺少任意一项时后台会拒绝访问：
|
||
|
||
- `CF_ACCESS_TEAM_DOMAIN`：例如 `https://your-team.cloudflareaccess.com`
|
||
- `CF_ACCESS_AUD`：Access Application 的 Audience (AUD) Tag
|
||
|
||
本地生产预览可复制 `.dev.vars.example` 为 `.dev.vars` 并填入真实值。开发服务器会保留仅限 `dev` 模式的本地认证旁路。
|
||
|
||
## 📦 构建与部署
|
||
|
||
### 构建项目
|
||
|
||
```bash
|
||
pnpm run build
|
||
```
|
||
|
||
你可以使用 `pnpm run preview` 来预览生成的生产版本构建。
|
||
|
||
### 部署到 Cloudflare
|
||
|
||
项目已经配置了 `@sveltejs/adapter-cloudflare`，可以通过连接 GitHub/GitLab 仓库到 Cloudflare Pages 实现自动构建部署，或者使用 Wrangler CLI 进行手动发布：
|
||
|
||
```bash
|
||
pnpm exec wrangler pages deploy .svelte-kit/cloudflare
|
||
```
|
||
|
||
_(注意：正式部署前请确保在 Cloudflare 仪表盘中创建了对应的 D1 数据库，并绑定到项目中)_
|
||
|
||
## 🛠️ 核心技术栈
|
||
|
||
- [SvelteKit](https://kit.svelte.dev/)
|
||
- [Cloudflare Pages](https://pages.cloudflare.com/) & [Cloudflare D1](https://developers.cloudflare.com/d1/)
|
||
- [Vite](https://vitejs.dev/)
|
||
- Markdown 解析与净化: `marked`, `highlight.js`, `sanitize-html`, `mdsvex`
|