> 版本：3.0

> 更新日期：2026-07-29

> 基于架构：Cloudflare Workers + D1 + KV + R2 + Cache API

---

目录

1. 系统概览与架构
2. 核心功能
3. 环境准备
4. 详细部署步骤
5. 系统初始化配置
6. 域名绑定与优化
7. 后台操作指南
8. 安全机制说明
9. 缓存策略与性能优化
10. 故障排查指南
11. 常见问题FAQ
12. 升级与维护建议

---

1. 系统概览与架构

1.1 系统特点

本博客系统基于 Cloudflare Workers 无服务器架构运行，具有以下核心优势：

• 高可用性：全球边缘节点部署，自动容灾
• 低延迟：内容就近分发，全球访问速度优化
• 高安全性：多层防护，包括 CSRF、CSP、PBKDF2 等
• 零运维：无需管理服务器，自动扩缩容
• 成本效益：免费额度充足，按需计费

1.2 技术架构

┌─────────────────────────────────────────────────────────┐
│                      Cloudflare Edge                    │
├─────────────────────────────────────────────────────────┤
│  用户请求 → CDN 边缘节点 → Workers 运行时               │
│           ↓                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐   │
│  │  Cache API  │  │  KV 存储    │  │   R2 存储    │   │
│  │  (缓存层)   │  │ (配置/会话) │  │  (图片文件)  │   │
│  └─────────────┘  └─────────────┘  └──────────────┘   │
│           ↓                                             │
│  ┌─────────────┐                                        │
│  │  D1 数据库  │  (文章、评论、分类)                    │
│  └─────────────┘                                        │
└─────────────────────────────────────────────────────────┘

1.3 数据流程

graph TD
    A[用户请求] --> B{请求类型}
    B -->|静态资源| C[Cache API]
    B -->|动态内容| D[Workers]
    D --> E[会话检查]
    E -->|需要认证| F[KV 读取会话]
    E -->|无需认证| G[D1 数据查询]
    D --> H[数据处理]
    H --> I[R2 图片访问]
    H --> J[页面渲染]
    J --> K[响应返回]
    K --> L[缓存更新]

---

2. 核心功能

2.1 内容管理

• 文章发布：支持 Markdown 编辑器，实时预览
• 文章编辑：在线编辑，支持标题、分类、密码设置
• 删除管理：支持单个删除，级联删除评论
• 图片上传：拖拽上传，自动生成随机文件名，按年月组织

2.2 分类系统

• 文章分类：支持多级分类，自定义分类名
• 类型区分：
• post：普通博客文章
• memo：随心说（类似推特/说说）

2.3 评论系统

• 访客评论：支持昵称、内容提交
• 审核机制：评论需管理员审核后显示
• 人机验证：集成 Cloudflare Turnstile（可选）
• 频率限制：IP 级别评论频率限制（60秒冷却）

2.4 安全功能

• 文章加密：支持单篇文章密码保护（PBKDF2 强哈希）
• 管理员认证：用户名密码登录，会话管理
• CSRF 防护：所有写操作强制 CSRF 校验
• XSS 防护：严格的输入过滤和输出转义

2.5 数据管理

• 全站备份：JSON 格式导出所有数据
• 数据恢复：从备份文件导入恢复
• 单篇导出：单篇文章导出为 Markdown 文件
• 缓存刷新：手动清理边缘缓存

---

3. 环境准备

3.1 必备条件

• Cloudflare 账号：免费账号即可
• 域名：
• 选项 A：使用自定义域名（推荐）
• 选项 B：使用 *.workers.dev 测试域名
• 浏览器：Chrome、Firefox、Safari 等现代浏览器
• 编辑器：
• 选项 A：VS Code + Cloudflare Workers 插件
• 选项 B：直接使用 Cloudflare Dashboard

3.2 Cloudflare 服务检查

在开始部署前，请确保您的 Cloudflare 账号已开通以下服务：

• Workers 服务（免费）
• D1 数据库（Beta，免费额度充足）
• KV 存储空间（免费）
• R2 对象存储（免费额度）

3.3 推荐工具安装

