🚀 一个运行在 Cloudflare Workers 上的轻量个人导航面板——前台展示常用站点，后台管理分类、书签、主题、搜索引擎和数据备份。
核心特性 • 效果预览 • 快速部署 • 项目文档 • 本地开发 • 环境变量说明 • 贡献 • 致谢
| 特性 | 说明 |
|---|---|
| ☁️ 轻量部署 | 全栈运行在 Cloudflare Workers + D1 + KV，无需自建服务器 |
| 🧭 清爽首页 | 分类分区、响应式布局；导航可配置为左侧或顶部，支持桌面常显、横向滚动和移动端触摸滑动；详情/极简两种卡片样式，描述可始终显示、悬停提示或隐藏 |
| 🛠️ 顺手管理 | 分类和书签支持新增、编辑、跨页批量删除、搜索、分页和拖拽排序；后台书签列表支持本地字段排序 |
| 🎨 图标省心 | 支持 favicon、文字图标、Iconify、自定义图片 URL、文字或表情；首页优先使用聚合数据和浏览器本地缓存展示图标 |
| 🌓 主题完整 | 亮色、暗色、跟随系统；内置 13 套跨色系配色方案，保存选中状态；书签卡片为真实毛玻璃质感——亮色透出背景色彩，暗色使用深色玻璃提亮，背景、遮罩、卡片尺寸和图标大小都可配置 |
| 🔎 搜索实用 | 首页输入直接筛选本地书签（匹配标题、描述、URL 和分类），也可切换外部搜索引擎 |
| 💾 数据可控 | 支持 JSON 导出、导入、恢复；兼容 Sun-Panel 数据迁移和浏览器标准书签 HTML，可追加合并或覆盖 |
| 🔐 安全可靠 | 密码 PBKDF2 哈希存储、HttpOnly Session Cookie、CSRF 防护；登录失败限流、默认 7 天会话有效期 |
| 📱 PWA 支持 | 生产构建提供基础 PWA app shell，Service Worker 离线回退 |
| ⚡ 极致加载 | 边缘缓存、图标懒加载、代码分割、聚合数据批量读取、浏览器本地快照增量更新，畅享本地化的速度感 |
默认主题 · 深海蔚蓝亮色
|
深海蔚蓝暗色
|
13 套内置主题模板 · 亮暗双背景 · 一键套用推荐参数
|
|
移动端亮色
|
移动端暗色
|
首次运行安装器
|
分类视图
|
小卡片样式
|
书签编辑弹窗
|
后台分类管理
|
后台书签管理
|
浏览器网络耗时
|
后台备份
|
🎨 内置 13 套跨色系模板，每套同时提供亮色与暗色背景，并自动带入推荐的遮罩、卡片透明度和文字参数；仍可分别改成纯色、渐变或图片背景。
🌊 新安装站点默认启用「深海蔚蓝」亮色模式；前台仍可临时切换亮色、暗色或跟随系统，不会改写后台保存的主题配置。
🧩 首次部署通过
/install引导校验绑定、创建数据库结构和管理员账号，完成后直接进入已登录状态。🧭 后台「站点设置 → 布局与导航」可选择左侧或顶部布局。桌面左侧模式可开启常显并手动收缩；顶部模式固定悬浮，分类溢出时支持箭头、鼠标拖动和移动端触摸滑动。
前置要求：Node.js 18+、npm、Cloudflare 账号
# 1. 克隆并安装依赖
git clone https://github.com/lbjxr/CF-Navs.git
cd CF-Navs
npm install
# 2. 登录 Cloudflare
npx wrangler login
# 3. 创建 D1 数据库
npx wrangler d1 create cf-navs-db
# 4. 创建 KV 命名空间
npx wrangler kv namespace create SESSION
# 5. 生成本地 Wrangler 配置（保存真实资源 ID）
npm run setup:wrangler
# 6. 设置一次性安装令牌
npx wrangler secret put SETUP_TOKEN
# 7. 构建并部署
npm run deploy部署成功后，访问 Wrangler 返回的 Workers URL 并打开 /install，输入刚设置的 SETUP_TOKEN，再创建管理员用户名和密码。安装器会初始化数据库 schema 和管理员账号。确认登录成功后，可删除或轮换 SETUP_TOKEN。npm run db:init:remote 仅用于安装器无法初始化 schema 时的恢复，不是全新 CLI 部署的正常步骤。
适合不想在本地运行 CLI、希望从自己的 GitHub 仓库完成在线部署的用户。
- 点击上方按钮，在 GitHub 中 Fork 本项目。请确认 Fork 后的仓库归属于你的 GitHub 账号。
- 进入 Cloudflare 控制台的 Workers & Pages → Create application → Import a repository，关联 GitHub 并选择你 Fork 后的
CF-Navs仓库。不要选择上游仓库，也不要使用会自动创建新 GitHub 项目的 Cloudflare Deploy Button。 - 保持生产分支为
main，构建命令填写npm run build，部署命令填写：
npx wrangler deploy- 保存并部署。Cloudflare 的 Git 引导流程会根据
wrangler.toml中不带 ID 的声明创建并绑定DBD1 数据库与SESSIONKV 命名空间。待部署完成后，进入该 Worker 的 设置 → 变量和密钥，添加一个类型为密钥的变量，变量名填写SETUP_TOKEN，值填写一段足够长且随机的字符串。
- 打开部署后的 Workers URL，并访问
/install。输入SETUP_TOKEN，再设置管理员用户名和密码；安装器会初始化数据库 schema 和管理员账号。 - 进入该 Worker 的 域和路由 页面，关闭两个 Workers URL，然后添加并启用你的自定义域名。
如果
/install无法完成 schema 初始化，才使用 D1 SQL Console 手动执行 schema.sql 作为恢复手段；不要把手动 SQL 当作正常安装步骤。
首次部署请从生产分支 main 触发。不要在资源尚未创建前使用预览分支自动部署；预览分支可能走 wrangler versions upload 流程。
资源绑定名必须保持如下配置：
| 类型 | 绑定名 | 选择 |
|---|---|---|
| D1 database | DB |
cf-navs-db |
| KV namespace | SESSION |
你的会话 KV 命名空间 |
⚠️ 这个部署方式必须使用你 Fork 后的仓库。Cloudflare 的通用 Deploy Button 会新建 GitHub 仓库，不能部署到已有 Fork；已有 Fork 必须在 Dashboard 选择 Import a repository。控制台中 Worker 名称需与wrangler.toml的name一致（默认cf-navs），并确保绑定名为DB和SESSION。
首次使用请先
npm install。本地开发依赖wrangler.toml公开模板配置；真实资源 ID 通过npm run setup:wrangler写入 Git 忽略的wrangler.local.toml。
# 终端 1：启动 Worker 开发服务
npm run dev
# 终端 2：启动前端开发服务器
npm run dev:web访问 http://localhost:5173。验证完成后在对应终端按 Ctrl+C 停止服务。
npm run type-check # TypeScript 与 Svelte 类型检查
npm test # Vitest 单元测试
npm run build # 生产构建
npm run db:init # 初始化本地 D1
npx wrangler tail # 查看 Worker 日志| 变量名 | 说明 |
|---|---|
SETUP_TOKEN |
Cloudflare Git 和 Wrangler CLI 新部署必需的一次性安装令牌。部署后访问 /install，用它授权 schema 与管理员初始化；应使用足够长的随机值并保存为加密 Secret。确认安装成功后建议删除或轮换；公开安装状态检查不需要它，删除后不影响运行，保留也不会解除永久安装锁 |
INIT_ADMIN_PASSWORD |
仅用于旧数据库升级或凭据恢复的兼容 Secret。全新的 Cloudflare Git 和 Wrangler CLI 安装不要设置它，而是在 /install 中创建管理员密码 |
| 绑定名 | 类型 | 说明 |
|---|---|---|
DB |
D1 database | 数据库，存储分类、书签、设置 |
SESSION |
KV namespace | 会话存储，保存登录 Token |
| 变量名 | 默认值 | 说明 |
|---|---|---|
INIT_ADMIN_USER |
admin |
旧数据库升级或凭据恢复时使用的兼容管理员用户名；全新安装在 /install 中设置 |
RESET_ADMIN_CREDENTIALS |
空 | 旧数据库首次升级或需要强制重置时使用一次性标记，例如 reset-2026-07-12；每次强制重置请更换标记值 |
SESSION_TTL |
604800 |
会话有效期（秒），默认 7 天 |
INIT_ADMIN_USER、INIT_ADMIN_PASSWORD 和 RESET_ADMIN_CREDENTIALS 仅保留给旧数据库升级与凭据恢复。全新的 Cloudflare Git 或 Wrangler CLI 部署都应使用 SETUP_TOKEN + /install 设置管理员，日常修改密码请使用后台「账号安全」。升级已有旧数据库时，如果数据库还没有初始化标记，可设置新的 RESET_ADMIN_CREDENTIALS 值并重新部署，成功登录后移除该变量。
欢迎通过 Issue 或 Pull Request 为本项目贡献代码。
- Fork 本仓库
- 创建特性分支：
git checkout -b feature/amazing-feature - 提交更改：
git commit -m 'Add some amazing feature' - 推送到分支：
git push origin feature/amazing-feature - 创建 Pull Request
本项目参考了 Sun-Panel 的设计思路，部分图标获取逻辑受 iori-nav 启发。