零服务器成本打造优雅书签导航站：开源项目iori-nav（灰色轨迹）完全介绍

• 前端
• 后端

iori-nav（灰色轨迹）是一个完全基于 Cloudflare 全家桶构建的开源书签收藏与分享平台：零服务器成本、秒级加载、三套可切换视觉风格，自带搜索、多级分类、后台管理、投稿审核与 AI 一键生成描述，帮你免费拥有一个属于自己的优雅网址导航站。

✨ 为什么选择 iori-nav 做你的导航站

很多书签导航方案都需要一台 VPS + Nginx + 数据库，长期产生服务器费用，运维也不省心。iori-nav 把计算、存储全部放在 Cloudflare 免费层上：

首页通过服务端渲染模板 + 边缘缓存输出，核心入口见 functions/index.js；静态资源采用长缓存策略，配置在 public/_headers。

🖼️ 三大视觉风格：一键切换的导航站皮肤

iori-nav 内置三套卡片风格，每套都配有默认壁纸，在后台即可切换，无需改一行代码：

• 风格一（毛玻璃）：半透明磨砂卡片，适合清新壁纸，保留描述与链接行
• 风格二（轻量图标）：白色紧凑网格，信息密度高，一眼看全
• 风格三（深色星空）：暗色沉浸主题，突出图标与标题，夜间浏览舒适

壁纸也支持自定义，下面这张海滩风景就是项目提供的默认壁纸之一，卡片叠加在壁纸上呈现出"导航即壁纸"的视觉效果：

🚀 核心功能：搜索、分类、投稿审核与 AI 补齐

• 🔍站内模糊搜索：首页搜索框即可定位网站，前端逻辑在 public/js/home-search.js
• 📂多级分类：书签按分类组织、可拖拽排序，接口位于 functions/api/categories/
• 📝访客投稿 + 管理员审核：访客提交后进入待审核队列，管理员在后台一键通过或拒绝；通过环境变量ENABLE_PUBLIC_SUBMISSION即可随时开关投稿入口，接口见 functions/api/config/submit.js
• 🤖AI 一键生成描述：接入 Workers AI、Gemini、OpenAI 三种模型，批量补齐卡片描述，逻辑在 functions/api/ai-chat.js；Logo 图标默认自动抓取，无需手动上传
• 📤导入 / 导出书签数据：兼容 Chrome 导出的 HTML 格式，一键迁移旧收藏
• 🔒安全机制齐备：HttpOnly 会话 Cookie、CSRF Token、登录限流、HTML 转义与参数绑定防注入，全部集中在 functions/_middleware.js

⚙️ 后台管理：卡片、壁纸、动画全可视化

后台地址为你的域名/admin（页面在 public/admin/index.html），登录后即可看到"预览 + 设置"双栏界面，所见即所得：

• 桌面布局支持4 / 5 / 6 / 7 列，卡片风格三选一
• 切换动画可挑：中心扩散、向上滑入、左侧滑入、翻转进入、随机动画等
• 毛玻璃效果与程度、圆角、是否隐藏分类 / 描述 / 链接行均可开关
• 标题与描述的字体样式单独可调，壁纸在"壁纸设置"页上传

📱 手机端独立设置：1 / 2 / 3 列随心切换

手机端不再是桌面版"缩水"，而是独立的一套布局：可设置1 / 2 / 3 列，卡片密度会自动优化复制按钮显示，风格与动画同样独立配置。

🚀 部署教程：6 步免费把书签导航站上 Cloudflare

准备工作：一个 Cloudflare 账号（免费版即可）。

第 1 步：获取代码

将仓库 Fork 到你的代码平台，或克隆到本地：

git clone https://gitcode.com/gh_mirrors/io/iori-nav

第 2 步：创建 Cloudflare Pages 项目

在 Cloudflare 控制台创建 Pages 项目并关联你的代码仓库，构建输出目录填写public，其余保持默认。

第 3 步：创建 D1 数据库

进入「存储和数据库 → D1 SQL 数据库」，创建名为book的数据库。表结构由应用首次请求时自动迁移完成，无需手动执行 SQL（初始建表脚本见 schema.sql）。

第 4 步：创建 KV 命名空间

创建名为NAV_AUTH的 Worker KV，并添加两个条目：admin_username（后台用户名）与admin_password（后台密码），它们就是/admin的登录凭据。

第 5 步：添加绑定

在 Pages 项目的「设置 → 绑定」中依次添加：NAV_DB→ D1 数据库book（必需）、NAV_AUTH→ KV 命名空间（必需）、AI→ Workers AI（可选，用 AI 生成描述时需要）。

第 6 步：重新部署并绑定域名

触发一次重新部署，绑定自定义域名后，访问首页即可使用，/admin进入后台。

常用可选环境变量：

💻 本地开发：克隆仓库快速启动

想在自己的机器上调试？复制配置模板（见 wrangler.example.toml）填入自己的 D1 / KV 资源 ID 即可：

npm install cp wrangler.example.toml wrangler.toml # 填入自己的 D1/KV 资源 ID npm run build:css # 构建 TailwindCSS npm run dev # 启动本地开发服务器

本地执行数据库脚本（可选）：npx wrangler d1 execute book --local --file=schema.sql

📁 项目结构速览

• functions/— Cloudflare Pages Functions 后端：首页 SSR、/admin后台、REST API 与安全中间件
• public/— 静态资源：首页模板、后台页面、CSS 与前端脚本
• test/— 基于node:test的接口与渲染测试
• AGENTS.md / CLAUDE.md — 面向贡献者的架构与开发规范文档

❓ 常见问题 FAQ

• /admin无法登录或反复跳回登录页：确认已绑定NAV_AUTH，且 KV 中存在admin_username、admin_password两个条目。
• 首页 500 或数据为空：检查NAV_DB是否正确绑定到book数据库。
• 前台看不到投稿入口：将ENABLE_PUBLIC_SUBMISSION设为true。
• 改了public/css/tailwind.css但样式没生效：先执行npm run build:css，再重新部署。

iori-nav 采用 MIT 许可证开源，从 Fork 到上线不到半小时，不写一行服务器代码，也不花一分钱服务器费用——这就是"灰色轨迹"给书签导航站带来的答案。

• 前端
• 后端