# 云收藏

**Repository Path**: own-item/cloud-marks

## Basic Information

- **Project Name**: 云收藏
- **Description**:  CloudMarks 是一个轻量的自托管书签同步工具。一个浏览器扩展 + 一个 Go 后端，让
  ▎ Chrome、Edge、Firefox 的收藏夹实时保持一致——右键快速收藏、分类管理、地址栏
  ▎ 搜索、增量同步、离线缓存，日常该有的都有。后端用 Go 
  ▎ 标准库零框架实现，部署简单，书签数据完全由你掌控。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CloudMarks

跨浏览器云端书签同步工具。浏览器扩展 + Go 后端服务，解决 Chrome、Edge、Firefox 等不同浏览器之间书签无法同步的问题。

## 功能

- 一键收藏当前页面，支持右键菜单快速收藏
- 分类管理，书签按分类归类
- 云端同步，多浏览器实时一致
- 地址栏快捷搜索（输入 `cm 关键词`）
- 导入/导出 JSON，支持导入浏览器书签 HTML 文件
- 离线可用，本地缓存书签数据
- Token 自动刷新，7 天内免重新登录
- 连接状态指示灯，实时显示服务器状态

## 技术栈

| 组件 | 选型 |
|------|------|
| 浏览器扩展 | Manifest V3，原生 HTML/CSS/JS |
| 后端 | Go 标准库，零框架依赖 |
| 数据库 | PostgreSQL |
| 认证 | JWT（access token 15min + refresh token 7d） |
| 密码 | bcrypt 哈希 |

## 项目结构

```
cloud-marks/
├── extension/          # 浏览器扩展
│   ├── manifest.json
│   ├── config.js       # API 地址配置（改这一个文件即可）
│   ├── popup/          # 弹出窗口 UI
│   ├── background/     # Service Worker
│   └── icons/
├── server/             # Go 后端服务
│   ├── cmd/server/     # 入口
│   ├── internal/
│   │   ├── config/     # 配置
│   │   ├── handler/    # HTTP 处理器
│   │   ├── middleware/ # JWT 鉴权
│   │   ├── model/      # 数据模型
│   │   └── store/      # 数据库操作
│   └── .env.example
├── build-server.sh     # 交叉编译脚本
└── docs/               # 文档
```

## 快速开始

### 1. 部署后端

```bash
git clone git@gitee.com:own-item/cloud-marks.git
cd cloud-marks/server

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入数据库连接串和 JWT 密钥

# 本地运行
go mod tidy
go run cmd/server/main.go

# 或交叉编译部署到 Linux 服务器
cd .. && bash build-server.sh
```

### 2. PostgreSQL 准备

```bash
sudo -u postgres psql -c "CREATE USER cloud_marks WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "CREATE DATABASE cloud_marks OWNER cloud_marks;"
sudo -u postgres psql -d cloud_marks -c "CREATE EXTENSION IF NOT EXISTS pgcrypto;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE cloud_marks TO cloud_marks;"
```

数据库表会在服务首次启动时自动创建。

### 3. 配置 .env

```env
PORT=8080
DATABASE_URL=postgres://cloud_marks:your_password@localhost:5432/cloud_marks?sslmode=disable
JWT_SECRET=your-random-secret-string
```

### 4. 加载扩展

1. 打开 `chrome://extensions/`
2. 开启「开发者模式」
3. 点击「加载已解压的扩展程序」，选择 `extension/` 目录
4. 编辑 `extension/config.js`，把 `API_BASE` 改成你的服务器地址

```js
var API_BASE = 'http://your-server:8080/api/v1';
```

5. 点击扩展图标，注册账号或登录，开始使用

## 使用

- 点击工具栏图标打开书签管理弹窗
- 右键页面 ->「收藏到 CloudMarks」快速收藏
- 地址栏输入 `cm` + 空格 + 关键词搜索书签
- Ctrl+K 聚焦搜索框，方向键导航书签列表
- 开启「分类收藏」后右键收藏可选择分类
- 支持导入 Chrome/Edge/Firefox 导出的书签 HTML 文件

## 同步机制

- 添加/编辑/删除书签后自动推送到服务器
- 打开扩展弹窗时自动拉取增量更新
- 每 2 分钟后台轮询同步
- 浏览器启动时自动同步
- Token 过期后自动用 refresh_token 刷新，7 天内免登录

## API

| 方法 | 路径 | 说明 | 鉴权 |
|------|------|------|------|
| POST | /api/v1/auth/register | 注册 | 否 |
| POST | /api/v1/auth/login | 登录 | 否 |
| POST | /api/v1/auth/refresh | 刷新 token | 否 |
| GET | /api/v1/bookmarks | 获取书签列表 | 是 |
| POST | /api/v1/bookmarks | 添加书签 | 是 |
| PUT | /api/v1/bookmarks/:id | 更新书签 | 是 |
| DELETE | /api/v1/bookmarks/:id | 删除书签 | 是 |
| GET | /api/v1/folders | 获取分类列表 | 是 |
| POST | /api/v1/folders | 创建分类 | 是 |
| DELETE | /api/v1/folders/:id | 删除分类 | 是 |
| GET | /api/v1/sync/pull | 拉取增量更新 | 是 |
| POST | /api/v1/sync/push | 推送本地变更 | 是 |

## License

MIT