doxwant/go-nav

By doxwant

•Updated 2 days ago

一个简洁高效的个人/团队导航站

Image

Web servers

10K+

Overview Tags

doxwant/go-nav repository overview

⁠Go Nav

一个简洁高效的个人/团队导航站，基于 Next.js 16、React 19、HeroUI v3 和 Tailwind CSS v4 构建。项目使用 JSON 配置驱动内容和布局，支持前台导航、后台管理、图片上传、备份还原和 Docker 部署。

Go Nav 同时支持两种部署形态：

Server 模式：保留 /admin 后台、API、上传和备份能力，适合自用或团队维护，推荐使用 Docker 部署。
Static 模式：导出纯静态前台页面，适合 GitHub Pages、对象存储、CDN 等无需后台的场景。

⁠在线体验

官网：https://www.gotab.cn⁠
项目预览：https://nav.gotab.cn⁠

⁠交流群

欢迎加入 QQ 交流群一起反馈问题、交流部署和分享使用经验。

QQ 群：727809499
加群链接：点击加入 Go Nav QQ 交流群⁠

⁠功能特性

配置驱动：通过 data/nav.json 和 data/website.json 管理站点信息、布局、搜索、广告、插件和分类数据。
多级导航：分类支持递归嵌套，二级分类自动以标签页展示。
站内搜索：前端本地搜索支持标题、描述、标签和分类名命中。
外部搜索引擎：可配置百度、Bing、Google 等搜索 URL，使用 {query} 作为搜索词占位符。
后台管理：server 模式下提供 /admin，可管理网站信息、分类、站点、广告、搜索引擎、插件、备份和上传素材。
双构建模式：server 模式保留后台和 API；static 模式导出纯静态页面，适合 GitHub Pages、对象存储、CDN。
Docker 友好：内置 Dockerfile、Compose 配置和发布脚本，镜像自带默认数据，挂载数据目录时优先使用用户数据。
上传与备份：支持图片上传、完整 ZIP 备份、备份还原和无用素材清理。
响应式体验：桌面侧边栏、移动端抽屉导航、最近访问、回到顶部和二维码入口。

⁠环境要求

Node.js 20+ 推荐，最低请使用当前 Next.js 16 支持的 Node 版本
pnpm：建议使用 Corepack 读取项目 packageManager 指定版本；升级项目 pnpm 时更新该字段即可
Docker / Docker Compose：仅 Docker 部署需要

⁠快速开始

git clone https://github.com/dengxiwang/go-nav.git
cd go-nav
pnpm install
pnpm dev

开发服务默认运行在 http://localhost:3000。server 模式下后台入口为 http://localhost:3000/admin。

后台默认账号来自环境变量。开发时可以复制示例文件：

cp .env.example .env.local

生产环境务必修改 ADMIN_PASS 和 SESSION_SECRET。

⁠常用命令

命令	说明
`pnpm dev`	以 server 模式启动开发环境，包含前台、后台和 API
`pnpm dev:static`	以 static 模式启动开发环境，排除 `/admin` 与 `/api`
`pnpm build`	默认 server 模式构建
`pnpm build:server`	明确以 server 模式构建
`pnpm build:static`	同步 uploads 后导出静态站点到 `out/`
`pnpm start`	启动 server 模式 standalone 生产服务
`pnpm lint`	运行 ESLint
`pnpm docker:build`	构建本地 Docker 镜像
`pnpm docker:up`	构建并启动本地 Docker Compose 测试环境
`pnpm docker:push`	构建多架构镜像并推送到 Docker Hub

⁠运行模式

⁠Server 模式

server 模式是默认模式，适合需要后台管理、登录、上传、备份和 API 的部署。构建产物使用 Next.js standalone 输出，可直接用 Node.js 运行，也可以打包进 Docker 镜像。

pnpm build:server
pnpm start

后台登录账号来自环境变量：

ADMIN_USER=admin
ADMIN_PASS=admin123
SESSION_SECRET=please-change-me-to-a-long-random-string

生产环境务必修改 ADMIN_PASS 和 SESSION_SECRET。可以复制 .env.example 为 .env.local 后调整。

⁠Docker 部署