# 安装 Wrangler CLI（可选，用于本地开发）
npm install -g @cloudflare/wrangler
# 安装 VS Code 插件（推荐）
code --install-extensionryanwohara.cloudflare

---

4. 详细部署步骤

4.1 步骤 1：创建 D1 数据库

#### 4.1.1 创建数据库

1. 登录 Cloudflare Dashboard
2. 左侧导航栏选择 Workers & Pages > D1 SQL Database
3. 点击 Create database 按钮
4. 输入数据库名称：blog-db
5. 点击 Create 按钮创建
6. 复制并保存 Database ID（格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

#### 4.1.2 执行数据库初始化脚本

在数据库创建页面，点击 Console 按钮，依次执行以下 SQL 语句：

-- 1. 创建分类表
CREATE TABLE IF NOT EXISTS categories (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    slug TEXT
);

-- 2. 创建文章表
CREATE TABLE IF NOT EXISTS posts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT,
    content TEXT,
    cover_image TEXT,
    category_id INTEGER,
    password TEXT,
    type TEXT DEFAULT 'post',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    is_top INTEGER DEFAULT 0
);

-- 3. 创建评论表
CREATE TABLE IF NOT EXISTS comments (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    post_id INTEGER,
    author_name TEXT,
    content TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    status TEXT DEFAULT 'pending'
);

#### 4.1.3 数据表结构说明

分类表 (categories)

文章表 (posts)

评论表 (comments)

---

4.2 步骤 2：创建 KV 命名空间

#### 4.2.1 创建 KV 命名空间

1. 在左侧导航栏选择 Workers & Pages > KV
2. 点击 Create a namespace 按钮
3. 输入命名空间名称：blog-config
4. 点击 Add 按钮创建
5. 复制并保存 Namespace ID（格式：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）

#### 4.2.2 KV 存储内容规划

KV 命名空间将存储以下类型的数据：

• 系统配置：site_name, site_desc, footer_text 等
• 管理员凭据：admin_user, admin_pass
• 会话数据：session:{session_id}
• 文章会话：post_session:{post_id}
• 频率限制：rate:{ip}

---

4.3 步骤 3：创建 R2 存储桶

#### 4.3.1 创建 R2 Bucket

1. 在左侧导航栏选择 R2 Object Storage
2. 点击 Create bucket 按钮
3. 输入 Bucket 名称：blog-images
4. 点击 Create bucket 创建
5. 记录 Bucket 名称（不是ID，是名称）

#### 4.3.2 安全配置

1. 点击创建好的 Bucket，进入 Settings 标签
2. 找到 Public access 部分
3. 重要：保持 "Public Access" 开关 关闭 状态
4. 本系统通过 Worker 代码鉴权后代理访问图片，更加安全

#### 4.3.3 文件组织结构

上传的图片将按以下结构组织：

blog/
└── image/
    ├── 202607/
    │   ├── 1722191234567-abc1.jpg
    │   ├── 1722191234568-def2.png
    │   └── ...
    └── 202608/
        └── ...

---

4.4 步骤 4：创建 Worker 服务

#### 4.4.1 创建 Worker

1. 在左侧导航栏选择 Workers & Pages > Overview
2. 点击 Create Worker 按钮
3. 输入 Worker 名称：my-blog
4. 点击 Deploy 按钮部署（使用默认代码）
5. 部署完成后，点击 Edit code 进入编辑器

#### 4.4.2 配置资源绑定

在 Worker 详情页面，按以下步骤绑定资源：

1. 点击 Settings > Variables and Secrets 标签
2. 在 Bindings 部分，添加以下绑定：

1. 重要提示：Variable name 必须与代码中的 env.DB, env.CONFIG, env.BUCKET 完全一致

绑定类型	Variable name	资源选择	说明
D1 Database	DB	blog-db	数据库连接
KV Namespace	CONFIG	blog-config	配置存储
R2 Bucket	BUCKET	blog-images	图片存储

---

4.5 步骤 5：部署代码

#### 4.5.1 替换代码

1. 在 Worker 编辑器中，删除所有默认代码
2. 将提供的完整 JavaScript 代码粘贴进去
3. 确保代码完整，没有截断

