Stirling-PDF

基本信息

项目	内容
GitHub	https://github.com/Stirling-Tools/Stirling-PDF
Stars	79,420 ⭐ (#1 PDF Application on GitHub)
描述	随时随地编辑PDF的开源PDF编辑平台
技术栈	Java/Spring Boot + Python AI Engine + React
许可证	Open-core

核心功能

50+ PDF工具

• 编辑: 合并、分割、旋转、裁剪
• 安全: 签名、编辑、密码保护
• 转换: PDF与Word/Excel/图片互转
• OCR: 文字识别
• 压缩: 优化PDF大小
• 自动化: 无代码工作流 + REST API

部署方式

• 桌面客户端: Tauri跨平台桌面应用
• 浏览器UI: React SPA
• Docker: docker run -p 8080:8080 docker.stirlingpdf.com/stirlingtools/stirling-pdf
• Kubernetes: Helm charts支持

企业级功能

• SSO: 单点登录
• 审计: 操作审计日志
• 私有API: REST API for 几乎所有工具
• 40+语言: 国际化支持

技术架构

三组件分离设计

┌─────────────────────────────────────────────────────────────┐
│                     Stirling-PDF                             │
├─────────────────────────────────────────────────────────────┤
│  Frontend (React SPA)                                       │
│  - React + TypeScript + Vite                                │
│  - Mantine UI + TailwindCSS                                │
│  - PDF.js (客户端渲染)                                      │
│  - IndexedDB (本地存储)                                     │
├─────────────────────────────────────────────────────────────┤
│  Backend (Java Spring Boot)                                 │
│  - JDK 25                                                   │
│  - PDFBox (PDF操作)                                         │
│  - LibreOffice (文档转换)                                   │
│  - qpdf (PDF优化)                                           │
│  - Spring Security (可选)                                  │
├─────────────────────────────────────────────────────────────┤
│  Engine (Python FastAPI)                                    │
│  - AI推理服务                                               │
│  - 任务规划和解译                                           │
│  - 不持有持久状态                                           │
└─────────────────────────────────────────────────────────────┘

技术栈

组件	技术
Backend	Spring Boot (JDK 25), PDFBox, LibreOffice, qpdf, Lombok
Frontend	React, TypeScript, Vite, Mantine, TailwindCSS, PDF.js, i18next
Engine	Python FastAPI
Desktop	Tauri (Rust)
Infrastructure	Docker, Gradle

目录结构

Stirling-PDF/
├── app/
│   ├── common/          # 公共代码
│   ├── core/            # 核心PDF操作
│   ├── proprietary/     # 专有功能(企业版)
│   └── saas/            # SaaS功能
├── frontend/            # React前端
├── engine/              # Python AI引擎
├── docker/              # Docker构建
├── gradle/              # Gradle构建
└── Taskfile.yml         # 统一命令

Taskfile 统一命令系统

项目使用 Task 作为统一命令运行器：

快速参考

命令	功能
task install	安装所有依赖
task dev	启动后端+前端
task dev:all	启动后端+前端+引擎
task build	构建所有组件
task test	运行所有测试
task lint	运行所有linter
task format	自动修复格式
task check	完整质量检查
task docker:build	构建Docker镜像
task docker:up	启动Docker compose

Docker变体

• standard: 标准版本
• fat: 包含所有依赖
• ultra-lite: 精简版

项目亮点

1. Taskfile 统一命令

所有构建/开发/测试命令统一管理，跨平台一致体验。

2. 三组件分离架构

• Java后端: 核心业务逻辑
• Python Engine: AI推理
• 前端: 用户界面

3. 企业级功能设计

• SSO单点登录
• 操作审计
• 完整REST API

4. Open-core 商业模式

• 核心开源
• 企业版付费功能

5. 完善的国际化

• 40+语言支持
• 完善的翻译指南

6. 安全设计

• 私有化部署
• 不上传外部服务
• 安全模式开发

开发环境

前置要求

• Task
• Docker
• Git
• Java JDK 25
• Node.js 18+
• Gradle 7.0+
• Python + uv (for engine)

快速开始

# 克隆项目
git clone https://github.com/Stirling-Tools/Stirling-PDF.git
cd Stirling-PDF

# 安装依赖
task install

# 启动开发
task dev

# 运行测试
task test

# 质量检查
task check

添加新工具

目录结构

frontend/editor/src/
├── hooks/tools/[toolName]/
│   ├── use[ToolName]Parameters.ts     # 参数定义
│   └── use[ToolName]Operation.ts      # 操作逻辑
├── components/tools/[toolName]/
│   └── [ToolName]Settings.tsx         # 设置UI
└── tools/
    └── [ToolName].tsx                 # 主组件

核心模式

// 使用 useBaseTool 简化hook管理
export const use[ToolName]Parameters = () => {
  return useBaseParameters({
    defaultParameters,
    endpointName: 'your-endpoint-name',
  });
};

// 使用 useToolOperation 处理操作
export const use[ToolName]Operation = () => {
  return useToolOperation({
    toolType: ToolType.singleFile,
    buildFormData: build[ToolName]FormData,
    endpoint: '/api/v1/category/endpoint-name',
  });
};

相关项目

• Stirling-PDF-chart - Helm charts
• Stirling-PDF-Enterprise-and-Login - 企业版
• stirling_pdf_addon - 插件

---

研究笔记

注意: 由于GitHub下载超时，此仓库仅包含从API获取的文档信息。

研究日期: 2026-05-25 Stars: 79,420 建议: 高价值项目，架构设计值得学习

借鉴价值:

• ⭐⭐⭐⭐⭐ Taskfile统一命令系统
• ⭐⭐⭐⭐⭐ 三组件分离架构
• ⭐⭐⭐⭐⭐ 企业功能(SSO/审计/API)
• ⭐⭐⭐⭐ Python Engine模式
• ⭐⭐⭐⭐ 多语言国际化