docs: 添加 README、Release 模板、docker-compose 编排、构建发布脚本
This commit is contained in:
245
README.md
Normal file
245
README.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 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
|
||||
|
||||
私有项目 — 保留所有权利。
|
||||
Reference in New Issue
Block a user