Flare Stack Blog部署教程

本指南旨在帮助你快速、稳健地将博客部署到 Cloudflare 平台。我们提供两种自动化部署方案，你可以根据自己的习惯选择。

核心配置预览

在开始之前，先看看这两种方式的差异：

方案	平台	免费额度	特点
方案一	GitHub Actions	2000 分钟/月	灵活性高，可以手动触发部署，自动清除 CDN 缓存，后续更新方便
方案二	Cloudflare Workers Builds	3000 分钟/月	配置简单，无需管理 Token，但只能通过push来触发部署

两种的额度都挺慷慨的，根本用不完，其中GitHub Actions对于公开仓库是免费用，2000分钟是对于私有仓库的限制。

第一阶段：前置准备（通用）

无论选择哪种部署方式，你都需要先准备好这些「基础设施」。

1. Fork 本仓库 (必备)

这是所有部署的第一步。点击仓库右上角的 Fork 按钮，将项目源码克隆到你自己的 GitHub 账号下。

只有 Fork 到自己的账号，你才有权配置密钥和触发自动部署。

2. 注册与启用服务

Cloudflare 账号：点击注册。注意需绑定付款方式以启用免费额度充足的 R2 和 Workers AI 服务（个人博客通常不会产生费用）。
域名托管：将你的域名 DNS 托管到 Cloudflare，这是使用免费 CDN 和自动化部署的前提。

3. 创建 Cloudflare 资源

在 Cloudflare Dashboard 中创建以下资源并记录其名称/ID：

R2 存储桶：用于存储图片和静态资源（记录存储桶名称）。
D1 数据库：用于存储文章和配置（记录 Database ID）。
KV 命名空间：用于缓存（记录 Namespace ID）。
Queues 消息队列：用于处理异步任务（队列名称为 blog-queue）。

4. 获取核心凭证 (IDs)

你需要以下两个 ID 贯穿整个部署过程：

Account ID：域名的概览页右侧查看。
Zone ID：域名的概览页右侧查看。
Account Home -> 你的域名

5. 创建 API 令牌 (Token)

我们需要赋予部署脚本操作你账户的权限。点击右上角 头像 -> 我的个人资料 -> API 令牌 -> 创建令牌。

A. CDN 刷新令牌 (必填)

模板：使用「编辑区域 DNS」模板。
权限：区域 -> 清除缓存 -> 清除。
资源：包括 -> 所有区域（或指定域名）。
用途：应用部署后自动强制更新 CDN 缓存。
点击查看大图
CDN清除token摘要

B. 部署令牌 (仅方案一需要)

模板：使用「编辑 Cloudflare Workers」模板。
权限：添加更多 -> D1 -> 编辑。
资源：包括 -> 所有区域（或指定域名）
用途：允许 GitHub Actions 远程部署代码和执行数据库迁移。
点击查看大图
部署token摘要

6. 创建 GitHub OAuth App

为了实现 GitHub 登录功能：

前往 GitHub Settings -> Developer Settings -> OAuth Apps -> New OAuth App。
Homepage URL: https://<你的域名>
Authorization callback URL: https://<你的域名>/api/auth/callback/github
创建后记录 Client ID，并生成一个新的 Client Secret。

第二阶段：选择部署方案

方案一：GitHub Actions 自动部署

通过 GitHub 的服务器进行构建和分发。

0. 启用Actions

默认情况下，GitHub 为了安全考虑，不会在 Fork 的仓库中自动启用 Actions。需要在仓库设置里启用

1. 配置仓库变量

在 GitHub 仓库中，进入 Settings -> Secrets and variables -> Actions，点击 New repository secret 添加以下变量：

A. 必填部署变量配置（Secrets - CI/CD）

变量名	说明
`CLOUDFLARE_API_TOKEN`	步骤 5中的部署令牌
`CLOUDFLARE_ACCOUNT_ID`	你的 Account ID
`D1_DATABASE_ID`	D1 数据库 ID
`KV_NAMESPACE_ID`	KV 命名空间 ID
`BUCKET_NAME`	R2 桶名称

B. 必填运行时配置（Secrets - 运行时）

变量名	说明
`BETTER_AUTH_SECRET`	终端运行 `openssl rand -hex 32` 生成
`BETTER_AUTH_URL`	应用 URL（如 `https://blog.example.com`）
`ADMIN_EMAIL`	管理员邮箱
`GH_CLIENT_ID`	GitHub OAuth Client ID
`GH_CLIENT_SECRET`	GitHub OAuth Client Secret
`CLOUDFLARE_ZONE_ID`	你的 Zone ID
`CLOUDFLARE_PURGE_API_TOKEN`	步骤 5 中的刷新令牌
`DOMAIN`	博客域名（如 `blog.example.com`）

C. 选填运行时统计配置

变量名	说明
`UMAMI_SRC`	Umami 实例 URL
`UMAMI_API_KEY`	Umami API Key (Umami Cloud)
`UMAMI_USERNAME`	Umami 用户名 (自部署)
`UMAMI_PASSWORD`	Umami 密码 (自部署)
`VITE_UMAMI_WEBSITE_ID`	这个既是运行时变量，也是构建时变量，不过要填Variables不是Secrets，见下

D. 选填构建时个性化配置 (Variables) 这些变量通常放在 Variables 栏目，以 VITE_ 开头，会注入到客户端代码。

变量名	说明
`VITE_BLOG_TITLE`	博客标题
`VITE_BLOG_NAME`	导航栏显示的短名称
`VITE_BLOG_AUTHOR`	作者名称
`VITE_BLOG_DESCRIPTION`	主页显示的描述
`VITE_BLOG_GITHUB`	GitHub 主页链接
`VITE_BLOG_EMAIL`	联系邮箱
`VITE_UMAMI_WEBSITE_ID`	Umami Website ID

