ABNCMS 开发手册#
一份从入门到上线的完整技术文档。ABNCMS 是一款面向 Cloudflare Workers + D1 + 外部图床 的免费开源轻量级 CMS——零服务器、零托管费用、生产依赖仅 Hono,全部能力落在 Cloudflare 免费计划内。
本手册覆盖产品介绍、环境搭建、本地开发、部署上线、系统架构、后台使用、API 与图床、缓存机制,以及常见问题与故障排查。当前版本 v0.2.7,基于 Cloudflare Workers。
真正零成本
全部跑在 Cloudflare 免费计划内,无需服务器、无需绑卡。
生来全球加速
页面缓存分发到全球边缘,访客就近访问,自带 HTTPS 与 DDoS 防护。
有后台,随时更新
可视化后台写文章传图片,保存后前台立即更新,无需重新构建。
边缘缓存极速
命中缓存 0 次数据库查询,发布自动让缓存代数 +1,全站秒级更新。
核心能力#
一个 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.js | 20+(推荐 22 LTS) | 运行 Wrangler 与本地开发 |
| Python | 3.8+ | 仅辅助脚本与冒烟测试,纯标准库无需 pip |
| Cloudflare 账号 | 免费计划即可 | 无需绑卡 |
| Wrangler | devDependency 自带 | 用 npx wrangler 调用 |
| workers.dev 子域 | 需预先注册一次 | OAuth 登录态无法用 API 创建,需在控制台手动注册 |
hono 一个包,TypeScript 严格模式,Wrangler 内置 esbuild 打包,无需额外构建工具。快速开始#
从克隆源码到看见页面,最短路径如下。
克隆项目
git clone https://github.com/baiyirui/abncms.git && cd abncms
安装依赖
npm install
准备配置
复制 wrangler.example.jsonc 为 wrangler.jsonc,.dev.vars.example 为 .dev.vars,填入资源 ID 与管理员密码。
初始化本地库并启动
npm run db:local → npx wrangler d1 execute cf-press-db --local --file=./seed.sql → npm run dev
访问
浏览器打开 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 typecheck | TypeScript 类型检查(tsc --noEmit) |
npm run build | dry-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,然后一条命令部署到全球边缘。
登录 Cloudflare
npx wrangler login
创建远程资源
python scripts/setup_remote.py 自动建 D1 / KV / Vectorize,并把返回的 ID 写回 wrangler.jsonc。
初始化数据库
全新库执行 npm run db:remote;从旧版升级不要重跑 schema,改用 npm run db:migrate 增量迁移。
注入 Secrets
设置管理员密码、配置加密主密钥等(见下一节)。
部署
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 id | wrangler.jsonc | 资源绑定,不入库 |
SITE_NAME / SITE_DESCRIPTION / SITE_URL | vars | 站点信息,后台可改 |
TURNSTILE_SITE_KEY | vars | 与后台 Secret 成对替换 |
IMGBED_BASE_URL / IMGBED_TOKEN_NAME | vars | 环境变量模式的图床配置 |
ADMIN_PASSWORD | Secret | 仅首次初始化管理员 |
CONFIG_ENCRYPTION_KEY | Secret | 加密后台写入的 Token(32 字节随机串) |
IMGBED_TOKEN | Secret | 环境变量模式的图床 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(FormDatafile+ 可选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 可以直接判断本次是否命中边缘缓存。不同场景的访问成本#
| 场景 | Workers | D1 | KV |
|---|---|---|---|
| 匿名前台,缓存命中 | 1 次(极轻) | 0 | 0 |
| 匿名前台,未命中 | 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 重置。
| 资源 | 免费额度 | 设计含义 |
|---|---|---|
| Workers | 10 万请求/天,10ms CPU/请求,50 subrequests | 单次渲染要轻 |
| D1 | 500 万行读 / 10 万行写 / 5 GB | 按扫描行数计费,列表必走索引 |
| KV | 10 万读 / 1,000 写 / 1 GB | 前台请求禁止写 KV |
| Workers AI | 1 万 neurons / 天 | AI 功能可降级 |
| R2 | 10 GB / 月 | 本项目不使用 |
后台使用#
访问 /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) |
/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-ImgBed(MIT 协议,仅供部署方法参考)。你也可以 点此查看源码仓库 或访问 官方文档 了解项目本身。使用第三方程序时请自行审阅其许可协议与安全风险。
方案总览#
整套链路只有三个角色,各司其职:Cloudflare Pages 免费托管图床程序(自带全球加速、不限流量),Workers KV 保存渠道配置,HuggingFace 仓库作为文件仓库。文件进的是你自己的仓库,不寄存在任何人的服务器。
下图为本方案部署过程中采集的真实界面截图(已去除原作者水印)。
- 部署免费:Pages 与 KV 均在 Cloudflare 免费计划内,无需绑卡。
- 流量不限:图片走 Cloudflare 边缘网络,读图不消耗 ABNCMS 的 D1 / KV 额度。
- 文件自有:图片最终落在你自己的代码托管仓库,可随时下载、迁移。
- 容量可观:免费仓库配额足以支撑个人站与中小型内容站的图片需求。
准备工作#
- 一个 Cloudflare 账号(用于 Pages 与 KV)。
- 一个 GitHub 账号(用于 Fork 图床程序源码)。
- 一个 HuggingFace 账号(用于存放图片文件)。
第 1 步:Fork 图床程序源码#
在代码托管平台找一款支持 Cloudflare Pages 部署、且提供 HuggingFace 上传渠道的开源图床程序,点 Fork 复制到你自己的账号下。选择时留意三点:
- 仓库里带有 Pages 部署所需的构建脚本与
wrangler/ 前端目录结构。 - README 写明了构建命令和输出目录(本教程以
npm install+/frontend-dist为例,实际以你选中项目的文档为准)。 - 后台支持多存储渠道,且渠道名与上传参数可自定义——这是对接 ABNCMS 的关键。
第 2 步:用 Cloudflare Pages 部署图床#
进入 Cloudflare 后台 → Workers 和 Pages → 创建应用程序 → Pages → 导入 Git 仓库,选中刚 Fork 的项目,按图填写构建配置。
第 3 步:创建并绑定 Workers KV#
图床程序用 KV 保存渠道配置,需要新建命名空间并与 Pages 项目绑定:
- Cloudflare 后台 → Workers 和 Pages → KV → 创建命名空间,名称随意,例如
img_url。 - 回到刚才的 Pages 项目 → 设置 → 绑定 → 添加 → 选择 KV 命名空间。
- 在「Variable name / 变量名」一栏固定填
img_url,命名空间选刚创建的那个,保存。 - 绑定完成后重新部署一次项目让配置生效。
img_url 是图床程序代码里写死的读取名。写成 IMG_URL、kv 等任何其它名字,程序都读不到配置,后台会异常。第 4 步:申请 HuggingFace 写入令牌#
图床程序需要一个有写权限的令牌,才能把图片推进你的仓库。
- 登录后点右上角头像 → Settings → Access Tokens → Create new token。
- Token type 选择 Write(只读的 Read 无法上传)。
- 填一个便于识别的名字,创建后立即复制令牌——完整令牌只显示这一次,关掉页面就再也看不到了。
第 5 步:准备图片仓库#
在 HuggingFace 新建一个用来存图的仓库,记下它的完整名称,格式为 用户名/仓库名(例如 abncms/gallery)。这一步只需建好空仓库,图片会在首次上传时由程序自动写入。若希望外链无需鉴权即可访问,把仓库设为公开更省心;设为私有则需要程序额外处理鉴权。
第 6 步:在图床后台添加 HuggingFace 渠道#
打开 Pages 分配给你的图床域名,进入后台:系统设置 → 上传设置 → 新增 HuggingFace 渠道,按图填写四项。
| 字段 | 填写内容 |
|---|---|
| 渠道名称 | 自定义识别名,例如 hf-main,后续切换默认渠道时要选它 |
| 令牌 | 第 4 步复制的 HuggingFace Write Token |
| 仓库名 | 用户名/仓库名,例如 abncms/gallery |
| 私有开关 | 按仓库实际可见性设置;公开仓库可关闭 |
保存后点「测试连接」确认渠道可用(只校验连通性,不会真的上传测试图)。
第 7 步:把渠道设为默认#
到 客户端设置 里,把默认上传类型改成 HuggingFace,渠道名称选第 6 步建的那个。这一步最容易被漏掉。
第 8 步:上传验证#
- 回到图床首页,拖一张图片上传,复制返回的公开外链。
- 在新标签打开外链,返回
200且能正常显示图片即成功。 - 到 HuggingFace 仓库确认文件已自动生成。
在 ABNCMS 中使用这套图床#
图床就绪后,回到 ABNCMS 后台 设置 → 图床接入:
- 图床地址填 Cloudflare Pages 分配给图床的域名(如
https://你的图床.pages.dev)。 - API Token填图床后台生成的上传令牌,不是 HuggingFace 的令牌。
- 点「测试连接」通过后保存。之后在文章编辑器里插图、上传 LOGO,都会走
/api/upload,由 Worker 在服务端注入令牌,前端看不到密钥。
成本与额度说明#
| 组件 | 用途 | 免费计划内的表现 |
|---|---|---|
| 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.xml | RSS / 站点地图 |
/comment | 发表评论(POST) |
/media/* | 历史媒体文件读取 |
后台与系统接口#
| 路径 | 说明 |
|---|---|
/admin/login / /admin/logout | 登录 / 退出 |
/admin/post/* / /admin/page/* | 文章 / 页面 CRUD(需登录) |
/admin/settings | 站点设置(需登录) |
/admin/backup/export|import | 备份导出 / 导入 |
/api/upload | 图床上传(需登录) |
/api/preview | Markdown 预览(需登录) |
/api/ai/summary-tags | AI 摘要标签(需登录) |
/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。