Stirling-PDF

---

一、Stirling-PDF

github: https://github.com/Stirling-Tools/Stirling-PDFAPI : https://app.swaggerhub.com/apis-docs/Stirling-Tools/Stirling-PDF/

1、什么是 Stirling-PDF

Stirling-PDF 是一个强大的、本地托管的基于Web的PDF操作工具，使用Docker。

它使您能够对PDF文件执行各种操作，包括拆分、合并、转换、重组、添加图像、旋转、压缩等。

这个本地托管的Web应用程序已经发展到包含一组全面的功能，寻址您的所有PDF需求。

Stirling PDF 不会出于记录保存或跟踪目的 发起任何站外呼叫。

所有文件和PDF要么只存在于客户端，要么仅在任务执行期间 驻留在服务器记忆中，要么仅在任务执行时 临时驻留在文件中。到那时，用户下载的任何文件都将从服务器中删除。

---

---

2、特点

Dark mode 支持。自定义下载选项并行文件处理和下载用于接入外部脚本的API可选的登录和鉴权支持（见这里的文档）数据库备份和导入（见这里的文档）

---

3、PDF功能

---

页面操作

查看和修改PDF —— 通过自定义查看排序和搜索查看多页PDF。

在页面上添加注释、绘制和添加文本和图像等编辑功能。（使用PDF. js与Joxit和Liberation。解放字体）用于合并/拆分/旋转/移动PDF及其页面的全交互式GUI。将多个PDF合并到一个结果文件中。将PDF拆分为指定页码的多个文件或将所有页面提取为单个文件。将PDF页面重新组织成不同的顺序。以90度增量旋转PDF。删除页面。多页布局（将PDF格式化为多页页面）。按设置%缩放页面内容大小。调整对比度。裁剪PDF。自动拆分PDF（使用物理扫描的分页器）。提取页面。将PDF转换为单页。

---

转换操作

将PDF与图像相互转换。将任何通用文件转换为PDF（使用LibreOffice）。将PDF转换为Word/Powerpoint/其他（使用LibreOffice）。将超文本标记语言转换为PDF。PDF的URL。MarkdownPDF。

---

安全和权限

添加和删除密码。更改/设置PDF权限。添加水印。认证/签署PDF。消毒PDF。自动编辑文本。

---

其他操作

添加/生成/写入签名。修复PDF。检测并删除空白页。比较2个PDF并显示文本的差异。将图像添加到PDF。压缩PDF以减小其文件大小（使用OCRMyPDF）。从PDF中提取图像。从扫描中提取图像。添加页码。通过检测PDF表头文本自动重命名文件。PDF上的OCR （使用OCRMyPDF）。PDF/A转换（使用OCRMyPDF）。编辑元信息。展平PDF。获取PDF上的所有信息以查看或导出为JSON。

---

有关任务和每个使用的技术的概述，请查看 Endpoint-groups.md

该应用程序的演示可 在此处 获得。

---

使用的技术

Spring Boot + ThymeleafPDFBoxLibreOffice 用于高级转换OcrMyPdfHTML， CSS，JavaScriptDockerPDF.jsPDF-LIB.js

---

二、如何使用

---

1、本地

请查看 https://github.com/Stirling-Tools/Stirling-PDF/blob/main/LocalRunGuide.md

---

2、Docker/Podman

https://hub.docker.com/r/frooodle/s-pdf

Stirling PDF 有3个不同的版本，完整版 和 超精简版 以及 “Fat”版。

根据您使用的功能类型，您可能需要更小的镜像来节省空间。

要查看不同版本提供的内容，请查看我们的版本映射

对于那些不介意空间最优化的人，只需使用最新的标签。

Full | Ultra-Lite | Fat

请注意，在下面的示例中，您可能需要根据需要更改卷路径，当前示例将它们安装到当前工作目录，例如 <code>./extraConfigs:/configs 到 /opt/stirlingpdf/extraConfigs:/configs

---

3、Docker 运行

docker run -d \

-p 8080:8080 \

-v ./trainingData:/usr/share/tessdata \

-v ./extraConfigs:/configs \

-v ./logs:/logs \

-e DOCKER_ENABLE_SECURITY=false \

