在实际项目部署中很多开发者希望拥有一个私人的、可自定义的导航站点用于管理个人或团队的常用链接。但自建服务往往意味着需要购买服务器、配置域名、维护安全成本和精力投入都不小。Cloudflare 提供的 Workers 和 Pages 服务允许开发者以近乎零成本的方式部署和运行轻量级 Web 应用这为部署一个功能完整的私人导航站提供了绝佳的平台。CF-Navs 正是一个为 Cloudflare 平台设计的导航站项目它具备现代导航站的核心功能美观的界面、链接分类管理并且额外集成了密码保护、访问数据统计以及一键备份恢复等实用特性。对于希望快速搭建一个安全、私有且免运维导航页面的用户来说这是一个非常合适的选择。本文将带你从零开始在 Cloudflare 上完整部署 CF-Navs 导航站并详细解释每一步的操作目的、关键配置以及部署后如何管理你的站点。1. 理解 CF-Navs 的技术架构与部署原理在开始动手之前理解 CF-Navs 如何在 Cloudflare 上运行至关重要。这能帮助你在后续配置和排查问题时清楚知道每个环节的作用。1.1 基于 Cloudflare Pages 的静态站点托管CF-Navs 的前端本质上是一个静态 Web 应用。它使用 HTML、CSS 和 JavaScript 构建不依赖传统的后端服务器如 Nginx、Apache来提供页面服务。Cloudflare Pages 是一个针对静态站点和全栈应用的托管平台它能够自动从你的 Git 仓库如 GitHub拉取代码运行构建命令并将生成的静态文件部署到 Cloudflare 的全球边缘网络上。这意味着你的导航站页面文件会被分发到全球数百个数据中心用户访问时由离他最近的节点响应从而获得极快的加载速度。同时Cloudflare Pages 为每个项目提供免费的*.pages.dev子域名并支持绑定自定义域名。1.2 利用 Cloudflare Workers 实现动态功能一个纯粹的静态站点无法实现密码保护、数据统计和备份恢复。CF-Navs 通过 Cloudflare Workers 来弥补这一缺陷。Workers 是一个无服务器函数平台允许你在 Cloudflare 的边缘网络上运行 JavaScript 代码。CF-Navs 将核心业务逻辑如密码验证、访问记录、备份 API编写为 Worker 脚本。当用户访问导航站时请求会先经过这个 Worker。Worker 会检查访问权限密码保护记录访问数据然后再将请求转发给 Pages 托管的静态资源或者处理来自前端的 API 调用如提交备份数据。这种架构被称为“边缘计算”动态逻辑在靠近用户的边缘节点执行延迟极低。1.3 数据存储Workers KV 与 D1 数据库动态功能需要存储数据。CF-Navs 主要使用两种 Cloudflare 存储服务Workers KV一个全球分布的键值存储数据库。它读写速度极快但更适合存储会话、配置、缓存或访问计数这类简单数据。CF-Navs 可能用它来存储密码哈希、站点配置或临时的访问令牌。D1 DatabaseCloudflare 推出的基于 SQLite 的边缘数据库。它支持完整的 SQL 语法适用于存储更结构化、需要复杂查询的数据例如详细的访问日志、备份记录等。根据项目实现数据统计功能可能会用到 D1。理解这个架构后你就知道部署过程不仅仅是上传文件还需要创建和绑定这些 Cloudflare 服务资源。2. 部署前的环境与账号准备部署 CF-Navs 不需要本地开发环境但需要准备好以下几个关键账号和工具。2.1 注册与准备 Cloudflare 账号首先你需要一个 Cloudflare 账号。如果你还没有请前往 Cloudflare 官网进行注册。注册过程简单只需邮箱验证。注册成功后登录到 Cloudflare 仪表板。重要准备步骤验证邮箱确保注册邮箱已验证否则可能无法创建某些服务。了解免费额度Cloudflare 的 Workers、Pages、KV 和 D1 都有慷慨的免费套餐对于个人导航站完全够用。你可以在仪表板各产品的介绍页面查看详细限额。2.2 准备 GitHub 账号与仓库由于 Cloudflare Pages 通常从 Git 仓库直接部署你需要一个 GitHub 账号。如果你没有同样去 GitHub 官网注册。接下来你需要获取 CF-Navs 的源代码。通常这类项目会托管在 GitHub 上。假设项目仓库地址为https://github.com/username/cf-navs请替换为实际仓库地址。你有两种选择Fork 仓库在 GitHub 上找到该项目点击 “Fork” 按钮将其复制到你自己的 GitHub 账号下。这是推荐做法方便你后续自定义修改。直接使用如果你不打算修改代码也可以在部署时直接填写原项目仓库地址。2.3 安装 Wrangler CLI 工具可选但推荐Wrangler 是 Cloudflare 官方提供的命令行工具用于管理 Workers、Pages、KV 和 D1 等资源。虽然大部分操作可以通过网页仪表板完成但使用 Wrangler 可以更高效、可脚本化地完成部署和配置。通过 npm 全局安装 Wranglernpm install -g wrangler安装完成后登录你的 Cloudflare 账号wrangler login执行此命令会打开浏览器引导你授权 Wrangler 访问你的 Cloudflare 账户。3. 分步部署 CF-Navs 导航站现在我们开始实际的部署流程。整个过程分为创建底层数据服务、部署前端页面、配置密码保护与统计。3.1 创建与配置 Workers KV 命名空间KV 命名空间是存储键值对的容器。我们需要为 CF-Navs 创建一个。通过仪表板创建登录 Cloudflare 仪表板侧边栏选择 “Workers Pages”。切换到 “KV” 标签页。点击 “创建命名空间”输入一个名称例如CF_NAVS_STORE然后创建。获取命名空间 ID创建成功后在 KV 列表中找到你刚创建的命名空间其 ID 是一串字符串如xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。记下这个 ID后续配置会用到。可选通过 Wrangler 创建wrangler kv:namespace create CF_NAVS_STORE命令输出会包含命名空间的id。3.2 创建与配置 D1 数据库如需要如果 CF-Navs 使用 D1 存储统计信息则需要创建。通过仪表板创建在仪表板侧边栏选择 “Workers Pages”。切换到 “D1” 标签页。点击 “创建数据库”输入数据库名称例如cf-navs-stats然后创建。初始化数据库结构项目通常会提供一个 SQL 文件如schema.sql来创建所需的表。你需要在数据库的 “执行 SQL” 页面中运行它或使用 Wrangler 执行wrangler d1 execute cf-navs-stats --file./path/to/schema.sql获取数据库 ID同样记下数据库的 ID用于后续绑定。3.3 部署前端页面到 Cloudflare Pages这是部署的核心步骤将网站的静态文件托管起来。进入 Pages 创建流程在 Cloudflare 仪表板的 “Workers Pages” 下选择 “Pages” 标签页。点击 “创建应用程序”然后选择 “连接到 Git”。选择仓库授权 Cloudflare 访问你的 GitHub 账户。选择你之前 Fork 的或原始的 CF-Navs 仓库。配置构建设置项目名称系统会自动生成如cf-navs你可以修改。这将决定你的*.pages.dev子域名例如cf-navs.pages.dev。生产分支通常为main或master。构建设置框架预设如果项目是 React、Vue 等框架构建可以选择对应预设。如果是纯静态选择 “None”。构建命令查看项目package.json或文档。常见命令为npm run build或yarn build。如果项目无需构建此项留空。输出目录构建后静态文件所在的文件夹。通常是dist、build或public。请根据项目说明填写例如dist。环境变量与绑定这是关键步骤。点击 “环境变量” 部分需要添加变量以连接前面创建的服务。KV_NAMESPACE_ID: 值为你之前记录的 KV 命名空间 ID。DB_ID(如需要): 值为你记录的 D1 数据库 ID。SITE_PASSWORD: 设置你的导航站访问密码。注意为了安全密码应在 Worker 中加盐哈希存储但这里可以先设置一个明文后续在 Worker 代码中处理哈希。例如MY_SECURE_PASSWORD_123。根据项目文档可能还需要其他变量如ADMIN_TOKEN用于管理API等。保存并部署点击 “保存并部署”。Cloudflare Pages 会自动拉取代码、执行构建如果有并将网站部署到全球网络。首次部署可能需要几分钟。部署成功后你会获得一个https://你的项目名.pages.dev的访问地址。此时访问可能看到基础页面但密码保护等功能可能还未生效因为 Worker 尚未部署。3.4 部署与配置边缘 WorkerWorker 是实现动态功能的“大脑”。你需要将 CF-Navs 的 Worker 代码部署上去。方法一通过 Wrangler 部署推荐假设项目根目录下有一个worker文件夹里面是 Worker 的代码通常是一个index.js或src目录。进入 Worker 代码目录cd path/to/cf-navs/worker配置wrangler.toml文件。如果项目没有你需要创建一个。这是一个示例name cf-navs-worker # Worker 的名称 main src/index.js # 入口文件 compatibility_date 2024-01-01 [vars] # 这里定义环境变量会被注入到 Worker 的 env 对象中 SITE_PASSWORD_HASH 这里应该是你密码的bcrypt哈希值可通过在线工具或代码生成 [[kv_namespaces]] binding MY_KV # Worker 代码中使用的变量名 id 你的 KV 命名空间 ID # 填入之前记录的 ID [[d1_databases]] binding DB # Worker 代码中使用的变量名 database_name cf-navs-stats database_id 你的 D1 数据库 ID # 填入之前记录的 ID # 如果 Worker 需要与 Pages 关联可能需要路由配置 # routes [{ pattern your-domain.com/*, custom_domain true }]关键解释binding这是在 Worker 代码中访问该资源时使用的变量名。例如代码中可能会通过env.MY_KV来操作 KV。id和database_id必须与你之前创建的资源 ID 一致。SITE_PASSWORD_HASH为了安全不应存储明文密码。你应该使用 bcrypt 等算法生成密码哈希将哈希值存放在这里。Worker 在验证时会对用户输入的密码进行相同哈希计算后对比。发布 Workerwrangler deploy部署成功后你会获得一个https://cf-navs-worker.你的账户子域.workers.dev的地址。方法二通过仪表板创建在 “Workers Pages” 页面点击 “创建应用程序”选择 “创建 Worker”。你可以将项目中的 Worker 代码粘贴到在线编辑器中并在 “设置” - “变量” 中手动添加 KV 和 D1 绑定以及环境变量。这种方法适合代码量小的 Worker。3.5 绑定自定义域名与配置路由为了让用户通过你的域名如nav.yourdomain.com访问并且让请求经过 Worker 处理需要配置路由。添加自定义域名到 Pages在你的 Pages 项目详情页进入 “自定义域” 设置。点击 “设置自定义域”输入你的域名如nav.yourdomain.com。按照提示去你的域名注册商或 DNS 管理面板如果域名已在 Cloudflare则在此处添加指定的 CNAME 记录。通常是将navCNAME 指向你的项目名.pages.dev。配置 Worker 路由目标是让所有到达nav.yourdomain.com的流量先经过你的 Worker。在 Worker 的详情页进入 “触发器” 设置。在 “路由” 部分点击 “添加路由”。路由填写nav.yourdomain.com/*选择你刚刚部署的 Workercf-navs-worker。保存后DNS 生效需要几分钟。生效后访问nav.yourdomain.com的请求将先由 Worker 处理再返回 Pages 的内容。至此一个具备密码保护、数据统计能力的 CF-Navs 导航站就部署完成了。4. 关键配置详解与功能验证部署完成后你需要登录后台进行配置并验证各项功能是否正常工作。4.1 访问管理后台与初始配置大多数导航站项目会提供一个管理后台。CF-Navs 的管理后台地址通常是https://你的域名/admin或类似路径。首次访问时需要使用你之前设置的管理员令牌ADMIN_TOKEN环境变量或密码进行登录。登录后你通常可以进行以下操作修改站点信息如标题、Logo、描述等。管理导航分类添加、删除、排序不同的链接分类如“开发工具”、“设计资源”、“日常办公”。管理链接在每个分类下添加具体的网站链接包括名称、URL、图标等。修改密码更改访问站点的密码。4.2 密码保护功能验证这是核心安全功能。验证步骤如下在浏览器中打开你的导航站首页https://nav.yourdomain.com。预期行为页面应首先显示一个密码输入框而不是直接展示导航链接。输入错误的密码点击提交。页面应提示密码错误并保持在密码输入界面。输入正确的密码点击提交。页面应跳转并显示完整的导航站内容。检查 Cookie/Session登录成功后关闭浏览器标签页重新打开导航站地址。此时应该无需再次输入密码即可直接进入因为会话可能被保存在 Cookie 或 LocalStorage 中。清除浏览器站点数据后再次访问应重新要求输入密码。4.3 数据统计功能验证数据统计功能可能以后台仪表板或 API 形式提供。触发访问记录从不同的设备或浏览器或使用无痕模式访问你的站点并成功输入密码进入。模拟几次点击链接的行为。查看统计数据登录管理后台寻找“数据统计”、“访问日志”或类似模块。你应该能看到总访问次数PV。独立访客数UV。最近访问时间/IP可能脱敏显示。最常点击的链接排行。检查数据存储你可以通过 Cloudflare 仪表板查看 D1 数据库或 KV 命名空间确认是否有新的数据写入。例如在 D1 数据库的“执行 SQL”页面运行SELECT COUNT(*) FROM access_logs;假设表名为此来查看日志数量。4.4 一键备份与恢复功能验证这是防止数据丢失的重要功能。执行备份在管理后台找到“备份”或“导出数据”功能。点击后系统应生成一个 JSON 格式的文件并自动下载。打开该文件确认其中包含了你的所有分类和链接数据。模拟数据丢失为了测试你可以在管理后台手动删除一个不重要的分类或链接。执行恢复在管理后台找到“恢复”或“导入数据”功能选择刚才下载的备份 JSON 文件并上传。系统应提示恢复成功。验证恢复结果刷新页面检查之前删除的分类或链接是否已恢复原状。5. 常见问题排查与解决方案部署和使用过程中你可能会遇到一些问题。以下是典型问题的排查路径。5.1 页面访问出现 Cloudflare 5XX 错误问题现象可能原因检查方式处理建议访问域名显示5XX错误如500、530。1. Worker 代码运行时出错未捕获的异常。2. Worker 与 KV/D1 的绑定配置错误导致访问资源失败。3. 环境变量未正确设置或读取。1. 在 Cloudflare 仪表板中进入你的 Worker查看“日志”流。这里会显示运行时错误信息和堆栈跟踪。2. 检查wrangler.toml或仪表板中的绑定配置确认binding名称与代码中引用的名称完全一致且id正确。3. 检查环境变量是否在 Pages 和 Worker 中都已正确设置变量名大小写是否匹配。1. 根据 Worker 日志修正代码错误。2. 核对并修正绑定配置。3. 重新配置环境变量并重新部署 Worker。5.2 密码保护失效或一直提示密码错误问题现象可能原因检查方式处理建议直接打开网站不显示密码框或输入正确密码仍提示错误。1. Worker 路由未生效请求直接到了 Pages未执行密码检查。2. 密码哈希值配置错误。3. 浏览器缓存了旧的、无效的认证 Cookie。1. 在浏览器开发者工具的“网络”选项卡中查看访问首页请求的响应头。如果经过 Worker通常会看到server: cloudflare或包含cf-worker字样。如果没有说明路由可能有问题。2. 确认SITE_PASSWORD_HASH环境变量中的值是正确的 bcrypt 哈希。你可以写一个简单的 Node.js 脚本验证哈希生成。3. 清除浏览器对该站点的所有 Cookie 和本地存储数据后重试。1. 检查 Worker 路由配置nav.yourdomain.com/*是否正确并确保 DNS 已生效。2. 重新生成正确的密码哈希并更新环境变量然后重新部署 Worker。3. 引导用户清除缓存或在 Worker 代码中设置合理的 Cookie 过期时间。5.3 数据统计不记录或备份恢复失败问题现象可能原因检查方式处理建议后台看不到访问数据或备份/恢复操作无反应。1. D1 数据库表结构未初始化。2. Worker 对 D1/KV 的写入权限不足通常不会免费套餐足够。3. 备份恢复的 API 接口路径或方法不对。4. 前端与管理后台的通信被 CORS 策略阻止。1. 在 D1 数据库控制台运行SELECT * FROM sqlite_schema;查看表是否存在。2. 在 Worker 日志中查看执行数据库操作时是否有权限错误。3. 使用浏览器开发者工具的“网络”选项卡观察执行备份/恢复操作时发出的请求查看其 URL、方法和响应状态码。4. 同样在“网络”选项卡查看 API 请求是否被 CORS 错误阻止。1. 运行项目提供的schema.sql文件初始化数据库。2. 检查 Worker 的绑定配置确保数据库绑定名称正确。3. 根据网络请求的失败信息修正前端调用的 API 地址或方法或检查后端 Worker 是否正确处理了该路由。4. 在 Worker 代码的响应头中添加正确的 CORS 头例如Access-Control-Allow-Origin: *生产环境应指定具体域名。5.4 自定义域名无法访问或显示空白页问题现象可能原因检查方式处理建议使用自定义域名访问时无法打开或显示空白页但*.pages.dev域名可以。1. DNS 解析未生效或配置错误。2. Pages 项目的自定义域名未成功配置。3. Worker 路由未包含自定义域名。1. 使用dig或nslookup命令检查你的自定义域名如nav.yourdomain.com是否正确解析到了 Cloudflare 的地址。2. 在 Pages 项目设置中确认自定义域名状态为“有效”。3. 检查 Worker 的路由列表是否包含了你的自定义域名模式如nav.yourdomain.com/*。1. 等待 DNS 生效最长可能 48 小时或检查 CNAME 记录值是否正确。2. 按照 Pages 提示重新配置或验证域名所有权。3. 在 Worker 中添加针对自定义域名的路由。6. 生产环境最佳实践与安全建议将导航站用于实际日常使用后以下几点能提升稳定性和安全性。6.1 安全加固措施密码管理切勿使用弱密码访问密码和管理员令牌都应使用强密码生成器生成。使用哈希存储绝对不要在环境变量或代码中存储明文密码。务必使用 bcrypt 或 Argon2 等抗碰撞的哈希算法存储密码哈希。在 Worker 中验证时对比哈希值。定期更换定期更换访问密码和管理员令牌。环境变量保护ADMIN_TOKEN、数据库连接字符串如有等敏感信息必须通过环境变量注入而不是硬编码在代码中。确保你的 GitHub 仓库.gitignore文件排除了包含敏感信息的本地配置文件。限制管理后台访问如果可能在 Worker 中增加一层 IP 白名单限制只允许你信任的 IP 地址访问/admin路径。保持依赖更新如果你 Fork 了项目并进行了自定义修改定期关注原项目的安全更新及时合并或更新依赖包。6.2 数据备份与恢复策略虽然项目自带一键备份功能但仍需建立外部备份机制。定期导出设定日历提醒每月或每季度手动在后台导出一次备份 JSON 文件并存储到本地或其他云存储。数据库快照对于 D1 数据库可以利用其导出功能通过仪表板或 Wrangler 命令wrangler d1 export定期创建完整的 SQL 转储文件。KV 数据备份Workers KV 的数据可以通过 Worker 脚本编程式地遍历并导出或者使用社区提供的备份工具。将关键配置的 KV 键值对记录在文档中。6.3 性能与成本监控Cloudflare 免费套餐额度很高但仍需留意。监控用量定期在 Cloudflare 仪表板的 “Workers Pages” 总览页查看 Workers 调用次数、Pages 带宽、KV 读写次数和 D1 操作次数。确保它们在免费限额内。优化 Worker 逻辑避免在 Worker 中执行耗时的同步操作或循环大量数据。保持 Worker 轻量以快速响应。缓存静态资源确保 Pages 部署的静态资源如图片、CSS、JS具有正确的缓存头利用 Cloudflare 的全球 CDN 缓存减少回源请求。6.4 自定义与扩展方向基础功能满足后你可以考虑以下扩展UI 主题定制修改项目的 CSS 文件更换颜色、字体、布局使其更符合你的审美。添加新功能例如集成搜索引擎快捷方式、增加天气预报小部件、为链接添加标签和搜索功能。多用户支持修改 Worker 逻辑支持多个密码或简单的用户系统为不同用户组展示不同的链接集合。更丰富的统计利用 D1 数据库记录更详细的点击行为并构建一个可视化的数据看板。部署 CF-Navs 的过程是一次对 Cloudflare 边缘计算平台核心服务Pages、Workers、KV、D1的综合性实践。通过这个项目你不仅获得了一个实用的私人工具也深入理解了如何将这些服务组合起来构建一个完整的、生产可用的应用。如果在后续使用中遇到任何问题首先查看 Cloudflare 仪表板中的日志和监控它们通常能提供最直接的错误线索。