#### 4.5.2 代码结构说明

// 配置常量
const KV_SITE_NAME = 'site_name';
const KV_SITE_DESC = 'site_desc';
// ... 其他常量
// 工具函数
function generateNonce() { ... }
function escapeHtml(unsafe) { ... }
// ... 其他工具函数
// Markdown 解析器
function parseMarkdown(text) { ... }
// 主逻辑
export default {
  async fetch(request, env, ctx) {
    // 路由处理
    // 返回响应
  }
};

#### 4.5.3 部署与测试

1. 点击 Save and Deploy 按钮部署代码
2. 部署成功后，会显示一个 *.workers.dev 域名
3. 访问该域名，应看到 "Config Error" 提示（这是正常的，因为还未初始化配置）

---

5. 系统初始化配置

5.1 访问 KV 管理界面

1. 在左侧导航栏选择 Workers & Pages > KV
2. 点击创建的 blog-config 命名空间
3. 点击 Add entry 按钮添加配置项

5.2 必需配置项

#### 5.2.1 基础配置

#### 5.2.2 管理员配置

#### 5.2.3 系统配置

- 以下是根据最新优化代码整理的 KV 命名空间键值说明表格：

补充说明

1. 必须手动添加的键：

• admin_user 和 admin_pass 是系统初始化的关键，必须手动在 KV 管理界面添加，否则无法登录后台。
• admin_pass 建议首次设置为 8 位以上 的明文密码，首次登录成功后，代码会自动将其升级为加密哈希存储。

1. 自动生成的键：

• 类型为 "会话管理"、"文章安全"、"评论限制" 和 "登录安全" 的键，均由代码在特定触发条件下自动写入，无需也不建议手动创建。
• 这些键通常带有过期时间（TTL），例如 session 为 24 小时，login_lock 为 1 小时，过期后会自动清理。

1. 默认值逻辑：

• 对于 site_name、site_desc 等系统配置，代码中内置了默认值。如果在 KV 中找不到对应的键，系统会使用这些默认值运行。为了保证个性化，建议在 KV 中手动设置。

5.3 可选配置项

#### 5.3.1 Turnstile 验证（推荐）

1. 访问 Cloudflare Turnstile
2. 创建新的 Site Key 和 Secret Key
3. 在 KV 中添加：

• turnstile_site_key: 0x4AAAAxxx... (Site Key)
• turnstile_secret_key: 0x4AAAAyyy... (Secret Key)

5.4 安全配置说明

#### 5.4.1 管理员密码安全

• 首次部署：可直接在 KV 中设置明文密码
• 首次登录后：系统会自动将密码升级为 PBKDF2 哈希
• 哈希格式：100000:saltHex:hashHex（迭代次数:盐值:哈希值）
• 建议：首次登录后，不要手动修改 KV 中的密码值

#### 5.4.2 密码强度要求

• 至少 12 个字符
• 包含大小写字母、数字和特殊符号
• 不要使用常见密码或个人信息

---

6. 域名绑定与优化

6.1 绑定自定义域名

#### 6.1.1 添加域名

1. 在 Worker 详情页，点击 Triggers 标签
2. 在 Custom Domains 部分，点击 Add Custom Domain
3. 输入您的域名（如 blog.example.com）
4. 点击 Add domain

#### 6.1.2 DNS 配置

Cloudflare 会自动：

• 添加 DNS 记录（CNAME 或 A 记录）
• 申请 SSL 证书（自动续期）
• 配置 CDN 加速

6.2 安全头配置

系统已自动配置以下安全头：

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: interest-cohort=()
Content-Security-Policy: default-src 'self'; ...

6.3 性能优化建议

#### 6.3.1 缓存策略

• HTML 页面：浏览器缓存 1 小时，边缘缓存 1 天
• R2 图片：缓存 1 年
• 静态资源：从 CDN 加载

#### 6.3.2 Gzip 压缩

Cloudflare 自动启用 Gzip 压缩，无需手动配置

#### 6.3.3 图片优化

• 上传前建议压缩图片
• 系统限制文件大小为 5MB
• 支持格式：JPG, PNG, GIF, WebP

---

7. 后台操作指南

