这次我们来看一个完全零成本、基于 Cloudflare 平台部署的私人导航站项目:CF-Navs。对于需要整理个人书签、团队链接库,或者想拥有一个带访问统计和密码保护的专属导航页的用户来说,这个方案几乎没有任何硬件门槛和持续费用。
CF-Navs 的核心价值在于,它完全运行在 Cloudflare 的 Workers 和 Pages 服务上。这意味着你不需要购买服务器,不需要关心运维,甚至不需要域名(可以使用 Cloudflare 提供的*.pages.dev子域名)。项目开源,部署过程主要依赖 GitHub 和 Cloudflare 控制台的操作,几分钟内就能让一个功能完整的导航站上线。
本文将带你完整走通从 Fork 代码到最终访问的整个流程。我们会重点关注几个实用功能:如何设置密码保护来限制访问、如何查看详细的点击数据统计、以及如何一键备份/恢复你的导航站数据。整个过程不需要你写代码,但需要你有一个 GitHub 账号和一个 Cloudflare 账号。
1. 核心能力速览
在开始动手之前,先快速了解 CF-Navs 能做什么,以及它的技术特点。
| 能力项 | 说明 |
|---|---|
| 部署平台与成本 | 完全基于 Cloudflare Workers & Pages,零服务器成本,无月度费用。 |
| 访问控制 | 支持全局密码保护,访问首页需输入预设密码。 |
| 数据统计 | 内置访问统计,可查看每个导航链接的点击次数、来源等数据。 |
| 数据管理 | 支持通过 GitHub 仓库一键备份和恢复导航站数据(链接配置)。 |
| 自定义域名 | 支持绑定自定义域名(非必须),也可直接使用xxx.pages.dev免费域名。 |
| 前端技术 | 基于纯静态页面(HTML, CSS, JS),无需数据库,数据存储在 Cloudflare KV 中。 |
| 部署复杂度 | 低。主要操作为 GitHub Fork、Cloudflare 控制台配置,无需命令行。 |
| 适合场景 | 个人书签管理、团队内部工具导航、项目链接门户、学习资源聚合页。 |
从表格可以看出,这个项目的门槛极低,核心价值是“零成本”和“开箱即用”。下面我们就从环境准备开始。
2. 适用场景与使用边界
在部署前,明确一下 CF-Navs 最适合谁,以及它不能做什么,可以帮你更好地决策。
最适合的场景:
- 个人效率工具:开发者、设计师、研究人员将日常高频使用的网站(如文档、工具、仪表盘)聚合在一个页面,避免书签栏杂乱。
- 团队资源共享:小团队或项目组可以部署一个内部导航,集中放置项目文档、测试环境、监控系统等链接,方便新成员快速上手。
- 学习资源导航:将自己收藏的教程、博客、在线工具分门别类,打造一个专属的学习门户。
- 临时项目门户:为某个短期活动或项目快速创建一个链接集合页面,活动结束后可直接删除,无残留成本。
需要注意的边界:
- 功能复杂度:它是一个静态导航页,核心功能是链接跳转和统计。不支持用户注册、评论、动态内容发布等Web应用功能。
- 数据存储量:数据存储在 Cloudflare KV 中,免费 tier 有读写次数和存储容量限制。对于纯链接导航场景,通常完全够用,但不应存储大文件。
- 访问性能:依赖 Cloudflare 全球网络,访问速度通常很快。但免费 Workers 有每日请求次数限制,对于个人或小团队使用,几乎不可能触达。
- 定制化程度:界面样式和结构需要通过修改前端代码来定制,对于没有前端基础的用户,可能仅限于修改配置文件和简单CSS。
安全与合规提醒:虽然可以设置密码保护,但这并非企业级安全认证。请勿用于存放高度敏感的商业机密或个人信息链接。绑定自定义域名时,请确保你拥有该域名的合法使用权。
3. 环境准备与前置条件
部署 CF-Navs 不需要本地开发环境,但需要准备好以下几个在线服务和账号。
GitHub 账号
- 作用:Fork 项目代码仓库,并作为连接 Cloudflare 的桥梁。
- 准备:访问 github.com 注册或登录你的账号。
Cloudflare 账号
- 作用:提供 Workers、Pages、KV 等运行时资源。
- 准备:访问 dash.cloudflare.com 注册或登录。新账号有充足的免费额度。
一个可用的邮箱
- 作用:接收 GitHub 和 Cloudflare 的验证邮件。
(可选)自定义域名
- 作用:如果你不想使用
xxx.pages.dev的域名,可以准备一个自己的域名,并将其 DNS 托管到 Cloudflare。 - 准备:购买一个域名(如从 Namesilo、GoDaddy 等),并将其 DNS 服务器修改为 Cloudflare 提供的地址。
- 作用:如果你不想使用
检查清单:
- [ ] 拥有并登录 GitHub 账号
- [ ] 拥有并登录 Cloudflare 账号
- [ ] 网络可以正常访问 GitHub 和 Cloudflare 控制台
4. 安装部署与启动方式
整个部署流程是一条清晰的流水线:Fork 代码 -> 在 Cloudflare 创建 KV -> 部署 Pages 项目 -> 绑定 Workers 和 KV。我们一步步来。
4.1 Fork 项目代码仓库
首先,你需要将 CF-Navs 的代码复制到自己的 GitHub 账户下。
- 打开 CF-Navs 的项目主页。你可以通过 GitHub 搜索
CF-Navs找到它,或者直接访问其仓库地址(请根据实际搜索到的仓库地址操作)。 - 在仓库页面的右上角,点击
Fork按钮。 - 在弹出的页面中,选择你的个人账户作为目标,点击创建 Fork。
- 稍等片刻,你会在自己的 GitHub 主页下看到一个同名的仓库,这表示 Fork 成功。这是你后续所有操作的起点。
4.2 在 Cloudflare 中创建 KV 命名空间
KV(Key-Value)是 Cloudflare 的分布式键值存储,CF-Navs 用它来存储导航链接数据和访问统计。
- 登录 Cloudflare 仪表板。
- 在左侧菜单栏,进入Workers & Pages。
- 在顶部选项卡中,选择KV。
- 点击Create namespace按钮。
- 输入一个名称,例如
CF_NAVS_STORE,然后点击Add。 - 创建成功后,记住这个Namespace ID(一长串字符),后面配置会用到。
4.3 部署到 Cloudflare Pages
Pages 是 Cloudflare 的静态网站托管服务,我们将把前端代码部署在这里。
- 在 Cloudflare 仪表板,进入Workers & Pages->Overview->Create application->Pages。
- 在 “Connect to Git” 部分,选择GitHub并授权 Cloudflare 访问你的 GitHub 账户。
- 授权后,选择你刚刚 Fork 的
CF-Navs仓库。 - 进入配置页面:
- Project name:给你的项目起个名字,如
my-navs。这将决定你的免费访问域名(my-navs.pages.dev)。 - Production branch:通常为
main或master,保持默认即可。 - Framework preset:选择
None或Static,因为这是一个纯静态项目。 - Build command:留空。
- Build output directory:填写
.(一个点),表示根目录就是构建输出目录。
- Project name:给你的项目起个名字,如
- 点击Save and Deploy。Cloudflare 会自动开始部署。首次部署可能耗时1-2分钟。
- 部署成功后,你会看到一个
*.pages.dev的预览链接,例如https://my-navs.pages.dev。点击它,你应该能看到 CF-Navs 的默认界面。此时还没有功能,因为后台 Workers 和 KV 还没配置。
4.4 配置环境变量与绑定 KV
我们需要告诉 Pages 应用,它应该连接哪个 KV 命名空间。
- 在你的 Pages 项目详情页,进入Settings->Environment variables。
- 点击Add variable。
- Variable name:输入
KV_NAMESPACE_ID - Value:输入你在4.2步骤中创建的 KV 命名空间的ID。
- 确保Environment选择了
Production。
- Variable name:输入
- 点击Save。
接下来,需要将 KV 命名空间绑定到 Pages 函数(Functions)上。CF-Navs 使用 Pages Functions 来处理 API 请求(如数据统计、密码验证)。
- 在 Pages 项目详情页,进入Functions选项卡。
- 在KV namespace bindings区域,点击Add binding。
- Variable name:输入
NAV_STORE(此名称与项目代码中的调用名对应,请务必准确)。 - KV namespace:选择你之前创建的
CF_NAVS_STORE。
- Variable name:输入
- 点击Save。
4.5 重新部署并验证
环境变量和绑定配置完成后,需要触发一次重新部署使其生效。
- 回到 Pages 项目的Deployments选项卡。
- 找到最新的那次部署,点击右侧的…菜单,选择Retry deployment或Redeploy。
- 等待部署完成。
- 再次访问你的
*.pages.dev域名。现在,页面应该可以正常加载,并且底部可能显示“数据加载成功”或类似提示。这表示前端已经成功连接到后台 KV 存储。
至此,基础部署完成。接下来我们配置核心功能。
5. 功能测试与效果验证
现在导航站已经可以访问,但里面是空的,且没有密码保护。我们来逐一测试和配置各项功能。
5.1 初始数据导入与界面管理
CF-Navs 的数据管理通常通过一个特定的管理页面或 API 来完成。你需要查阅你 Fork 的仓库的README.md文件,找到具体的数据初始化方法。
常见操作模式:
- 通过管理页面:访问
https://你的域名.com/admin(或类似路径),输入初始密码(可能在环境变量中设置或为默认值)进入管理后台,在网页表单中添加、编辑、删除链接分类和项目。 - 通过导入配置文件:在项目代码的
src或config目录下,找到一个如data.json或links.example.json的示例文件。按照其格式,在本地编辑你的导航数据,然后通过某个 API 端点(如POST /api/init)或管理页面的导入功能上传。
测试步骤:
- 按照项目文档,找到初始化数据的方法。
- 添加几个测试链接,例如:
[ { "category": "搜索引擎", "items": [ { "name": "Google", "url": "https://www.google.com", "icon": "search" }, { "name": "Bing", "url": "https://www.bing.com", "icon": "search" } ] }, { "category": "开发工具", "items": [ { "name": "GitHub", "url": "https://github.com", "icon": "code" } ] } ] - 提交数据。
- 刷新导航站首页,检查测试链接是否正常显示,点击后能否正确跳转。
成功标准:首页按分类展示你添加的链接,图标和名称显示正常,点击链接能在新标签页或当前页打开目标网站。
5.2 密码保护功能配置与测试
密码保护是 CF-Navs 的一个重要特性,确保只有知道密码的人可以访问导航页。
配置方法(通常有以下两种):
方法A:通过环境变量配置
- 在 Cloudflare Pages 的Settings->Environment variables中,添加一个新的变量。
- Variable name:
SITE_PASSWORD - Value: 你的访问密码,例如
MySecurePass123 - Environment:
Production
- Variable name:
- 保存并重新部署项目。
方法B:通过 KV 存储配置有些实现会将密码存储在 KV 中。你可能需要通过一个特殊的初始化 API 或首次访问的安装流程来设置密码。
测试步骤:
- 配置好密码后,在浏览器中打开无痕窗口(防止缓存)。
- 访问你的导航站地址。
- 预期行为:页面应该首先显示一个密码输入框,而不是直接显示导航内容。
- 输入错误的密码,应提示错误。
- 输入正确的密码,应成功进入导航主页,并且后续刷新页面(在同一浏览器会话中)可能不再需要输入密码(依赖 Cookie 或 LocalStorage)。
验证要点:
- 密码保护是否生效。
- 密码验证是否正确。
- 登录状态是否有合理的保持时间。
5.3 数据统计功能验证
数据统计功能用于记录每个链接的点击次数。
测试步骤:
- 在已通过密码验证的页面,点击几个你添加的测试链接。
- 查看统计页面。统计页面的入口通常是点击首页的“统计”或“Analytics”链接,或者访问
https://你的域名.com/stats。 - 在统计页面,你应该能看到被点击过的链接,并且其“点击次数”应该增加了。
- 统计信息可能包括:点击总量、每个链接的独立点击、最近访问时间、访问来源(如果实现)等。
成功标准:统计页面能正确显示数据,点击操作能实时或近实时地反映在统计数字上。
5.4 一键备份与恢复测试
这个功能通常依赖于 GitHub 仓库。你的导航站配置(data.json)可能会被自动提交到你 Fork 的仓库的某个分支(如backup)或目录下。
操作与验证流程:
- 触发备份:在管理页面或通过访问特定 API 端点(如
GET /api/backup)触发备份操作。 - 检查 GitHub 仓库:稍后,刷新你 Fork 的 GitHub 仓库页面,检查是否生成了一个新的提交,提交信息可能包含“backup”字样,并且修改了存储数据的文件(如
data.json)。 - 模拟数据丢失:在导航站管理页面,删除或修改某个链接并保存。
- 执行恢复:在管理页面找到“从备份恢复”功能,或调用恢复 API(如
POST /api/restore)。选择最新的备份文件进行恢复。 - 验证恢复结果:刷新导航站首页,确认之前删除或修改的链接已恢复到备份时的状态。
成功标准:备份操作能在 GitHub 仓库留下记录;恢复操作能准确地将导航站数据回滚到备份点。
6. 接口 API 与批量任务
CF-Navs 的核心数据操作通常通过其内置的 Pages Functions API 完成。了解这些 API 有助于你进行自动化管理。
常见的 API 端点(请以实际项目代码为准):
GET /api/links: 获取所有导航链接数据。POST /api/links: 更新或设置导航链接数据(需要密码或令牌验证)。GET /api/stats: 获取统计数据。POST /api/record: 记录一次链接点击(通常由前端自动调用)。GET /api/backup: 触发数据备份。POST /api/restore: 从备份恢复数据。
使用 curl 测试 API(示例):
假设你的域名是https://my-navs.pages.dev,且已设置密码。
# 1. 获取链接数据 (如果不需要密码) curl -X GET "https://my-navs.pages.dev/api/links" # 2. 更新链接数据 (需要认证,示例中通过HTTP Basic Auth传递密码) # 首先,将你的密码进行base64编码:echo -n 'MySecurePass123' | base64 # 假设编码后得到 TXlTZWN1cmVQYXNzMTIzCg== curl -X POST "https://my-navs.pages.dev/api/links" \ -H "Content-Type: application/json" \ -H "Authorization: Basic TXlTZWN1cmVQYXNzMTIzCg==" \ -d '{"categories": [...]}' # 3. 触发备份 curl -X GET "https://my-navs.pages.dev/api/backup" \ -H "Authorization: Basic TXlTZWN1cmVQYXNzMTIzCg=="批量任务场景: 虽然 CF-Navs 本身不直接提供批量任务队列,但你可以利用其 API 结合脚本实现批量操作。
- 批量初始化链接:编写一个 Python/Node.js 脚本,读取本地的 CSV 或 JSON 文件,通过
POST /api/links接口批量写入。 - 定期备份:使用 GitHub Actions、Cloudflare Workers Cron Trigger 或简单的服务器定时任务,定期调用
/api/backup接口,实现自动化备份。 - 数据同步:如果你有多个导航站实例,可以通过脚本调用 API 获取一个实例的数据,然后更新到另一个实例。
7. 资源占用与性能观察
由于 CF-Navs 完全运行在 Cloudflare 无服务器平台上,因此你无需关心传统的服务器资源(CPU、内存、带宽)占用。你需要关注的是 Cloudflare 免费额度的使用情况。
主要配额与观察点:
Cloudflare Workers 请求次数:
- 免费额度:每日 100,000 次请求。
- 如何观察:在 Cloudflare 仪表板,进入Workers & Pages-> 选择你的 Pages 项目 ->Analytics选项卡。这里可以看到请求量、错误率等图表。
- 影响:对于导航站,每次页面加载、API 调用(获取数据、记录点击)都算一次请求。个人使用几乎不可能用完。
Cloudflare KV 操作次数与存储:
- 免费额度:每日 100,000 次读取操作,1,000 次写入/删除/列出操作;存储空间 1 GB。
- 如何观察:在Workers & Pages->KV-> 选择你的命名空间 ->Analytics。
- 影响:每次读取链接数据、写入点击记录都会消耗操作次数。存储导航链接的 JSON 文本,大小通常只有几 KB 到几十 KB,远低于 1 GB。
Cloudflare Pages 带宽与构建次数:
- 免费额度:每月 500 次构建,无限带宽(但有公平使用原则)。
- 如何观察:Pages 项目详情页的Deployments和Analytics。
- 影响:频繁重新部署会消耗构建次数。正常内容更新后部署,每月500次完全足够。
性能优化建议:
- 减少不必要的重新部署:仅在配置(如环境变量)或代码更新时触发部署。
- 利用浏览器缓存:静态资源(JS、CSS、图标)会被 Cloudflare CDN 缓存,后续访问速度极快。
- API 调用优化:前端代码应合理设计,避免短时间内频繁调用统计记录 API。
8. 常见问题与排查方法
部署和使用过程中可能会遇到一些问题,下表列出了常见现象及解决方法。
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
部署后访问*.pages.dev显示空白页或错误 | 1. 构建输出目录设置错误。 2. 前端资源路径错误。 3. KV 未正确绑定或环境变量未设置。 | 1. 检查 Pages 部署日志(Deployments -> 点击某次部署 -> Logs)。 2. 浏览器开发者工具查看 Console 和 Network 报错。 3. 检查环境变量 KV_NAMESPACE_ID和 KV 绑定NAV_STORE是否正确。 | 1. 确认Build output directory为.。2. 根据错误日志修正代码或配置。 3. 核对并修正环境变量与绑定,然后重新部署。 |
| 页面能打开,但显示“加载数据失败”或列表为空 | 1. KV 命名空间 ID 错误。 2. KV 绑定变量名与代码中使用的名称不匹配。 3. KV 中尚未存储任何数据。 | 1. 检查环境变量KV_NAMESPACE_ID的值是否为正确的 ID。2. 检查 Pages Functions 的 KV 绑定名称是否与代码中 env.NAV_STORE一致。3. 尝试通过管理页面或 API 初始化数据。 | 1. 修正环境变量。 2. 确保绑定名称一致。 3. 执行数据初始化操作。 |
| 密码保护不生效,直接进入主页 | 1. 环境变量SITE_PASSWORD未设置或设置错误。2. 前端密码验证逻辑有缓存或错误。 | 1. 确认 Pages 环境变量已设置并已重新部署。 2. 使用浏览器无痕模式访问测试。 3. 查看前端代码中读取环境变量的逻辑。 | 1. 正确设置SITE_PASSWORD并重新部署。2. 清除浏览器缓存或使用无痕窗口。 |
| 输入正确密码仍无法进入 | 1. 密码验证 API (Function) 部署失败或逻辑错误。 2. 密码在传输或比对时出错。 | 1. 查看 Pages Functions 的部署日志和调用日志。 2. 检查密码验证的 API 端点是否正常工作(可用 curl 测试)。 | 1. 检查 Functions 代码,确保密码验证逻辑正确。 2. 确认密码字符串前后无多余空格。 |
| 点击统计不增长 | 1. 记录点击的 API 端点 (/api/record) 调用失败。2. 前端 JavaScript 代码未正确发送点击事件。 3. KV 写入额度用尽(极罕见)。 | 1. 浏览器开发者工具 Network 面板,查看点击链接时是否有对/api/record的请求,以及请求状态。2. 检查该 Function 的日志。 | 1. 修复前端点击事件监听和 API 调用代码。 2. 检查并修复 /api/record这个 Function 的代码。 |
| 备份/恢复功能无效 | 1. 备份/恢复 API 未正确实现或部署。 2. 缺少必要的 GitHub Token 或仓库写入权限。 3. 备份文件路径或格式错误。 | 1. 直接调用备份/恢复 API,查看返回错误信息。 2. 检查 GitHub Actions 或 Function 日志。 3. 确认备份数据文件的格式符合要求。 | 1. 根据项目文档,配置正确的 GitHub Token 等密钥。 2. 确保 Fork 的仓库有写入权限。 3. 检查备份生成的文件内容。 |
| 自定义域名绑定后无法访问 | 1. DNS 解析未生效或错误。 2. Cloudflare Pages 自定义域名配置未完成。 3. SSL/TLS 证书问题。 | 1. 使用dig或在线工具检查域名是否解析到 Cloudflare。2. 在 Pages 项目设置中,检查自定义域名状态是否为 “Active”。 3. 检查浏览器证书错误信息。 | 1. 等待 DNS 生效(最多72小时,通常很快)。 2. 按照 Cloudflare 指引完成 CNAME 记录设置和页面验证。 3. 确保 Cloudflare 的 SSL/TLS 模式为 “Full” 或 “Full (strict)”。 |
9. 最佳实践与使用建议
为了让你的 CF-Navs 导航站更稳定、安全、易用,可以参考以下建议。
- 环境变量管理:将密码等敏感信息始终放在 Cloudflare Pages 的Environment variables中,而不是硬编码在代码里。这样更安全,也便于在不同环境(如生产、预览)使用不同配置。
- 定期备份验证:虽然有一键备份功能,建议定期(如每月)手动检查一下 GitHub 备份仓库,确认备份文件存在且内容是最新的。你可以将备份仓库设置为私有。
- 使用强密码:用于保护导航站的密码应足够复杂,避免使用简单数字或常见单词。可以考虑使用密码生成器。
- 分类与标签规划:在添加大量链接前,先规划好分类体系。可以按用途(开发、设计、学习)、按项目、按频率等维度划分,使导航站保持清晰。
- 图标优化:项目通常支持从 iconfont 或指定图标库选择图标。使用统一的图标风格能让页面更美观。如果支持自定义图标 URL,可以准备一套尺寸一致的 favicon。
- 渐进式更新:当需要大规模修改导航结构时,先在本地编辑好数据文件(如
data.json),通过测试环境或本地预览确认无误后,再通过管理页面或 API 更新到线上。 - 监控额度使用:虽然免费额度很充裕,但建议在 Cloudflare 仪表板为 Workers 和 KV 设置简单的通知,当用量达到额度的80%时收到告警,以防意外流量冲击。
- 合规使用:确保你添加到导航站的链接都是可公开访问且不侵犯他人版权的。如果是内部使用,请确保密码保护有效,并提醒使用者不要泄露密码。
10. 总结与下一步
CF-Navs 提供了一个极其轻巧且零成本的方案,来解决私人导航站的需求。它最大的优势在于利用了 Cloudflare 的免费生态,免去了服务器维护的烦恼,同时提供了密码保护、数据统计、一键备份这三个非常实用的功能。
部署成功后,你最先应该验证的就是密码保护和数据统计是否工作正常,这是区别于公开书签页的核心。最容易踩的坑在于KV 绑定和环境变量的配置,务必仔细核对 Namespace ID 和绑定变量名。
如果你满足于基本功能,到这里就已经足够了。如果你希望进一步定制,可以考虑以下几个方向:
- 界面美化:修改项目的 CSS 文件,调整颜色、布局、字体,使其更符合你的审美。
- 功能增强:如果你懂一些 JavaScript,可以尝试为它增加搜索框、暗黑模式切换、链接拖拽排序等功能。
- 自动化集成:利用 GitHub Actions,实现当你更新本地数据文件后,自动触发 Cloudflare Pages 部署和 KV 数据更新,实现“GitOps”式的管理。
这个项目很好地展示了如何将静态前端、无服务器函数和键值存储组合成一个可用的应用。即使你不深入修改代码,其部署流程本身也是一次不错的云原生实践。建议收藏本文,如果在部署中遇到问题,可以对照第8部分的排查表逐一检查。