iori-nav部署教程：优雅的书签导航页，基于Cloudflare Workers搭建

luoli2026-07-172026-07-18

前言

iori-nav 是一个基于 Cloudflare Workers + D1 + KV 构建的优雅书签（网址）收藏与分享平台。它可以作为你的个人导航页，支持多级分类、模糊搜索、暗黑模式、AI 描述生成等丰富功能。

项目地址：https://github.com/love-ztm/iori-nav
在线演示：https://iori.hidns.vip
开源协议：MIT

功能特点

功能	说明
📱 响应式设计	完美适配桌面、平板和手机等各种设备
🎨 主题定制	自定义主色调、暗黑模式、毛玻璃效果
🔍 模糊搜索	内置全局搜索，快速查找书签
📂 多级分类	支持多层级书签分类管理
🔐 安全后台	KV 认证 + HttpOnly Cookie，支持完整的书签 CRUD
👥 用户投稿	访客可提交书签，管理员审核后展示
⚡ 边缘缓存	Cloudflare 边缘缓存加速，减少 D1 读取
📥 导入导出	支持 Chrome HTML 书签格式
🤖 AI 描述生成	支持 Workers AI、Google Gemini、OpenAI
🖼️ 多风格切换	三种桌面风格、三种移动端风格

技术栈

类别	技术
运行平台	Cloudflare Workers / Pages
数据库	Cloudflare D1
缓存/认证	Cloudflare KV
前端样式	TailwindCSS
开发语言	JavaScript

准备工作

在开始部署之前，需要准备以下内容：

Cloudflare 账号 — 注册 Cloudflare 并绑定一个域名
GitHub 账号 — 用于 Fork 仓库
信用卡（可选） — 使用 Workers AI 功能时需要开通

部署步骤

1. Fork 项目仓库

访问 iori-nav 项目，点击右上角 Fork，将仓库克隆到你的 GitHub 账号下。

2. 创建 D1 数据库

登录 Cloudflare Dashboard
进入 Workers 和 Pages → D1 → 创建数据库
输入数据库名称 book，点击创建
创建成功后记下 数据库 ID

3. 创建 KV 命名空间

进入 Workers 和 Pages → KV → 创建命名空间
输入名称 NAV_AUTH，点击创建
创建后进入命名空间，添加两条记录：
- 键：admin_username → 值：你的管理员用户名（例如 admin）
- 键：admin_password → 值：你的管理员密码

⚠️ 这两条 KV 记录用于管理员登录认证，请务必牢记。

4. 部署到 Cloudflare Pages

进入 Workers 和 Pages → 创建应用程序 → Pages → 连接到 Git
授权 Cloudflare 访问你的 GitHub，选择 Fork 的 iori-nav 仓库
配置构建信息：
- 框架预设：None
- 构建命令：npm run build:css
- 构建输出目录：public
点击 保存并部署

部署配置

5. 绑定 D1 数据库和 KV

在 Pages 项目详情页 → 设置 → 函数 → KV 命名空间绑定
点击 添加绑定：
- 变量名：NAV_AUTH
- KV 命名空间：选择你刚创建的 NAV_AUTH
点击 添加绑定（D1 数据库）：
- 变量名：NAV_DB
- D1 数据库：选择你刚创建的 book

绑定配置

6. 初始化数据库

在项目根目录找到 schema.sql 文件，复制其内容。然后：

进入 Pages 项目 → D1 选项卡
选择 book 数据库
点击查询，粘贴 schema.sql 的内容并执行

或者使用命令行：

1	npx wrangler d1 execute book --remote --file=schema.sql

7. 重新部署

回到 Pages 项目 → 部署页面，点击 重新部署 使其生效。

配置环境变量（可选）

在 Pages 项目 → 设置 → 环境变量 中，可以添加以下配置：

变量名	默认值	说明
`SITE_NAME`	`灰色轨迹`	网站名称
`SITE_DESCRIPTION`	见 README	网站描述
`FOOTER_TEXT`	`曾梦想仗剑走天涯`	页脚文字
`ICON_API`	`https://faviconsnap.com/...`	网站图标生成 API
`ENABLE_PUBLIC_SUBMISSION`	`false`	设为 `true` 开启访客投稿
`TURNSTILE_SITE_KEY`	空	Turnstile 人机验证密钥
`TURNSTILE_SECRET_KEY`	空	Turnstile 人机验证密钥
`WORKERS_AI_MODEL`	`@cf/google/gemma-4-26b-a4b-it`	AI 模型选择

配置 Workers AI（可选）

如需 AI 描述生成功能，还需要额外配置：

在 Pages 项目 → 设置 → 函数 → 绑定
添加 Workers AI 绑定，变量名设为 AI
在后台管理 → AI 设置中配置模型和 API

推荐模型：

@cf/google/gemma-4-26b-a4b-it（默认）
@cf/mistralai/mistral-small-3.1-24b-instruct
@cf/qwen/qwen3-30b-a3b-fp8
@cf/meta/llama-3.1-8b-instruct-fp8

后台管理

部署完成后，访问 https://你的域名/admin 进入后台管理：

使用你在 KV 中设置的用户名和密码登录
登录后可以：
- 添加/编辑/删除 书签和分类
- 管理访客提交的书签
- 配置网站样式、AI 模型、Turnstile 等
- 导入/导出 书签数据

登录有效期可在登录时选择：1 天 / 7 天 / 30 天 / 60 天 / 90 天。

后台设置

风格切换

iori-nav 支持多种显示风格，在后台管理中可切换：

桌面端风格

风格	特点
风格一	经典卡片式布局
风格二	列表式紧凑布局
风格三	毛玻璃效果布局

移动端风格

风格	特点
风格一	单列简洁布局
风格二	双列网格布局
风格三	三列密集布局

桌面端和移动端的风格可以独立设置，互不影响。

风格预览

常见问题

管理员登录失败（无限循环）？

确认 NAV_AUTH KV 命名空间已正确绑定，且其中包含 admin_username 和 admin_password 两条记录。

首页 500 错误或数据为空？

确认 NAV_DB D1 数据库已正确绑定，并且 schema.sql 已成功执行。

访客看不到投稿按钮？

在环境变量中设置 ENABLE_PUBLIC_SUBMISSION=true。

CSS 样式未更新？

重新运行 npm run build:css 后重新部署。

如何绑定自定义域名？

在 Pages 项目 → 自定义域 → 设置自定义域，输入你的域名即可。