-e INSTALL_BOOK_AND_ADVANCED_HTML_OPS=false \

-e LANGS=en_GB \

--name stirling-pdf \

frooodle/s-pdf:latest

Can also add these for customisation but are not required

-v /location/of/customFiles:/customFiles \

---

4、Docker Compose

version: '3.3'

services:

stirling-pdf:

image: frooodle/s-pdf:latest

ports:

- '8080:8080'

volumes:

- ./trainingData:/usr/share/tessdata #Required for extra OCR languages

- ./extraConfigs:/configs

# - ./customFiles:/customFiles/

# - ./logs:/logs/

environment:

- DOCKER_ENABLE_SECURITY=false

- INSTALL_BOOK_AND_ADVANCED_HTML_OPS=false

- LANGS=en_GB

---

注意：Podman 与 DockerCLI 兼容，因此只需将 “docker” 替换为 “podman”。

---

三、启用 OCR/Compression 功能

https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToUseOCR.md

1、我的OCR 曾经工作，现在不工作了！

新docker映像上tessadata位置的路径已更改，请使用/usr/share/tessdata（其他路径仍应用于向后兼容，但可能不会）

2、OCR 如何工作

Stirling-PDF使用OCRmyPDF，而OCRmyPDF又使用 tesseract 进行文本识别。 所有的功劳都归功于他们的出色工作！

3、语言包

TesseractOCR 支持多种语言。您可以在Tesseract GitHub存储库中找到其他语言包：

tessdata_fast：这些语言包更小，加载速度更快，但可能提供较低的识别精度。TessData：这些语言包更大，提供更好的识别精度，但可能需要更长的时间来加载。

根据您的要求，您可以为您的使用案例选择合适的语言包。默认情况下，Stirling-PDF使用tessdata_fasteng，但这可以替换。

---

4、安装语言包

通过选择所需语言的.traineddata文件 下载所需语言包。将.traineddata文件放在Tesseract tessdata目录中：/usr/share/tessdata

5、不要删除现有的ENG. TRAINEDDATA，这是必需的。

6、Docker

如果使用Docker，则需要将 Tesseract tessdata目录作为卷公开，以便使用其他语言包。

7、Docker Compose

修改docker-compose.yml文件以包含以下卷配置：

services:

your_service_name:

image: your_docker_image_name

volumes:

- /location/of/trainingData:/usr/share/tessdata

8、Docker 运行

将以下内容添加到您现有的docker run命令中

-v /location/of/trainingData:/usr/share/tessdata

9、非Docker

如果您不使用Docker，则需要安装OCR 组件，包括Ocrmypdf应用程序。 你可以看到OCRmyPDF安装指南

基于Debian的系统，使用以下命令安装语言：

sudo apt update &&\

# All languages

# sudo apt install -y 'tesseract-ocr-*'

# Find languages:

apt search tesseract-ocr-

# View installed languages:

dpkg-query -W tesseract-ocr- | sed 's/tesseract-ocr-//g'

---

Fedora：

# All languages

# sudo dnf install -y tesseract-langpack-*

# Find languages:

dnf search -C tesseract-langpack-

# View installed languages:

rpm -qa | grep tesseract-langpack | sed 's/tesseract-langpack-//g'

---

四、定制

Stirling PDF 允许轻松自定义应用程序。包括诸如

自定义应用程序名称自定义标语、图标、超文本标记语言、图像CSS等（通过文件覆盖）

---

有两个选项，要么使用生成的设置文件settings.yml， 该文件位于/configs目录中，遵循标准YAML格式

环境变量也受支持，并将覆盖设置文件。例如，在您拥有的 settings.yml 中

security:

enableLogin: 'true'

---

要通过环境变量获得这个，您需要有 SECURITY_ENABLELOGIN

当前设置列表是

security:

enableLogin: false # set to 'true' to enable login

csrfDisabled: true # Set to 'true' to disable CSRF protection (not recommended for production)

loginAttemptCount: 5 # lock user account after 5 tries

loginResetTimeMinutes: 120 # lock account for 2 hours after x attempts

loginMethod: all # 'all' (Login Username/Password and OAuth2[must be enabled and configured]), 'normal'(only Login with Username/Password) or 'oauth2'(only Login with OAuth2)

initialLogin:

