这次我们来看一个完全零成本、基于 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 命名空间KVKey-Value是 Cloudflare 的分布式键值存储CF-Navs 用它来存储导航链接数据和访问统计。登录 Cloudflare 仪表板。在左侧菜单栏进入Workers Pages。在顶部选项卡中选择KV。点击Create namespace按钮。输入一个名称例如CF_NAVS_STORE然后点击Add。创建成功后记住这个Namespace ID一长串字符后面配置会用到。4.3 部署到 Cloudflare PagesPages 是 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填写.一个点表示根目录就是构建输出目录。点击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_IDValue输入你在4.2步骤中创建的 KV 命名空间的ID。确保Environment选择了Production。点击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。点击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_PASSWORDValue: 你的访问密码例如MySecurePass123Environment:Production保存并重新部署项目。方法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部分的排查表逐一检查。
