部署

如果你希望独立运行计数服务，只需一个 Cloudflare 账号即可将 Tally API 部署到自己的域名下。整个项目基于 Cloudflare Pages Functions 与 D1 构建，除 Cloudflare 账号外无需额外维护数据库。

准备工作

一个 Cloudflare 账号
JavaScript 运行环境，例如 Bun 或 Node.js

由于我的个人使用习惯，以下示例使用 Bun 做演示。如果你只是参考部署流程，也可以将包管理器命令替换为 npm、pnpm 或 yarn 的等价写法。

如果 Wrangler 尚未登录，需要先执行 bunx wrangler login，再创建 D1 数据库或部署站点。

开始部署

克隆仓库并安装依赖：

git clone https://github.com/xueelf/tally-api.git
cd tally-api
bun install

创建 D1 数据库：

bunx wrangler d1 create tally-api

将返回的 database_id 填进 wrangler.json 的 d1_databases 字段：

json

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "tally-api",
    "database_id": "<你的数据库 ID>"
  }
]

请务必替换实际 ID，否则本地调试或部署时会出现认证或资源错误。若数据库已存在，可执行 bunx wrangler d1 list 查看其 ID。

将表结构应用到远程数据库：

bunx wrangler d1 migrations apply DB --remote

迁移文件位于 migrations/，执行记录保存在 d1_migrations 表中，因此该命令只会应用尚未执行的部分。

生成类型声明：

bun run types

构建文档站点：

bun run docs:build

部署到 Cloudflare Pages

bunx wrangler pages deploy

Wrangler 会依据 wrangler.json 中的 pages_build_output_dir 配置，将文档站点与 functions 目录下的 API 一并部署。

迁移已有的 KV 数据

如果计数仍然保存在 KV 中，可以用 scripts/migrate-kv-to-d1.ts 将其复制到 D1。该脚本采用覆盖写入而非累加，重复执行也不会重复计数。脚本通过 Cloudflare REST API 操作，请先准备具备 Workers KV Storage: Read 与 D1: Edit 权限的 API Token：

export CLOUDFLARE_API_TOKEN=<API Token>
bun run db:migrate            # 加上 --dry-run 可先预演，不写入任何数据

脚本默认读取 wrangler.json 中的 KV 命名空间与 D1 数据库 ID，也可以通过 KV_NAMESPACE_ID、D1_DATABASE_ID、CLOUDFLARE_ACCOUNT_ID 覆盖。

确认数据迁移完成且校验无误后，可以从 wrangler.json 中删除不再使用的 kv_namespaces 字段，并在 Cloudflare 控制台删除对应的 KV 命名空间。

本地调试

bun run db:migrate:local
bun run dev

db:migrate:local 会先把迁移应用到 wrangler pages dev 使用的本地 SQLite 数据库，dev 则会构建文档、生成类型并通过 wrangler pages dev ./dist 启动本地服务。服务运行后，可在 http://localhost:8788 同时访问文档与 API。

补充

如果只是为了搭建自己的访问计数器，以上步骤就已经足够了。后续可根据需要更换域名、调整文案或修改偏好的主题。

关于路径规则、返回格式及错误响应的详细说明，请参阅 API 参考。

部署 ​

准备工作 ​

开始部署 ​

迁移已有的 KV 数据 ​

本地调试 ​

补充 ​

部署

准备工作

开始部署

迁移已有的 KV 数据

本地调试

补充