7.1 访问后台

• 后台地址：https://你的域名/admin
• 登录页面：https://你的域名/login

7.2 发布文章

#### 7.2.1 普通文章

1. 在后台选择 文章 类型
2. 填写标题、内容、分类
3. 可选：设置访问密码、置顶
4. 点击 发布 按钮

#### 7.2.2 随心说

1. 选择 说说 类型
2. 直接填写内容（无需标题）
3. 点击 发布

7.3 图片上传

#### 7.3.1 拖拽上传

• 在编辑器中直接拖拽图片文件
• 自动上传到 R2 并插入 Markdown 语法

#### 7.3.2 按钮上传

• 点击 上传图片 按钮
• 选择文件后自动处理

7.4 分类管理

#### 7.4.1 添加分类

1. 在后台 分类管理 区域
2. 输入新分类名称
3. 点击 + 按钮

#### 7.4.2 删除分类

• 点击分类右侧的 删除 按钮
• 分类下的文章会自动移至 未分类

7.5 评论审核

#### 7.5.1 审核流程

1. 访客提交评论
2. 评论状态为 待审核
3. 在后台点击 通过 按钮
4. 评论状态变为 已审核，前台可见

#### 7.5.2 评论管理

• 查看、删除评论
• 批准/拒绝评论
• 查看关联文章

7.6 数据备份与恢复

#### 7.6.1 导出备份

1. 在后台点击 导出全站备份
2. 下载 JSON 格式备份文件
3. 文件包含：文章、分类、评论

#### 7.6.2 导入备份

1. 点击 导入备份 按钮
2. 选择之前导出的 JSON 文件
3. 系统会覆盖现有数据

#### 7.6.3 单篇导出

• 在文章列表点击 MD 按钮
• 下载单篇 Markdown 文件

7.7 缓存管理

#### 7.7.1 手动刷新缓存

1. 在后台右上角点击 刷新缓存
2. 系统会清除以下路径的缓存：

• 首页
• 站点地图
• 相关文章页
• 相关分类页

#### 7.7.2 自动缓存失效

以下操作会自动触发缓存刷新：

• 发布新文章
• 更新文章内容
• 删除文章
• 修改分类
• 审核评论

---

8. 安全机制说明

8.1 会话安全

#### 8.1.1 会话管理

• 生成随机 session_id
• 会话数据存储在 KV 中
• 绑定用户 IP 地址
• 24 小时自动过期

#### 8.1.2 会话验证

// 会话数据结构
{
  user: 'admin',
  ip: '203.0.113.1',
  csrf: 'random-csrf-token'
}

8.2 CSRF 防护

#### 8.2.1 实现机制

• 每个 session 关联唯一的 CSRF token
• 所有 POST 请求必须包含 _csrf 参数
• 后台验证 token 是否匹配

#### 8.2.2 防护范围

• 文章发布/编辑/删除
• 分类管理
• 评论审核
• 数据导入/导出

8.3 密码安全

#### 8.3.1 PBKDF2 哈希

• 算法：PBKDF2-HMAC-SHA256
• 迭代次数：100,000
• 随机盐值：16 字节
• 输出长度：256 位

#### 8.3.2 密码升级流程

明文密码 → 首次登录 → 自动检测 → PBKDF2 哈希 → 存储哈希值

8.4 XSS 防护

#### 8.4.1 输入过滤

• 所有用户输入经过 HTML 转义
• Markdown 解析前先转义

#### 8.4.2 输出转义

• 模板渲染时自动转义
• 特殊字符安全处理

8.5 文件上传安全

#### 8.5.1 文件类型验证

• 检查魔术字节（文件头）
• 支持格式：
• JPG: FF D8 FF
• PNG: 89 50 4E 47
• GIF: 47 49 46 38
• WebP: 52 49 46 46

#### 8.5.2 文件大小限制

• 最大文件大小：5MB
• 超过大小拒绝上传

#### 8.5.3 文件名处理

• 使用时间戳 + 随机字符串
• 按年月组织目录结构
• 防止文件名冲突

8.6 速率限制

#### 8.6.1 评论频率限制

