# bookmarks

**Repository Path**: TechFunWay/bookmarks

## Basic Information

- **Project Name**: bookmarks
- **Description**: 飞牛应用，网址收藏夹功能
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-13
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网址收藏夹

一个简单易用的网址收藏夹管理工具，基于Go语言后端和Vue.js前端构建。

## 应用截图

![网址收藏夹应用界面](./docs/screenshots/app-interface.jpg)

_书签卡片网格、文件夹管理与快速搜索_

---

## 功能特性

- 📁 **文件夹管理** - 创建、编辑、删除文件夹，支持嵌套结构
- 🔖 **书签管理** - 添加、编辑、删除网址书签，支持批量操作
- 🔄 **拖拽排序** - 支持文件夹和书签的拖拽重排序
- 📦 **批量操作** - 批量选择、删除和移动书签
- 🌐 **元数据获取** - 自动获取网页标题和favicon图标
- 🎨 **现代化界面** - 简洁美观的用户界面
- 📱 **响应式设计** - 适配不同屏幕尺寸
- ⚡ **快速响应** - 基于SQLite本地数据库，查询速度快
- 🔒 **安全可靠** - 支持内网HTTPS站点访问
- 📤 **导入导出** - 支持JSON格式书签的导入和导出
- 🌐 **Edge浏览器支持** - 支持导入和导出Edge浏览器的HTML格式书签
- 🎨 **主题切换** - 支持浅色和深色主题切换
- 🎨 **背景设置** - 支持自定义背景（默认、纯色、图片），可调节面板透明度
- 📊 **每页显示** - 支持自定义每行显示的书签数量（1-6个）
- 🔍 **搜索功能** - 支持按网址名称搜索书签
- 💾 **配置保存** - 书签、排序和大部分显示配置按账号保存；部分主题、移动端视图等浏览器本地偏好仅在当前浏览器中保存

## 多用户、权限与公共书签

项目支持在同一个实例中创建多个用户。书签树和用户配置使用账号维度隔离，适合部署在飞牛 NAS 上供家人或朋友共同使用。需要注意：这是同一个 SQLite 数据库中的逻辑隔离，不是为每个用户创建独立数据库文件。

### 当前行为

| 问题 | 当前行为 |
| --- | --- |
| 文件夹、书签和排序是否独立 | 是。普通接口会按当前登录用户的 `user_id` 查询、创建、修改、删除和排序，用户 A 无法通过普通接口读取或操作用户 B 的私有数据。 |
| 主题、背景、页面布局等配置是否独立 | 不完全一致。显示开关、每行数量、默认首页、文件夹视图缩放和桌面端背景等配置保存在用户级 `sys_config` 中；部分主题、移动端视图/背景和模板排序仍保存在浏览器 `localStorage`，同一浏览器切换账号时可能沿用本地偏好。 |
| 浏览器扩展同步范围 | 是。扩展使用 `X-API-Key`，API Key 先解析到所属用户，随后所有同步查询和写入都限制在该用户的数据范围内。不要在多个账号之间共用 API Key。 |
| 管理员能否操作其他用户数据 | 可以。管理员后台可以查看指定用户的书签树、修改或删除节点、为用户创建节点、调整排序，并导出指定用户的 JSON 数据。相关操作受管理员接口保护。 |
| 免登录模式的数据归属 | 未携带有效 Token 的访客会以当前第一个启用的管理员账号访问和修改数据；所有未登录访客看到的是同一份管理员数据。免登录模式不等于为每位访客创建临时账号。携带有效 Token 的用户仍会使用自己的数据。 |

### 公共书签与共享收藏夹的边界

当前已经支持“公开书签”：书签可以设置为 `public`，并通过“公开门户”、`/public-bookmarks.html` 和 `/api/public-tree` 对外展示。公开内容不是用户私有树的一部分，其他用户不能因此获得该书签的编辑或删除权限。

当前还不支持真正的“公共收藏夹/共享文件夹”模型：

- 文件夹仍归属于创建它的用户，不能把整个文件夹授权给多个用户共同维护；
- 管理员可以为指定用户预置书签，也可以把书签设为公开，但这不是一个所有用户共同挂载的公共目录；
- 暂无把公开书签一键复制到当前用户收藏夹的接口或页面，用户需要手动重新添加，或由管理员分别预置副本；
- 因此下面这种“管理员维护一份公共收藏夹、用户各自拥有私人收藏夹”的结构目前尚未完整实现：

```text
公共收藏夹（当前版本：仅支持公开书签展示，不支持共享目录）
├── 常用工具
├── 公司系统
└── 推荐网站

用户 A / 用户 B：各自独立的私人收藏夹
```

公共收藏夹、指定文件夹共享、公共书签复制等功能可作为后续版本的独立权限模型设计；在实现前不会把现有的“公开书签”描述为“共享收藏夹”，以免造成权限预期误解。

## 技术架构

### 后端技术栈
- **Go 1.21+** - 主要编程语言
- **Chi** - 轻量级HTTP路由器
- **SQLite** - 本地数据库存储
- **Go Modules** - 依赖管理

