Sign inSign up

kokojacket/panbox-sync

By kokojacket

•Updated 18 days ago

PanBox Sync - 自动化文件同步与转码系统

Buildkit cache
Image
0

10K+

kokojacket/panbox-sync repository overview

⁠PanBox Sync - 自动化文件同步系统

围绕 OpenList 的文件同步系统：以下载 → 伪转码（MD5）→ 上传为核心的异步流水线，通过 SSE 推送实时进度，支持并发配置热更新与崩溃恢复。

⁠功能特性

⁠核心功能
  • ✅ OpenList API 集成（登录、文件管理）
  • ✅ 任务管理（创建、编辑、删除、批量操作、复制）
  • ✅ 定时任务（基于间隔配置，支持热更新）
  • ✅ 伪转码（MD5 修改，无需 FFmpeg）
  • ✅ 压缩上传（可选加密 zip，pro 功能）
  • ✅ 文件规则（正则 + 魔法匹配预设 + AI 辅助生成）
  • ✅ AI 辅助能力（文件夹名称混淆、文件规则需求理解与生成）
  • ✅ 并发控制（可配置同时下载/转码/上传数量）
  • ✅ 智能防重复下载
  • ✅ 用户认证系统
  • ✅ SSE 实时进度推送
  • ✅ 崩溃恢复（上传任务断点续传）
  • ✅ 下载目录优先级排序与一键清理（强制清理下载/转码/上传缓存，并清空默认下载目录与挂载下载目录）
⁠任务配置项
  • 任务名称、分类
  • 下载路径（OpenList 源路径）
  • 文件规则：过滤和匹配 + 重命名替换
  • 魔法匹配预设：$TV、$BLACK_WORD、$MOVIE、$ANIME
  • AI 规则需求：可让 AI 理解自然语言需求并生成文件规则
  • 是否启用压缩上传（及可选压缩密码）
  • 上传路径（OpenList 目标路径）
  • 全局扫描间隔（分钟，支持热更新）
  • 任务优先级、状态（启用/禁用）

⁠技术栈

⁠后端
  • 框架: FastAPI (Python 3.9+)
  • 数据库: SQLite + SQLAlchemy（短连接模式）
  • 伪转码: 纯 Python，末尾追加随机字节修改 MD5
  • 压缩: pyzipper（支持加密 zip）
  • 认证: JWT (JSON Web Tokens)
  • HTTP 客户端: httpx（异步）
⁠前端
  • 框架: Vue 3 + TypeScript + Vite
  • UI: Tailwind CSS + shadcn-vue
  • 状态管理: Pinia
  • 路由: Vue Router
  • 实时推送: SSE（EventSource）

⁠快速开始

💡 快速部署：访问 部署仓库⁠ 获取一键安装脚本和 Docker Compose 配置。

⁠前置要求

本地部署：

  • Python 3.9+
  • Node.js 18+

Docker部署（推荐）：

  • Docker 20.10+
  • Docker Compose 2.0+ (可选)
⁠🐳 方式一：Docker 部署（最简单）⭐

使用预构建的 Docker 镜像，无需安装 Python 和 Node.js：

# 使用 Docker Compose（推荐）
docker-compose up -d

# 或直接使用 Docker
docker run -d \
  --name panbox-sync \
  -p 8000:8000 \
  -v $(pwd)/data:/data \
  -e ENVIRONMENT=production \
  -e PANBOX_SYNC_CONTAINER_MODE=true \
  -e PANBOX_SYNC_DATA_DIR=/data \
  -e INTERNAL_OPENLIST_DATA=/data/openlist \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  kokojacket/panbox-sync:latest

访问: http://localhost:8000⁠

详细说明请查看 📘 Docker 完全指南⁠

⁠方式二：一键启动（本地开发）

Windows:

scripts\start.bat

Linux/Mac:

./scripts/start.sh
⁠方式三：手动启动后端

开发调试临时免登录（仅开发环境）： 在 backend/.env 中设置 DEV_DISABLE_AUTH=true，即可跳过登录与激活校验（严禁用于生产）。

快速启动（推荐）：

# 在项目根目录
python scripts/run.py

详细步骤：

# 进入后端目录
cd backend

# 创建虚拟环境（首次运行）
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖（首次运行）
pip install -r requirements.txt

# 初始化数据库（首次运行）
python -m app.utils.init_db

# 返回项目根目录
cd ..

# 启动后端服务
python scripts/run.py

后端将运行在: http://localhost:8000⁠ API文档: http://localhost:8000/docs⁠

⁠前端启动
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

前端将运行在: http://localhost:5173⁠

⁠Docker启动（推荐）
# 构建并启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

⁠配置说明

⁠后端配置 (backend/.env)

参考 backend/env.example，关键配置项：

SECRET_KEY=your-secret-key-change-this-in-production
DEV_DISABLE_AUTH=false  # 仅开发环境可设为 true

# 并发控制
MAX_CONCURRENT_DOWNLOADS=3
MAX_CONCURRENT_UPLOADS=2
# 转码固定串行（无需配置）

# 文件存储
DOWNLOAD_DIR=./data/downloads
UPLOAD_DIR=./data/uploads
LOG_DIR=./data/logs
⁠前端配置 (frontend/.env)
VITE_API_BASE_URL=http://localhost:8000
VITE_APP_TITLE=PanBox Sync

⁠伪转码原理

在文件末尾追加 8-16 个随机字节，MD5 值完全改变，文件功能不受影响，处理速度秒级完成。参考：kokojacket/md5-modifier⁠

⁠故障排除

⁠数据库错误
# 重新初始化数据库
cd backend
python -m app.database reset
⁠端口被占用

修改配置文件中的端口号或终止占用进程：

# 查找占用8000端口的进程
lsof -i :8000  # Linux/macOS
netstat -ano | findstr :8000  # Windows

⁠开发指南

⁠后端开发
# 安装开发依赖
pip install -r requirements-dev.txt

# 运行测试
pytest

# 代码格式化
black app/
isort app/

# 类型检查
mypy app/
⁠前端开发
# 代码格式化
npm run format

# 代码检查
npm run lint

# 类型检查
npm run type-check

# 构建生产版本
npm run build

⁠贡献

欢迎提交Issue和Pull Request！

⁠许可证

本项目基于AGPLv3许可证（与OpenList保持一致）

⁠致谢

Tag summary

Content type

Image

Digest

sha256:efb6cab72…

Size

166.6 MB

Last updated

18 days ago

docker pull kokojacket/panbox-sync