# onepiece

**Repository Path**: StarsJsm/onepiece

## Basic Information

- **Project Name**: onepiece
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: 001-content-collector
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Collect-Now (OnePiece)

> 多平台内容收藏管理工具 — 一键收藏，智能整理，版权溯源

Collect-Now 是一个多平台内容收藏管理工具的后端服务。用户提交网页链接后，系统自动抓取并解析内容，通过 AI 生成摘要、分类和标签，同时保留完整的版权元信息，实现智能化的内容收藏与管理。

## 功能特性

- 🔗 **一键收藏** — 提交链接，自动抓取解析，异步处理不阻塞
- 🤖 **AI 智能处理** — 自动生成摘要、分类和标签（支持 OpenAI 兼容 API）
- 🌐 **多平台支持** — 知乎、微信公众号、小红书、B站、抖音等
- 📝 **版权溯源** — 自动提取作者、原文链接、发布时间等元信息
- 🔒 **安全可靠** — JWT 认证、SSRF 防护、账户锁定、CORS 控制
- 💾 **双存储模式** — 支持云端存储和本地存储，配额管理
- 📊 **全文检索** — 支持 PostgreSQL 全文检索和 SQLite LIKE 回退
- 🏷️ **分类体系** — 系统预设分类 + 用户自定义分类，支持层级
- 📡 **链路追踪** — TraceID 贯穿请求全生命周期
- 🐳 **容器化部署** — Docker Compose 一键部署（Nginx + Backend + PostgreSQL）

## 技术栈

| 层级 | 技术 |
|------|------|
| Web 框架 | FastAPI |
| ASGI 服务器 | Uvicorn |
| ORM | SQLAlchemy 2.0 (async) |
| 数据库 | PostgreSQL / SQLite |
| 数据校验 | Pydantic v2 + pydantic-settings |
| HTTP 客户端 | httpx |
| HTML 解析 | BeautifulSoup4 + lxml |
| 认证 | JWT (python-jose) + bcrypt |
| 任务队列 | arq + Redis（预留） |
| 容器化 | Docker + Docker Compose + Nginx |

## 项目结构

```
onepiece/
├── backend/                    # 后端 FastAPI 应用
│   ├── Dockerfile              # 多阶段构建
│   ├── pyproject.toml          # 项目元数据与依赖
│   └── app/
│       ├── main.py             # 应用入口
│       ├── config.py           # 配置管理
│       ├── database.py         # 数据库连接
│       ├── api/                # API 路由层（薄路由）
│       │   ├── auth.py         #   认证（注册/登录/刷新）
│       │   ├── collections.py  #   收藏 CRUD
│       │   ├── links.py        #   链接检测/短链展开
│       │   ├── platforms.py    #   平台列表
│       │   └── tasks.py        #   任务状态查询
│       ├── models/             # SQLAlchemy 数据模型
│       │   ├── user.py         #   用户模型
│       │   ├── collection.py   #   收藏内容模型
│       │   ├── platform.py     #   平台配置模型
│       │   ├── attribution.py  #   版权元信息模型
│       │   ├── category.py     #   分类/标签模型
│       │   └── task_record.py  #   异步任务记录模型
│       ├── schemas/            # Pydantic 请求/响应模型
│       ├── services/           # 业务逻辑层
│       │   ├── collection.py   #   收藏业务编排
│       │   ├── task.py         #   任务生命周期管理
│       │   ├── ai/             #   AI 处理（摘要/分类/标签）
│       │   ├── crawler/        #   抓取层（浏览器模拟/知乎专用）
│       │   └── parser/         #   解析层（通用HTML/知乎JSON/注册表）
│       ├── middleware/         # 中间件
│       │   └── trace_id.py     #   TraceID 中间件
│       ├── utils/              # 工具函数
│       │   ├── logging.py      #   日志（ContextLogger）
│       │   ├── security.py     #   JWT + 密码哈希
│       │   └── validators.py   #   URL 校验/SSRF 防护
│       └── static/             # Swagger UI / ReDoc 离线资源
├── docker/                     # Docker 部署配置
│   ├── docker-compose.yml      #   编排文件
│   ├── nginx.conf              #   Nginx 反向代理配置
│   └── init-db.sql             #   数据库初始化脚本
├── .env.example                # 环境变量模板
└── .python-version             # Python 版本 (3.11)
```

## 快速开始

### 环境要求

- Python >= 3.11
- PostgreSQL 16+（生产环境）或 SQLite（开发环境）
- Redis（可选，用于异步任务队列）

### 安装

