ABNCMS/开发手册 产品官网 GitHub 中文EN
首页/开发手册

ABNCMS 开发手册#

一份从入门到上线的完整技术文档。ABNCMS 是一款面向 Cloudflare Workers + D1 + 外部图床 的免费开源轻量级 CMS——零服务器、零托管费用、生产依赖仅 Hono,全部能力落在 Cloudflare 免费计划内。

本手册覆盖产品介绍、环境搭建、本地开发、部署上线、系统架构、后台使用、API 与图床、缓存机制,以及常见问题与故障排查。当前版本 v0.2.7,基于 Cloudflare Workers。

真正零成本

全部跑在 Cloudflare 免费计划内,无需服务器、无需绑卡。

生来全球加速

页面缓存分发到全球边缘,访客就近访问,自带 HTTPS 与 DDoS 防护。

有后台,随时更新

可视化后台写文章传图片,保存后前台立即更新,无需重新构建。

边缘缓存极速

命中缓存 0 次数据库查询,发布自动让缓存代数 +1,全站秒级更新。

核心设计目标匿名访问命中页面缓存时 0 次 D1 查询、0 次 KV 读写;未命中时不超过 5 次 D1 查询。所有可选消耗功能都有后台开关,小站可一键降到「只缓存 HTML + 少量读」。

核心能力#

一个 Worker 进程同时完成前台 SSR、后台管理、API 与定时任务,功能覆盖面广却保持极轻。

前台#

  • 首页大横幅、文章流(伪静态 /p/{slug}.html)、独立页面(/page/{slug}.html)
  • 自定义导航、分类 / 标签 / 归档、全文搜索、Markdown 渲染
  • AI 摘要、上下篇、相关阅读、评论(默认关闭统计)
  • RSS(/feed.xml)、Sitemap(/sitemap.xml)、JSON-LD 结构化数据
  • 两栏侧栏(热门文章、分类、标签、友情链接)、响应式布局

后台#

  • 登录保护:PBKDF2 密码 + KV 会话 + 同 IP 失败限流 + Turnstile 人机验证
  • 文章 CRUD、Markdown 双栏编辑器、AI 摘要标签
  • 图床地址与 Token 可视化配置、站点 LOGO 上传、第三方统计代码
  • 独立页面、导航菜单、友情链接、媒体库、分类、评论审核
  • 全量导出 / 导入备份、站点设置、修改密码、概览面板

定时任务(Cron)#

每日 UTC 03:00 自动清理 30 天前的访问明细与 90 天前的垃圾评论,并写入一条心跳记录。

环境要求#

项目要求说明
Node.js20+(推荐 22 LTS)运行 Wrangler 与本地开发
Python3.8+仅辅助脚本与冒烟测试,纯标准库无需 pip
Cloudflare 账号免费计划即可无需绑卡
WranglerdevDependency 自带用 npx wrangler 调用
workers.dev 子域需预先注册一次OAuth 登录态无法用 API 创建,需在控制台手动注册
提示生产依赖只有 hono 一个包,TypeScript 严格模式,Wrangler 内置 esbuild 打包,无需额外构建工具。

快速开始#

从克隆源码到看见页面,最短路径如下。

1

克隆项目

git clone https://github.com/baiyirui/abncms.git && cd abncms

2

安装依赖

npm install

3

准备配置

复制 wrangler.example.jsonc 为 wrangler.jsonc,.dev.vars.example 为 .dev.vars,填入资源 ID 与管理员密码。

4

初始化本地库并启动

npm run db:local → npx wrangler d1 execute cf-press-db --local --file=./seed.sql → npm run dev

5

访问

浏览器打开 http://127.0.0.1:8787,后台在 /admin/login。

完整命令
# 克隆并进入项目
git clone https://github.com/baiyirui/abncms.git && cd abncms
npm install
# 配置(填入 account_id / D1 / KV ID)
cp wrangler.example.jsonc wrangler.jsonc
cp .dev.vars.example .dev.vars
# 初始化本地数据库
npm run db:local
npx wrangler d1 execute cf-press-db --local --file=./seed.sql
# 启动本地开发服务器
npm run dev   # → http://127.0.0.1:8787

