React 19 + Flask PDF 工具箱，支持本机自托管和公开服务器部署。公开站点会通过 HTTPS 上传文件到服务器临时处理，并使用匿名会话隔离后台任务。
- 部署方式透明 — 本机部署时文件留在设备；在线站点会明确提示上传服务器临时处理
- 27 种工具 — 合并、拆分、旋转、水印、加密、OCR、压缩、格式转换...
- 智能压缩 — 多候选竞赛 + 清晰度守门，在体积和质量间自动寻找最优解
- 自动化流水线 — 像搭积木一样组合处理步骤，一键批量执行
- 任务队列 — 异步后台处理，可取消、重试，结果自动过期清理
- AI Agent 友好 — 完整的 AGENTS.md 指引，让 AI 助手理解你的项目
git clone https://github.com/ImyoungF/FantasyCube.git
cd FantasyCube/app
python -m venv .venvWindows：
.venv\Scripts\activate
pip install -r requirements.txt
python server.pymacOS / Linux：
source .venv/bin/activate
pip install -r requirements.txt
python server.py在启动服务的这台电脑上访问：
http://127.0.0.1:8082
127.0.0.1 仅代表当前电脑，其他设备无法通过这个地址访问。公开站点请使用 https://fantasycube.top；如需让局域网设备访问，请按部署与安全配置说明设置服务监听和访问控制，不要直接暴露本机开发端口。
使用 Docker 或把服务监听到非回环地址时，必须设置至少 24 字符的 FANTASYCUBE_API_TOKEN。公开部署还必须设置 FANTASYCUBE_PUBLIC_MODE=1、至少 32 字符的 FANTASYCUBE_SESSION_SECRET 和 HTTPS 安全 Cookie。网页令牌仅保存在当前标签页的 sessionStorage。
管理员后台位于 /admin。首次启动前只在服务器环境设置 FANTASYCUBE_ADMIN_USERNAME 和 FANTASYCUBE_ADMIN_PASSWORD；系统会仅保存密码哈希。管理员会话要求 HTTPS，后台不提供用户任务产物下载。
pip install -r requirements-advanced.txt| 引擎 | 作用 | 安装方式 |
|---|---|---|
| Tesseract OCR | 扫描件文字识别 | apt install tesseract-ocr |
| Ghostscript | 智能压缩 / PDF/A | apt install ghostscript |
| LibreOffice | Office 高保真转 PDF | apt install libreoffice-core |
未安装时自动回退基础模式，不影响核心功能。
graph LR
A[React 19 + Vite] --> B[Flask REST API]
B --> C[PDF 引擎层]
C --> D[pypdf / PyMuPDF]
C --> E[Tesseract OCR]
C --> F[Ghostscript]
C --> G[LibreOffice]
B --> H[任务队列]
H --> I[SQLite 持久化]
H --> J[隔离 Worker 子进程]
前端：React 19 + Vite 8 + TailwindCSS 4 + Zustand 状态管理 后端：Flask + 5 蓝图（25+ REST 端点） 任务引擎：异步 Worker、并发控制、资源隔离、超时保护 存储：SQLite 用户数据目录；后台任务以签名的匿名浏览器会话隔离
| 分类 | 工具 |
|---|---|
| 页面编辑 | 合并 PDF、拆分、旋转、裁剪、删除页面、提取页面 |
| 水印标记 | 添加水印、添加页码 |
| 安全保护 | 加密、解密、涂抹修订、隐私清理 |
| 格式转换 | PDF 转图片/Word/Excel/文本、图片转 PDF、Office 转 PDF、PDF/A 归档 |
| 压缩修复 | 智能压缩（4 种模式）、PDF 修复 |
| 提取分析 | OCR 文字识别、提取图片、PDF 属性查看 |
| 效率工具 | 去空白页 |
FantasyCube 的压缩不是简单的参数调节，而是一个多候选竞赛系统：
原始文件
├── 无损结构优化
├── 300 DPI 候选
├── 240 DPI 候选
├── 200 DPI 候选
└── 积极图片压缩候选
↓ 清晰度守门 ↓
页面数不变？ 尺寸不变？ 文字层保留？
亮度相似度 > 阈值？ 边缘清晰度 > 阈值？
颜色还原度 > 阈值？ 体积确实缩小？
↓ 通过的候选 ↓
选择体积最小 + 质量最优 → 输出
全部未通过 → 回退无损结果或原始文件
四种模式：无损优化 | 智能压缩（推荐） | 均衡压缩 | 强力压缩
POST /api/v1/jobs/{operation} 提交任务
GET /api/v1/jobs 查询历史
GET /api/v1/jobs/{id} 查询进度
POST /api/v1/jobs/{id}/cancel 取消任务
POST /api/v1/jobs/{id}/retry 重试任务
GET /api/v1/jobs/{id}/download 下载结果
DELETE /api/v1/jobs/{id} 删除任务
GET /api/v1/jobs/capabilities 引擎能力检测
POST /api/v1/general/merge-pdfs POST /api/v1/security/add-watermark
POST /api/v1/general/split-pages POST /api/v1/security/add-password
POST /api/v1/general/rotate-pdf POST /api/v1/security/redact
POST /api/v1/convert/pdf/img POST /api/v1/misc/compress-pdf
POST /api/v1/convert/img/pdf POST /api/v1/misc/add-page-numbers
... 共 25 个端点
本机服务的 API 文档访问 http://127.0.0.1:8082/api/docs；公开站点的 API 文档访问 https://fantasycube.top/api/docs。
| 变量 | 默认值 | 说明 |
|---|---|---|
FANTASYCUBE_HOST |
127.0.0.1 |
监听地址 |
FANTASYCUBE_DATA_DIR |
用户数据目录 | SQLite 与持久任务数据的根目录 |
FANTASYCUBE_JOB_ROOT |
<data-dir>/jobs |
任务输入、输出和日志目录（0700） |
FANTASYCUBE_MAX_CONCURRENT_JOBS |
2 |
并行任务数 |
FANTASYCUBE_JOB_TIMEOUT |
1800 |
任务超时（秒） |
FANTASYCUBE_JOB_MEMORY_MB |
2048 |
Worker 内存上限 |
FANTASYCUBE_JOB_TTL_HOURS |
24 |
结果保留时长 |
FANTASYCUBE_JOB_HISTORY_LIMIT |
200 |
保留的终态任务记录上限 |
FANTASYCUBE_JOB_RECORD_RETENTION_DAYS |
7 |
终态任务记录最长保留天数 |
FANTASYCUBE_MAX_PENDING_JOBS |
100 |
排队及运行任务总上限 |
FANTASYCUBE_MAX_PENDING_JOBS_PER_OWNER |
10 |
单匿名会话待处理任务上限 |
FANTASYCUBE_JOB_STORAGE_LIMIT_MB |
4096 |
任务目录总容量上限 |
FANTASYCUBE_JOB_STORAGE_LIMIT_MB_PER_OWNER |
1024 |
单匿名会话任务存储上限 |
FANTASYCUBE_JOB_MIN_FREE_MB |
512 |
接受新任务所需最小磁盘余量 |
FANTASYCUBE_API_TOKEN |
空 | 非回环监听时必须设置，至少 24 字符 |
FANTASYCUBE_ADMIN_TOKEN |
空 | 管理员专用令牌，不得与普通 API Token 相同 |
FANTASYCUBE_ADMIN_USERNAME |
空 | 首次启动时创建的管理员账号，仅在服务器环境设置 |
FANTASYCUBE_ADMIN_PASSWORD |
空 | 首次启动时创建的管理员密码，仅保存哈希，至少 12 位 |
公网部署脚本不会把管理员 Token 注入普通浏览器请求。管理员操作必须携带 FANTASYCUBE_ADMIN_TOKEN，应通过服务器本机、SSH 隧道或单独受保护的管理入口执行；未配置该令牌时，删除留言等管理员操作会被禁用。
| FANTASYCUBE_PUBLIC_MODE | 0 | 公开服务器模式；启用后强制要求会话签名密钥 |
| FANTASYCUBE_SESSION_SECRET | 空 | 签名匿名会话 Cookie，公开模式至少 32 字符 |
| FANTASYCUBE_SESSION_COOKIE_SECURE | 0 | HTTPS 公网部署必须设为 1 |
cd pdf-toolbox-pro
npm ci
npm run dev # 开发模式 → localhost:5173
npm run build # 生产构建 → dist/构建后使用原子同步脚本复制到 Flask 静态目录：
cd ..
python scripts/build_frontend.py首次安装前端依赖时使用 python scripts/build_frontend.py --install。
pip install -r app/requirements-dev.txt
python scripts/verify_release.py --install-frontend该命令会执行 Python 编译、前端 lint/build、51 项 pytest、Ruff、静态文件同步、两次确定性打包和 ZIP 完整性校验。可在安装 Docker 后追加 --docker。
tests/
├── test_core_regressions.py # 核心功能回归
├── test_background_jobs.py # 任务系统端到端
├── test_quality_compression.py # 压缩质量守卫
├── test_second_release.py # Office/PDFA/工作流
├── test_core_fixes.py # 独立 smoke test
└── conftest.py # 共享 fixtures
FantasyCube/
├── app/ # Flask 后端
│ ├── server.py # 入口
│ ├── utils.py # PDF 处理核心
│ ├── compression_engine.py # 智能压缩
│ ├── job_store.py # 任务持久化
│ ├── job_worker.py # 隔离 Worker
│ ├── job_operations.py # 任务执行逻辑
│ ├── blueprints/ # API 蓝图（6 模块）
│ ├── static/ # 前端构建产物
│ └── requirements.txt
├── pdf-toolbox-pro/ # React 前端
│ ├── src/
│ │ ├── components/ # UI 组件
│ │ ├── data/ # 工具定义 + 图标
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── stores/ # Zustand 状态
│ │ └── utils/
│ └── package.json
├── tests/ # pytest 测试
├── integration/ # 补丁 + 报告
├── deploy/ # 部署脚本
├── AGENTS.md # AI Agent 指南
├── CONTRIBUTING.md # 贡献指南
├── CHANGELOG.md # 更新日志
├── SECURITY.md # 安全策略
├── LICENSE # MIT
└── README.md
本项目包含完整的 AGENTS.md，告诉 AI 编程助手如何：
- 理解代码结构和架构
- 添加新的 PDF 工具
- 遵循编码规范和测试流程
- 构建和部署
如果你使用 Codex、Claude Code、Cursor 或其他 AI 编程工具，直接把项目交给它即可。
欢迎贡献！请先阅读 AGENTS.md 和 CONTRIBUTING.md。
- Fork 本项目
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m "feat: Add some amazing feature") - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
子进程隔离和资源限制属于应用级保护，不适合处理来自完全不可信来源的恶意 PDF。生产部署建议配合容器或虚拟机沙箱。详见 SECURITY.md。
MIT © 2026 FantasyCube