Paperless-ngx开发环境极速配置：从零到调试的全链路实践
【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx
Paperless-ngx是一款社区支持的超级文档管理系统，能够帮助用户扫描、索引和归档所有文档。本文将为你提供从克隆仓库到前后端调试的完整开发环境配置指南，让你快速上手这个强大的开源项目。
开发环境准备
必要工具安装
开始配置Paperless-ngx开发环境前，需要确保系统中已安装以下工具：
- Git
- Python 3.10+
- Node.js 24+
- pnpm
- uv (Python包管理器)
项目克隆
首先，克隆Paperless-ngx项目仓库到本地：
git clone https://gitcode.com/GitHub_Trending/pa/paperless-ngx cd paperless-ngx后端开发环境配置
后端项目结构
Paperless-ngx的后端是一个基于Django的应用，主要代码位于src/目录下。核心模块包括文档处理、搜索功能和任务队列等。
依赖安装
使用uv安装后端依赖：
# 在项目根目录执行 uv install数据库配置
默认情况下，开发环境使用SQLite数据库，无需额外配置。如果需要使用其他数据库，可以修改配置文件paperless.conf。
启动后端服务
启动Django开发服务器、文档消费者和Celery工作器：
# 进入src目录 cd src # 启动服务 uv run manage.py runserver & \ uv run manage.py document_consumer & \ uv run celery --app paperless worker -l DEBUG服务启动后，后端API将在http://localhost:8000/api/可用。
图：Paperless-ngx开发环境仪表板界面
前端开发环境配置
前端项目结构
前端使用AngularJS构建，代码位于src-ui/目录。该目录包含了所有前端组件、服务和资源文件。
依赖安装
使用pnpm安装前端依赖：
# 返回项目根目录 cd .. # 进入前端目录 cd src-ui # 安装依赖 pnpm install安装Angular CLI
pnpm install -g @angular/cli启动前端开发服务器
pnpm ng serve前端开发服务器默认在http://localhost:4200/运行，并自动连接到本地后端API。
开发工作流
了解Paperless-ngx的推荐工作流有助于更高效地进行开发：
图：Paperless-ngx文档处理推荐工作流
主要开发步骤：
- 编写代码（前端或后端）
- 运行测试
- 提交更改
- 构建并验证
测试与调试
后端测试
在src/目录下运行pytest进行后端测试：
cd src uv run pytest前端测试
在src-ui/目录下运行单元测试和端到端测试：
cd src-ui pnpm ng test pnpm playwright test文档管理功能调试
开发过程中，可以通过前端界面测试文档管理功能，如文档列表、筛选和搜索等：
图：Paperless-ngx文档列表界面
构建生产版本
前端构建
cd src-ui pnpm ng build --configuration production构建后的前端文件将被放置在Django可以提供的静态文件目录中。
后端打包
使用uv可以轻松创建生产环境的依赖包：
cd src uv export requirements.txt --prod常见问题解决
端口冲突
如果8000或4200端口被占用，可以修改启动命令指定其他端口：
# 后端 uv run manage.py runserver 8001 # 前端 pnpm ng serve --port 4201依赖问题
如果遇到依赖冲突，可以尝试更新uv和pnpm：
uv self-update pnpm install -g pnpm开发资源
- 官方开发文档：docs/development.md
- 后端源代码：src/
- 前端源代码：src-ui/
- 测试样例：src/documents/tests/samples/
通过以上步骤，你已经成功配置了Paperless-ngx的完整开发环境。现在可以开始探索这个强大的文档管理系统的内部工作原理，或者为项目贡献自己的代码了！
【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
