# CloudSearch · 自托管云盘资源搜索引擎

**CloudSearch** 是一个自托管的网盘资源搜索引擎。支持多网盘（夸克、百度、阿里云盘等）Cookie 接入、关键词搜索、一键转存、多通道消息推送、每日数据汇报。

> 🏷️ 当前版本：**v0.3.32** · 活跃开发中  
> 🔒 私有项目 — [Gitea 镜像](https://gitea.timxx.cn/admin/CloudSearch)

---

## ✨ 主要特性

- 🔍 **多源搜索** — 聚合 PanSou + 内置搜索引擎，毫秒级返回
- ☁️ **多云盘接入** — 支持夸克、百度网盘、阿里云盘、115、UC、迅雷、天翼云、PikPak、123 云盘
- 📦 **一键转存** — 搜索结果直接转存到已连接的网盘
- 📊 **管理面板** — 网盘管理、搜索统计、转存记录、系统配置
- 🔔 **14 通道通知** — 飞书/Lark、Telegram、钉钉、企业微信、Discord、Bark、Server酱、PushPlus、Gotify、ntfy、SMTP 邮件、Qmsg酱、自定义 Webhook
- 📈 **每日汇报** — 定时统计搜索/转存/用户数据，自动推送到通知通道
- 🧹 **自动清理** — Cookie 到期检测、空间自动清理、关键词审核
- 🎬 **TMDB 增强** — 搜索结果自动匹配影视元数据（海报、评分、简介）

---

## 📋 前置要求

| 软件 | 最低版本 | 说明 |
|------|---------|------|
| Docker | 24.0+ | 构建和运行容器 |
| Docker Compose | v2.20+ | 编排多服务 |
| Git | 2.40+ | 克隆仓库 |

---

## 🚀 快速部署（3 步）

### 1. 克隆仓库

```bash
git clone https://gitea.timxx.cn/admin/CloudSearch.git
cd CloudSearch
```

### 2. 配置环境变量

```bash
cp docker-compose.env .env
# 编辑 .env，修改以下必填项：
#   JWT_SECRET        — JWT 签名密钥（生成：openssl rand -hex 32）
#   ADMIN_PASSWORD    — 管理后台登录密码
#   CORS_ORIGIN       — 前端访问域名（如 http://your-domain.com）
#   REDIS_URL         — Redis 连接地址
#   PANSOU_AUTH_TOKEN — PanSou 搜索 Token（可选）
```

<details>
<summary>📋 完整环境变量参考</summary>

| 变量 | 默认值 | 必填 | 说明 |
|------|--------|------|------|
| `PORT` | `9527` | | 服务端口 |
| `NODE_ENV` | `production` | | 运行环境 |
| `TZ` | `Asia/Shanghai` | | 时区 |
| `JWT_SECRET` | — | ✅ | JWT 签名密钥 |
| `ADMIN_USERNAME` | `admin` | | 管理员用户名 |
| `ADMIN_PASSWORD` | — | ✅ | 管理员密码 |
| `CORS_ORIGIN` | — | ✅ | CORS 允许的域名 |
| `COOKIE_ENCRYPTION_KEY` | — | | Cookie 加密密钥（生产环境建议设置） |
| `DB_PATH` | `/data/database.sqlite` | | SQLite 数据库路径 |
| `REDIS_URL` | — | ✅ | Redis 连接（格式 `redis://[:password@]host:port`） |
| `PANSOU_URL` | `http://pansou:80` | | PanSou 搜索服务地址 |
| `PANSOU_AUTH_TOKEN` | — | | PanSou 鉴权 Token |
| `VALIDATION_CONCURRENCY` | `10` | | 网盘并发校验数 |
| `VALIDATION_TIMEOUT` | `5000` | | 单次校验超时(ms) |
| `CACHE_TTL_VALID` | `14400` | | 有效结果缓存(秒) |
| `CACHE_TTL_INVALID` | `3600` | | 无效结果缓存(秒) |
| `LOG_LEVEL` | `info` | | 日志级别（debug/info/warn/error） |
| `UPLOAD_DIR` | `/app/uploads` | | 上传文件目录 |
| `APP_VERSION_FILE` | `/app/VERSION` | | 版本文件路径 |

</details>

### 3. 启动服务

```bash
docker compose up -d
```

访问 `http://localhost:9527` — 管理面板：`http://localhost:9527/admin`

---

## 📦 服务架构

```
┌─────────────────────────────────────────────────────┐
│                   Nginx / OpenResty                  │
│                   (反向代理 + HTTPS)                  │
├─────────────────────────────────────────────────────┤
│  CloudSearch_App (:9527)    CloudSearch_PanSou (:80) │
│  Node.js + Express + TS     第三方搜索聚合服务         │
│  ┌─────────────────────┐                             │
│  │ 前端 (Vue 3 + Vite) │                             │
│  │ 后端 (Express API)  │                             │
│  │ SQLite + Redis      │                             │
│  │ Chromium (Playwright)│                            │
│  └─────────────────────┘                             │
├─────────────────────────────────────────────────────┤
│  Redis (:6379)                                       │
│  缓存 + 会话                                          │
└─────────────────────────────────────────────────────┘
```

| 容器 | 镜像 | 端口 | 说明 |
|------|------|------|------|
| `CloudSearch_App` | `cloudsearch-app:latest` (自构建) | `9527` | 主服务 |
| `CloudSearch_PanSou` | `ghcr.io/fish2018/pansou-web:latest` | `80` (内部) | 搜索聚合 |
| Redis | `redis:7-alpine` | `6379` (内部) | 缓存 |

---

## 🔄 升级指南

### 方案 A：拉取新镜像（推荐生产环境）

```bash
# 拉取最新版本
docker pull gitea.timxx.cn/admin/cloudsearch:v0.3.32

# 更新 .env 中的镜像标签或使用 latest
docker compose up -d app
```

### 方案 B：从源码重新构建

```bash
git pull origin master
./build.sh          # 读取 VERSION 构建新镜像
docker compose up -d app
```

> 升级后验证：`curl -s http://localhost:9527/health | jq .version`

---

## 🛠️ 常用命令

```bash
# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f app          # 主服务实时日志
docker compose logs --tail=100 app  # 最近100行

# 进入容器
docker compose exec app sh

# 重启服务
docker compose restart app

# 健康检查
curl http://localhost:9527/health

# 查看版本
curl -s http://localhost:9527/health | jq .version
```

---

## 📁 目录结构

```
CloudSearch/
├── VERSION                  # 🏷️ 当前版本号（唯一真相来源）
├── build.sh                 # 🔨 构建 Docker 镜像
├── docker-compose.yml       # 🐳 服务编排
├── docker-compose.env       # 📋 环境变量模板
├── .env                     # 🔐 本地环境变量（Git 忽略）
├── source_clean/            # 🧩 主应用
│   ├── Dockerfile           # 多阶段构建（node:20-alpine）
│   ├── package.json         # Node.js 依赖
│   ├── tsconfig.json
│   ├── src/                 # 后端 TypeScript 源码
│   │   ├── main.ts          # 入口
│   │   ├── config/          # 配置管理
│   │   ├── routes/          # API 路由
│   │   ├── cloud/           # 云盘驱动（quark/baidu/aliyun...）
│   │   ├── search/          # 搜索服务
│   │   ├── database/        # SQLite 数据库
│   │   ├── services/        # 业务逻辑
│   │   └── middleware/      # 中间件
│   ├── frontend-src/        # 🎨 Vue 3 前端源码
│   │   ├── src/pages/       # 页面组件
│   │   ├── src/api/         # API 封装
│   │   ├── vite.config.ts
│   │   └── package.json
│   └── frontend/            # 📦 编译后的静态资源
├── icons/                   # 🖼️ 云盘品牌图标
└── uploads/                 # 📤 上传文件
```

---

## 🏗️ 开发指南

### 后端开发

```bash
cd source_clean
npm install
npm run dev           # tsx watch，热重载
```

### 前端开发

```bash
cd source_clean/frontend-src
npm install
npm run dev           # Vite 开发服务器
```

### 构建部署

```bash
# 完整构建流程
./build.sh                        # 构建 Docker 镜像
docker compose up -d app          # 部署

# 仅前端修改（跳过 Docker 重建）
cd source_clean/frontend-src && npm run build
# 将 dist/ 复制到 source_clean/frontend/，重启容器
```

---

## 🔗 相关链接

- 📦 Gitea 镜像：[gitea.timxx.cn/admin/CloudSearch](https://gitea.timxx.cn/admin/CloudSearch)
- 🐳 容器注册表：`gitea.timxx.cn/admin/cloudsearch`
- 📝 版本规则：`X.Y.Z` — patch 每次任务 +0.0.1，minor 每轮测试稳定 +0.1.0

---

## 📄 License

私有项目 — 保留所有权利。