docs: 完善README - 功能描述、架构图、一键部署命令

README.md

@@ -1,32 +1,170 @@
-# CloudSearch — 网盘搜索 + 视频解析一站式平台
+# CloudSearch — 网盘内容搜索与智能管理平台
 
-## 快速部署
+CloudSearch 是一款集**跨网盘搜索引擎、网盘资源管理、存储空间清理、转存自动化**于一体的全栈 Web 应用。支持夸克网盘、百度网盘、阿里云盘等主流云盘，提供统一的管理后台和用户友好的搜索首页。
+
+---
+
+## 功能全景
+
+### 🔍 搜索引擎
+- **多数据源聚合**：集成 PanSou 搜索引擎 + 多个 TG 频道资源，一站式查找网盘资源
+- **多盘直链转存**：支持夸克网盘、百度网盘、阿里云盘、115 网盘等主流平台的转存操作
+- **分享链接复用**：相同原始链接自动复用已有资源，60 秒内重复请求直接返回缓存
+- **Cookie 验证**：自动检测各网盘 Cookie 有效性，过期自动标记
+
+### 📊 管理后台
+- **仪表盘**：实时展示网盘数量、总空间、转存统计、活跃配置等核心指标
+- **网盘配置**：添加/管理各网盘账号（夸克、百度、阿里云、115 等），支持主账号设置、转存启用控制
+- **存储清理**：
+  - 自动清理策略设置（保留天数、回收站清空、空间阈值自动清理）
+  - 白名单目录保护（排除不清理的目录）
+  - 一键清理、一键清空回收站
+  - 空间校准与 Cookie 检测间隔配置
+- **系统配置**：管理员密码修改、Logo 自定义、搜索策略配置
+- **转存日志**：查看所有转存操作记录，支持搜索与详情展开
+
+### 🧹 智能存储管理
+- **存储空间校准**：快速获取网盘实际使用空间（支持夸克 `/member` 接口，单次 API 调用）
+- **空间阈值自动清理**：超出设定使用率阈值时按比例自动删除最旧文件
+- **回收站清空**：一键清空所有已启用驱动的网盘回收站
+
+### 🌐 用户前端（首页 + H5）
+- 响应式搜索界面，支持桌面端与移动端
+- 搜索结果即时展示
+- 推广内容展示
+
+### 🔐 安全特性
+- Cookie 加密存储（AES-256-GCM）
+- JWT 登录认证
+- 暗色/亮色主题切换
+- 非 root 容器运行
+
+---
+
+## 技术架构
+
+```
+┌──────────────────────────────────────────────────┐
+│                   用户浏览器                       │
+│         Vue 3 SPA（Element Plus UI）              │
+└──────────────┬──────────────────┬────────────────┘
+               │  http/9527        │
+┌──────────────▼──────────────────▼────────────────┐
+│              Express.js 后端 API                   │
+│         TypeScript + better-sqlite3               │
+├──────────────────────────────────────────────────┤
+│  📦 网盘驱动                                       │
+│  ┌──────┐ ┌──────┐ ┌────────┐ ┌──────┐           │
+│  │ 夸克  │ │ 百度  │ │ 阿里云  │ │ 115  │  …      │
+│  └──────┘ └──────┘ └────────┘ └──────┘           │
+├──────────────────────────────────────────────────┤
+│  🗃️ 数据层                                         │
+│  SQLite（系统配置 + 转存记录 + Cookie缓存）         │
+│  Redis 缓存（可选自动降级）                        │
+└──────────────┬────────────────────────────────────┘
+               │
+┌──────────────▼────────────────────────────────────┐
+│            PanSou 搜索引擎容器                      │
+│    80+ 数据源（网盘/资源站/TG 频道/磁力）            │
+└───────────────────────────────────────────────────┘
+```
+
+### 组件栈
+| 层 | 技术 |
+|---|---|
+| **前端** | Vue 3 (Composition API) + TypeScript + Element Plus + Vite |
+| **后端** | Node.js + Express + TypeScript + better-sqlite3 |
+| **搜索引擎** | PanSou（独立容器，80+ 数据源插件） |
+| **缓存** | Redis 7（可选，自动降级内存缓存） |
+| **容器化** | Docker + Docker Compose（3 服务：app + pansou + redis） |
+
+---
+
+## 一键部署
+
+### 前置条件
+- 服务器：**Linux x86_64**（推荐 2C4G 以上）
+- Docker Engine 24+ & Docker Compose v2
+
+### 部署命令
 
 ```bash
-# 1. 解压
+# 1. 下载部署包
+wget https://gitea.timxx.cn/admin/CloudSearch/releases/download/v0.1.6/cloudsearch-deploy.tar.gz
+# 或直接从仓库克隆
+# git clone https://gitea.timxx.cn/admin/CloudSearch.git && cd CloudSearch
+
+# 2. 解压 & 进入目录
 tar xzf cloudsearch-deploy.tar.gz
 cd cloudsearch
 
-# 2. 配置环境变量
+# 3. 一键配置 + 启动
 cp .env.example .env
-# 自动生成 JWT Secret
 sed -i "s/change-me-to-a-random-64-char-hex-string/$(openssl rand -hex 32)/" .env
-# 自动生成 Cookie 加密密钥
 sed -i "s/change-me-to-a-random-key/$(openssl rand -hex 32)/" .env
-# ⚠️ 务必手动修改 ADMIN_PASSWORD 和 CORS_ORIGIN
 echo "⚠️  请编辑 .env 文件，修改 ADMIN_PASSWORD 和 CORS_ORIGIN"
-
-# 3. 一键启动
 docker compose up -d
 
-# 4. 访问
+# 4. 检查服务状态
-# 首页: http://服务器IP
+docker compose ps
-# 管理后台: http://服务器IP/admin/login
+# 预期输出：CloudSearch_App、CloudSearch_PanSou 均为 Up
+
+# 5. 访问
+# 搜索页面： http://your-server-ip:9527
+# 管理后台： http://your-server-ip:9527/admin/login
 ```
 