3. 触发部署

进入 GitHub 仓库的 Actions 标签页，启用并手动运行 Deploy 工作流。后续你每次推送代码到仓库，系统都会自动更新博客。

方案二：Cloudflare Dashboard 直接部署

直接在 Cloudflare Workers上连接仓库。

1. 修改配置文件

在本地或 GitHub 网页端将 wrangler.example.jsonc 复制并重命名为 wrangler.jsonc，替换其中的 ID 和名称。

JSON

{
  "keep_vars": true, // 每次构建不清楚运行时变量
  "routes": [{ "pattern": "blog.example.com", "custom_domain": true }],
  "d1_databases": [{ "binding": "DB", "database_id": "你的-D1-ID", ... }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "你的-R2-名称", ... }],
  "kv_namespaces": [{ "binding": "KV", "id": "你的-KV-ID", ... }]
}

2. 创建并连接工程

在 Cloudflare Dashboard 进入 Workers 和 Pages -> 创建 -> 连接到 Git。
选择你的仓库，并配置构建设置：
- Framework preset: None
- Build command: bun run build
- Deploy command: bun run deploy
添加环境变量：
- 在构建配置中添加 BUN_VERSION: 1.3.5。
- 添加所有以 VITE_ 开头的前端变量（如 VITE_BLOG_TITLE）。

3. 配置运行时变量

部署完成后，进入该 Worker 的 设置 -> 变量 -> 机密，点击 添加机密，填入 BETTER_AUTH_SECRET、GITHUB_CLIENT_ID、ADMIN_EMAIL 等敏感配置，具体变量详见方案一的运行时变量表格。

注意变量名：在 Cloudflare Dashboard 中，Github的变量名必须使用全称：
GH_CLIENT_ID → GITHUB_CLIENT_ID
GH_CLIENT_SECRET → GITHUB_CLIENT_SECRET

CDN 缓存：方案二由于不经过 GitHub Actions，不会自动清除缓存。每次部署后，请在博客后台「设置」页面手动点击「清除 CDN 缓存」，如果还没注册管理员账号，出现网页样式丢失无法导航，前往cloudflare面板里清除缓存

第三阶段：可选进阶配置

1. 图片优化 (Cloudflare Images)

在管理页为你的域名开启图片转换。每月 5000 次免费转换额度，能极大提升博客图片的加载速度。

2. 邮件系统 (Resend)

获取 API Key 后，填入博客后台的「设置」页面。
开启后，你的博客将支持：密码登录、验证码安全校验、评论回复邮件通知。

个性化配置

博客基础信息

项目通过环境变量配置博客的基本信息，这些变量在构建时注入到客户端代码

变量名	说明
`VITE_BLOG_TITLE`	博客标题
`VITE_BLOG_NAME`	导航栏显示的短名称
`VITE_BLOG_AUTHOR`	作者名称
`VITE_BLOG_DESCRIPTION`	主页显示的描述
`VITE_BLOG_GITHUB`	GitHub 主页链接
`VITE_BLOG_EMAIL`	联系邮箱

网站图标

步骤 1：生成图标文件包

使用 Real Favicon Generator 在线工具

步骤 2：替换项目文件

解压下载的文件，将文件覆盖到仓库的 public/ 目录

第四阶段：后续维护与更新

同步上游更新

当原项目发布新功能或修复 Bug 时，你只需：

进入你 Fork 的仓库主页。
点击 Sync fork -> Update branch。
自动部署：
- 方案一：GitHub Actions 会感应到代码更新并自动触发部署。
- 方案二：Cloudflare 会自动检测到 GitHub 的新提交并开始构建。

关于合并冲突：该项目将所有个性化配置都抽离到了环境变量中，直接同步上游代码通常不会产生任何合并冲突。

常见问题

1. 部署成功，网页却打不开，某些操作报错？如何排查问题？

如果部署过程没报错，但访问时出现错误（如 500 错误或白屏），通常按以下步骤排查：

检查控制台：按下 F12 打开浏览器开发者工具，查看 Console 标签页是否有报错信息。
查看实时日志：在 Cloudflare Dashboard 进入对应的 Worker 项目，点击 Observability (观测) -> Live。保持该页面打开的同时访问你的博客，即可捕获实时的报错日志，通常能直接看到是哪个环境变量缺失或配置错误。
检查环境变量：绝大多数打不开的情况都是因为环境变量未正确设置。

2. 构建时变量 vs 运行时变量有什么区别？

由于该项目是全栈项目，环境变量的使用场景有所不同：

构建时变量：由 VITE_ 前缀开头。这些变量会在项目编译打包时「硬编码」进客户端脚本中。如果这些变量配置错误，必须重新触发部署构建才能生效。

运行时变量：服务器端代码在运行时读取。这些变量通常在服务端执行逻辑中起作用。

不同方案下的配置方式：

方案一 (GitHub Actions)：你只需要在 GitHub 仓库的 Settings -> Secrets and variables -> Actions 中统一配置所有的 Secrets 和 Variables。部署流水线会自动处理它们的归类。

方案二 (Cloudflare Dashboard)：
- 构建时变量：在连接 GitHub 仓库初期的「高级选项」中配置；若项目已创建，可在 Worker 的 Settings -> Build -> Variables 中配置。

运行时变量：在 Worker 的 Settings -> Variables and Secrets 中配置。

3. Umami 如何配置？

Umami Cloud 配置示例：

Bash

UMAMI_SRC=https://cloud.umami.is
UMAMI_API_KEY=your-cloud-api-key
VITE_UMAMI_WEBSITE_ID=your-website-id
# 不需要设置 UMAMI_USERNAME 和 UMAMI_PASSWORD

自部署 Umami 配置示例：