• 每个 IP 60 秒内只能提交 1 次评论
• 超出限制会提示 "评论太快啦"

#### 8.6.2 实现机制

// 速率限制键名格式
rate:203.0.113.1
// 存储
await env.CONFIG.put(rateKey, Date.now().toString(), { expirationTtl: 60 });

---

9. 缓存策略与性能优化

9.1 缓存层级

浏览器缓存 (1小时) → 边缘缓存 (1天) → 源站计算

9.2 缓存规则

#### 9.2.1 HTML 页面

• 首页：/
• 分类页：/category/*
• 文章页：/post/*

缓存头：

Cache-Control: public, max-age=3600, stale-while-revalidate=86400

#### 9.2.2 R2 图片

• 路径：/r2/*

缓存头：

Cache-Control: public, max-age=31536000

#### 9.2.3 不缓存内容

• 后台页面：/admin*
• 登录页面：/login
• 评论提交：/comment
• 搜索结果：/search

9.3 缓存失效机制

#### 9.3.1 自动失效

• 发布文章：清除首页、相关分类缓存
• 更新文章：清除文章页、首页、相关分类缓存
• 删除文章：清除文章页、首页、相关分类缓存
• 修改分类：清除分类页、首页缓存

#### 9.3.2 手动失效

• 后台 刷新缓存 按钮
• 清除全站缓存

9.4 性能监控

#### 9.4.1 Cloudflare Analytics

• 访问量统计
• 响应时间分析
• 错误率监控
• 地理分布

#### 9.4.2 Worker 日志

• 审计日志：auditLog()
• 错误日志：Worker 控制台
• 性能日志：自定义记录

---

10. 故障排查指南

10.1 常见问题

#### 10.1.1 配置错误

症状：访问网站显示 "Config Error"

排查步骤：

1. 检查 KV 命名空间是否正确绑定
2. 验证 KV 中是否存在必需配置项
3. 检查 Variable name 是否正确

#### 10.1.2 数据库连接失败

症状：显示数据库相关错误

排查步骤：

1. 检查 D1 数据库是否正确绑定
2. 验证 Database ID 是否正确
3. 检查数据库表结构是否完整

#### 10.1.3 图片无法显示

症状：上传的图片无法访问

排查步骤：

1. 检查 R2 Bucket 是否正确绑定
2. 确认 R2 Public Access 已关闭
3. 检查文件上传路径是否正确

#### 10.1.4 登录失败

症状：无法登录后台

排查步骤：

1. 检查 KV 中 admin_user 和 admin_pass 是否存在
2. 验证密码是否正确（区分大小写）
3. 检查浏览器 Cookie 是否启用

10.2 调试技巧

#### 10.2.1 Worker 日志

1. 在 Worker 详情页点击 Logs 标签
2. 查看实时日志输出
3. 搜索错误信息

#### 10.2.2 浏览器控制台

1. 打开浏览器开发者工具
2. 查看 Network 标签
3. 检查请求和响应状态

#### 10.2.3 本地测试

# 使用 Wrangler 本地测试
wrangler dev my-blog
# 测试特定路由
curl https://your-worker.workers.dev/

---

11. 常见问题FAQ

11.1 功能相关

Q: 支持多语言吗？

A: 当前版本仅支持中文，但可以通过修改配置实现多语言支持。

Q: 支持多人协作吗？

A: 当前版本仅支持单管理员，如需多人协作需要修改认证逻辑。

Q: 支持评论回复吗？

A: 当前版本仅支持一级评论，回复功能可以在后续版本中添加。

Q: 文章可以设置定时发布吗？

A: 当前版本不支持，但可以通过 Workers Cron Triggers 实现。

11.2 技术相关

Q: Workers 有流量限制吗？

A: 免费计划每日 10 万次请求，付费计划无限制。

Q: D1 数据库有存储限制吗？

A: 免费计划 5GB 存储空间，足够个人博客使用。

Q: R2 存储有费用吗？

A: 免费计划每月 10GB 存储和 100万次 Class A 操作。

Q: 可以使用自己的域名吗？

A: 完全支持，只需在 Cloudflare 添加域名即可。

11.3 安全相关

Q: 密码忘记怎么办？

A: 可以在 KV 中重置 admin_pass 为新密码，首次登录后会自动哈希。

Q: 如何启用 HTTPS？

A: Cloudflare 自动为所有域名提供免费 SSL 证书。

Q: 支持双因素认证吗？

A: 当前版本不支持，但可以集成第三方 2FA 服务。

11.4 迁移相关

Q: 从 WordPress 迁移难吗？

A: 可以导出 WordPress XML，编写脚本转换为本系统格式。

Q: 数据可以导出吗？

A: 完全支持导出为 JSON 或 Markdown 格式。

Q: 可以迁移到其他平台吗？

A: 可以导出数据后转换为目标平台格式。

---

12. 升级与维护建议

12.1 定期维护任务

#### 12.1.1 每周

• 检查系统日志
• 审核待审核评论
• 备份全站数据

#### 12.1.2 每月

• 更新依赖库（如有）
• 检查安全公告
• 优化数据库性能

#### 12.1.3 每季度

• 评估系统性能
• 规划功能升级
• 检查费用使用情况

12.2 版本升级流程

#### 12.2.1 备份数据

# 导出当前数据
curl https://your-domain.com/export/json > backup.json

#### 12.2.2 测试升级

1. 创建测试 Worker
2. 部署新版本代码
3. 导入测试数据
4. 验证功能正常

#### 12.2.3 正式升级

1. 在测试环境验证通过
2. 备份生产数据
3. 部署新版本代码
4. 验证关键功能
5. 监控系统日志

12.3 性能优化建议

#### 12.3.1 数据库优化

-- 定期优化数据库
VACUUM;
-- 分析查询性能
EXPLAIN QUERY PLAN SELECT * FROM posts;

#### 12.3.2 缓存优化

• 根据访问模式调整缓存时间
• 监控缓存命中率
• 优化缓存失效策略

#### 12.3.3 资源优化

• 压缩图片文件
• 使用 WebP 格式
• 优化 CSS 和 JS

12.4 安全加固建议

#### 12.4.1 定期更新密码

• 每 90 天更换管理员密码
• 使用强密码生成器
• 启用密码历史记录

#### 12.4.2 启用安全日志

• 记录所有登录尝试
• 监控异常访问
• 设置告警机制

#### 12.4.3 数据加密

• 考虑加密敏感数据
• 使用 Cloudflare 加密功能
• 定期检查加密配置

---

附录

A. 配置参考

#### A.1 推荐配置

{
  "site_name": "技术博客",
  "site_desc": "分享技术与生活",
  "footer_text": "© 2026 My Blog. Powered by Cloudflare Workers",
  "admin_user": "admin",
  "page_size": 10
}

#### A.2 Turnstile 配置

{
  "turnstile_site_key": "0x4AAAAAAAxxxxxxxx",
  "turnstile_secret_key": "0x4AAAAAAAyyyyyyyyyyyy"
}

B. API 参考

#### B.1 主要端点

• GET / - 首页
• GET /post/:id - 文章页
• GET /category/:slug - 分类页
• GET /admin - 后台首页
• POST /publish - 发布文章
• POST /comment - 提交评论

#### B.2 API 格式

// 请求示例
POST /comment
Content-Type: application/x-www-form-urlencoded
post_id=1&author_name=Guest&content=Hello
// 响应示例
HTTP/1.1 302 Found
Location: /post/1?msg=success

C. 错误代码

---

附录：数据库性能优化说明（可选）

本系统的基础部署方案（主要文档中的 SQL 部分）仅包含必要的数据表结构，足以保证所有功能的正常运行。

然而，随着博客文章数量的增长（例如超过 500 篇），为了提升长期的查询速度和代码的健壮性，您可以选择执行以下 补充的 SQL 优化命令。

> 注意：这些命令均为非破坏性操作，添加后不会影响现有数据和代码运行。

---

1. 添加数据库索引

原理说明：

索引就像书籍的目录，能够让数据库在查找数据时“直达目标”，而无需逐行扫描。以下索引专门针对本博客系统的核心查询场景进行了优化。

优化效果：

• 加速首页文章列表加载（按时间排序）。
• 加速分类页面和“随心说”页面的过滤速度。
• 加速文章详情页评论列表的加载。

执行方法：

在 Cloudflare Dashboard 的 D1 > Console 中，依次执行以下 SQL 语句：

-- 1. 为文章表的“分类ID”建立索引
-- 作用：加速访问 /category/xxx 页面时的查询
CREATE INDEX IF NOT EXISTS idx_posts_category ON posts(category_id);
-- 2. 为文章表的“类型”建立索引
-- 作用：加速区分“文章(post)”和“随心说(memo)”的查询
CREATE INDEX IF NOT EXISTS idx_posts_type ON posts(type);
-- 3. 为文章表的“创建时间”建立索引（降序）
-- 作用：加速首页文章列表的按时间倒序排列
CREATE INDEX IF NOT EXISTS idx_posts_created ON posts(created_at DESC);
-- 4. 为评论表的“文章ID”建立索引
-- 作用：加速加载单篇文章下所有评论的查询
CREATE INDEX IF NOT EXISTS idx_comments_post ON comments(post_id);
-- 5. 为评论表的“审核状态”建立索引
-- 作用：加速后台管理页面筛选“待审核”评论
CREATE INDEX IF NOT EXISTS idx_comments_status ON comments(status);

---

2. 添加自动更新触发器

原理说明：

在当前的代码逻辑中，更新文章时需要显式地写入 updated_at=datetime("now")。

添加触发器后，数据库会监听 posts 表的更新动作，一旦检测到 UPDATE 操作，就会自动将 updated_at 字段刷新为当前时间。

优势：

• 防止遗漏：即使未来修改代码时忘记手动更新时间戳，数据库也会自动处理，确保“最后修改时间”的准确性。
• 简化代码：理论上可以允许代码简化（虽然不简化也能运行）。

执行方法：

在 D1 Console 中执行以下语句：

-- 创建触发器：每当更新 posts 表的一行数据时，自动更新 updated_at
CREATE TRIGGER IF NOT EXISTS update_posts_timestamp 
AFTER UPDATE ON posts
BEGIN
    UPDATE posts SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
END;

与现有代码的兼容性：

您不需要修改任何 JavaScript 代码。

• 现状：代码执行 UPDATE ... SET updated_at='10:00:00' -> 数据库更新 -> 触发器再次更新为 10:00:00。结果正常。
• 未来（可选）：如果您愿意，可以删除代码中 UPDATE 语句里的 updated_at 部分，完全交给触发器处理，代码会更简洁。

---

3. 优化总结

如何回滚：

如果您添加后发现不需要，可以在 D1 Console 中执行以下命令删除：

-- 删除索引
DROP INDEX IF EXISTS idx_posts_category;
DROP INDEX IF EXISTS idx_posts_type;
DROP INDEX IF EXISTS idx_posts_created;
DROP INDEX IF EXISTS idx_comments_post;
DROP INDEX IF EXISTS idx_comments_status;
-- 删除触发器
DROP TRIGGER IF EXISTS update_posts_timestamp;

以上是进行模板分离前版本的详细说明

---

📝 v3.0 “模板分离”更新日志

1. 更新概览

本次更新对博客系统进行了架构级重构。将原本嵌入在 Worker JS 代码中的 HTML/CSS 模板剥离，移至 Cloudflare R2 存储桶进行托管。实现了代码逻辑与页面样式的完全解耦。

2. 目的与达到的效果

🎯 目的

• 解耦：让开发者可以专注于逻辑开发，而设计者可以专注于样式调整，两者互不干扰。
• 热更新：修改博客样式或布局不再需要重新部署 Worker，只需在后台修改模板文件保存即可生效。
• 可维护性：解决单文件代码过长导致难以维护的问题，将 3000+ 行代码清晰分层。

✨ 达到效果

• 零部署修改样式：调整 CSS 颜色、字体、排版，无需动用代码编辑器。
• 在线可视化编辑：后台新增“主题设置”面板，支持在线编辑 HTML/CSS。
• 代码体积优化：Worker 代码体积显著减小，执行效率提升。
• 完全兼容：保留所有原有功能（置顶、加密、评论、说说等），无缝升级。

3. 文件结构变更

原 R2 结构（可能为空或仅有图片）

<bucket>
└── (无特定结构)

新 R2 结构（标准化目录）

<bucket>
│
├── blog
│   ├── avatar/                 (系统自动生成)
│   │   └── avatar-xxxxx.jpg    
│   │
│   ├── image/                  (系统自动生成)
│   │   └── 202310/             
│   │       └── xxxxx.jpg       
│   │
│   └── themes/
│       └── default/            (核心模板目录，需手动创建)
│           ├── admin/          
│           │   └── layout.html (后台骨架模板)
│           │
│           ├── style.css       (全局样式)
│           ├── layout.html     (前台骨架模板)
│           ├── sidebar.html    (左侧栏模板)
│           ├── memo_feed.html  (右侧栏模板)
│           └── footer.html     (页脚模板)

4. 核心功能变更详解

📦 模板系统分离

• 原理：Worker 启动时自动检测 R2 中的模板文件。
• 占位符系统：引入 <!--{variable}--> 语法，用于 Worker 动态插入数据。
• 例如：<!--{content_html}--> 会被替换为文章列表或文章内容。
• 严格摘录：所有 HTML 模板文件均严格从源代码中提取，保留了原代码的 DOM 结构、类名和 ID，确保样式 100% 兼容。

🎨 样式文件提取

• 将原 getStyles() 函数中的 CSS 代码完整提取为 style.css。
• 保留所有 CSS 变量（如 --accent-color），确保配色一致性。
• 保留响应式断点（1024px），确保移动端适配不变。

⚙️ 后台管理增强

• 新增路由：/admin/theme 提供在线文件管理。
• 在线编辑器：集成代码高亮编辑器，支持实时修改模板。
• 热加载机制：保存模板后，Worker 自动清除内存缓存，刷新页面即可看到效果。
• 导航栏修复：修复了重构初期遗漏的“刷新缓存”、“退出登录”等按钮。

5. 操作指南

🚀 部署/升级步骤

1. 更新 Worker 代码：将最新的 JS 代码粘贴至 Cloudflare Worker 编辑器并部署。
2. 创建 R2 目录：在 R2 存储桶中手动创建路径 blog/themes/default/ 以及子目录 admin。
3. 上传模板文件：将提供的 5 个模板文件（见下文）内容复制保存，并上传至对应路径。

• style.css -> blog/themes/default/
• layout.html -> blog/themes/default/
• sidebar.html -> blog/themes/default/
• memo_feed.html -> blog/themes/default/
• footer.html -> blog/themes/default/
• admin/layout.html -> blog/themes/default/admin/

1. 验证：访问博客首页，确认样式加载正常。

🛠️ 日常使用

• 修改样式：访问 https://您的域名/admin/theme，点击 style.css 进行编辑。
• 修改布局：同上，编辑 layout.html 或 sidebar.html。
• 刷新缓存：如果修改后样式未更新，点击后台右上角“🚀 刷新缓存”。

6. 完善的细节记录

1. 后台骨架独立：为后台管理页面设立了独立的 admin/layout.html，避免前后台样式冲突。
2. CSRF 保护适配：模板分离过程中，完整保留了 CSRF Token 的注入逻辑，确保后台操作的安全性。
3. Markdown 解析器保留：完美兼容版 Markdown 解析器保留在 Worker 逻辑中，确保文章渲染效果不变。
4. 压缩上传保留：头像和图片上传的压缩逻辑保留在 Worker 中，保证图片加载速度。

7. 模板文件内容参考

• style.css: 包含所有 CSS 样式，严格遵循原代码。
• layout.html: 包含 <head> 头部、三栏布局结构。
• sidebar.html: 包含头像、站点名称、分类导航。
• memo_feed.html: 包含右侧“随心说”卡片列表。
• footer.html: 包含页脚版权信息。
• admin/layout.html: 包含后台管理页面的基础骨架。

---

总结：本次更新成功实现了模板与逻辑的分离，极大提升了系统的可维护性和二次开发的便捷性，是博客系统向模块化迈进的重要一步。