paperless-ngx

### Paperless-ngx 使用指南和技术文档 #### 一、概述 Paperless-ngx 是一款强大的开源文档管理系统，专注于将纸质文档数字化并提供高效的检索能力。其核心功能包括支持多种文件格式（PDF、图片、Office 文档等）、集成 OCR 技术以及云端或本地化的存储方案[^1]。 为了更好地理解和使用 Paperless-ngx，以下是关于该系统的常见配置和操作说明： --- #### 二、安装与部署 ##### 1. 基于 Docker 的快速部署 Docker 提供了一种简单的方式来运行 Paperless-ngx。如果遇到官方镜像下载速度较慢的情况，可以选择国内加速源替代默认地址[^3]。具体命令如下： ```bash docker pull swr.cn-north-4.myhuaweicloud.com/jeven/paperless-ngx:latest ``` 完成镜像拉取后，可以通过 `docker-compose` 文件定义服务依赖关系。以下是一个典型的 `docker-compose.yml` 配置示例[^4]: ```yaml version: '3' services: db: image: mariadb:10.5 restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: rootpassword MYSQL_DATABASE: paperless MYSQL_USER: paperless MYSQL_PASSWORD: paperless volumes: - db_data:/var/lib/mysql broker: image: redis:alpine restart: unless-stopped webserver: image: ghcr.io/paperless-ngx/paperless-ngx:latest restart: unless-stopped depends_on: - db - broker ports: - "8000:8000" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000"] interval: 30s timeout: 10s retries: 5 volumes: - data:/usr/src/paperless/data - media:/usr/src/paperless/media - ./export:/usr/src/paperless/export - ./consume:/usr/src/paperless/consume environment: PAPERLESS_REDIS: redis://broker:6379 PAPERLESS_DBENGINE: mariadb PAPERLESS_DBHOST: db PAPERLESS_DBUSER: paperless PAPERLESS_DBPASS: paperless PAPERLESS_DBPORT: 3306 volumes: db_data: data: media: ``` 启动容器时执行以下命令即可： ```bash docker-compose up -d ``` --- #### 三、基本使用方法 ##### 1. 添加文档 用户可通过 Web 界面上传新文档或将文件放置到指定的消费目录 (`./consume`) 中。系统会自动处理这些文件，并将其转化为可搜索的内容[^2]。 ##### 2. 搜索功能 Paperless-ngx 支持全文检索，允许用户输入关键词来定位目标文档。这得益于内置的 OCR 工具对扫描件的文字提取能力。 ##### 3. 自动分类 通过设置标签规则，可以实现新增文档的自动化归类。例如，基于文件名模式匹配特定类别。 --- #### 四、高级定制选项 对于有更高需求的技术人员来说，还可以进一步调整参数以优化性能表现或者扩展功能性。比如修改数据库连接字符串、Redis 地址以及其他环境变量值均需编辑对应的 YAML 定义部分。 --- #### 五、常见问题排查 当遇到无法访问前端页面或其他异常状况时，请依次检查以下几个方面： - **网络连通性**：确认宿主机端口映射正常工作。 - **日志分析**：查看各子服务的日志输出寻找错误提示信息。 - **资源占用情况**：确保硬件资源配置充足满足应用运行所需条件。 ---