NavSphere：打造个性化网址导航的开源利器

简介

NavSphere 是一款免费开源的网址导航源码，基于 Next.js 14 + React 18 + TypeScript 构建，以 GitHub 为数据存储后端，提供安全可靠的网址管理解决方案。

cloudflare上部署NavSphere导航站管理系统指南

核心功能

• 现代技术栈：采用 Next.js 14、React 18、TypeScript 和 Tailwind CSS，确保高性能与优雅体验。
• GitHub 认证：通过 NextAuth.js 实现 OAuth 安全登录，保障数据隐私。
• 高效管理：支持拖拽排序、智能搜索、深色/浅色主题切换，满足个性化需求。
• 多语言支持：中英文界面无缝切换，适应全球化用户。
• 灵活部署：提供 Vercel 一键部署和 Docker 容器化部署方案。

适用场景

• 个人：快速搭建私人书签管理平台。
• 团队：构建协作式导航门户，共享资源。
• 开发者：通过 GitHub 存储实现数据持久化与版本控制。

访问方法

开源地址
https://github.com/tianyaxiang/NavSphere
在线演示
https://dh.leti.ltd/

• 🛠️ 技术架构

🚀 快速开始

点击上方按钮即可一键部署到 Vercel，部署完成后需要配置环境变量。

• Node.js 18.0+
• pnpm 8.0+ (推荐) 或 npm/yarn
• GitHub 账户

1. 克隆项目

git clone https://github.com/tianyaxiang/NavSphere.git
cd NavSphere

2. 安装依赖

pnpm install

3. 配置环境变量

cp .env.example .env.local

4. 启动开发服务器

pnpm dev

5. 访问应用

   打开浏览器访问 http://localhost:3000

# GitHub OAuth App 配置
GITHUB_ID=your-github-client-id
GITHUB_SECRET=your-github-client-secret

# GitHub 仓库配置  
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-repo-name
GITHUB_BRANCH=main

# NextAuth 配置
NEXTAUTH_URL=http://localhost:3000/api/auth
NEXT_PUBLIC_API_URL=http://localhost:3000

1. 创建 OAuth App

   • 访问 GitHub Developer Settings
   • 点击 "New OAuth App"
   • 填写应用信息：

     Application name: NavSphere
     Homepage URL: http://localhost:3000
     Authorization callback URL: http://localhost:3000/api/auth/callback/github
     

2. 获取凭据

   • Client ID: 应用详情页显示
   • Client Secret: 点击 "Generate a new client secret" 生成

1. 创建数据仓库

   • 访问 GitHub New Repository
   • 仓库名建议: navsphere-data
   • 可选择 Public 或 Private

2. 初始化数据文件

   项目会自动创建以下数据文件：

   • navigation.json - 导航数据
   • site.json - 站点配置
   • resources.json - 资源数据

•  创建 GitHub OAuth App 并获取 Client ID 和 Secret
•  创建用于存储数据的 GitHub 仓库
•  记录你的 GitHub 用户名和数据仓库名称
•  准备好你的 Vercel 项目域名（用于配置 NEXTAUTH_URL 和 NEXT_PUBLIC_API_URL）

1. 点击部署按钮

   

2. 配置环境变量

   在部署过程中，Vercel 会要求你配置以下环境变量：

   GITHUB_ID=your-github-client-id
   GITHUB_SECRET=your-github-client-secret
   GITHUB_OWNER=your-github-username
   GITHUB_REPO=your-data-repo-name
   GITHUB_BRANCH=main
   NEXTAUTH_URL=https://your-project-name.vercel.app/api/auth
   NEXT_PUBLIC_API_URL=https://your-project-name.vercel.app

3. 更新 OAuth 回调地址

   部署完成后，需要在 GitHub OAuth App 设置中更新回调地址：

   https://your-project-name.vercel.app/api/auth/callback/github
   

1. Fork 项目到你的 GitHub

2. 连接 Vercel

   • 访问 Vercel Dashboard
   • 点击 "New Project"
   • 选择你 Fork 的仓库

3. 配置环境变量

   在 Vercel 项目设置中添加环境变量（同上）

4. 部署

   Vercel 会自动检测 Next.js 项目并进行部署

1. 创建项目

   • 登录 Cloudflare Pages
   • 连接 GitHub 仓库

2. 构建设置

   在 Cloudflare Pages 项目设置中配置：

   # 构建命令
   npx @cloudflare/next-on-pages@1
   
   # 输出目录
   .vercel/output/static
   
   # Node.js 版本
   18.17.0

3. 环境变量配置

   在 Cloudflare Pages 环境变量中添加：

   GITHUB_ID=your-github-client-id
   GITHUB_SECRET=your-github-client-secret
   GITHUB_OWNER=your-github-username
   GITHUB_REPO=your-repo-name
   GITHUB_BRANCH=main
   NEXTAUTH_URL=https://your-domain.pages.dev/api/auth
   NEXT_PUBLIC_API_URL=https://your-domain.pages.dev

4. 兼容性设置

   项目已包含 wrangler.toml 配置文件，确保 Cloudflare Pages 兼容性。

1. 克隆项目

git clone https://github.com/tianyaxiang/NavSphere.git
cd NavSphere

2. 配置环境变量

cp .env.example .env.local
# 编辑 .env.local 文件，配置必要的环境变量

1. 构建镜像

docker build -f docker/Dockerfile -t navsphere:latest .

2. 使用 Docker Compose

# 开发环境
docker-compose -f docker/docker-compose.yml up -d

# 生产环境
docker-compose -f docker/docker-compose.prod.yml up -d

3. 检查服务状态

# 查看容器状态
docker-compose -f docker/docker-compose.yml ps

# 查看日志
docker-compose -f docker/docker-compose.yml logs -f

# 停止服务
docker-compose -f docker/docker-compose.yml down

• 端口映射: 容器内部端口 3000 映射到主机端口 3000
• 环境变量: 通过 .env.local 文件注入
• 健康检查: 内置健康检查端点 /api/health
• 自动重启: 容器异常退出时自动重启

• Netlify: 需要配置构建命令
• Railway: 支持 Docker 部署
• 自托管: 支持 Docker 容器部署

数据格式示例

# 开发模式
pnpm dev

# 构建项目
pnpm build

# 启动生产服务器
pnpm start

# 代码检查
pnpm lint

# 清理构建文件
pnpm clean

NavSphere/
├── app/                    # Next.js App Router
│   ├── api/               # API 路由
│   ├── components/        # 页面组件
│   ├── globals.css        # 全局样式
│   └── layout.tsx         # 根布局
├── components/            # 共享组件
├── lib/                   # 工具函数
├── public/               # 静态资源
├── styles/               # 样式文件
└── types/                # TypeScript 类型定义