### 前端技术栈
- **Vue.js 3** - 现代JavaScript框架
- **HTML5/CSS3** - 页面布局和样式
- **Fetch API** - HTTP请求处理

### 数据存储
- SQLite数据库文件：`data.db`
- 支持外键约束和数据一致性
- 自动维护排序位置

## 快速开始

### 系统要求
- Go 1.21 或更高版本
- 支持SQLite的操作系统（Windows/macOS/Linux）

### 安装步骤

#### 方式一：直接运行

1. **克隆或下载项目**
   ```bash
   git clone <项目地址>
   cd bookmarks
   ```

2. **运行应用**
   - 使用默认端口8901启动：
   ```bash
   go run main.go
   ```

   - 自定义端口启动：
   ```bash
   go run main.go -port 3000
   ```

   - 自定义数据路径和端口：
   ```bash
   go run main.go -dataUrl /path/to/data -port 8080
   ```

3. **访问应用**
   - 默认访问地址：http://localhost:8901
   - 或访问您指定的端口地址
   - 查看所有可用选项：`go run main.go -h`

### 自定义配置

启动时可以通过命令行参数自定义配置：

#### 数据路径
```bash
go run main.go -dataUrl=/path/to/your/data/
```

#### 端口配置
```bash
go run main.go -port 3000
```

#### 组合配置
```bash
go run main.go -dataUrl=/path/to/data -port 8080
```

#### 查看所有选项
```bash
go run main.go -h
```

**可用参数：**
- `-dataUrl`：数据存储路径（默认："./"）
- `-port`：服务器监听端口（默认："8901"）

## 使用说明

### 基础操作

1. **创建文件夹**
   - 点击左侧"新建文件夹"按钮
   - 或右键点击现有文件夹选择"新建子文件夹"

2. **添加书签**
   - 点击左侧"添加网址"按钮
   - 或右键点击文件夹选择"添加网址"
   - 输入网址后点击"获取信息"可自动填充标题和图标

3. **编辑项目**
   - 双击文件夹或书签名称进行编辑
   - 或右键选择"编辑"选项

4. **删除项目**
   - 右键选择"删除"选项
   - 或在编辑模式下批量选择删除

### 高级功能

1. **重排序**
   - 拖拽文件夹或书签到新位置
   - 或使用右键菜单的"上移"/"下移"选项

2. **移动到文件夹**
   - 右键选择"移动到文件夹"
   - 选择目标文件夹并确认

3. **批量操作**
   - 点击"编辑"按钮进入编辑模式
   - 使用复选框选择多个项目
   - 执行批量删除或移动操作

4. **搜索和组织**
   - 通过文件夹结构组织书签
   - 查看书签路径信息
   - 使用搜索框按名称搜索书签

5. **导入导出**
   - 点击顶部的"导出"按钮导出JSON格式书签
   - 点击顶部的"导入"按钮导入JSON格式书签
   - 选择导入模式（合并或替换）
   - 选择导入目标文件夹
   - 支持从Edge浏览器导入HTML格式书签

6. **主题切换**
   - 点击右上角的主题切换按钮
   - 在浅色和深色主题之间切换
   - 主题设置会自动保存

7. **背景设置**
   - 点击右上角的"背景"按钮
   - 选择背景类型：默认背景、纯色背景、图片背景
   - 可以上传自定义图片作为背景
   - 支持调节面板透明度，让背景图片或颜色透过面板显示
   - 背景设置会自动保存

8. **每页显示设置**
   - 在网址列表上方选择每行显示的书签数量（1-6个）
   - 设置会自动保存到数据库
   - 换浏览器后设置依然有效

### 快捷操作

- **右键菜单**：在任何项目上右键查看可用操作
- **双击编辑**：双击项目名称快速编辑
- **拖拽移动**：直接拖拽到目标位置
- **批量选择**：使用编辑模式进行批量操作

## API接口

### RESTful API
- `GET /api/tree` - 获取完整树结构
- `GET /api/metadata?url=<网址>` - 获取网页元数据
- `POST /api/folders` - 创建文件夹
- `POST /api/bookmarks` - 创建书签
- `PUT /api/nodes/{id}` - 更新节点
- `DELETE /api/nodes/{id}` - 删除节点
- `POST /api/nodes/reorder` - 重新排序节点
- `POST /api/import` - 导入JSON格式书签
- `POST /api/import-edge` - 导入Edge浏览器HTML格式书签
- `GET /api/config` - 获取配置（主题、背景、每页显示等）
- `POST /api/config` - 保存配置（主题、背景、每页显示等）

### 请求示例

```bash
# 获取树结构
curl http://localhost:8901/api/tree

# 创建文件夹
curl -X POST http://localhost:8901/api/folders \
  -H "Content-Type: application/json" \
  -d '{"title":"工作相关","parent_id":null}'

# 创建书签
curl -X POST http://localhost:8901/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"title":"GitHub","url":"https://github.com","parent_id":1}'
```

## 配置说明

### 数据库配置
- 数据库文件位置：可通过`-dataUrl`参数指定
- 默认位置：当前目录下的`data.db`
- 自动创建必要的表和索引

