# BookmarkSync

**Repository Path**: zcoolq/BookmarkSync

## Basic Information

- **Project Name**: BookmarkSync
- **Description**: 浏览器书签同步助手
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 13
- **Forks**: 1
- **Created**: 2025-02-19
- **Last Updated**: 2025-09-01

## Categories & Tags

**Categories**: chrome-plugins

**Tags**: None

## README

# 书签同步助手使用说明

## 简介
书签同步助手是一个浏览器扩展，可以帮助您在不同设备间同步浏览器书签。通过 Gitee 代码片段功能实现安全可靠的书签存储和同步。

## 安装步骤
### 1. 下载扩展程序
### 2. 打开浏览器的扩展管理页面（chrome://extensions/）
### 3. 开启"开发者模式"
### 4. 点击"加载已解压的扩展程序"
### 5. 选择扩展程序所在文件夹

## 初始配置
### 1. 获取 Gitee 访问令牌：
   - 登录您的 [Gitee 账号](https://gitee.com)
   - 进入[设置 -> 私人令牌](https://gitee.com/profile/personal_access_tokens)
   - 点击"生成新令牌"
   - 勾选 `gists` 权限
   - 生成并复制令牌

### 2. 配置访问令牌：
   - 点击扩展图标
   - 点击右上角的设置图标（⚙️）
   - 在"访问令牌"输入框中粘贴您的 Gitee 令牌
   - （可选）在"代码片段描述"输入框中自定义代码片段描述信息，用于标识不同的远程书签分支（默认值为书签同步助手）
   - （可选）在"加密密钥"输入框中设置自定义加密密钥，用于保护您的书签数据（默认使用系统提供的密钥）
   - 点击"保存"按钮

## 主要功能

### 1. 本地同步到云端
- 点击"本地同步到云端"按钮
- 将本地新增的书签上传到 Gitee
- 不会覆盖云端已有的书签
- 上传成功后会显示新增书签数量

### 2. 云端同步到本地
- 点击"云端同步到本地"按钮
- 从 Gitee 下载书签并合并到本地
- 不会覆盖本地已有的书签
- 同步成功后会显示提示信息

### 3. 自动同步
- 在设置页面启用"自动同步"功能
- 当书签发生变化时，会自动同步到云端
- 同步特点：
  - 仅同步新增的书签，不会覆盖现有书签
  - 两次同步之间至少间隔5分钟
  - 每30分钟自动检查一次是否需要同步
  - 同步完成后会显示系统通知
  - 支持多种浏览器（Chrome、Firefox、Edge）

### 5. 强制本地同步到云端
- 点击"强制本地同步到云端"按钮
- 将完全覆盖云端的书签数据
- 请谨慎使用此功能

### 6. 清除本地书签
- 点击"清除本地书签"按钮
- 会弹出确认对话框
- 确认后将清除浏览器中的所有书签
- 此操作不可恢复，请谨慎操作

## 注意事项
### 1. 首次使用前必须配置 Gitee 访问令牌
### 2. 清除本地书签操作不可恢复，请谨慎操作
### 3. 同步过程中请勿关闭浏览器
### 4. 建议在同步前备份重要书签
### 5. 如遇到同步失败，请检查：
   - 网络连接是否正常
   - 访问令牌是否正确
   - Gitee 服务是否可用
### 6. 自动同步注意事项：
   - 需要在设置中手动启用
   - 需要保持浏览器运行
   - 可能会消耗少量网络流量
   - 建议配合手动同步使用
### 7. 加密密钥注意事项：
   - 如果设置了自定义加密密钥，请务必妥善保管
   - 一旦丢失自定义密钥，将无法解密已加密的书签数据
   - 更换设备或重新安装扩展时，需要使用相同的密钥才能正常访问云端数据

## 文件夹结构说明
书签会保持原有的文件夹结构：
- 书签栏（Bookmarks Bar）
- 其他书签（Other Bookmarks）

## 常见问题解答

### Q: 为什么需要 Gitee 访问令牌？
A: 访问令牌用于安全地访问您的 Gitee 账号，确保只有您能访问和修改您的书签数据。

### Q: 书签数据是否安全？
A: 是的。书签数据以私有代码片段形式存储在您的 Gitee 账号中，只有您能访问。

### Q: 自动同步是如何工作的？
A: 自动同步功能会监听书签的变化，当检测到变化时：
<br>1. 等待3秒以收集可能的批量更改
<br>2. 检查距离上次同步是否超过5分钟
<br>3. 比较本地和云端书签，找出新增的书签
<br>4. 将新书签合并到云端数据中
<br>5. 显示同步完成的通知

### Q: 同步失败怎么办？
A: 请尝试以下步骤：
<br>1. 检查网络连接
<br>2. 确认访问令牌是否有效
<br>3. 重新配置访问令牌
<br>4. 重启浏览器后重试
<br>5. 如果问题仍然存在，可以尝试恢复之前的云端备份

### Q: 为什么需要设置加密密钥？
A: 加密密钥用于保护您的书签数据安全：
<br>1. 使用加密密钥对书签数据进行加密后再上传到云端
<br>2. 即使云端数据被意外泄露，没有密钥也无法解密获取书签内容
<br>3. 默认使用系统提供的密钥，但您可以设置自定义密钥以增强安全性
<br>4. 如果设置了自定义密钥，请务必妥善保管，一旦丢失将无法恢复数据

## 技术支持
如果您遇到任何问题或需要帮助，请：
<br>1. 检查本说明书的常见问题解答
<br>2. 查看控制台日志了解详细错误信息
<br>3. 提交 issue 到项目仓库

## 隐私声明
本扩展程序：
- 只会访问浏览器的书签数据
- 只会将数据保存到您的 Gitee 账号中
- 不会收集任何个人信息
- 不会向第三方传输数据

## 更新日志
v1.4
- 增强安全性：
  - 支持自定义加密密钥，提高数据安全性
  - 改进错误处理机制，提供更清晰的错误信息和解决建议
  - 添加密钥相关错误的特殊处理，帮助用户快速识别和解决问题

v1.3
- 增强远程书签管理功能：
  - 支持自定义代码片段描述
  - 支持远程分支管理

v1.2
- 增强远程书签管理功能：
  - 添加书签搜索和筛选功能
  - 支持分页显示书签列表
  - 添加批量删除书签功能
  - 添加手动刷新书签列表功能

v1.1
- 添加自动同步功能
- 优化同步逻辑
- 增加浏览器兼容性支持
- 改进用户界面

v1.0
- 初始版本发布
- 支持基本的书签同步功能
- 使用 Gitee 存储服务
- 提供书签管理功能