username: '' # Initial username for the first login

password: '' # Initial password for the first login

oauth2:

enabled: false # set to 'true' to enable login (Note: enableLogin must also be 'true' for this to work)

client:

keycloak:

issuer: '' # URL of the Keycloak realm's OpenID Connect Discovery endpoint

clientId: '' # Client ID for Keycloak OAuth2

clientSecret: '' # Client Secret for Keycloak OAuth2

scopes: openid, profile, email # Scopes for Keycloak OAuth2

useAsUsername: preferred_username # Field to use as the username for Keycloak OAuth2

google:

clientId: '' # Client ID for Google OAuth2

clientSecret: '' # Client Secret for Google OAuth2

scopes: https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile # Scopes for Google OAuth2

useAsUsername: email # Field to use as the username for Google OAuth2

github:

clientId: '' # Client ID for GitHub OAuth2

clientSecret: '' # Client Secret for GitHub OAuth2

scopes: read:user # Scope for GitHub OAuth2

useAsUsername: login # Field to use as the username for GitHub OAuth2

issuer: '' # set to any provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) end-point

clientId: '' # Client ID from your provider

clientSecret: '' # Client Secret from your provider

autoCreateUser: false # set to 'true' to allow auto-creation of non-existing users

useAsUsername: email # Default is 'email'; custom fields can be used as the username

scopes: openid, profile, email # Specify the scopes for which the application will request permissions

provider: google # Set this to your OAuth provider's name, e.g., 'google' or 'keycloak'

system:

defaultLocale: 'en-US' # Set the default language (e.g. 'de-DE', 'fr-FR', etc)

googlevisibility: false # 'true' to allow Google visibility (via robots.txt), 'false' to disallow

enableAlphaFunctionality: false # Set to enable functionality which might need more testing before it fully goes live (This feature might make no changes)

showUpdate: true # see when a new update is available

showUpdateOnlyAdmin: false # Only admins can see when a new update is available, depending on showUpdate it must be set to 'true'

customHTMLFiles: false # enable to have files placed in /customFiles/templates override the existing template html files

ui:

appName: '' # Application's visible name

homeDescription: '' # Short description or tagline shown on homepage.

appNameNavbar: '' # Name displayed on the navigation bar

endpoints:

toRemove: [] # List endpoints to disable (e.g. ['img-to-pdf', 'remove-pages'])

groupsToRemove: [] # List groups to disable (e.g. ['LibreOffice'])

metrics:

enabled: true # 'true' to enable Info APIs (`/api/*`) endpoints, 'false' to disable

---

还有一个额外的配置文件/configs/custom_settings.yml，熟悉 java 和 spring application.properties 的用户 可以在 Stirling-PDF 现有的基础上输入自己的设置

---

额外注释

端点。目前，端点 ENDPOINTS_TO_REMOVE 和 GROUPS_TO_REMOVE 可以包括 要禁用的端点 和 组的逗号单独列表，例如 ENDPOINTS_TO_REMOVE=img-to-pdf，删除页面将禁用 image-to-pdf 和 删除页面，GROUPS_TO_REMOVE=LibreOffice 将禁用所有使用LibreOffice 的东西。

您可以在 此处 查看所有端点和组的列表customStaticFilePath 通过在 /customFiles/static/ 目录中放置文件 来自定义应用程序徽标等静态文件。

自定义应用程序徽标的一个示例是放置 /customFiles/static/favicon.svg 以覆盖当前SVG。这可用于更改 Stirling-PDF 中的任何 图像/图标/css/字体/js 等

---

仅环境参数

SYSTEM_ROOTURIPATH ie 设置为/pdf-app 来将应用程序的根URI设置为localhost:8080/pdf-appSYSTEM_CONNECTIONTIMEOUTMINUTES 设置自定义连接超时值DOCKER_ENABLE_SECURITY 告诉 docker 下载安全 jar（身份验证登录需要true）INSTALL_BOOK_AND_ADVANCED_HTML_OPS将 calibre 下载到 Stilin-pdf 上，实现 pdf 与 书 和 高级html 的转换。LANGS 定义用于安装文档转换的自定义字体库。

---

五、API