### 服务器配置
- 默认端口：8901
- 支持静态文件服务
- 内置CORS支持

## 目录结构

```
bookmarks/
├── main.go              # 主程序入口
├── go.mod               # Go模块定义
├── go.sum               # 依赖校验
├── data.db              # SQLite数据库文件（运行时生成）
├── static/              # 静态文件目录
│   ├── index.html       # 主页面
│   ├── app.js          # Vue.js应用
│   └── style.css       # 样式文件
├── README.md           # 中文说明
├── README.en.md        # English README
```

## 开发说明

### 环境要求
- Go 1.21+
- 现代浏览器支持（Chrome、Firefox、Safari、Edge）

### 开发运行
```bash
# 启动开发服务器
go run main.go

# 修改前端代码后刷新浏览器即可看到效果
```

### 部署建议
- 可以打包成单文件可执行程序
- 支持在任何支持Go的平台上运行
- 数据文件可与程序分离，便于备份

## 故障排除

### 常见问题

1. **端口被占用**
   - 检查8901端口是否被其他程序占用
   - 或修改代码中的端口配置

2. **数据库错误**
   - 确保有写入权限
   - 检查磁盘空间是否充足

3. **网页元数据获取失败**
   - 检查网络连接
   - 某些网站可能限制爬虫访问

4. **HTTPS站点访问失败**
   - 应用支持自签名证书
   - 内网HTTPS站点可正常访问

### 日志查看
- 启动时会显示服务器运行端口
- 浏览器开发者工具查看前端错误
- 服务器日志显示API请求和错误信息

## 许可证

本项目采用MIT许可证，详见LICENSE文件。

## 参与贡献

欢迎提交Issue和Pull Request！

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

## 更新日志

### v2.1.0
- 1.更新：浏览器同步插件支持同时同步多个设备，每个设备独立配置设置
- 2.新增：免登录功能（开启免登录后实际使用的是管理员数据）
- 3.新增：新增分类显示页面，支持滑动缩放图标大小

### v1.4.0
- 新增背景设置功能，支持默认背景、纯色背景、自定义图片背景
- 新增面板透明度调节功能，可调节列表和结构面板的透明度
- 新增每页显示数量保存功能，设置自动保存到数据库，跨浏览器同步
- 优化浅色主题下选中数字的显示效果
- 调整PC端列表布局高度，解决内容超出问题
- 性能优化和bug修复

### v1.2.0
- 新增导入导出功能，支持JSON格式书签的导入和导出
- 新增Edge浏览器支持，支持导入和导出Edge浏览器的HTML格式书签
- 新增主题切换功能，支持浅色和深色主题切换
- 优化了文件夹选择功能，修复了导入时无法选择文件夹的问题
- 修复了交叉编译问题，支持生成不同架构的Linux二进制文件
- 性能优化和bug修复

### v1.1.0
- 新增搜索功能，支持按网址名称搜索
- 手机端适配优化
- 性能优化和bug修复

### v1.0.0
- 初始版本发布
- 基础文件夹和书签管理功能
- 拖拽排序支持
- 批量操作功能
- 网页元数据获取
- 响应式设计，适配不同屏幕尺寸
- 现代化美观界面
- 支持内网HTTPS站点访问

## 安全说明

### 数据安全
- 数据存储在本地SQLite数据库文件中，不会上传到云端
- 支持定期备份数据库文件
- 建议将数据文件存储在安全位置

### 网络安全
- 仅通过本地HTTP服务器访问，不暴露公网
- 支持内网HTTPS站点访问
- 无第三方依赖，减少安全风险

## 浏览器兼容性

- ✅ Chrome 80+
- ✅ Firefox 75+
- ✅ Safari 13+
- ✅ Edge 80+

## 性能优化

- 本地SQLite数据库，查询速度快
- 前端采用Vue.js 3，渲染性能优秀
- 支持大量书签和文件夹的高效管理
- 拖拽操作流畅，响应迅速

## 备份和恢复

### 备份数据
1. 关闭应用程序
2. 复制`data.db`文件到安全位置
3. 完成备份

### 恢复数据
1. 关闭应用程序
2. 将备份的`data.db`文件复制到应用程序目录
3. 启动应用程序
4. 数据将自动恢复

## 未来计划

- [ ] 支持标签功能
- [ ] 支持快捷键操作
- [ ] 支持书签预览功能
- [ ] 支持云同步功能
- [ ] 支持更多浏览器的书签导入导出
- [ ] 支持更高级的搜索功能
- [ ] 支持书签分组和智能分类
- [ ] 支持自定义主题和样式

## 支持和反馈

如果您在使用过程中遇到问题或有任何建议，欢迎通过以下方式反馈：

- 创建Issue：在GitHub仓库提交Issue
- 邮件反馈：发送邮件到[your-email@example.com]
- 提交Pull Request：贡献代码或改进

## 致谢

感谢所有为本项目做出贡献的开发者和用户！

## 关于作者

一个热爱技术的开发者，致力于创建简单易用的工具，提高工作效率。