零成本构建私有导航站：Cloudflare Pages与CF-Navs实战指南

1. 先搞清楚 Cloudflare Pages 和 CF-Navs 能帮你做什么如果你需要一个完全免费、带密码保护、能看访问数据、还能一键备份的私人导航页那 Cloudflare Pages CF-Navs 这个组合就值得你花时间研究一下。它解决的核心问题是用零成本把一个静态网页变成有后台管理、有访问控制、有数据追踪的“准动态”应用。很多人一听“导航站”就觉得是 hao123 那种其实不然。对于个人或小团队它更像是一个私有化的浏览器主页或资源聚合面板。你可以把常用的内部工具链接、文档地址、监控面板、甚至是只有自己知道的“神秘网站”都放上去用一个统一的入口管理并且通过密码保护确保只有授权的人能访问。CF-Navs 这个项目本质上是一个为 Cloudflare Pages 深度优化的静态网站生成器。它最大的价值不是功能多强大而是把“动态”需求登录、统计、备份通过 Cloudflare 的边缘网络服务和 Workers 来实现从而绕开了传统方案需要服务器、数据库的麻烦。这意味着你不需要租 VPS不需要维护数据库甚至连域名都可以用 Cloudflare 提供的免费二级域名。所以这篇文章适合两类人技术爱好者或开发者想找一个极简、可定制、零运维成本的个人项目部署方案。需要管理小团队内部资源的非技术人员希望有一个安全、稳定、不花钱的共享入口。最关键的几个能力在部署前你心里要有数零成本完全依托 Cloudflare 的免费额度Pages, Workers, KV, Analytics只要不超量一分钱不花。密码保护不是简单的.htpasswd而是通过 Cloudflare Workers 实现的前端鉴权体验更现代。数据统计集成 Cloudflare Web Analytics能看到访问量、来源、页面停留等基础数据。一键备份/恢复导航数据链接、分类保存在 Cloudflare KV 存储里可以通过后台一键导出为 JSON 文件也能一键导入恢复迁移和备份非常方便。下面我就按实际部署和踩坑的顺序带你走一遍。2. 部署前必须准备好的三样东西在点击“Deploy”按钮之前先把环境理顺能避免 80% 的部署失败。你不需要服务器但需要准备好以下三样2.1 一个 Cloudflare 账号这是基础。去 cloudflare.com 注册一个账号。如果你已经有账号确保你能登录到 Dashboard。这个账号将管理你所有的免费服务。2.2 一个 GitHub 账号及仓库CF-Navs 的代码托管在 GitHub并且 Cloudflare Pages 的自动部署需要连接你的 GitHub 仓库。所以你需要有一个 GitHub 账号。将 CF-Navs 的项目 Fork 到你自己的 GitHub 账户下。这一步很重要因为后续的定制化修改比如样式、配置都是在你的仓库里进行。2.3 理清 Cloudflare 的几项服务CF-Navs 用到了 Cloudflare 的多个产品理解它们的关系后面配置才不会懵服务名称作用免费额度在本项目中的角色Pages托管静态网站提供全球 CDN 和自动构建部署。每月 500 次构建无限请求无限带宽。网站本体的托管平台。你的导航站就运行在这里。Workers在边缘网络运行 JavaScript 代码。每日 10 万次请求。提供密码保护的鉴权逻辑。访问网站时先经过 Worker 检查密码。KV (Workers KV)一个键值对存储数据库。每日 1000 次读取、1000 次写入、1000 次删除、1GB 存储。存储导航数据链接、分类和密码的哈希值。Web Analytics网站访问统计。免费无限制。提供数据统计面板查看访客数据。注意免费额度对于个人导航站来说完全够用。除非你的导航站日访问量巨大否则不用担心超限。3. 一步步部署从 Fork 到上线部署流程可以拆解为几个清晰的阶段我们按顺序来。3.1 Fork 项目并初始化 PagesFork 仓库访问 CF-Navs 的 GitHub 仓库页面点击右上角的Fork按钮。这会在你的账号下创建一个副本。创建 Pages 项目登录 Cloudflare Dashboard侧边栏找到Workers Pages点击Create application-Pages-Connect to Git。连接仓库选择你刚刚 Fork 过来的 CF-Navs 仓库。在配置构建和部署的页面CF-Navs 通常已经预设好了直接使用默认设置即可Production branch:mainFramework preset:None或StaticBuild command:npm run build(或yarn build)Build output directory:dist环境变量先跳过先不设置任何环境变量直接点击Save and Deploy。让 Pages 先完成第一次构建和部署。这个过程可能需要2-5分钟。第一次部署成功后你会获得一个*.pages.dev的免费域名。此时访问这个域名你会看到一个空白的导航站框架因为没有数据。同时后台管理入口 (/admin) 也无法登录因为 KV 和 Worker 还没配置。这是正常现象。3.2 配置核心Workers KV 命名空间KV 是存储所有动态数据的地方必须先创建。在 Cloudflare Dashboard 的Workers Pages下找到KV。点击Create namespace给它起个名字比如CF_NAVS_STORE。创建成功后记住这个命名空间的 ID一串长字符。绑定到 Pages进入你刚刚创建的 Pages 项目的设置 (Settings-Functions-KV namespace bindings)。点击Add bindingVariable name必须填写CF_NAVS这是代码里预定义的变量名不能错。KV namespace选择你刚创建的CF_NAVS_STORE。保存。这步操作是告诉你的 Pages 应用“你的数据存在那个叫CF_NAVS_STORE的 KV 里我通过变量CF_NAVS来访问它”。3.3 部署鉴权 Worker实现密码保护密码保护是通过一个独立的 Cloudflare Worker 来实现的。你需要部署这个 Worker并将你的 Pages 网站流量指向它。获取 Worker 代码在你 Fork 的 CF-Navs 仓库里通常有一个worker或auth-worker目录里面是index.js文件。这就是鉴权 Worker 的代码。创建 Worker 服务在 Dashboard 的Workers Pages下点击Create application-Worker。粘贴并修改代码将index.js的内容全部粘贴到在线编辑器中。关键配置在代码开头部分找到需要你修改的配置项通常包括site_url改成你 Pages 站点的域名https://你的站点.pages.dev。password_hash这里需要填入一个bcrypt 哈希后的密码字符串。你不能直接写明文密码。你需要在线找一个bcrypt生成工具或者用 Node.js 命令行npm install bcryptjs后写两行代码生成你的密码哈希。例如你的密码是mysecret123就生成对应的哈希串替换这里。kv_namespace_id把你之前创建的 KV 命名空间 ID 填在这里。部署 Worker点击Save and Deploy。部署成功后你会获得一个*.workers.dev的域名比如my-auth.workers.dev。添加 KV 绑定对 Worker在刚部署的 Worker 的Settings-Variables-KV namespace bindings中同样添加一个绑定变量名可能也是CF_NAVS选择同一个CF_NAVS_STORE命名空间。这样 Worker 也能读写导航数据。3.4 设置路由让流量经过 Worker这是最后一步也是让密码保护生效的关键。回到你的 Pages 项目设置找到Custom domains或Triggers部分。你需要添加一个Custom Domain如果你有自己的域名或者配置*.pages.dev域名的路由。更通用的方法在 Workers Pages 仪表板在 Dashboard 首页找到Workers Pages。你应该能看到你创建的 Worker (my-auth) 和 Pages 站点。Cloudflare 现在提供了Routes功能。你需要创建一个路由规则将你的 Pages 站点域名或自定义域名的流量指向你刚创建的 Worker。例如添加一条路由你的站点.pages.dev/*然后目标选择my-auth这个 Worker。验证设置完成后清除浏览器缓存再次访问你的导航站域名。此时应该会弹出一个密码输入框。输入你之前设置的明文密码如mysecret123即可进入网站。至此密码保护功能已就绪。接下来是初始化数据。4. 初始化后台与数据管理通过密码进入网站后访问https://你的站点.pages.dev/admin即可进入后台管理界面。4.1 首次登录与初始化第一次进入/admin由于 KV 里是空的系统可能会提示你初始化或直接显示空状态。你需要在后台进行以下操作设置导航站信息在后台找到“站点设置”或类似选项填写网站标题、Logo、描述等。添加分类和链接这是主要操作。按照界面提示创建分类如“开发工具”、“日常办公”、“娱乐”然后在对应分类下添加链接名称、URL、图标等。图标CF-Navs 通常支持从 FontAwesome 或 Iconify 选择图标。你只需要输入图标的名字如fa-github即可。所有你添加、修改、删除的操作都会实时保存到 Cloudflare KV 中。4.2 数据统计的查看数据统计功能依赖于 Cloudflare Web Analytics。在 Cloudflare Dashboard 侧边栏找到Analytics Logs-Web Analytics。点击Add a site输入你的导航站完整域名https://你的站点.pages.dev。按照提示在你的网站首页的head标签内插入一段给定的 JS 代码片段。如何插入对于 CF-Navs你需要修改源代码。在你 Fork 的仓库里找到 HTML 模板文件通常是index.html或src/index.html将 Analytics 的代码片段粘贴到head里。然后提交代码Cloudflare Pages 会自动重新构建部署。部署完成后等待一段时间可能需要几小时你就能在 Web Analytics 面板里看到访问数据了。这个统计面板是独立于导航站后台的你需要到 Cloudflare Dashboard 查看。4.3 一键备份与恢复这是 CF-Navs 非常实用的功能在后台管理界面应该能找到“备份”或“数据”选项。备份点击“导出”或“备份”系统会从 KV 中读取所有数据站点配置、分类、链接并生成一个navs-backup-日期.json文件供你下载。恢复点击“导入”或“恢复”选择你之前备份的 JSON 文件上传系统会清空现有 KV 数据并写入备份内容。操作前务必谨慎最好先做一次备份。这个功能完美解决了数据迁移和版本回退的问题。你可以本地保存多个备份文件随时切换。5. 常见问题与排查思路部署过程不会总是一帆风顺遇到问题按这个顺序查。5.1 页面打开空白或显示错误先看 Pages 部署状态进入 Pages 项目查看最近的部署记录。如果是Failed查看构建日志 (Build Logs)。常见原因是构建命令错误或依赖安装失败。确保package.json和构建配置正确。检查 KV 绑定确认 Pages 的CF_NAVS变量绑定到了正确的 KV 命名空间 ID。绑定错误会导致前端无法读取数据显示空白。检查路由确认你的域名是否成功解析并指向了 Cloudflare。如果用了自定义域名检查 DNS 记录A 记录或 CNAME 记录是否正确。5.2 密码保护不生效直接进入网站不弹窗检查 Worker 路由这是最常见的原因。确认你为 Pages 域名设置的路由规则是否成功指向了鉴权 Worker (my-auth)。检查 Worker 代码配置确认 Worker 代码中的site_url是否填写正确必须是https://开头。确认password_hash是否是有效的 bcrypt 哈希。浏览器缓存强制刷新页面 (CtrlF5)或打开浏览器无痕模式测试。Worker 是否部署成功直接访问*.workers.dev域名看 Worker 本身是否运行正常可能会返回一个简单页面或提示。5.3 后台/admin无法登录或操作无效KV 权限确保 Worker 和 Pages 都绑定了同一个KV 命名空间且变量名正确。后台操作增删改通常是通过 Worker 触发的 API 写入 KV如果 Worker 没有 KV 写入权限操作会失败。查看浏览器控制台 (Console)打开浏览器的开发者工具进入 Network 和 Console 标签页尝试在后台做一个操作如添加链接。看是否有红色的错误请求Console 是否有报错信息。错误信息通常会提示是网络请求失败还是权限问题。Worker 日志在 Worker 的 Dashboard 中查看Logs标签页。这里能看到 Worker 每次被调用时的详细日志包括错误信息是排查鉴权和 API 问题的利器。5.4 数据统计不显示代码是否插入检查网站页面源代码 (CtrlU)搜索cloudflare-analytics或相关 JS 片段看是否成功插入。等待时间Cloudflare Web Analytics 不是实时的数据收集和展示有数小时的延迟。刚插入代码需要等待。广告拦截插件有些浏览器插件会屏蔽统计脚本。尝试禁用插件或使用无痕模式访问几次自己的网站帮助触发数据记录。5.5 自定义样式或功能如果你想修改导航站的样式颜色、布局或增加功能你需要在你 Fork 的 GitHub 仓库里修改源代码。提交 (commit) 更改。Cloudflare Pages 检测到仓库变更会自动触发一次新的构建和部署。等待部署完成刷新页面查看效果。这意味着你有完全的代码控制权。但请注意如果你修改了核心数据结构或 Worker 逻辑可能会与后续的原项目更新产生冲突。6. 生产环境下的几点实用建议把导航站跑起来只是第一步要稳定、安心地用下去还需要注意以下几点。6.1 关于自定义域名Cloudflare 提供的*.pages.dev域名在国内访问可能不太稳定或速度慢。强烈建议绑定自己的域名。在域名注册商那里将域名的 DNS 服务器修改为 Cloudflare 提供的ns1.cloudflare.com等在 Cloudflare 添加站点时会给出。在 Cloudflare Dashboard 你的站点配置中添加自定义域名。按照提示在 DNS 设置里添加对应的 CNAME 记录指向你的 Pages 域名。最后别忘了在鉴权 Worker 的代码里把site_url也更新为你的自定义域名。6.2 密码安全与更换密码哈希一旦写入 Worker 代码更换起来需要重新部署 Worker。用 bcrypt 工具生成新密码的哈希。修改 Worker 代码中的password_hash值。保存并部署 Worker。所有用户再次访问时就需要输入新密码了。建议将密码哈希值作为一个环境变量来管理而不是硬编码在代码里。这样可以在 Worker 的Settings-Variables中直接修改无需改动代码。具体实现需要你稍微修改 Worker 代码使用env.PASSWORD_HASH的方式来读取环境变量。6.3 定期备份数据虽然 KV 很稳定但定期备份是个好习惯。利用后台的“一键备份”功能每个月或每次重大更新前手动下载一次 JSON 备份文件存到本地或其他网盘。这是最可靠的灾难恢复手段。6.4 监控免费额度进入 Cloudflare Dashboard 的Workers Pages总览页可以查看 Workers 请求次数、KV 操作次数等使用量。对于个人导航站几乎不可能用完每日 10 万次的 Worker 请求额度但了解一下没有坏处。6.5 更新项目版本CF-Navs 项目原作者可能会更新功能或修复 Bug。你可以通过 GitHub 的Sync fork功能将原仓库的更新拉取到你 Fork 的仓库中然后触发 Pages 的自动构建即可完成升级。升级前务必在后台进行数据备份以防不兼容。我个人更建议在第一次部署稳定后就把数据备份好。之后无论是修改样式、更新版本还是迁移到其他平台这份 JSON 数据都是你的核心资产。这个方案的魅力就在于它用一系列无服务器云服务拼出了一个有模有样的私人工具而且所有环节都在你的控制之下没有黑盒。