# navi

**Repository Path**: MM-Q/navi

## Basic Information

- **Project Name**: navi
- **Description**: 一个极简、高效的 Web 书签导航应用，采用 Go 语言构建，支持分类管理、快速搜索和批量操作。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-14
- **Last Updated**: 2026-01-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 导航页, Go语言

## README

# 🚀 Navi

> 一个极简、高效的 Web 书签导航应用，采用 Go 语言构建，支持分类管理、快速搜索和批量操作。

[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](https://github.com/)
[![SQLite](https://img.shields.io/badge/Database-SQLite-003B57?style=flat&logo=sqlite)](https://www.sqlite.org/)

## 📖 项目简介

Navi 是一个轻量级的书签管理系统，旨在帮助用户高效地管理和组织网页链接。项目采用 Go 标准库构建，无第三方框架依赖，部署简单，性能优异。支持分类管理、实时搜索、批量操作等功能，适合个人和团队使用。

### 核心设计理念

- **极简主义**：零框架依赖，使用 Go 标准库实现
- **单文件部署**：嵌入静态资源，编译后仅一个可执行文件
- **高性能**：SQLite 数据库 + 原生 JavaScript
- **易用性**：现代化 UI 设计，直观的操作体验

---

## ✨ 核心特性

### 🎯 功能特性

| 特性 | 描述 |
|------|------|
| 🔗 **链接管理** | 添加、编辑、删除书签链接 |
| 📂 **分类管理** | 支持自定义分类，自动归类 |
| 🔍 **实时搜索** | 快速搜索标题、URL 和分类 |
| ✅ **批量操作** | 多选、全选、批量删除 |
| � **用户管理** | 管理员可添加、编辑、删除用户账号 |
| 🔐 **账号锁定** | 登录失败自动锁定，支持管理员解锁 |
| � **响应式设计** | 完美适配桌面和移动设备 |
| 🎨 **现代 UI** | 卡片式布局，简洁美观 |
| 💾 **SQLite 存储** | 轻量级数据库，无需独立服务 |
| 📦 **单文件部署** - 编译后一个文件即可运行 |
| 🚀 **高性能** - 原生 Go 实现，启动迅速 |

### 🛠️ 技术亮点

- ✅ RESTful API 设计
- ✅ 前后端分离架构
- ✅ 嵌入式文件系统（Go embed）
- ✅ HTML5 + CSS3 + Vanilla JavaScript
- ✅ 参数化 SQL 查询，防止注入
- ✅ 代码静态检查通过（golangci-lint）

---

## 📦 安装指南

### 前置要求

- Go 1.25 或更高版本
- Git（用于克隆仓库）

### 从源码安装

```bash
# 1. 克隆仓库
git clone https://gitee.com/MM-Q/navi.git
cd navi

# 2. 安装依赖
go mod download

# 3. 构建项目
go build -o navi cmd/server/main.go

# 4. 运行服务
./navi
# Windows: navi.exe
```

### 使用构建脚本（Windows）

```bash
# 使用提供的构建脚本
build.bat
```

### 从 Release 下载

```bash
# 下载最新版本的可执行文件
wget https://gitee.com/MM-Q/navi/releases/latest/download/navi.exe  # Windows
wget https://gitee.com/MM-Q/navi/releases/latest/download/navi      # Linux/Mac
```

### Docker 部署（可选）

```bash
# 构建镜像
docker build -t navi:latest .

# 运行容器
docker run -d -p 18888:18888 -v $(pwd)/data:/app/data navi:latest
```

---

## 🎮 使用示例

### 基础用法

#### 1. 启动服务

```bash
# 默认端口 18888
./navi

# 访问 http://localhost:18888
```

#### 2. 添加链接

点击右上角菜单 → **添加链接** → 填写表单 → 保存

**表单字段：**
- **标题**：链接名称（必填）
- **URL**：链接地址（必填）
- **分类**：选择已有分类或输入新分类（可选）

#### 3. 搜索链接

在搜索框输入关键词，实时过滤显示匹配的链接。

### 高级用法

#### 批量删除链接

```bash
# 1. 点击右上角菜单 → 批量管理
# 2. 点击链接卡片选中
# 3. 点击底部操作栏的"删除选中"按钮
```

#### 分类筛选

```bash
# 点击左侧分类列表，快速筛选对应分类的链接
# 支持"全部"查看所有链接
```

#### 用户管理（管理员功能）

```bash
# 1. 点击右上角菜单 → 用户管理
# 2. 查看所有用户列表，包括用户名、角色和创建时间
# 3. 添加新用户：点击"添加用户"按钮
# 4. 编辑用户：点击用户卡片上的"编辑"按钮
# 5. 删除用户：点击用户卡片上的"删除"按钮
# 6. 解锁账号：点击用户卡片上的"解锁"按钮（仅对被锁定的账号可用）
```

#### 账号锁定机制

```bash
# 系统自动锁定：
# - 用户连续5次登录失败后，账号将被自动锁定30分钟
# - 锁定期间无法登录，显示剩余锁定时间

# 管理员解锁：
# - 管理员可以在用户管理界面查看所有用户的锁定状态
# - 被锁定的账号显示可点击的"解锁"按钮
# - 未锁定的账号显示灰色的"解锁"按钮
```

### API 使用示例

#### 获取所有链接

```bash
curl -X GET http://localhost:18888/api/links
```

**响应：**
```json
[
  {
    "id": 1,
    "title": "Google",
    "url": "https://www.google.com",
    "category": "搜索",
    "icon": "",
    "created_at": "2026-01-14T10:30:00Z"
  }
]
```

#### 添加新链接

```bash
curl -X POST http://localhost:18888/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "title": "GitHub",
    "url": "https://github.com",
    "category": "开发",
    "icon": ""
  }'
```

#### 批量删除链接

```bash
curl -X DELETE http://localhost:18888/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [1, 2, 3]
  }'
```

---

## 📚 API 文档

### 端点概览

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/` | 主页 |
| GET | `/api/links` | 获取所有链接 |
| POST | `/api/links` | 添加新链接 |
| DELETE | `/api/links` | 批量删除链接 |
| GET | `/static/*` | 静态资源服务 |
| POST | `/api/auth/register` | 用户注册 |
| POST | `/api/auth/login` | 用户登录 |
| POST | `/api/auth/logout` | 用户登出 |
| GET | `/api/auth/me` | 获取当前用户信息 |
| GET | `/api/users` | 获取用户列表（管理员） |
| POST | `/api/users/add` | 添加新用户（管理员） |
| POST | `/api/users/update` | 更新用户信息（管理员） |
| DELETE | `/api/users/delete` | 删除用户（管理员） |
| GET | `/api/users/check-lock` | 检查用户锁定状态（管理员） |
| POST | `/api/users/unlock` | 解锁用户账号（管理员） |

### 详细 API 说明

#### GET `/api/links`

获取所有链接列表。

**请求参数：** 无

**响应格式：**
```json
{
  "id": int,
  "title": string,
  "url": string,
  "category": string,
  "icon": string,
  "created_at": string (ISO 8601)
}
```

**状态码：**
- `200 OK` - 成功
- `500 Internal Server Error` - 服务器错误

#### POST `/api/links`

添加新链接。

**请求体：**
```json
{
  "title": "string (必填)",
  "url": "string (必填)",
  "category": "string (可选)",
  "icon": "string (可选)"
}
```

**响应：**
- `201 Created` - 创建成功
- `400 Bad Request` - 请求格式错误
- `500 Internal Server Error` - 服务器错误

#### DELETE `/api/links`

批量删除链接。

**请求体：**
```json
{
  "ids": [int, int, ...]
}
```

**响应：**
- `200 OK` - 删除成功
- `400 Bad Request` - 请求格式错误
- `500 Internal Server Error` - 服务器错误

#### POST `/api/auth/register`

用户注册。

**请求体：**
```json
{
  "username": "string (必填)",
  "password": "string (必填)",
  "role": "int (可选, 0=普通用户, 1=管理员)"
}
```

**响应：**
```json
{
  "success": true,
  "token": "string",
  "username": "string",
  "role": "int",
  "user_id": "int"
}
```

#### POST `/api/auth/login`

用户登录。

**请求体：**
```json
{
  "username": "string (必填)",
  "password": "string (必填)"
}
```

**响应：**
- 成功：
```json
{
  "success": true,
  "token": "string",
  "username": "string",
  "role": "int",
  "user_id": "int"
}
```
- 账号被锁定：
```json
{
  "success": false,
  "message": "账号已被锁定",
  "remaining_time": 30.5
}
```

#### GET `/api/users`

获取用户列表（仅管理员）。

**请求头：**
```
Authorization: Bearer <token>
```

**响应：**
```json
[
  {
    "id": 1,
    "username": "admin",
    "role": 1,
    "created_at": "2026-01-14T10:30:00Z"
  }
]
```

#### GET `/api/users/check-lock`

检查用户锁定状态（仅管理员）。

**请求头：**
```
Authorization: Bearer <token>
```

**查询参数：**
- `id` (int): 用户ID

**响应：**
```json
{
  "success": true,
  "locked": true,
  "remaining_time": 15.5,
  "username": "testuser"
}
```

#### POST `/api/users/unlock`

解锁用户账号（仅管理员）。

**请求头：**
```
Authorization: Bearer <token>
```

**请求体：**
```json
{
  "id": 1
}
```

**响应：**
```json
{
  "success": true,
  "message": "账号解锁成功"
}
```

---

## 🎨 支持的功能/格式

### 数据格式

| 类型 | 格式 | 说明 |
|------|------|------|
| URL | 标准网址 | 支持 HTTP/HTTPS |
| 分类 | 文本字符串 | UTF-8 编码 |
| 图标 | 文本字符串 | Emoji 或图标名称 |
| 时间戳 | ISO 8601 | RFC3339 格式 |

### 浏览器支持

| 浏览器 | 版本 |
|--------|------|
| Chrome | 最新版 |
| Firefox | 最新版 |
| Safari | 最新版 |
| Edge | 最新版 |
| 移动浏览器 | iOS 12+, Android 8+ |

---

## ⚙️ 配置选项

### 环境变量

| 变量名 | 默认值 | 描述 |
|--------|--------|------|
| `PORT` | `18888` | 服务器监听端口 |
| `DB_PATH` | `nav.db` | SQLite 数据库文件路径 |

### 配置示例

```bash
# 自定义端口
PORT=3000 ./navi

# 自定义数据库路径
DB_PATH=/data/my.db ./navi

# 组合使用
PORT=3000 DB_PATH=/data/my.db ./navi
```

### 数据库配置

数据库表结构：

#### links 表（链接表）

| 字段名 | 类型 | 约束 | 描述 |
|--------|------|--------|------|
| id | INTEGER | PRIMARY KEY AUTOINCREMENT | 链接ID |
| title | TEXT | NOT NULL | 链接标题 |
| url | TEXT | NOT NULL | 链接URL |
| category | TEXT | | 链接分类 |
| icon | TEXT | | 链接图标 |
| icon_mode | TEXT | | 图标显示模式 |
| visit_count | INTEGER | | 访问次数 |
| user_id | INTEGER | | 用户ID，关联users表 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

#### users 表（用户表）

| 字段名 | 类型 | 约束 | 描述 |
|--------|------|--------|------|
| id | INTEGER | PRIMARY KEY AUTOINCREMENT | 用户ID |
| username | TEXT | NOT NULL UNIQUE | 用户名 |
| password_hash | TEXT | NOT NULL | 密码哈希值 |
| role | INTEGER | NOT NULL DEFAULT 0 | 角色（0: 普通用户, 1: 管理员） |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

---

## 📁 项目结构

```
navi/
├── cmd/
│   └── server/
│       └── main.go              # 应用入口
├── internal/
│   ├── auth/                   # 认证相关
│   │   ├── account_lock.go      # 账号锁定管理
│   │   └── token.go            # JWT令牌管理
│   ├── database/
│   │   └── sqlite.go            # 数据库操作层
│   ├── handler/
│   │   ├── api.go               # API 请求处理
│   │   ├── auth.go             # 认证相关API
│   │   ├── import.go           # 导入功能
│   │   └── page.go            # 页面路由处理
│   ├── models/
│   │   ├── link.go             # 链接数据模型
│   │   └── user.go            # 用户数据模型
│   ├── router/
│   │   └── router.go           # 路由配置
│   ├── utils/
│   │   └── utils.go           # 工具函数
│   └── web/
│       ├── embed.go             # 嵌入式文件系统
│       ├── static/              # 静态资源
│       │   ├── css/
│       │   │   └── style.css    # 样式表
│       │   └── js/
│       │       ├── app.js       # 前端主逻辑
│       │       ├── auth.js      # 认证相关逻辑
│       │       ├── icon-manager.js # 图标管理
│       │       ├── import-export.js # 导入导出功能
│       │       ├── links.js     # 链接管理
│       │       └── ui.js       # UI交互
│       └── templates/           # HTML 模板
│           ├── base.html        # 基础模板
│           └── partials/        # 模板片段
│               ├── header.html
│               ├── sidebar.html
│               ├── add_link_modal.html
│               ├── edit_link_modal.html
│               └── import_modal.html
├── server/                      # 服务器相关
│   ├── init.go               # 初始化
│   └── server.go            # 服务器启动
├── build.bat                    # Windows 构建脚本
├── go.mod                       # Go 模块依赖
├── go.sum                       # 依赖校验文件
└── README.md                    # 项目文档
```

### 目录说明

| 目录 | 说明 |
|------|------|
| `cmd/` | 应用程序入口点 |
| `internal/` | 内部私有包 |
| `database/` | 数据访问层 |
| `handler/` | HTTP 请求处理 |
| `models/` | 数据模型定义 |
| `web/` | 前端资源和模板 |
| `static/` | CSS、JS 静态资源 |
| `templates/` | HTML 模板文件 |

---

## 🧪 测试说明

### 运行测试

```bash
# 运行所有测试
go test ./...

# 运行指定包的测试
go test ./internal/database
go test ./internal/handler

# 查看测试覆盖率
go test -cover ./...

# 生成覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

### 代码检查

```bash
# 运行 golangci-lint
golangci-lint run ./...

# 格式化代码
golangci-lint fmt ./...
```

### 手动测试

1. **功能测试**
   - 启动服务
   - 访问 http://localhost:18888
   - 测试添加、搜索、分类、删除功能

2. **API 测试**
   ```bash
   # 测试获取链接
   curl http://localhost:18888/api/links

   # 测试添加链接
   curl -X POST http://localhost:18888/api/links \
     -H "Content-Type: application/json" \
     -d '{"title":"Test","url":"http://test.com","category":"测试"}'

   # 测试删除链接
   curl -X DELETE http://localhost:18888/api/links \
     -H "Content-Type: application/json" \
     -d '{"ids":[1]}'
   ```

3. **性能测试**
   ```bash
   # 使用 Apache Bench 进行压力测试
   ab -n 1000 -c 100 http://localhost:18888/api/links
   ```

---

## 📄 许可证

本项目采用 [MIT License](LICENSE) 许可证。

```
Copyright (c) 2026 M乔木

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
...
```

---

## 🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 如何贡献

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码规范

- 遵循 Go 标准代码风格
- 运行 `golangci-lint` 确保代码质量
- 添加必要的测试用例
- 更新相关文档

### 问题反馈

- 使用 [Issues](https://gitee.com/MM-Q/navi/issues) 报告 Bug
- 提供详细的复现步骤和环境信息
- 包含错误日志和截图（如适用）

---

## 📞 联系方式

### 项目信息

- **项目名称**: Navi
- **作者**: M乔木
- **邮箱**: 暂无
- **项目仓库**: https://gitee.com/MM-Q/navi.git

### 相关链接

| 资源 | 链接 |
|------|------|
| 📦 仓库地址 | https://gitee.com/MM-Q/navi.git |
| 🐛 问题反馈 | https://gitee.com/MM-Q/navi/issues |
| 📝 文档 | https://gitee.com/MM-Q/navi/wikis |
| 📦 发布版本 | https://gitee.com/MM-Q/navi/releases |

### 技术支持

- 查看文档：[Wiki](https://gitee.com/MM-Q/navi/wikis)
- 提交问题：[Issues](https://gitee.com/MM-Q/navi/issues)
- 讨论交流：[Gitee Discussions](https://gitee.com/MM-Q/navi/discussions)

---

## 🙏 致谢

感谢以下开源项目：

- [Go](https://go.dev/) - 编程语言
- [SQLite](https://www.sqlite.org/) - 数据库引擎
- [mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) - SQLite 驱动

---

## 📊 项目统计

![Repo Size](https://img.shields.io/github/repo-size/user/repo)
![Code Size](https://img.shields.io/github/languages/code-size/user/repo)
![Last Commit](https://img.shields.io/github/last-commit/user/repo)
![Contributors](https://img.shields.io/github/contributors/user/repo)

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给它一个 Star！**

Made with ❤️ by M乔木

[⬆ 返回顶部](#-navi)

</div>