DIY NAV WEB

一个本地优先、支持云同步与 AI 批量整理的个人导航管理平台。

在线体验 · 快速开始 · 部署

DIY NAV WEB 用于集中管理网站、分类和标签。未登录时数据保存在当前浏览器；登录后可以开启跨设备同步、创建历史备份，并在数据冲突或云端快照异常时进行恢复。

项目采用 pnpm + Turborepo Monorepo：Web 端基于 Vue 3，API 基于 Fastify，结构化数据支持 Cloudflare D1 或 MySQL；对象存储支持 Cloudflare R2、S3 兼容服务和 WebDAV。AI 能力支持用户配置多个 OpenAI 或 Claude 协议服务。

以下截图来自当前本地代码和测试数据，桌面端尺寸为 1440 × 892。

首页	全部网站

登录	注册

备份	移动端首页	移动端全部网站

AI 助手	AI 助手：添加网站

AI 助手：添加标签	AI 助手：备份数据	AI 助手：查看备份数据

.
├── apps
│   ├── web                 # Vue Web 应用
│   └── api                 # Fastify API 服务
├── packages
│   ├── ai-core             # AI 协议、Provider 与结构化输出
│   ├── auth-providers      # GitHub、Google、Linux.do OAuth
│   ├── config              # 环境配置
│   ├── core                # 认证、同步、备份等领域服务
│   ├── database            # Cloudflare D1 / MySQL 数据库适配
│   ├── icon-core           # 网站图标获取
│   ├── storage             # R2、WebDAV、本地存储
│   ├── types               # 共享类型
│   └── ui                  # 共享 UI 组件
├── deploy                  # Docker Compose 与部署脚本
├── doc/images              # README 截图
└── README.md

• Node.js 20 或更高版本
• pnpm 8 或更高版本
• Cloudflare D1 或 MySQL 数据库
• Docker 与 Docker Compose（仅 Docker 部署需要）

git clone https://github.com/slightlee/diy-nav-web.git
cd diy-nav-web
pnpm install

cp .env.example .env

完整配置和注释以 .env.example 为准。至少需要根据部署方式检查以下配置：

站点、SMTP、OAuth 和对象存储配置由管理后台写入数据库，不再通过环境变量维护。不要提交真实 Token、Secret、API Key 或 WebDAV 密码；后台保存的敏感值会使用 OAUTH_CONFIG_ENCRYPTION_KEY 加密。

迁移前让 .env 同时保留有效的 D1 与 MySQL 配置，并设置 DB_PROVIDER=mysql。然后在项目根目录执行：

pnpm --filter api migrate:d1-to-mysql

迁移脚本会在 MySQL 中初始化表结构、幂等写入 D1 数据并校验各表行数。备份和同步快照的文件本体仍保存在对象存储中，不会由该脚本搬迁。需要回滚时，将 DB_PROVIDER 改回 d1 并重启服务即可。

管理员登录后可通过 /admin 进入管理后台。

新注册用户默认角色为 USER。首次部署后，先注册管理员账号，再通过 D1 控制台或 MySQL 客户端执行：

UPDATE users SET role = 'ADMIN' WHERE email = 'admin@example.com';

重新登录后即可进入管理后台。系统会阻止降级或停用最后一个有效管理员。

# 同时启动 Web、API 和内部包的开发任务
pnpm dev

• Web: http://localhost:3000
• API: http://localhost:8787
• 健康检查: http://localhost:8787/healthz

也可以分别启动：

pnpm dev:web
pnpm dev:api

• 浏览器数据采用本地优先策略，未登录也可以管理导航。
• 开启云同步后，网站、分类和标签会在同一账号的设备间同步。
• 写入同步快照前会校验版本，避免静默覆盖其他设备上的更新。
• 自动备份和手动备份均可在历史列表中恢复或删除。
• JSON 导入只覆盖文件中包含的对应数据；执行覆盖操作前请先创建备份。
• 主题、默认首页等偏好与导航数据分开管理。

pnpm type-check
pnpm lint
pnpm stylelint
pnpm test
pnpm build

提交前可执行完整校验：

pnpm ci:verify

cp .env.example .env
# 修改 .env 中的生产配置
sh deploy/deploy.sh

脚本会使用当前 Git Tag；没有 Tag 时使用当前 Commit SHA 构建并启动 nav-web 与 nav-api 容器。

当 MySQL 由另一个 Compose 项目管理时，确保其容器名或网络别名为 mysql，并且已经加入 mysql_default 网络：

docker network inspect mysql_default

如果现有 MySQL 网络不是 mysql_default，请同步修改 deploy/docker-compose.mysql.yml 中的外部网络名称。

MySQL 专用配置是基础 Compose 的增量覆盖文件。手动部署时同时加载两份配置：

docker compose \
  --env-file .env \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.mysql.yml \
  up --build -d

deploy/remote-deploy.sh 会读取 .env 中的 DB_PROVIDER：使用 mysql 时自动加载 docker-compose.mysql.yml，使用 d1 时只加载基础 Compose。运行远程脚本前，需要先在脚本配置区设置 SSH 用户、密钥路径和部署目录，并通过 shell 环境变量提供 SSH 服务器地址：

DB_HOST=服务器地址 sh deploy/remote-deploy.sh

这里的 DB_HOST 仅用于定位部署服务器；数据库连接仍由 .env 中的 DB_PROVIDER 和对应数据库变量控制。

• Web: http://localhost:3000
• API: http://localhost:8787

1. Fork 本仓库。
2. 创建功能分支：git checkout -b feat/example。
3. 完成修改并执行质量检查。
4. 按 Conventional Commits 规范提交。
5. 推送分支并创建 Pull Request。

本项目基于 MIT License 开源。