Paperless-ngx 项目开发环境搭建与贡献指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00818/article/details/148360691

Paperless-ngx 项目开发环境搭建与贡献指南

paperless-ngx A community-supported supercharged version of paperless: scan, index and archive all your physical documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless-ngx

项目概述

Paperless-ngx 是一个开源的文档管理系统，旨在帮助用户实现无纸化办公。它提供了强大的文档扫描、索引和检索功能，让用户能够轻松管理数字化文档。本文将详细介绍如何搭建 Paperless-ngx 的开发环境，以及如何为项目贡献代码。

开发环境准备

代码结构说明

Paperless-ngx 采用前后端分离的架构，代码仓库主要包含以下目录结构：

src/：后端 Django 应用代码
src-ui/：前端 AngularJS 应用代码
docs/：项目文档
scripts/：开发辅助脚本
docker/：Docker 构建相关文件

项目采用分支管理策略：

main：稳定发布分支
dev：下一版本开发分支
feature-X：特定功能开发分支

初始设置步骤

配置文件准备：
- 复制 paperless.conf.example 为 paperless.conf
- 设置 PAPERLESS_DEBUG=true 启用调试模式
创建必要目录：
```
mkdir -p consume media
```
安装依赖：
```
uv sync --group dev
```

初始化数据库：

cd src/
uv run manage.py migrate
uv run manage.py createsuperuser

Redis 服务：可选择本地安装 Redis 或使用 Docker 启动 Redis 容器：
```
docker run -d -p 6379:6379 --restart unless-stopped redis:latest
```

后端开发指南

开发环境配置

后端基于 Django 框架开发，推荐使用 PyCharm 或 VS Code 作为开发工具。需要配置以下启动项：

Django 开发服务器：
```
python3 manage.py runserver
```
文档消费服务：
```
python3 manage.py document_consumer
```
Celery 工作进程：
```
celery --app paperless worker -l DEBUG
```

测试与代码规范

运行测试：
```
pytest
```
测试会生成覆盖率报告，确保测试时使用默认配置
代码格式化使用 ruff 工具，通过 pre-commit 钩子自动执行

包管理

项目使用 uv 进行包管理：

升级所有依赖：
```
uv lock --upgrade
```
添加新依赖：
```
uv add <package>
```

前端开发指南

开发环境配置

前端基于 AngularJS 开发，需要 Node.js 14.15+ 和 pnpm：

安装 Angular CLI：
```
pnpm install -g @angular/cli
```
安装依赖：
```
pnpm install
```
启动开发服务器：
```
ng serve
```
开发服务器默认运行在 http://localhost:4200/，API 请求会代理到 http://localhost:8000/api/

测试与构建

单元测试：
```
ng test
```
E2E 测试：
```
npx playwright test
```
生产构建：
```
ng build --configuration production
```

本地化开发

前端本地化

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

后端本地化

源语言文件：src/locale/en_US/LC_MESSAGES/django.po
编译翻译文件：
```
python3 manage.py compilemessages
```

扩展开发

自定义解析器

可以通过实现 DocumentParser 类来扩展支持的文档类型：

class MyCustomParser(DocumentParser):
    def parse(self, document_path, mime_type):
        self.text = "extracted content"
        self.archive_path = "/path/to/archived.pdf"
        self.date = datetime.now()
        
    def get_thumbnail(self, document_path, mime_type):
        return "/path/to/thumbnail.webp"

然后通过信号注册解析器：

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