Typecho-Workers 安装指南

在前面的几篇文章中，我梳理了把博客搬迁到 Cloudflare 边缘无服务器（Serverless / Edge）架构的完整过程：从最开始处理 10ms CPU 超时、平滑迁移历史文章与笔记，到构建平台层零 CPU 缓存，再到重构主题并实现评论动静分离。

在这段重构与打磨后，这个名为 Typecho-Workers 的项目已经在我的生产环境平稳运行。对于同样希望摆脱传统 VPS 维护繁琐、搭建一套轻量且低成本个人博客的朋友，这篇文章将详细介绍这套系统的全貌，并提供一份清晰完整的部署上手指南。

一、系统全貌与核心特性

Typecho-Workers 是基于经典博客系统 Typecho 的数据库设计，使用 TypeScript 在 Astro + Cloudflare Workers 架构下重写的一套现代博客系统。

它拥有静态博客的低维护成本与极速响应，同时完整保留了动态博客的在线写作后台、原生评论互动与插件扩展能力。

1. 现代边缘计算架构

运行环境：跑在 Cloudflare 全球 300+ 节点的 Workers 运行时中；
数据与存储：使用 Cloudflare 原生的 D1（基于 SQLite 的边缘关系型数据库）与 R2（S3 兼容且免公网出流量费用的对象存储）；
边缘级缓存：通过 Workers Caching 平台层深度接管页面存储，公共页面命中时直接在 CDN 边缘直出，Worker 不消耗 CPU 时间，全球 TTFB 延迟低至 15~45ms；
全家桶闭环：无需依赖第三方托管数据库或云存储服务，一个 Cloudflare 账号即可完成全部部署。

2. 前台浏览与互动体验

Warm 响应式主题：界面简洁克制，内嵌 InstantClick 预加载引擎，站内文章点击切换几乎无白屏等待；
评论动静分离：文章正文由 CDN 纯静态缓存，评论区通过客户端异步接口按需拉取（支持滚动触底与鼠标悬停预加载），评论者称呼和邮箱由前端 LocalStorage 本地回填，彻底杜绝缓存隐私泄露；
朋友圈微动态（Notes）：原生支持微贴与随笔发布，内置自适应九宫格网格、+N 多图折叠、HTML5 音视频播放器，以及自研的 2KB 极轻量图片灯箱 ViewImage.js；
全格式 Feed 订阅：内置 RSS 2.0、Atom 1.0 与 RSS 1.0 聚合订阅源。

3. 后台管理与扩展生态

Typecho 原生操作体验：熟悉的文章、独立页面、评论审核、分类与标签管理界面；
查询读模型缓存（Query Cache）：为后台高频列表建立读模型缓存，列表切换响应耗时由 300ms 降至 5~15ms；
Passkey 免密登录：支持通过 WebAuthn 使用指纹（Touch ID）、Face ID 或安全密钥秒级登入后台；
Engine 智能引擎：编辑器内置流式写作辅助、独创纯文本 Markdown Diff 比对、文章发布自动提炼摘要，以及站内搜索范围自定义配置；
Notifier 邮件通知：评论提交与博主回复支持通过通用 SMTP 或 Resend API 异步非阻塞投递；
动态防垃圾防护：集成 Antispam 动态蜜罐与 Cloudflare Turnstile 免感知人机校验。

二、安装部署指南

部署一套属于自己的 Typecho-Workers 非常简单，整个过程通常只需要 10 到 15 分钟。

1. 前置准备

在开始前，你需要准备好以下环境与账号：

一个 Cloudflare 账号（免费版计划完全足够）；
本地安装好 Node.js（≥ 22.12.0）与 Bun（≥ 1.2，推荐安装命令：curl -fsSL https://bun.sh/install | bash）；
全局安装 Cloudflare CLI 工具：npm install -g wrangler（或使用 bunx wrangler）。

2. 克隆项目与安装依赖

打开终端，拉取项目代码并安装依赖：

git clone https://github.com/Tokinx/typecho-workers.git
cd typecho-workers
bun install

3. 创建 Cloudflare 边缘资源

在终端登录 Cloudflare 并创建所需的数据库与存储桶：

# 登录 Cloudflare
wrangler login

# 1. 创建 D1 关系型数据库
wrangler d1 create typecho-db

# 2. 创建 R2 对象存储桶（用于存放上传的图片与媒体附件）
wrangler r2 bucket create typecho-uploads

# 3. 创建 Workers KV 命名空间（供多级缓存使用）
wrangler kv namespace create TYPECHO_CACHE

命令执行完毕后，终端会分别输出 D1 的 database_id 和 KV 的 id，请记下这几串值。

4. 配置 `wrangler.toml`

在项目根目录下找到 wrangler.toml，更新其中的资源绑定配置：