```bash
# 克隆项目
git clone <repository-url>
cd onepiece

# 使用 uv 安装（推荐）
cd backend
uv sync

# 或使用 pip 安装
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows
pip install -e ".[dev]"
```

### 配置

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填写必要配置
# 必须修改：SECRET_KEY（生产环境）
# 可选修改：DATABASE_URL、OPENAI_API_KEY 等
```

### 运行

```bash
# 开发模式（使用 SQLite，无需 PostgreSQL）
cd backend
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 访问 API 文档
# Swagger UI: http://localhost:8000/api/docs
# ReDoc:      http://localhost:8000/api/redoc
```

## 配置说明

所有配置通过环境变量或 `.env` 文件加载，配置项说明如下：

### 数据库

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DATABASE_URL` | `postgresql+asyncpg://...` | PostgreSQL 连接 URL |
| | `sqlite+aiosqlite:///./data/local.db` | SQLite（开发环境） |

### 认证

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SECRET_KEY` | — | JWT 密钥，**生产环境必须修改**（至少 32 字符） |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `1440` | Access Token 有效期（分钟） |
| `REFRESH_TOKEN_EXPIRE_DAYS` | `7` | Refresh Token 有效期（天） |

### AI 服务（可选）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `OPENAI_API_KEY` | — | OpenAI API Key |
| `OPENAI_MODEL` | `gpt-4o-mini` | 使用的模型名称 |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | API Base URL（支持兼容接口） |

### 存储

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DEFAULT_STORAGE_LIMIT` | `1073741824` | 云端存储上限（字节，默认 1GB） |
| `LOCAL_STORAGE_PATH` | `~/.collect-now/data` | 本地存储路径 |

### 应用

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_ENV` | `development` | 运行环境：`development` / `staging` / `production` |
| `DEBUG` | `true` | 调试模式（生产环境必须为 `false`） |
| `LOG_LEVEL` | `INFO` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` |

### 性能

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `FETCH_TIMEOUT` | `30` | 抓取超时时间（秒） |
| `MAX_RETRIES` | `3` | 最大重试次数 |
| `MAX_CONNECTIONS` | `100` | 并发连接数 |

### 安全

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CORS_ORIGINS` | `http://localhost:3000,http://localhost:5173` | CORS 允许的源（逗号分隔） |
| `MAX_LOGIN_ATTEMPTS` | `5` | 最大登录尝试次数 |
| `LOCKOUT_DURATION_MINUTES` | `15` | 账户锁定时长（分钟） |

### 邮件（可选，用于密码找回）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SMTP_HOST` | — | SMTP 服务器地址 |
| `SMTP_PORT` | `587` | SMTP 端口 |
| `SMTP_USER` | — | SMTP 用户名 |
| `SMTP_PASSWORD` | — | SMTP 密码 |

## API 文档

启动服务后，访问以下地址查看交互式 API 文档：

- **Swagger UI**: `http://localhost:8000/api/docs`
- **ReDoc**: `http://localhost:8000/api/redoc`

### API 路由概览

| 方法 | 路径 | 说明 | 认证 |
|------|------|------|------|
| `POST` | `/api/v1/auth/register` | 用户注册 | 否 |
| `POST` | `/api/v1/auth/login` | 用户登录 | 否 |
| `POST` | `/api/v1/auth/refresh` | 刷新令牌 | 否 |
| `POST` | `/api/v1/collections` | 创建收藏（异步） | 是 |
| `GET` | `/api/v1/collections` | 获取收藏列表 | 是 |
| `GET` | `/api/v1/collections/{id}` | 获取收藏详情 | 是 |
| `PATCH` | `/api/v1/collections/{id}` | 更新收藏信息 | 是 |
| `DELETE` | `/api/v1/collections/{id}` | 删除收藏（软删除） | 是 |
| `GET` | `/api/v1/collections/tasks/{id}` | 查询收藏任务状态 | 是 |
| `POST` | `/api/v1/links/detect` | 链接检测 | 否 |
| `POST` | `/api/v1/links/expand` | 短链展开 | 否 |
| `GET` | `/api/v1/platforms` | 获取支持的平台列表 | 否 |
| `GET` | `/api/v1/tasks/{id}` | 查询任务状态 | 是 |
| `GET` | `/api/health` | 健康检查 | 否 |

### 核心流程：创建收藏

```
POST /api/v1/collections
Body: { "url": "https://zhuanlan.zhihu.com/p/123456", "storage_type": "cloud" }
Response: { "data": { "task_id": "uuid", "status": "pending", "progress": 0 } }
```