本地开发#

Wrangler 提供与生产一致的本地运行环境,D1、KV、定时任务都可在本地模拟。

常用命令#

命令作用
npm run dev启动本地服务器(wrangler dev)
npm run typecheckTypeScript 类型检查(tsc --noEmit)
npm run builddry-run 构建产物到 dist/,不部署
npm run db:local本地建表(schema.sql)
npm run smoke冒烟测试,校验核心页面与接口
npx wrangler types根据配置生成 Worker 类型声明

初始管理员#

仅当用户表为空、首次登录时,系统用 .dev.vars 里的 ADMIN_PASSWORD 创建初始管理员。登录后请立即在后台「设置」中修改密码。

注意如果本地曾用过其他账号(如示例里的 baiyirui)登录失败,可删除本地 D1 的用户数据,让 ensureAdmin() 按 .dev.vars 重建 admin。本地库位于 .wrangler/ 目录。

冒烟测试#

SMOKE_ADMIN_USER=admin SMOKE_ADMIN_PASS='你的密码' \
  python scripts/smoke_test.py http://127.0.0.1:8787

部署上线#

推荐使用辅助脚本自动创建远程资源并回写 ID,然后一条命令部署到全球边缘。

1

登录 Cloudflare

npx wrangler login

2

创建远程资源

python scripts/setup_remote.py 自动建 D1 / KV / Vectorize,并把返回的 ID 写回 wrangler.jsonc。

3

初始化数据库

全新库执行 npm run db:remote;从旧版升级不要重跑 schema,改用 npm run db:migrate 增量迁移。

4

注入 Secrets

设置管理员密码、配置加密主密钥等(见下一节)。

5

部署

npm run deploy,完成后把 wrangler.jsonc 里的 SITE_URL 改成真实地址再部署一次。

部署命令
npx wrangler login
python scripts/setup_remote.py
npm run db:remote          # 全新库建表
# 升级旧库改用:npm run db:migrate
npx wrangler secret put ADMIN_PASSWORD
npx wrangler secret put CONFIG_ENCRYPTION_KEY
npm run deploy
升级注意线上已有数据时,不要重跑 schema.sql 覆盖后台设置。增量迁移只补齐缺失 key,绝不覆盖已修改过的站名 / 密码 / Token。

绑定自定义域名#

部署完成后可在 Cloudflare Workers 控制台添加自定义域名,也可以直接使用 *.workers.dev 免费子域。系统自带 HTTPS 证书,无需额外配置。

配置与 Secrets#

配置分为三类:资源绑定写在 wrangler.jsonc,敏感密钥用 wrangler secret put 注入,站点信息在后台维护。

名称位置作用
account_id / database_id / kv idwrangler.jsonc资源绑定,不入库
SITE_NAME / SITE_DESCRIPTION / SITE_URLvars站点信息,后台可改
TURNSTILE_SITE_KEYvars与后台 Secret 成对替换
IMGBED_BASE_URL / IMGBED_TOKEN_NAMEvars环境变量模式的图床配置
ADMIN_PASSWORDSecret仅首次初始化管理员
CONFIG_ENCRYPTION_KEYSecret加密后台写入的 Token(32 字节随机串)
IMGBED_TOKENSecret环境变量模式的图床 Token
site_logo / imgbed_*D1 settings后台维护(Token 为密文)
生成配置加密主密钥
openssl rand -hex 32
npx wrangler secret put CONFIG_ENCRYPTION_KEY

Turnstile 人机验证三态#

  • off / 留空:完全关闭,页面不加载组件、登录直接放行(适合无法访问 challenges.cloudflare.com 的网络)
  • 官方测试密钥:始终通过
  • 真实密钥:Site Key(vars)与 Secret(后台设置)必须成对替换,改完重新部署
安全提示wrangler.jsonc、.dev.vars 与临时诊断文件都已在 .gitignore 中,切勿提交含密钥的配置到公开仓库。

系统架构#

整个系统围绕「让边缘缓存承担绝大部分读取」设计,结构如下。

