Skip to content

README-CN.md

Latest commit

 

History

History
265 lines (205 loc) · 6.18 KB

README-CN.md

File metadata and controls

265 lines (205 loc) · 6.18 KB

NavSphere

Overview

NavSphere is a web application designed for managing navigation items and categories. It provides an intuitive interface for adding, editing, and organizing navigation entries, including site icons and descriptions.

Features

  • Add/Edit Navigation Items: Easily add or modify navigation items with titles, links, icons, and descriptions.
  • Icon Management: Upload or fetch icons for each navigation item.
  • Drag-and-Drop Interface: Reorder navigation items and categories using drag-and-drop functionality.
  • Responsive Design: Works seamlessly on various devices and screen sizes.

Installation

Prerequisites

  • Node.js (version x.x.x)
  • npm or yarn

Steps

  1. Clone the repository: 
    git clone https://github.com/tianyaxiang/NavSphere.git

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Inter, a custom Google Font.

Learn More

To learn more about Next.js, take a look at the following resources:

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.

本地开发配置

1. GitHub OAuth App 配置

  1. 访问 GitHub Developer Settings

    • 点击右上角头像
    • Settings
    • 左侧边栏底部 Developer settings
    • OAuth Apps
    • New OAuth App

  2. 填写应用信息：

    Application name: 你的应用名称
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:3000/api/auth/callback/github

  3. 创建后获取：

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

2. GitHub 仓库配置

  1. 创建用于存储数据的仓库：

  2. 获取仓库信息：

    GITHUB_OWNER: 你的 GitHub 用户名
GITHUB_REPO: 仓库名

  3. 创建 GitHub 组织（可选）：

3. 环境变量配置

# GitHub OAuth App 配置
GITHUB_ID=从 OAuth App 获取的 Client ID
GITHUB_SECRET=从 OAuth App 获取的 Client Secret

# GitHub 组织和仓库配置
GITHUB_ORG=你的组织名称（如果使用组织）
GITHUB_OWNER=你的 GitHub 用户名
GITHUB_REPO=用于存储数据的仓库名
GITHUB_BRANCH=main

# NextAuth 配置
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=使用以下命令生成:
# openssl rand -base64 32

4. 权限配置

  1. OAuth App 权限：

    • 在 OAuth App 设置页面
    • 确保 read:org 和 repo 权限被勾选

  2. 仓库权限：

    • 如果是私有仓库，确保 OAuth App 有访问权限
    • 如果使用组织，确保 OAuth App 已在组织中安装

5. 注意事项

  1. 本地开发和生产环境使用不同的 OAuth App
  2. 生产环境需要更新回调 URL 为实际域名
  3. 确保 .env.local 不被提交到 Git
  4. 生产环境使用 Cloudflare Pages 的环��
  5. 定期轮换 Client Secret 以提高安全性

Cloudflare Pages 部署

  1. 在 Cloudflare Pages 中创建新项目
  2. 连接 GitHub 仓库
  3. 设置构建命令： 
    pnpm install && pnpm build
  4. 设置环境变量：
    • GITHUB_ID
    • GITHUB_SECRET
    • GITHUB_OWNER
    • GITHUB_REPO
    • GITHUB_BRANCH
    • NEXTAUTH_URL (设置为你的域名)
    • NEXTAUTH_SECRET
  5. 部署项目

环境变量

需要配置以下环境变量：

NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-here
GITHUB_ID=your-github-id
GITHUB_SECRET=your-github-secret
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-repo-name
GITHUB_BRANCH=main

开发

  1. 安装依赖
pnpm install
  1. 配置环境变量
cp .env.example .env.local
  1. 启动开发服务器
pnpm dev

数据文件

项目使用 GitHub 仓库存储数据，需要以下数据文件：

  1. app/data/db/navigation.json - 导航数据
  2. app/data/db/resources.json - 资源数据

这些文件会在首次提交到仓库时自动创建。

数据格式

navigation.json

[
  {
    "id": "string",
    "title": "string",
    "icon": "string",
    "items": [
      {
        "title": "string",
        "titleEn": "string",
        "description": "string",
        "descriptionEn": "string",
        "icon": "string",
        "href": "string"
      }
    ],
    "subCategories": [
      {
        "id": "string",
        "title": "string",
        "items": []
      }
    ]
  }
]

resources.json

[
  {
    "id": "string",
    "title": "string",
    "items": [
      {
        "title": "string",
        "description": "string",
        "icon": "string",
        "url": "string"
      }
    ]
  }
]

故障排除

导航数据加载失败

  1. 检查环境变量配置

    • GITHUB_OWNER 是否正确
    • GITHUB_REPO 是否正确
    • GITHUB_BRANCH 是否正确

  2. 检查仓库权限

    • 仓库是否公开
    • OAuth App 是否有正确的权限
    • Token 是否有效

  3. 检查数据文件

    • navigation.json 是否存在
    • 文件格式是否正确
    • 文件路径是否正确

  4. 查看控制台日志

    • 检查 API 请求是否成功
    • 检查错误信息
    • 检查返回的数据格式
⚡