CF-Navs 使用与 Cloudflare Workers 部署指南

CF-Navs 是一个运行在 Cloudflare Workers 上的个人导航站。前端由 Svelte 构建，Worker 同时提供页面和 API；D1 保存站点设置、分类与书签，KV 保存登录限流、点击限流和会话撤销记录。它适合个人起始页、团队工具入口和公开资源导航，不需要单独维护服务器或数据库进程。

项目概览

信息	内容
项目名称	CF-Navs
项目定位	部署在 Cloudflare 边缘网络上的个人导航站和书签管理工具
GitHub 仓库	lbjxr/CF-Navs
主要技术	Svelte 5、TypeScript、Vite 7、Hono
Cloudflare 产品	Workers、D1、KV、Workers Assets
数据存储	D1 保存业务数据，KV 保存限流和会话撤销状态
部署方式	Cloudflare 控制台导入 GitHub，或使用 Wrangler CLI
开源许可证	MIT

适用场景

个人浏览器起始页

把每天访问的网站、开发工具和生活服务整理到同一个首页。两级分类、全站搜索、经常访问和响应式布局让电脑与手机可以共用一套入口，PWA 提供基础离线回退。

工作和团队工具入口

把项目管理、监控、文档和内部系统按业务域分组，使用拖拽排序和批量移动持续维护。公开内容可以直接分享；仅供管理员使用的入口可设为私密分类或私密书签。

公开资源导航

通过主题、亮暗模式、顶部或侧边导航、卡片样式和页脚内容搭建公开导航页。访客只会收到公开数据，管理员登录后仍能在同一个站点管理完整内容。

从现有书签或导航面板迁移

已有收藏可以通过 CF-Navs JSON、Sun-Panel 数据或浏览器书签 HTML 导入。全量导出和按分类导出适合迁移前备份，也便于把部分分类转移到另一个实例。

持续收集和整理书签

Chrome/Edge 扩展可以把浏览器中新建的书签单向写入“浏览器新增收藏”，随后再从首页或后台归类。点击统计会展示常用和零访问书签，帮助清理长期不用的入口。

CF-Navs 的同步方向是“浏览器新增书签到导航站”，不是浏览器与站点之间的双向镜像。需要多用户权限、团队审计或双向书签同步时，应先评估它是否符合需求。

运行架构

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    U[浏览器或 PWA] --> W[Cloudflare Worker]
    W --> A[ASSETS 静态资源绑定]
    W --> API[Hono API]
    API --> D1[(D1: 设置、分类、书签)]
    API --> KV[(KV: 限流、会话撤销)]
    T[SETUP_TOKEN] --> I["/install 首次安装"]
    I --> D1
    I --> KV