收藏创建为异步处理，返回任务 ID 后在后台执行完整链路：

1. URL 校验与清洗
2. 平台匹配（基于 URL 正则）
3. 内容抓取（Crawler）
4. 内容解析（Parser）
5. 持久化（Collection + Attribution）
6. AI 处理（摘要 / 分类 / 标签）
7. 更新存储配额
8. 任务完成

通过 `GET /api/v1/collections/tasks/{task_id}` 轮询任务进度。

## Docker 部署

### 使用 Docker Compose 一键部署

```bash
cd docker

# 设置必要环境变量
export SECRET_KEY="your-secret-key-at-least-32-characters-long"

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f backend
```

### 服务架构

```
                    ┌─────────┐
                    │  Nginx  │ :80
                    │ (代理)  │
                    └────┬────┘
                    ┌────┴────┐
              ┌─────┴──┐  ┌──┴──────┐
              │Backend │  │Frontend │
              │ :8000  │  │  :80    │
              └────┬───┘  └─────────┘
              ┌────┴────┐
              │Postgres │
              │  :5432  │
              └─────────┘
```

### 服务说明

| 服务 | 镜像 | 端口 | 说明 |
|------|------|------|------|
| `nginx` | `nginx:alpine` | 80:80 | 反向代理，安全头部 |
| `backend` | 自构建 | 8000 | FastAPI 后端 |
| `frontend` | 自构建 | 80 | 前端（待实现） |
| `postgres` | `postgres:16-alpine` | 5432 | PostgreSQL 数据库 |

### 生产环境注意事项

- **必须**设置非默认的 `SECRET_KEY`
- **必须**将 `APP_ENV` 设置为 `production`
- **必须**将 `DEBUG` 设置为 `false`
- 建议配置 HTTPS（Nginx 层面）
- 建议修改 PostgreSQL 默认密码

## 支持平台

### 专用支持（自定义 Crawler + Parser）

| 平台 | 抓取方式 | 说明 |
|------|----------|------|
| 知乎专栏 | API 抓取 | 通过知乎专栏 API 获取 JSON 数据 |

### 通用支持（BrowserCrawler + GenericParser）

| 平台 | 域名 |
|------|------|
| 知乎 | `zhuanlan.zhihu.com`, `www.zhihu.com` |
| 微信公众号 | `mp.weixin.qq.com` |
| 小红书 | `www.xiaohongshu.com`, `xhslink.com` |
| B站 | `www.bilibili.com`, `b23.tv` |
| 抖音 | `www.douyin.com`, `v.douyin.com` |

### 扩展新平台

通过解析器注册表（Registry）扩展新平台：

1. 创建自定义 Crawler（继承 `BaseCrawler`）
2. 创建自定义 Parser（继承 `BaseParser`）
3. 在 Registry 中注册：`register_crawler("platform_name", MyCrawler)`
4. 在数据库的 `platforms` 表中添加平台记录（含 URL 匹配正则和 `parser_type`）

## 开发指南

### 代码风格

项目使用以下工具保证代码质量：

```bash
# 代码格式化
black app/ --line-length 100

# Lint 检查
ruff check app/

# 类型检查
mypy app/
```

### 测试

```bash
# 运行测试
cd backend
uv run pytest

# 带覆盖率
uv run pytest --cov=app --cov-report=html
```

### 项目架构

项目采用**薄路由 + 业务编排**的分层架构：

- **API 层** (`api/`)：参数校验、权限检查、调用 service、返回响应
- **Service 层** (`services/`)：业务逻辑编排，不依赖 FastAPI
- **Model 层** (`models/`)：SQLAlchemy 数据模型，定义表结构
- **Schema 层** (`schemas/`)：Pydantic 模型，定义请求/响应格式
- **Crawler 层** (`services/crawler/`)：只负责 HTTP 请求，返回原始响应
- **Parser 层** (`services/parser/`)：只负责内容解析，不碰网络

## 安全特性

- **JWT 认证** — Access Token + Refresh Token 旋转，防止重放攻击
- **密码安全** — bcrypt 哈希存储
- **账户保护** — 连续登录失败自动锁定（默认 5 次 / 15 分钟）
- **SSRF 防护** — 域名白名单，拒绝未授权的 URL 请求
- **URL 清洗** — 输入校验与规范化
- **CORS 控制** — 可配置允许的源
- **生产安全** — 强制非默认 SECRET_KEY，CORS 通配符互斥检查
- **链路追踪** — 每个请求携带 TraceID（X-Request-ID）

## License

MIT