# 填入实际生成的 D1 database_id
[[d1_databases]]
binding = "DB"
database_name = "typecho-db"
database_id = "你的-D1-Database-ID"

# 填入实际生成的 KV namespace ID
[[kv_namespaces]]
binding = "TYPECHO_CACHE"
id = "你的-KV-Namespace-ID"

# 针对 Cloudflare Workers Free 计划配置密码迭代次数
[vars]
PBKDF2_ITERATIONS = "50000"

注意：Cloudflare Workers 免费版的 CPU 上限是 10ms。为了避免初始化安装与登录时因标准 60 万次 PBKDF2 计算超时，请务必将 PBKDF2_ITERATIONS 设置为 "50000"。

接下来，通过安全 Secret 注入密码 Pepper 密钥（用于防拖库碰撞增强）：

openssl rand -hex 32 | wrangler secret put PASSWORD_PEPPER

如果希望防止未授权的初始化抢注，还可以设置一个安装令牌：

wrangler secret put INSTALL_TOKEN

5. 构建与部署

执行部署命令，Wrangler 会自动构建项目并将 Worker 发布到 Cloudflare：

bun run deploy

部署完成后，终端会打印出分配给你的 Worker 访问域名（例如 https://typecho-workers.<你的子域>.workers.dev）。

如果更偏爱 Git 自动部署，也可以将仓库推送到 GitHub，在 Cloudflare Workers 控制台直接绑定 Git 仓库，并在 Build variables 中配置 TYPECHO_D1_DATABASE_ID 等参数，后续每次 git push 都会自动触发构建。

6. 执行初始化向导

打开浏览器，访问部署好的域名，系统会自动重定向到 /install 安装向导：

如果之前配置了 INSTALL_TOKEN，在表单中填入对应的令牌；
填写站点名称、管理员用户名、密码以及电子邮箱；
点击「开始安装」，系统会在约 7ms 内完成初始表结构的初始化与管理员账号创建。

安装完成后，直接访问 /admin 即可登入管理后台。

7. 启用与配置推荐插件

进入后台后，点击顶部导航的「插件」管理页面，建议按需启用以下核心插件：

typecho-plugin-cache（边缘缓存）：启用后系统会自动接管公共页面向 Workers Caching 平台层的注册与失效更新，并将全站查库开销压降 98% 以上；
typecho-plugin-notes（微动态/随笔）：启用后会在后台自动挂载独立的笔记单页发布界面，并在前台导航添加笔记展示流；
typecho-plugin-engine（智能引擎）：进入设置页填入你的大模型 API 密钥（兼容各类 OpenAI / DeepSeek 端点），即可解锁编辑器写作润色与全自动 AI 摘要生成；
typecho-plugin-notifier（邮件通知）：填入 SMTP 参数或 Resend API 密钥，以便在收到新评论时及时获得邮件提醒。

三、旧博客数据迁移（可选）

如果你原本有正在运行的 WordPress 或经典 PHP 版 Typecho 博客，可以通过项目内置的迁移脚本一键平滑搬迁数据：

从 WordPress 迁移（XML 导出文件）

将 WordPress 导出的 WXR XML 文件放到本地，执行迁移命令：

# 生成导入 SQL 并自动规划媒体转存
bun run db:migrate:wordpress -- \
  --target cloudflare \
  --source WordPress.xml \
  --author-id 1 \
  --site-url https://你的新域名.com \
  --download-media

随后通过 Wrangler 将生成的 SQL 批量写入生产库：

wrangler d1 execute typecho-db --remote --file=./drizzle/wordpress-import.sql

从 PHP 版 Typecho 迁移（SQLite 数据库）

如果旧站是使用 SQLite 数据库的 Typecho，直接指定数据库文件和上传附件目录即可：

bun run db:migrate:typecho -- \
  --target cloudflare \
  --source /path/to/typecho.db \
  --uploads /path/to/usr/uploads \
  --site-url https://你的新域名.com

迁移完成后，由于密码哈希算法升级，在终端运行密码重置命令重新设置管理员密码即可正常登入：

bun run reset-password:cloudflare -- --user admin

四、写在最后

把博客迁到 Cloudflare 边缘之后，最大的改变莫过于日常维护心智负担的归零。

不再需要为云服务器每月的账单精打细算，不再需要维护 Nginx、PHP-FPM 和 MySQL 进程，也不用担心操作系统补丁和端口被恶意扫描。在 CDN 边缘缓存和轻量存储的配合下，日常访问的资源消耗几乎只是免费配额的一个微小零头。

一个干净、顺手、成本极低的个人自留地，让人能重新把专注力放回到记录与写作本身。

如果你在部署或使用过程中遇到任何问题，欢迎在项目的 GitHub 仓库提交 Issue 或参与讨论：

GitHub 项目地址：https://github.com/Tokinx/typecho-workers