ASSETS 把 dist 中的前端产物交给 Worker；/api/* 由 Hono 路由处理。/install 会检查 DB、SESSION 和 SETUP_TOKEN，初始化 schema 并创建管理员。完成安装后，站点会拒绝再次初始化。

先选择一种部署方式

路径	适合谁	资源处理	版本控制
Cloudflare 控制台导入 GitHub	希望主要在浏览器中操作	Git 集成按 `wrangler.toml` 创建或绑定 D1、KV	Fork 后固定生产分支，推荐 `main`
Wrangler CLI	需要明确管理账号、资源 ID 和命令记录	手动创建 D1、KV，再生成本地配置	检出固定提交或明确 release

第一次部署应完整选择其中一条路径，不要一边让 Git 集成创建资源，一边在 CLI 中重复创建同名资源。无论采用哪条路径，最终都通过 /install 初始化 D1 和管理员。

项目 README 的控制台流程使用 main，CLI 示例会切换到 develop；仓库中的旧生产验收说明也以 develop 为部署源。develop 会继续变化，生产部署应使用 main 或明确的 release，并固定到经过验收的提交。后续升级时重新执行代码检查和功能验收。

前置条件

一个可创建 Workers、D1 和 KV 资源的 Cloudflare 账户。
一个 GitHub 账户；控制台路径需要 Fork 项目并授权 Cloudflare 读取该 Fork。
CLI 路径需要 Node.js 22.12+ 的 22.x 版本或 Node.js 24+，建议使用 Node.js 24 LTS。
准备一个足够长的随机安装令牌，只用于首次安装，不写入源码、命令历史或普通文本变量。
确认 Cloudflare 当前套餐的 Workers 请求、D1 行数读写与存储、KV 读写和存储额度能够覆盖预期访问量。

部署路径

路径一：Cloudflare 控制台导入 GitHub

这条路径适合首次部署。Cloudflare 的 Git 集成负责拉取 Fork、运行构建命令并调用 Wrangler 发布。

Fork lbjxr/CF-Navs，保留 main 分支。
在 Cloudflare Dashboard 进入 Workers & Pages，创建应用并选择导入 Git 仓库。
授权 Cloudflare 访问 GitHub，选择自己的 CF-Navs Fork。
填写生产构建配置：
配置项值
Production branch main
Root directory /
Build command npm run build
Deploy command npx wrangler deploy
Node.js 24 LTS；需要显式指定时使用构建变量 NODE_VERSION=24
启动第一次 Production 部署。完成后检查 Worker 的 Bindings，确认出现 D1 DB 和 KV SESSION。
在该 Worker 的生产环境变量与密钥设置中添加加密 Secret SETUP_TOKEN。不要创建同名普通变量。
保存 Secret 后重新触发一次生产部署，使新部署读取到 Secret。
先访问 Worker 的默认 workers.dev 地址，再打开 /install。输入安装令牌，创建管理员用户名和至少 12 位的管理员密码。
登录后台，完成下文的基本功能验收。安装成功后删除或轮换 SETUP_TOKEN。

配置项	值
Production branch	`main`
Root directory	`/`
Build command	`npm run build`
Deploy command	`npx wrangler deploy`
Node.js	24 LTS；需要显式指定时使用构建变量 `NODE_VERSION=24`

首次部署时若 DB 或 SESSION 没有创建成功，应先检查生产分支、Cloudflare 账号和部署日志。不要反复创建同名资源，否则后续很难判断 Worker 实际绑定了哪一个实例。

路径二：Wrangler CLI

先固定源码，再安装依赖：

bash

git clone https://github.com/lbjxr/CF-Navs.git
cd CF-Navs
git checkout 29276cf3c60038f78c0bc8f76fa1cfa21669904b
npm ci
npm run type-check
npm test
npm run build

bash

npx wrangler login
npx wrangler whoami
npx wrangler d1 list
npx wrangler kv namespace list

只有确认目标资源不存在时，才各执行一次创建命令：

bash

npx wrangler d1 create cf-navs-db
npx wrangler kv namespace create SESSION

让项目脚本读取当前账号的资源列表，并把 ID 写入 Git 忽略的 wrangler.local.toml：

bash

npm run setup:wrangler
git status --short

检查 wrangler.local.toml 未被 Git 跟踪，随后进行首轮部署：

bash

npm run deploy

Worker 创建成功后再设置安装 Secret，并重新部署：

bash

npx wrangler secret put SETUP_TOKEN
npm run deploy

最后访问部署 URL 的 /install，创建管理员。不要把真实 D1 ID、KV ID 或 Secret 回填到仓库中的 wrangler.toml。

配置与绑定

项目核心配置如下，资源 ID 由部署路径补齐：

toml

name = "cf-navs"
main = "worker/index.ts"
compatibility_date = "2025-06-01"
compatibility_flags = ["nodejs_compat"]
keep_vars = true

[assets]
directory = "./dist"
binding = "ASSETS"
not_found_handling = "none"

[vars]
INIT_ADMIN_USER = "admin"
SESSION_TTL = "2592000"

[[d1_databases]]
binding = "DB"
database_name = "cf-navs-db"

[[kv_namespaces]]
binding = "SESSION"

名称	Cloudflare 类型	作用	初始化、迁移与备份边界
`DB`	D1 binding	保存设置、分类、书签、点击数据和安装状态	`/install` 执行 schema 初始化；升级前必须导出业务数据或制作可恢复备份
`SESSION`	KV binding	保存登录限流、点击限流和会话撤销名单	不承载书签主数据；更换命名空间会影响限流与会话撤销状态
`ASSETS`	Workers Assets binding	提供 Vite 构建后的 `dist`	每次代码发布重新构建；旧资源随代码版本回滚
`SETUP_TOKEN`	Secret	授权第一次 `/install`	只在安装窗口存在；安装成功后删除或轮换
`SESSION_TTL`	Variable	会话有效期，配置默认 `2592000` 秒	未配置时程序回退为 7 天；缩短后应重新验证登录体验
`INIT_ADMIN_USER`	Variable	旧数据库升级或凭据恢复兼容项	全新安装在 `/install` 页面设置管理员，不依赖默认值

keep_vars = true 会保留 Dashboard 中维护的变量。修改配置文件时仍应核对远程变量与绑定，避免误以为代码回滚会恢复 Secret 或数据资源。

D1 初始化与恢复

正常新部署由 /install 使用打包进 Worker 的 schema.sql 初始化数据库，不需要手工执行 SQL。只有安装器明确报告 schema 初始化失败，并且已经确认 Worker 绑定到正确的 D1 数据库时，才考虑恢复命令：

bash

npm run db:init:remote

这是远程写操作。执行前先备份数据、确认 Wrangler 账号和 wrangler.local.toml，并阅读 SQL 内容。已有数据库的升级不能只靠重新部署代码判断完成，还要验证 schema 与旧数据兼容。

首次安装状态

Mermaid 流程图

正在准备渲染...

查看源码

flowchart TD
    A[部署 Worker] --> B{DB 与 SESSION 可用?}
    B -- 否 --> C[修复资源绑定]
    B -- 是 --> D{SETUP_TOKEN 已配置?}
    D -- 否 --> E[添加 Secret 并重新部署]
    D -- 是 --> F[访问 /install]
    F --> G[校验令牌并初始化 schema]
    G --> H[创建管理员并登录]
    H --> I[删除或轮换 SETUP_TOKEN]

安装接口限制同源请求，并对失败的安装令牌尝试做限流。管理员密码最少 12 位。安装完成后再次提交安装请求会被拒绝，因此不要把 /install 当作日常重置密码入口。

使用教程

建立分类和书签

使用安装时创建的管理员账户登录。
先建立少量一级分类，例如“工作”“开发”“生活”，再按需要添加二级分类。
新建书签时填写标题、URL、描述、打开方式和图标；先保存少量样本，确认页面布局后再批量导入。
桌面端可通过拖拽调整分类和书签顺序；移动端使用“移动到分类”完成同类操作。
大规模整理时在后台筛选书签并批量移动，避免逐条编辑。

两级分类适合保持导航层次稳定。超过两层的浏览器书签目录在导入时会压平到二级标题，导入前应先检查同名目录是否会造成理解混乱。

配置公开与私密内容

私密书签只向已登录管理员返回，适合个人后台入口和不希望公开的收藏。
私密分类会连同子分类和其中书签一起对访客隐藏。
公开模式适合资源导航；关闭公开模式后，应在无痕窗口确认访客不能读取受限数据。
私密链接仍保存在自己的 D1 中。导出的备份可能包含这些 URL，不要上传到公开网盘或公开仓库。

公开站点不应把管理控制台、临时签名 URL、内网地址或含访问令牌的链接当作普通公开书签。

导入现有数据

后台的数据备份与导入支持三类输入：

格式	适合场景	注意事项
CF-Navs JSON	站点迁移、全量备份、按分类迁移	可携带设置和私密内容，优先作为恢复格式
Sun-Panel 数据	从现有导航面板迁移	导入后检查分类和图标字段
浏览器书签 HTML	从 Chrome、Edge 等浏览器迁移	深层目录会压平，应抽样检查分类路径

首次导入前先导出一份当前数据。追加模式会保留重复链接，覆盖模式会替换全部分类与书签；覆盖导入前应再次确认备份可以下载并解析。

配置外观和搜索

在站点设置中可以修改标题、默认主题、亮暗模式、导航布局、搜索引擎和“经常访问”数量。建议按这个顺序调整：

先选择内置主题和亮暗模式。
再确定左侧或顶部导航布局。
调整卡片尺寸、透明度和字体，分别检查桌面与移动端。
最后添加自定义 CSS、页脚 HTML 或 JavaScript，并在隔离预览中检查。

自定义 JavaScript 会扩大站点脚本的维护和安全边界。只保存自己审阅过的代码，升级项目后重新验证 CSP、登录页和移动端布局。

使用浏览器扩展收集新书签

在后台开启浏览器书签同步后，安装项目 browser-extension 目录中的 Chrome/Edge 扩展并登录。之后在浏览器中新建的书签会进入“浏览器新增收藏”分类，再由管理员在首页排序或后台批量移动。

扩展不会按浏览器目录持续同步，也不会把站点中的删除反向同步到浏览器。更换域名后需要重新检查扩展的站点地址、登录状态和跨域请求。

建立备份习惯

大规模导入、覆盖恢复、schema 变更和版本升级前导出全量 JSON。
对重要分类额外做按分类导出，缩小误操作后的恢复范围。
定期实际下载并抽查备份，不以“页面上有导出按钮”代替恢复证据。
记录备份对应的项目提交、D1 数据库和站点环境，避免把测试环境备份误用于生产。
KV 不保存书签主数据，但更换 KV 会影响会话撤销和限流状态；变更后让管理员重新登录并观察异常流量。

验收

本地代码门槛

部署前在待发布源码目录执行以下检查：

bash

npm ci
npm run type-check
npm test
npm run build

只有类型检查、测试和生产构建全部成功，并且 Vite 生成完整的 dist 后，才继续远程部署。本地检查不覆盖 Cloudflare 账号权限、远程资源、域名和生产数据，仍需按下一节逐项验收。

远程部署验收清单

访问 https://<worker-host>/api/health，确认 HTTP 成功且响应数据中的 status 为 ok。
打开 /install，确认页面没有报告 DB、SESSION 或 SETUP_TOKEN 缺失。
完成安装并登录，创建一个测试分类和测试书签；刷新后确认数据仍然存在。
退出登录，在无痕窗口验证公开内容可见、私密分类和私密书签不可见。
导出一份 JSON 备份并检查文件可读；不要立刻在生产环境做覆盖导入测试。
查看 Worker 日志，确认没有 D1 schema、KV、Assets 或鉴权错误。CLI 可使用：
bash
```
npx wrangler tail
```
1
添加自定义域名时，先确认域名能够打开首页、登录和 API，再决定是否关闭 workers.dev。域名切换期间保留一个已验证的管理入口。

只有实际完成资源绑定、首次安装、登录、数据持久化、隐私隔离、备份和日志检查，才能把该部署视为可用。自定义域名启用后还要单独验证域名入口，不要用构建成功代替运行验收。

回滚边界

代码、配置和数据要分别准备回滚：

变更	可以怎样回滚	不能自动恢复的内容
Worker 代码与前端资源	重新部署上一个已验证提交，或使用 Cloudflare 的部署版本回退能力	D1 schema、书签数据、KV 状态、Dashboard 变量
`wrangler.toml`	从上一个提交恢复入口、兼容性日期和绑定声明	远程资源实例和 Secret 的实际值
D1 schema 或数据	使用升级前备份恢复，或执行已审阅的逆向迁移	没有备份时无法依靠代码回滚找回被覆盖的数据
KV `SESSION`	重新绑定原命名空间，或接受会话与限流状态重建	已丢失的撤销记录和限流窗口
自定义域名	恢复上一条已验证路由并保留 `workers.dev` 作为临时入口	DNS 缓存和证书生效时间

升级前应记录当前提交、Worker 名称、D1 数据库名与 ID、KV 命名空间、域名路由和备份位置。不要在没有 D1 备份时执行不可逆 schema 变更，也不要把“Worker 代码回滚成功”当作“数据已经恢复”。

常见问题

页面提示缺少 `DB` 或 `SESSION`

控制台路径检查 Production 部署是否读取了仓库根目录的 wrangler.toml，并在 Worker Bindings 中确认名称完全一致。CLI 路径先运行 wrangler d1 list 和 wrangler kv namespace list，再重新执行 npm run setup:wrangler。不要通过反复创建资源碰运气。

`/install` 提示缺少安装令牌

确认 SETUP_TOKEN 的类型为加密 Secret，作用环境是 Production，并且保存后重新部署过。只在 Dashboard 保存 Secret，不会让已经运行的旧部署自动获得该值。

安装器报告 schema 初始化失败

先确认 Worker 绑定的是预期 D1 数据库，并查看日志。全新空库仍失败时，再审阅项目中的 schema.sql 和远程初始化命令。已有数据的数据库先备份，避免手工 SQL 扩大问题。

CLI 找不到刚创建的资源

最常见原因是 Wrangler 登录了另一个 Cloudflare 账号。运行 npx wrangler whoami，核对 Account ID，再列出 D1 和 KV。多账号环境不要只根据资源名称判断目标。

发布后仍显示旧页面

先确认 Cloudflare 部署完成，再强制刷新，让新的 Service Worker 接管。不要用本机构建产物的文件哈希要求线上完全相同；Cloudflare 会在自己的构建环境重新生成产物。

应该部署 `main` 还是 `develop`

首次生产使用 main 或明确 release，并固定到已验证提交。develop 适合跟踪开发进度，但会引入尚未单独验收的变更。升级时先在隔离环境跑类型检查、测试、构建和功能验收，再更新生产分支或提交。

CF-Navs 使用与 Cloudflare Workers 部署指南 ​

项目概览 ​

适用场景 ​

个人浏览器起始页 ​

工作和团队工具入口 ​

公开资源导航 ​

从现有书签或导航面板迁移 ​

持续收集和整理书签 ​

运行架构 ​

先选择一种部署方式 ​

前置条件 ​

部署路径 ​

路径一：Cloudflare 控制台导入 GitHub ​

路径二：Wrangler CLI ​

配置与绑定 ​

D1 初始化与恢复 ​

首次安装状态 ​

使用教程 ​

建立分类和书签 ​

配置公开与私密内容 ​

导入现有数据 ​

配置外观和搜索 ​

使用浏览器扩展收集新书签 ​

建立备份习惯 ​

验收 ​

本地代码门槛 ​

远程部署验收清单 ​

回滚边界 ​

常见问题 ​

页面提示缺少 DB 或 SESSION ​

/install 提示缺少安装令牌 ​

安装器报告 schema 初始化失败 ​

CLI 找不到刚创建的资源 ​

发布后仍显示旧页面 ​

应该部署 main 还是 develop ​

参考资料 ​

CF-Navs 使用与 Cloudflare Workers 部署指南

项目概览

适用场景

个人浏览器起始页

工作和团队工具入口

公开资源导航

从现有书签或导航面板迁移

持续收集和整理书签

运行架构

先选择一种部署方式

前置条件

部署路径

路径一：Cloudflare 控制台导入 GitHub

路径二：Wrangler CLI

配置与绑定

D1 初始化与恢复

首次安装状态

使用教程

建立分类和书签

配置公开与私密内容

导入现有数据

配置外观和搜索

使用浏览器扩展收集新书签

建立备份习惯

验收

本地代码门槛

远程部署验收清单

回滚边界

常见问题

页面提示缺少 `DB` 或 `SESSION`

`/install` 提示缺少安装令牌

安装器报告 schema 初始化失败

CLI 找不到刚创建的资源

发布后仍显示旧页面

应该部署 `main` 还是 `develop`

参考资料