-## 首次使用
+### 环境变量说明
 
-1. 登录管理后台 `/admin/login`（账号: admin，密码: 你在 .env 中设置的）
+| 变量 | 必需 | 说明 |
-2. 在「网盘配置」中添加夸克网盘 Cookie
+|---|---|---|
-3. 在「推广管理」中添加首页推广内容（可选）
+| `ADMIN_USERNAME` | ✅ | 管理员用户名（默认 admin） |
-4. 返回首页即可开始搜索
+| `ADMIN_PASSWORD` | ✅ | **务必修改默认密码** |
+| `JWT_SECRET` | ✅ | 运行 `openssl rand -hex 32` 生成 |
+| `CORS_ORIGIN` | ✅ | 你的站点域名（如 `https://search.example.com`） |
+| `COOKIE_ENCRYPTION_KEY` | ⚠️ 推荐 | Cookie 加密密钥，不设置则重启后旧数据不可解密 |
+| `REDIS_URL` | ❌ 可选 | Redis 连接（不设则自动降级） |
+
+### 首次使用
+
+1. 登录管理后台 `/admin/login`
+2. 在「网盘配置」→「添加配置」中填入网盘 Cookie
+3. 启用对应网盘配置
+4. 返回首页即可搜索并转存资源
+
+---
+
+## 开发环境
+
+```bash
+# 后端
+cd packages/backend
+npm install
+cp .env.example .env  # 编辑数据库路径等
+npm run dev
+
+# 前端（新终端）
+cd packages/frontend
+npm install
+npm run dev
+```
+
+---
+
+## 更新升级
+
+```bash
+cd /opt/CloudSearch
+git pull origin master
+docker compose down
+docker compose build --no-cache app
+docker compose up -d
+```
+
+---
+
+## 许可
+
+本项目基于 Gitea 私有仓库维护，仅供授权用户使用。
+
+> **注意**：本系统仅用于合法用途，使用者需遵守当地法律法规。网盘 Cookie 等凭证由用户自行保管，系统以加密形式存储。