Docker 部署使用 server 模式，镜像基于 Next.js standalone 输出，只包含生产运行所需文件。Dockerfile 不固定 pnpm 版本，构建时会通过 Corepack 跟随项目 packageManager。镜像内会包含构建时的默认 data/nav.json、data/website.json 和 data/uploads/：

容器首次启动时，如果 /app/data/nav.json 或 /app/data/website.json 不存在，会从镜像内的默认数据初始化。
容器首次启动时，如果 /app/data/uploads/ 不存在或为空，会从镜像内的默认 uploads/ 初始化。
如果用户挂载了自己的目录，并且里面已有 nav.json / website.json / 上传文件，启动脚本不会覆盖用户数据。
默认使用 Docker 命名卷 go-nav-data 持久化 /app/data，也可以通过 DATA_MOUNT 改成本地目录挂载。

⁠本地构建测试

准备 .env：

cp .env.example .env

编辑 .env，至少修改：

ADMIN_USER=admin
ADMIN_PASS=change-this-password
SESSION_SECRET=change-this-to-a-long-random-string
PORT=3000

构建并启动：

pnpm docker:up

访问 http://localhost:3000，后台入口为 http://localhost:3000/admin。

查看状态和日志：

docker compose ps
pnpm docker:logs

停止服务：

pnpm docker:down

默认使用命名卷 go-nav-data 持久化 /app/data，其中包含 JSON 配置和 uploads/ 上传素材。需要迁移或备份时，可以通过后台备份功能导出，或直接备份该 Docker volume。

如果要用本地目录测试用户自定义数据：

mkdir -p docker-data
cp data/nav.json docker-data/nav.json
cp data/website.json docker-data/website.json
DATA_MOUNT=./docker-data:/app/data pnpm docker:up

如果需要重置默认命名卷中的数据：

docker compose down -v

⁠构建本地镜像

pnpm docker:build

默认构建 go-nav:latest。也可以指定镜像名和标签：

IMAGE_NAME=doxwant/go-nav IMAGE_TAG=1.0.0 pnpm docker:build

⁠推送 Docker Hub

先登录 Docker Hub：

docker login

默认会推送到 doxwant/go-nav。如果要推送到自己的镜像仓库，可以在 .env 里覆盖：

IMAGE_NAME=doxwant/go-nav

推送只需要一个命令：

pnpm docker:push

默认会推送：

doxwant/go-nav:<package.json version>
doxwant/go-nav:latest

IMAGE_TAG 默认读取 package.json 的 version，也可以在环境变量里临时覆盖。默认平台是 linux/amd64,linux/arm64；如需调整可以设置 PLATFORMS，或用 PUSH_LATEST=false 跳过 latest 标签。

⁠用户拉取运行

使用镜像内置默认数据：

docker run -d \
  --name go-nav \
  --restart unless-stopped \
  -p 3000:3000 \
  -e ADMIN_USER=admin \
  -e ADMIN_PASS=change-this-password \
  -e SESSION_SECRET=change-this-to-a-long-random-string \
  -e DATA_DIR=/app/data \
  -v go-nav-data:/app/data \
  doxwant/go-nav:latest

使用本地数据目录。目录为空时会初始化默认 JSON 和 uploads/；目录内已有 nav.json / website.json / 上传文件时会直接使用用户数据：

mkdir -p ./go-nav-data
docker run -d \
  --name go-nav \
  --restart unless-stopped \
  -p 3000:3000 \
  -e ADMIN_USER=admin \
  -e ADMIN_PASS=change-this-password \
  -e SESSION_SECRET=change-this-to-a-long-random-string \
  -e DATA_DIR=/app/data \
  -v "$(pwd)/go-nav-data:/app/data" \
  doxwant/go-nav:latest

如果用户想用 Docker Compose 部署远端镜像，可以创建自己的 docker-compose.yml：

services:
  go-nav:
    image: doxwant/go-nav:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      ADMIN_USER: admin
      ADMIN_PASS: change-this-password
      SESSION_SECRET: change-this-to-a-long-random-string
      DATA_DIR: /app/data
    volumes:
      - go-nav-data:/app/data

volumes:
  go-nav-data:

然后启动：

docker compose up -d

⁠Static 模式

static 模式会排除所有 .server.ts / .server.tsx 页面和路由，仅生成前台静态页面：