浏览器 ──► Cloudflare Worker(Hono SSR / 后台 / API / Cron)
              │  匿名访客先查边缘 Cache API 中的完整 HTML(键含 cache_gen 代数)
              │  ├─ 命中 → 直接返回,0 次 D1 / 0 次 KV
              │  └─ 未命中 → 读 D1 渲染 → 异步写入边缘缓存(不占 KV 额度)
          ├── D1        文章 · 页面 · 用户 · 分类 · 标签 · 评论 · 设置
          ├── KV        会话 · 设置 · 侧栏 · 限流
          ├── Workers AI + Vectorize   摘要 / 标签 / 语义搜索(默认关闭)
          └── 外部图床   POST /upload(Token 由 Worker 服务端注入)

技术栈#

TypeScript 严格模式 · Cloudflare Workers(V8 isolate,非 Node)· Hono 路由 · Wrangler 内置 esbuild。生产依赖仅 hono。

典型链路#

  • 发文:POST /admin/post/* → 同源校验 → Markdown 渲染 → 写入 posts / post_tags → bumpCacheGen() 递增代数,前台缓存即时失效。
  • 传图:POST /api/upload(FormData file + 可选 channel)→ Worker 注入 Authorization: Bearer → 图床 /upload → 外链写入 media → 返回 URL 插入编辑器。
  • 匿名读文章:读 settings → 用「完整 URL + cache_gen」查 Cache API → 命中直接返回(0 次 D1、0 次 KV);未命中则查 D1 渲染并 waitUntil 写边缘缓存。

缓存机制#

这是 ABNCMS 最核心的设计。页面 HTML 存在 Cloudflare Cache API(不占 KV 写额度),缓存键 = 完整 URL(含 ?page= 分页参数)+ cache_gen 代数,TTL 7 天。

发布即更新#

发布、改文、删文、改评论、改分类、改设置时,只把 cache_gen +1(1 次 D1 写),旧缓存立即不再命中,全站页面下一秒就是新内容——不需要 purge,也不用逐页删除。用完整 URL 做键还顺带修好了分页串页问题。

排障技巧响应头 x-abn-cache: HIT / MISS 可以直接判断本次是否命中边缘缓存。

不同场景的访问成本#

场景WorkersD1KV
匿名前台,缓存命中1 次(极轻)00
匿名前台,未命中1 次几次读1–2 读
关闭页面缓存1 次几次读读设置/侧栏
后台 / 搜索 / 登录态1 次读写读写
  • 登录态一律 no-store:草稿与后台不进缓存。
  • 404 页带 <!--nocache--> 标记不会被缓存,避免错误内容供给 7 天。
  • 新建文章默认「正式发布」:保存后首页立即可见;只有主动选「草稿」才隐藏。
  • 设置 / 侧栏缓存 TTL 6 小时:KV 每天只有 1,000 次写额度,6 小时把写入降到 4 次/天,且保存时主动删除缓存,不存在陈旧问题。

浏览量统计#

浏览量由前端 25% 采样 beacon → POST /api/hit → 权重 ×4 聚合写 D1。这是估算值,不是精确指标。/api/hit 校验同源 Origin、站内路径白名单与权重上限。建议在后台关闭内置统计,改用「第三方统计代码」接入百度统计 / GA / Umami——代码原样注入前台底部,与内置统计互不依赖,关闭后统计对本站 D1 / KV 的消耗为 0。

免费额度#

官方文档核实(2026-10-30 更新),所有日额度 UTC 00:00 重置。

资源免费额度设计含义
Workers10 万请求/天,10ms CPU/请求,50 subrequests单次渲染要轻
D1500 万行读 / 10 万行写 / 5 GB按扫描行数计费,列表必走索引
KV10 万读 / 1,000 写 / 1 GB前台请求禁止写 KV
Workers AI1 万 neurons / 天AI 功能可降级
R210 GB / 月本项目不使用
「发布后是不是就静态了?」不生成静态文件,但匿名访问的效果等价:命中边缘缓存时 Worker 读缓存直接返回,0 次 D1、0 次 KV,兼具静态站的速度与动态站的「随时可更新」。

后台使用#

访问 /admin/login 登录,后台左侧导航涵盖全部管理功能。

模块功能
概览文章数、草稿数、评论数、媒体数、访问量等统计面板
文章新建 / 编辑 / 删除,Markdown 双栏编辑器,AI 摘要标签
页面独立页面管理(/page/{slug}.html)
分类 / 标签分类增删,顶部分类菜单可一键从分类生成
评论评论审核(通过 / 删除)
媒体库已上传图片列表与删除
友链 / 菜单友情链接管理、导航菜单配置
设置站点信息、LOGO、图床、第三方统计、功能开关、修改密码
备份全量导出 / 导入(JSON)
写作提示新建文章默认「正式发布」,保存后前台立即可见;想暂存请主动选择「草稿」。保存文章会自动递增缓存代数,若仍是旧内容,多为浏览器缓存,按 Ctrl+F5 硬刷新。

安全机制#

  • 密码 PBKDF2-SHA256 加盐哈希;会话 Cookie HttpOnly + SameSite=Lax + HTTPS 下 Secure,7 天有效
  • 后台写操作校验登录态与同源 Origin;登录有同 IP 失败限流
  • Markdown 输出全转义、SQL 全参数化绑定
  • 图床 Token:AES-GCM 加密落库、页面掩码、不进日志、导出备份时排除

功能开关#

后台「设置 → 功能开关」可独立控制各项能力。关闭后对应 D1 / KV 查询或写入根本不执行。小站长建议只保留页面缓存 + 热门文章。

设置项默认值作用
enable_page_cache开启页面 HTML 边缘缓存
enable_hot开启侧栏热门文章
enable_related开启相关阅读
enable_prevnext开启上下篇
allow_comments开启评论功能
enable_links关闭友情链接模块
enable_semantic关闭语义搜索(Vectorize)
enable_ai关闭AI 摘要标签(Workers AI)
analytics_enabled关闭内置访问统计(写 D1)
关于阅读统计内置统计每次打点写 D1 两行(更新 posts.views + 插入 page_views),消耗 D1 写额度但不消耗 KV。默认已关闭,关闭后前端不注入打点脚本,服务端 /api/hit 也直接丢弃请求。

图床与媒体#

图片上传到任意兼容图床并以外链引用,Worker 在服务端注入 Token,避免前端暴露密钥。不引入 R2。

配置优先级#

后台 D1(AES-GCM 加密)  >  wrangler vars / Secret  >  未配置
  • 主密钥 CONFIG_ENCRYPTION_KEY 用 wrangler secret put 注入,不入库、页面不回显。
  • 后台设置页只显示 Token 后 4 位掩码;输入框留空 = 不修改;可「清除并回退到环境变量」。
  • 「测试连接」调图床 GET /api/channels,不上传测试图。
  • 未配置主密钥时降级为「仅环境变量模式」,后台只能改地址。

图床接口约定#

POST /upload,请求头 Authorization: Bearer <TOKEN>,字段 file;支持 returnFormat=full、responseFormat=object、uploadChannel=s3|huggingface;删除用 POST /api/manage/delete/{fileId}。

站点 LOGO#

LOGO 复用 /api/upload 走图床,推荐显示高 32–40px、2x 源图 64–80px、宽 ≤200px,SVG 优先。未上传时默认「图标 + 站名」内联样式,改站名自动同步。

搭建专属图床#

ABNCMS 本身不保存图片,图片全部以外链形式引用。上一节讲的是「如何接入一个已有图床」,本节则从零搭一套完全属于自己、长期免费、文件存在自己仓库里的图床,用来给文章和 LOGO 提供外链。

方案由来与开源参考这套组合的思路来自社区常见的「Cloudflare + 代码托管仓库」免费图床实践。本节按 ABNCMS 的实际对接方式重新整理为标准流程。
章节中的操作截图来自开源项目 CloudFlare-ImgBed(MIT 协议,仅供部署方法参考)。你也可以 点此查看源码仓库 或访问 官方文档 了解项目本身。使用第三方程序时请自行审阅其许可协议与安全风险。

方案总览#

整套链路只有三个角色,各司其职:Cloudflare Pages 免费托管图床程序(自带全球加速、不限流量),Workers KV 保存渠道配置,HuggingFace 仓库作为文件仓库。文件进的是你自己的仓库,不寄存在任何人的服务器。

图床工作流总览:ABNCMS 后台 → 图床服务 → 存储仓库,KV 保存渠道配置

下图为本方案部署过程中采集的真实界面截图(已去除原作者水印)。

  • 部署免费:Pages 与 KV 均在 Cloudflare 免费计划内,无需绑卡。
  • 流量不限:图片走 Cloudflare 边缘网络,读图不消耗 ABNCMS 的 D1 / KV 额度。
  • 文件自有:图片最终落在你自己的代码托管仓库,可随时下载、迁移。
  • 容量可观:免费仓库配额足以支撑个人站与中小型内容站的图片需求。
真实截图:图床程序前台上传界面

准备工作#

  1. 一个 Cloudflare 账号(用于 Pages 与 KV)。
  2. 一个 GitHub 账号(用于 Fork 图床程序源码)。
  3. 一个 HuggingFace 账号(用于存放图片文件)。
术语对齐「令牌 / Token」在下文出现两次,作用不同:HuggingFace 的 Access Token 给图床程序用来写仓库;图床后台生成的 API Token 给 ABNCMS 用来上传图片。不要混填。

第 1 步:Fork 图床程序源码#

在代码托管平台找一款支持 Cloudflare Pages 部署、且提供 HuggingFace 上传渠道的开源图床程序,点 Fork 复制到你自己的账号下。选择时留意三点:

GitHub 上 Fork 开源图床项目到自己的账号
  • 仓库里带有 Pages 部署所需的构建脚本与 wrangler / 前端目录结构。
  • README 写明了构建命令和输出目录(本教程以 npm install + /frontend-dist 为例,实际以你选中项目的文档为准)。
  • 后台支持多存储渠道,且渠道名与上传参数可自定义——这是对接 ABNCMS 的关键。

第 2 步:用 Cloudflare Pages 部署图床#

进入 Cloudflare 后台 → Workers 和 Pages → 创建应用程序 → Pages → 导入 Git 仓库,选中刚 Fork 的项目,按图填写构建配置。

真实截图:Cloudflare Pages 构建配置,项目名、生产分支 main、构建命令 npm install、输出目录 /frontend-dist
构建参数别照抄构建命令与输出目录因项目而异。上图是示例值,请务必打开你 Fork 的仓库 README 核对;填错会导致部署成功但页面空白或 404。

第 3 步:创建并绑定 Workers KV#

图床程序用 KV 保存渠道配置,需要新建命名空间并与 Pages 项目绑定:

  1. Cloudflare 后台 → Workers 和 Pages → KV → 创建命名空间,名称随意,例如 img_url。
  2. 回到刚才的 Pages 项目 → 设置 → 绑定 → 添加 → 选择 KV 命名空间。
  3. 在「Variable name / 变量名」一栏固定填 img_url,命名空间选刚创建的那个,保存。
  4. 绑定完成后重新部署一次项目让配置生效。
真实截图:Cloudflare Pages 项目的 KV 命名空间绑定,变量名为 img_url
变量名不能改img_url 是图床程序代码里写死的读取名。写成 IMG_URL、kv 等任何其它名字,程序都读不到配置,后台会异常。

第 4 步:申请 HuggingFace 写入令牌#

图床程序需要一个有写权限的令牌,才能把图片推进你的仓库。

真实截图:HuggingFace 控制台界面,用于创建 Write 类型访问令牌
  1. 登录后点右上角头像 → Settings → Access Tokens → Create new token。
  2. Token type 选择 Write(只读的 Read 无法上传)。
  3. 填一个便于识别的名字,创建后立即复制令牌——完整令牌只显示这一次,关掉页面就再也看不到了。

第 5 步:准备图片仓库#

在 HuggingFace 新建一个用来存图的仓库,记下它的完整名称,格式为 用户名/仓库名(例如 abncms/gallery)。这一步只需建好空仓库,图片会在首次上传时由程序自动写入。若希望外链无需鉴权即可访问,把仓库设为公开更省心;设为私有则需要程序额外处理鉴权。

真实截图:HuggingFace 图片仓库文件列表,图片以 LFS 文件形式存入

第 6 步:在图床后台添加 HuggingFace 渠道#

打开 Pages 分配给你的图床域名,进入后台:系统设置 → 上传设置 → 新增 HuggingFace 渠道,按图填写四项。

真实截图:图床后台上传设置中的 HuggingFace 渠道与仓库配置
字段填写内容
渠道名称自定义识别名,例如 hf-main,后续切换默认渠道时要选它
令牌第 4 步复制的 HuggingFace Write Token
仓库名用户名/仓库名,例如 abncms/gallery
私有开关按仓库实际可见性设置;公开仓库可关闭

保存后点「测试连接」确认渠道可用(只校验连通性,不会真的上传测试图)。

第 7 步:把渠道设为默认#

到 客户端设置 里,把默认上传类型改成 HuggingFace,渠道名称选第 6 步建的那个。这一步最容易被漏掉。

不改默认会上传失败很多图床程序默认走 Telegram 等其它渠道。若只添加了 HuggingFace 渠道却没切默认,上传会走错渠道而报错。

第 8 步:上传验证#

  1. 回到图床首页,拖一张图片上传,复制返回的公开外链。
  2. 真实截图:图片上传成功,进度条完成并显示文件列表
  3. 在新标签打开外链,返回 200 且能正常显示图片即成功。
  4. 到 HuggingFace 仓库确认文件已自动生成。

在 ABNCMS 中使用这套图床#

图床就绪后,回到 ABNCMS 后台 设置 → 图床接入:

  • 图床地址填 Cloudflare Pages 分配给图床的域名(如 https://你的图床.pages.dev)。
  • API Token填图床后台生成的上传令牌,不是 HuggingFace 的令牌。
  • 点「测试连接」通过后保存。之后在文章编辑器里插图、上传 LOGO,都会走 /api/upload,由 Worker 在服务端注入令牌,前端看不到密钥。
两层令牌,各管一段HuggingFace Token 让图床能写仓库;图床 API Token 让 ABNCMS 能调图床。前者存在图床后台,后者存在 ABNCMS 设置里,方向不要颠倒。

成本与额度说明#

组件用途免费计划内的表现
Cloudflare Pages托管图床程序免服务器费用、全球加速,图片读取流量不计入 ABNCMS
Workers KV保存渠道配置仅存少量配置,读写量极小,远低于免费额度
HuggingFace 仓库存放图片文件免费仓库配额,文件归你所有,可随时导出

各平台的免费额度会随时间调整,开通前请以官网当前说明为准。这套方案不产生服务器费用,也不占用 ABNCMS 站点的 D1 写入额度。

常见问题#

现象排查方向
上传报「渠道未配置」或走错渠道检查第 7 步默认渠道是否切到 HuggingFace
后台配置读不到 / 保存后失效确认 KV 变量名为 img_url,且绑定后已重新部署
外链打开 403 / 需要登录仓库设为私有导致,改为公开或按项目文档配置鉴权
Pages 部署后页面空白构建命令或输出目录填错,对照 Fork 仓库的 README 修正
ABNCMS 里测试连接失败确认填的是图床 API Token 而非 HuggingFace 令牌,且图床域名可公网访问

API 接口#

系统主要路由如下,前台公开接口与后台接口分离。

前台路由(公开)#

路径说明
/首页
/p/{slug}.html文章详情(旧 /p/{slug} 会 301 跳转)
/page/{slug}.html独立页面
/c/{slug} / /t/{slug}分类页 / 标签页
/tags / /archive / /search标签云 / 归档 / 搜索
/feed.xml / /sitemap.xmlRSS / 站点地图
/comment发表评论(POST)
/media/*历史媒体文件读取

后台与系统接口#

路径说明
/admin/login / /admin/logout登录 / 退出
/admin/post/* / /admin/page/*文章 / 页面 CRUD(需登录)
/admin/settings站点设置(需登录)
/admin/backup/export|import备份导出 / 导入
/api/upload图床上传(需登录)
/api/previewMarkdown 预览(需登录)
/api/ai/summary-tagsAI 摘要标签(需登录)
/api/hit浏览量打点(公开,同源校验)
/api/health健康检查

目录结构#

abncms/
├── src/
│   ├── index.ts              # 全部路由 + Cron + 缓存策略
│   ├── types.ts              # Env / SiteSettings / 数据类型
│   ├── lib/
│   │   ├── db.ts             # D1 访问层、站点设置读写
│   │   ├── auth.ts           # 密码哈希、会话、限流、Turnstile
│   │   ├── crypto.ts         # AES-GCM:敏感配置加解密
│   │   ├── imgbed.ts         # 图床代理:上传 / 删除 / 测试
│   │   ├── markdown.ts       # 零依赖 Markdown 渲染(转义防 XSS)
│   │   ├── ai.ts             # Workers AI + Vectorize
│   │   └── util.ts           # slug / 分页 / Cookie / 转义
│   └── views/                # layout.ts / front.ts / admin.ts
├── public/                   # admin.js / favicon.svg / robots.txt
├── scripts/                  # setup_remote.py / migrate.py / smoke_test.py
├── migrations/               # 增量迁移 SQL(按版本登记,幂等)
├── schema.sql                # 全新安装:幂等建表 + 版本基线
├── seed.sql                  # 中性示例数据
└── wrangler.example.jsonc    # 配置模板

数据模型#

数据主要存于 D1,核心表如下。

表用途
posts文章(含 slug、状态、浏览量、封面)
pages独立页面
categories / tags / post_tags分类、标签及其关联
users管理员账号
comments评论与审核状态
media已上传媒体外链
links友情链接
settings站点设置(键值对)
page_views访问明细(Cron 定期清理)

备份导出按固定顺序处理:settings → categories → tags → posts → pages → links → comments → post_tags → media,导入时同步处理关联关系,Token 等敏感字段会被排除。

常见问题#

发布后是不是就静态了?#

不生成静态文件,但匿名访问的效果等价——命中边缘缓存时直接返回完整 HTML,0 次 D1、0 次 KV;同时保留后台,内容随时可更新。

需要服务器或数据库主机吗?#

不需要。全部运行在 Cloudflare Workers + D1 + KV 上,免费计划即可,无需绑卡。

阅读统计会消耗额度吗?#

内置统计每次打点写 D1 两行,消耗 D1 写额度但不消耗 KV;默认是关闭的。建议改用第三方统计代码,关闭后统计部分消耗为 0。

自定义域名怎么绑定?#

在 Cloudflare Workers 控制台添加自定义域名并设置 DNS 解析即可,平台自动签发 HTTPS 证书。

可以在国内访问吗?#

workers.dev 与自建域名的实际可达性取决于当地网络环境,建议绑定自有域名以获得更稳定的访问体验。

故障排查#

现象处理
Turnstile 显示成功却提示未通过Site Key 与 Secret 必须成对替换;任一侧是测试密钥时代码会放行
后台改不了图床 Token未配置 CONFIG_ENCRYPTION_KEY,当前是「仅环境变量模式」
图片上传报「图床未配置」后台「设置 → 图床接入」填地址与 Token,或设置 IMGBED_TOKEN Secret
站名回退成默认值settings 缺键或 D1 异常时回落;进后台保存一次即可
改了文章前台没立刻变确认已部署 v0.2.1+;保存会自动递增 cache_gen;若仍为旧内容是浏览器缓存,按 Ctrl+F5 硬刷新
改了站名 / LOGO / 设置没变设置保存同样递增缓存代数;如仍为旧内容,执行 wrangler kv key delete settings:v1 --binding=KV --remote
阅读量不动或跳得快统计是 25% 采样 ×4 聚合的估算值;建议关掉内置统计,改用第三方统计代码
升级后后台缺 LOGO / 图床设置旧库需跑 python scripts/migrate.py 补齐设置项
子域注册失败 10405去 Cloudflare 控制台手动注册一次 *.workers.dev 子域

社区与支持#

ABNCMS 在 MIT 协议下开源,欢迎 Star、反馈 Issue 或参与共建。

渠道地址 / 方式
GitHub 源码github.com/baiyirui/abncms
问题反馈GitHub Issues
产品官网cms.abn.cn
在线演示abncms.eu.cc
联系邮箱a@abn.cn

许可:MIT · 名称与 Logo 使用见仓库 TRADEMARK.md。