Paperless-ng 项目开发环境搭建与扩展指南-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00368/article/details/148505474

Paperless-ng 项目开发环境搭建与扩展指南

前言

Paperless-ng 是一个开源的文档管理系统，旨在帮助用户实现无纸化办公。本文将详细介绍如何搭建 Paperless-ng 的开发环境，包括前后端开发配置、本地化支持以及如何扩展系统功能。

开发环境搭建

准备工作

在开始开发前，需要完成以下准备工作：

克隆项目源代码
创建必要的目录结构：
```
mkdir -p consume media
```
安装 Node.js 和 Angular CLI：
```
npm install -g @angular/cli
```

后端环境配置

安装 Python 依赖：
```
cd src/
pipenv install --dev
```
数据库和 Redis 配置：
- 可以选择安装本地 Redis 服务
- 或者使用 Docker 运行 Redis 容器：
```
docker run -d -p 6379:6379 --restart unless-stopped redis:latest
```

初始化数据库：

python3 manage.py migrate
python3 manage.py createsuperuser

启动开发服务：

python3 manage.py runserver & python3 manage.py document_consumer & python3 manage.py qcluster

前端环境配置

安装前端依赖：
```
cd src-ui/
npm install
```
启动开发服务器：
```
ng serve
```
开发服务器默认运行在 http://localhost:4200
生产环境构建：
```
ng build --prod
```

开发工作流程

后端开发

后端基于 Django 框架开发，建议开发流程：

使用 IDE（如 PyCharm）配置运行配置：
- python3 manage.py runserver
- python3 manage.py qcluster
- python3 manage.py document_consumer
代码质量检查：
- 运行测试：pytest
- 代码风格检查：pycodestyle

前端开发

前端基于 Angular 框架开发：

开发时使用 ng serve 启动实时重载的开发服务器
确保后端服务已启动并提供 API
需要先登录后端以获取有效会话

本地化支持

Paperless-ng 支持多语言，前后端需要分别处理本地化。

前端本地化

源语言文件：src-ui/messages.xlf
翻译文件存放位置：src-ui/src/locale/
提取新字符串：
```
ng xi18n --ivy
```

添加新语言需要：

修改 angular.json 文件
更新 settings.service.ts 中的语言选项
在 app.module.ts 中注册本地化数据

后端本地化

源语言文件：src/locale/en_US/LC_MESSAGES/django.po

提取新字符串：

python3 manage.py makemessages -l en_US

编译翻译文件：
```
python3 manage.py compilemessages
```

添加新语言需要更新 settings.py 中的 LANGUAGES 列表。

扩展 Paperless-ng

虽然 Paperless-ng 没有插件系统，但可以通过以下方式扩展功能。

自定义文档解析器

可以创建自定义解析器来处理新的文件类型：

继承 documents.parsers.DocumentParser 类
实现 parse() 和 get_thumbnail() 方法
可选实现 get_date() 方法

示例解析器结构：

class MyCustomParser(DocumentParser):
    def parse(self, document_path, mime_type):
        self.text = "提取的文本内容"
        self.archive_path = "生成的PDF路径"
        self.date = "提取的日期"

    def get_thumbnail(self, document_path, mime_type):
        return "缩略图路径"

注册解析器：

def myparser_consumer_declaration(sender, **kwargs):
    return {
        "parser": MyCustomParser,
        "weight": 0,
        "mime_types": {
            "application/pdf": ".pdf",
            "image/jpeg": ".jpg",
        }
    }