平时浏览网页时，总会遇到各种值得收藏的网站：开发工具、技术文档、开源项目、在线服务……时间久了，浏览器收藏夹里的内容越来越多，分类越来越复杂，有些网站甚至收藏之后就再也没有打开过。
我一直想拥有一个属于自己的导航站，既能集中管理这些网站，又能随时随地访问，同时不需要维护服务器，也不想依赖复杂的部署环境。
于是，我开发了 CF Workers Navigation。
这是一个基于 Cloudflare Workers + D1 + React 构建的个人书签导航项目，将网站导航、书签管理、分类整理、站内搜索与数据备份整合在一起。既可以作为公开的网站导航页，也可以用于管理自己的私人收藏。
项目采用前后端一体化部署，通过 Cloudflare 提供的基础设施运行，无需自行维护传统服务器。
项目地址： CF Workers Navigation - GitHub
一、为什么要开发这个项目？
浏览器自带的收藏夹其实已经能够满足基本需求，但对于长期积累大量网站的用户来说，仍然存在一些不方便的地方：
- 收藏分散：不同浏览器、不同设备之间管理收藏不够统一。
- 分类不够直观：嵌套文件夹虽然能整理书签，但查找时需要反复展开。
- 缺乏统一入口：希望打开一个网页，就能找到自己常用的网站和工具。
- 公开与私人内容混杂：有些网站适合分享给别人，有些则只想自己查看。
- 迁移和备份不够灵活：希望收藏的数据能够方便地导入、导出和恢复。
我希望做的并不只是一个展示网站链接的静态页面，而是一个可以长期使用、持续维护的个人导航系统。
它应该足够简单，打开就能使用；也应该有一定的管理能力，随着收藏的网站越来越多，依然能够保持清晰有序。
同时，既然主要面向个人使用，我也希望尽可能降低部署和维护成本。
Cloudflare Workers 与 D1 正好提供了这样的技术基础。
二、项目功能介绍
1. 分类导航：让收藏的网站井井有条
导航首页采用分类分区的形式展示书签。
与简单的平铺式导航不同，CF Workers Navigation 支持多级分类结构，可以根据自己的使用习惯灵活组织网站。
例如：
开发资源
├── 前端开发
│ ├── React
│ ├── Vue
│ └── CSS
├── 后端开发
│ ├── Node.js
│ └── 数据库
└── 云服务
├── Cloudflare
└── Vercel
学习资源
├── 技术文档
├── 在线课程
└── 论文研究首页不仅可以浏览一级分类，还可以逐层进入子分类，通过面包屑路径快速返回上级。
选择某个分类时，也可以查看其所有后代分类中的网站，不必逐个文件夹查找。
另外，首页提供常用网站区域，可以将经常访问的书签单独展示。
对于网站数量较多的分类，系统采用按需加载的方式展示内容，避免一次性加载全部数据。
2. 双模式搜索：既能搜索收藏，也能搜索互联网
搜索是这个项目中我比较重视的功能之一。
CF Workers Navigation 将搜索分成了两种独立模式。
站内搜索
用于快速寻找已经收藏的网站。
支持按照网站标题、描述、URL 进行全文检索，也可以结合标签进行筛选。
例如，想找之前收藏过的某个 React 组件库，不需要先进入开发分类，只需要输入关键词即可。
项目底层采用 SQLite FTS5 全文索引，提升书签检索效率。
网页搜索
除了站内搜索，导航页还可以直接作为日常网页搜索入口。
支持：
- 自定义和切换搜索引擎。
- 使用 Bang 语法快速指定搜索引擎。
- 输入网址后直接访问目标网站。
- 使用快捷键快速聚焦搜索框。
这样一来，导航站不仅是书签展示页面，也可以承担浏览器起始页的一部分功能。
3. 书签管理：从收藏到整理的一站式操作
登录管理员账户后，可以直接在首页添加或编辑书签，不需要每次都进入管理后台。
添加网站时，系统支持自动获取网页元数据，尝试补全：
- 网站标题
- 网站描述
- 网站图标
如果自动获取失败，也可以手动填写。
对于比较复杂的管理操作，项目提供独立的 /admin 后台。
后台目前包含：
| 管理模块 | 主要功能 |
|---|---|
| 概览 | 查看书签相关统计信息 |
| 书签管理 | 添加、编辑、筛选、归档和删除书签 |
| 分类管理 | 多级分类、排序、移动、重命名及权限设置 |
| 标签管理 | 创建、编辑、删除及合并标签 |
| 网站设置 | 主题、背景、默认权限及搜索引擎配置 |
| 数据管理 | 书签导入、导出与备份 |
书签还支持归档和回收站机制。
暂时不常用的网站可以先归档；删除的书签进入回收站，需要时能够恢复，也可以选择永久删除。
这样既能让导航首页保持整洁，也不用因为整理收藏而轻易丢失内容。
4. 公开与私有：一个导航站，两种使用场景
我希望这个导航站既可以作为对外展示的个人网站，也可以管理不适合公开的收藏。
因此，项目设计了公开与私有两种访问权限。
- 访客模式：无需登录，只能查看公开且处于活动状态的网站和分类。
- 管理员模式：登录后可以查看和管理私人书签，以及进行其他管理操作。
更重要的是，权限不仅可以设置在书签上，也可以设置在分类上。
例如：
公开分类：开发工具
├── GitHub（公开）
├── Cloudflare Docs（公开）
└── 私人项目地址（私有）
私有分类：个人服务
├── NAS 管理入口
├── 内部工具
└── 自建服务当某个父分类被设置为私有时，其下级分类及书签会受到继承保护。
即使子书签被单独设置为公开，只要仍位于私有分类下，访客就无法查看。
这个设计可以减少因忘记修改单个书签权限而导致内容意外公开的风险。
需要说明的是，私有权限控制的是书签记录的可见性，并不意味着被收藏的目标网站本身获得了访问保护。
5. 导入与导出：数据始终可以自己掌控
我不希望个人书签被某一种服务或者数据格式锁定。
因此，CF Workers Navigation 同时支持 JSON 和 浏览器书签 HTML 两种格式的导入、导出。
HTML 格式
兼容常见的 Netscape Bookmark 文件格式，适合将浏览器收藏夹迁移到导航站，也方便将书签导出到其他工具。
JSON 格式
更适合项目自身的完整备份与恢复。
除了基础的网站信息，还可以保留：
- 多级分类关系
- 标签信息
- 公开与私有权限
- 常用网站状态
- 归档与回收站记录
- 相关时间信息
导入过程中还会进行 URL 匹配与重复记录处理，避免简单导入导致大量重复书签。
需要注意的是，HTML 无法保留全部项目专属信息。如果希望完整备份，建议优先使用 JSON 格式。
另外，备份文件可能包含私有书签，请妥善保存。
6. 外观设计与多端适配
除了功能，我也希望这个项目在视觉上保持简洁。
整体设计参考了 Apple 风格的界面语言，强调清晰的内容层级、克制的配色以及舒适的交互反馈。
目前支持：
- 亮色主题
- 暗色主题
- 跟随系统主题
- 自定义背景图片
- 桌面与移动设备适配
导航首页和管理后台采用不同的界面组织方式。
前台更注重内容展示与快速访问，后台则更注重管理效率。
尤其是在移动端，后台针对较窄的屏幕进行了布局调整，方便使用手机完成简单的书签管理操作。
三、技术架构：为什么选择 Cloudflare？
这是一个比较轻量的个人项目，我不希望为了运行一个导航站，还需要单独购买服务器、安装数据库、配置反向代理并长期维护运行环境。
因此，从一开始就选择了 Cloudflare 的 Serverless 技术方案。
技术栈
| 技术 | 用途 |
|---|---|
| Cloudflare Workers | 后端 API 与应用运行环境 |
| Cloudflare D1 | SQLite 数据库存储 |
| React + TypeScript | 前端应用开发 |
| Vite | 前端构建 |
| TanStack Router | 前端路由 |
| Tailwind CSS | 样式开发 |
| Hono | Worker HTTP API |
| Drizzle ORM | 数据库访问 |
| Zod | 数据验证 |
| shadcn/ui + Base UI | 管理后台与交互组件 |
| GitHub Actions | 自动化检查与部署 |
整个项目采用单仓库、前后端一体化的组织方式。
核心代码结构如下：
src/
├── worker/
│ ├── routes
│ ├── services
│ └── 数据库及业务逻辑
├── web/
│ ├── navigation
│ └── admin
└── shared/
└── 前后端共享契约
migrations/ # D1 数据库迁移
public/ # 静态资源
test/ # 单元与 Worker 集成测试其中：
worker负责 API、数据处理和权限验证。web负责导航首页和管理界面。shared负责共享类型、接口契约和 API 客户端。
前端静态资源和 Worker API 由同一个 Cloudflare Worker 部署统一承载，不需要额外部署独立的前端服务。
为什么使用 D1？
D1 是 Cloudflare 提供的托管式 SQL 数据库服务，基于 SQLite。
对于书签导航来说，数据主要由网站信息、分类、标签及它们之间的关联组成，非常适合使用关系型数据库进行管理。
项目还使用了 SQLite FTS5 实现全文搜索，并通过数据库索引优化查询。
相比单纯把所有书签保存在 JSON 文件中，使用数据库更方便实现动态管理、分类关联、筛选和数据状态维护。
同时，也不用自己维护数据库服务器。
为什么选择 Hono？
Hono 是一个轻量级 Web 框架，能够很好地运行在 Cloudflare Workers 环境中。
它提供清晰的路由组织方式，适合处理书签 CRUD、身份认证、数据导入导出等 API 需求。
结合 TypeScript、Zod 与前后端共享接口契约，可以让不同模块之间的数据交互更加明确。
四、如何运行和部署？
项目已经提供本地开发及 Cloudflare 部署文档。
1. 本地运行
首先确保开发环境满足：
- Node.js >= 24
- pnpm >= 11
克隆仓库：
git clone https://github.com/honestman9527/CF-Workers-Navigation.git
cd CF-Workers-Navigation安装依赖：
pnpm install复制本地环境变量模板：
cp .dev.vars.example .dev.vars编辑 .dev.vars，配置本地管理员密码 ADMIN_PASSWORD 和会话签名密钥 SESSION_SECRET。
然后初始化本地数据库：
pnpm db:migrate:local最后启动项目：
pnpm dev浏览器访问：
http://localhost:8787即可查看本地导航站。
2. 部署到 Cloudflare
正式部署需要准备：
- Cloudflare 账户及 Workers 服务。
- 一个 D1 数据库。
- 管理员密码与会话签名密钥。
- 正确的 Wrangler 配置。
首次部署时，需要创建 D1 数据库，并将实际数据库 ID 写入 wrangler.jsonc。
之后配置生产环境 Secrets，完成数据库迁移，再发布 Worker。
项目提供以下部署命令：
pnpm run deploy但需要特别注意：这个命令只负责构建和部署应用，不会自动执行数据库迁移。
首次部署及后续数据库升级，都应该按照仓库部署文档执行完整流程，避免遗漏数据库初始化或迁移步骤。
详细操作请参考：
3. GitHub Actions 自动部署
除了手动部署，项目还配置了 GitHub Actions 工作流。
当代码推送到 main 分支后，会执行 CI 检查。对应提交的 CI 成功后，部署工作流可以自动进行发布。
主要流程包括：
代码推送
↓
CI 检查
↓
构建与部署前验证
↓
确认目标 D1 数据库
↓
记录数据库恢复点
↓
执行数据库迁移
↓
部署 Cloudflare Worker
↓
线上接口检查其中，部署流程会在执行迁移前记录 D1 Time Travel 恢复点，便于发生问题时进行针对性恢复。
为了避免误操作，工作流不会自动创建一个新的生产数据库，而是要求确认已有数据库。
这些设计也是我希望项目能够长期维护的一部分：不仅要能够部署成功，还应该尽可能降低更新时的数据风险。
五、实际使用场景
对我而言，这个项目主要有三个使用场景。
第一个是个人浏览器导航页。
把经常使用的开发文档、在线工具、云服务平台和开源项目放在一起，通过分类和搜索快速访问。
第二个是长期积累的网站收藏库。
一些网站不一定每天都会使用，但可能在将来重新用到。
通过分类、标签、搜索和归档，可以逐步积累自己的网络资源收藏，而不必把所有内容堆在浏览器收藏夹中。
第三个是公开分享与个人管理相结合。
公开分类可以用于分享自己常用的开发工具和资源，私人分类则保留个人服务入口和不希望公开的收藏。
同一个网站，就可以承担这两种用途。
六、开发过程中的一些思考
在开发这个项目时，我逐渐意识到，一个看起来简单的书签导航，实际上也涉及不少值得认真处理的细节。
例如，分类不只是给书签添加一个名称。支持多级分类后，还需要考虑分类移动、父子关系、权限继承以及删除后的处理方式。
搜索也不只是提供一个输入框，还需要区分站内检索和外部网页搜索，并处理筛选条件、浏览器历史和分页加载。
数据管理同样如此。除了能够导入导出，还需要考虑重复 URL、旧版本备份、部分导入失败以及恢复时的数据完整性。
另外，项目采用 Cloudflare D1，也意味着需要关注数据库查询次数、分页方式和部署迁移的安全性。
因此，我没有把它简单实现成一个只有前端页面的导航模板，而是围绕实际使用需求逐步建立了完整的数据模型、管理界面和部署流程。
当然，它仍然是一个面向个人需求持续完善的项目，并不意味着所有场景都已经得到充分验证。
后续也会根据实际使用体验继续调整和优化。
七、总结
CF Workers Navigation 最初只是为了给自己建立一个更方便的网站收藏入口。
随着功能逐步完善，它已经不再只是一个简单的链接展示页面，而是一个集导航、搜索、书签管理、分类标签、权限控制和备份迁移于一体的个人书签管理应用。
我比较满意的是，它将前端、API 和数据库整合到了 Cloudflare 生态中，日常使用无需自行维护传统服务器，同时依然保留了完整的数据管理和迁移能力。
如果你也喜欢收集各种网站、开发工具、技术文档，或者正在寻找一个可以自己部署和定制的个人导航项目，可以尝试一下。
项目开源，欢迎查看代码、提出建议，也欢迎根据自己的需求进行修改。
GitHub： https://github.com/honestman9527/CF-Workers-Navigation
使用文档： https://github.com/honestman9527/CF-Workers-Navigation/blob/main/docs/usage.md
部署文档： https://github.com/honestman9527/CF-Workers-Navigation/blob/main/docs/deployment.md
如果这个项目对你有所帮助，也欢迎在 GitHub 点一个 Star。
关键词： Cloudflare Workers、Cloudflare D1、React、TypeScript、Hono、个人导航、书签管理、Serverless、自部署