pnpm build:static

生成结果位于 out/，可以部署到任意静态托管服务。静态模式没有后台、登录、API 和运行时上传能力；已有的 data/uploads/ 会在构建前同步到 public/uploads/。

⁠数据目录

默认数据目录是项目根目录下的 data/：

data/
├── nav.json       # 站点设置、搜索、广告、布局、插件等
├── website.json   # 分类和网址数据
└── uploads/       # 后台上传的图片素材，默认不提交到 Git

server 模式可以通过 DATA_DIR 指定外部数据目录，便于持久化：

DATA_DIR=/app/data pnpm start

Docker 中固定使用 /app/data 作为容器内数据目录。推荐挂载 Docker volume 或宿主机目录保存这些文件：

/app/data/nav.json
/app/data/website.json
/app/data/uploads/

⁠配置说明

⁠`data/nav.json`

字段	说明
`title` / `name` / `description` / `keywords`	SEO 与品牌展示信息
`logo` / `favicon`	Logo 和浏览器图标路径
`author` / `copyright`	作者与版权信息
`icp` / `beian`	备案信息，留空则不显示
`qrCode` / `qrCodeText`	二维码图片与提示文案
`footerLinks`	页脚链接数组
`themeMode`	`light`、`dark` 或 `system`
`search`	搜索配置
`ads` / `showAds` / `adsAspectRatio`	广告配置
`showRecentVisits` / `recentVisitsMax`	最近访问配置
`layout`	布局与显示开关
`plugins`	自定义 CSS / JS 片段

⁠`data/website.json`

{
	"categories": [
		{
			"id": "tools",
			"name": "效率工具",
			"icon": "⚙️",
			"description": "常用工具集合",
			"sites": [
				{
					"title": "Go Nav",
					"description": "导航站项目",
					"url": "https://github.com/dengxiwang/go-nav",
					"icon": "/images/logo.svg",
					"tags": ["nav", "nextjs"]
				}
			],
			"children": []
		}
	]
}

分类可以无限嵌套。网站图标支持 emoji、本地路径、远程 URL；后台上传素材会返回 /uploads/xxx 路径。

⁠后台管理

server 模式访问 /admin 登录后台。后台可编辑：

网站基础信息、主题、页脚、布局
分类与网站条目，网址标签支持英文逗号 , 或中文逗号 ， 分隔
搜索引擎与搜索行为
广告位、捐赠/二维码、插件
图片上传、备份导出、备份还原、无用素材清理

上传接口仅接受 png、jpg、gif、webp、ico 图片，单文件最大 2MB。备份还原最大 20MB。

⁠部署建议

需要后台管理：使用 server 模式部署，并持久化 DATA_DIR；推荐 Docker。
只需要公开导航页：使用 static 模式构建，把 out/ 上传到静态托管/CDN。
发布镜像：镜像可以内置默认 nav.json / website.json / uploads/；用户挂载自己的数据目录后会优先使用挂载数据。
生产安全：修改默认管理员密码和 session 密钥，不要提交 .env.local、.env 和 data/uploads/。
配置更新：server 模式下后台保存会触发首页重新验证；static 模式下修改 JSON 后需要重新构建。

⁠项目结构

go-nav/
├── app/                    # Next.js App Router 页面和路由
│   ├── admin/              # 后台页面，仅 server 模式
│   ├── api/                # API 路由，仅 server 模式
│   └── uploads/            # 上传文件代理，仅 server 模式
├── components/             # 前台与后台 React 组件
├── data/                   # JSON 配置和上传数据
├── Dockerfile              # server 模式生产镜像
├── docker-compose.yml      # 本地测试和部署示例
├── hooks/                  # 自定义 Hooks
├── lib/                    # 配置读取、状态、服务端工具
├── public/                 # 静态资源
├── scripts/                # 构建、Docker 发布和数据同步脚本
└── types/                  # TypeScript 类型定义

⁠技术栈

⁠开源协议

本项目基于 MIT License⁠ 开源。你可以自由使用、修改和商用，但请保留原始项目署名信息。

⁠捐赠支持

如果这个项目帮到了你，欢迎扫码支持。你的鼓励会让这个小项目继续往前走。

Tag summary

Recent tags

Content type