对于那些想要使用 Stirling-PDF 后端API 与 他们自己的自定义脚本链接以编辑PDF的用户，您可以 在这里 查看全部现有API文档，或导航到 你的版本文档的 stirling-pdf 实例的 /swagger-ui/index.html。（或按照API按钮在您的 Stirling-PDF 设置）

---

六、登录鉴权

https://github.com/Stirling-Tools/Stirling-PDF/blob/main/images/login-light.png

---

先决条件

用户必须在 docker中包含 ./configs文件夹，以便在更新期间保留它。Docker用户必须通过在环境变量中将DOCKER_ENABLE_SECURITY设置为true来下载安全 jar 版本。然后要么通过 settings.yml 文件启用登录，要么通过将 SECURITY_ENABLE_LOGIN 设置为 true现在将使用用户名admin 和 密码stirling 生成初始用户。

登录时，您将被迫将密码更改为新密码。

您也可以使用环境变量SECURITY_INITIALLOGIN_USERNAME和SECURITY_INITIALLOGIN_PASSWORD 立即设置自己的（建议在用户创建后删除它们）。

---

完成上述操作后，在重新启动时，一个新的stirling-pdf-DB.mv.db 将显示是否一切正常。

当您登录 Stirling PDF时，您将被重定向到 /login 页面，以使用这些默认凭据登录。登录后，一切功能正常

要访问您的帐户设置，请转到设置齿轮菜单中的帐户设置（导航栏右上角）此帐户设置菜单也是您找到API密钥的地方。

要添加新增用户，请转到帐户设置底部并点击 Admin Settings，在这里您可以添加新增用户。其中提到的不同角色用于速率限制。这是一项工作，将在未来进行中扩展

对于API使用，您必须为该用户提供带有 X-API-Key 和关联API密钥的表头。

---

七、其它

1、支持的语言

Stirling PDF 目前支持33 种语言！

Arabic (العربية) (ar_AR)Basque (Euskara) (eu_ES)Bulgarian (Български) (bg_BG)Catalan (Català) (ca_CA)Croatian (Hrvatski) (hr_HR)Czech (Česky) (cs_CZ)Dutch (Nederlands) (nl_NL)English (English) (en_GB)English (US) (en_US)French (Français) (fr_FR)German (Deutsch) (de_DE)Greek (Ελληνικά) (el_GR)Hindi (हिंदी) (hi_IN)Hungarian (Magyar) (hu_HU)Indonesia (Bahasa Indonesia) (id_ID)Italian (Italiano) (it_IT)Japanese (日本語) (ja_JP)Korean (한국어) (ko_KR)Norwegian (Norsk) (no_NB)Polish (Polski) (pl_PL)Portuguese (Português) (pt_PT)Portuguese Brazilian (Português) (pt_BR)Romanian (Română) (ro_RO)Russian (Русский) (ru_RU)Sebian Latin alphabet (Srpski) (sr_LATN_RS)Simplified Chinese (简体中文) (zh_CN)Slovakian (Slovensky) (sk_SK)Spanish (Español) (es_ES)Swedish (Svenska) (sv_SE)Thai (ไทย) (th_TH)Traditional Chinese (繁體中文) (zh_TW)Turkish (Türkçe) (tr_TR)Ukrainian (Українська) (uk_UA)

---

2、常见问题解答

---

Q1：您计划的功能是什么？

进度条/跟踪完整的自定义逻辑管道，可将多个操作组合在一起。文件夹支持自动扫描以执行操作编辑文本（通过UI而不仅仅是自动方式）添加表单多页面布局（将PDF页面拼接在一起）支持x行y列和自定义页面大小手动或自动填写表格

---

Q2：为什么我的应用程序下载 .htm 文件？

这通常是由您的NGINX配置引起的问题。

NGINX的默认文件上传大小为1MB，您需要在Nginx站点可用文件中添加以下内容。client_max_body_size SIZE;，其中 “SIZE” 50M 代表50MB文件。

---

Q3：为什么我的下载超时了？

NGINX默认有超时值，因此如果您在NGINX后面运行 Stirling-PDF，您可能需要设置超时值，例如添加配置 proxy_read_timeout 3600;

---

3、贡献（创建问题、翻译、修复错误等）

请参阅我们的贡献指南！

---

2024-07-26（五）