最可靠省事的安装方式是官方Docker一键脚本部署：bash -c "$(curl --location --silent --show-error https://www.php.cn/link/a6cb414f9dfcc869891b29fe5a3fbf40)"，它自动处理镜像拉取、依赖配置、管理员创建和密钥生成，避免80%新手卡点。
Paperless-ngx 在 Linux 上最可靠、最省事的安装方式是 Docker 脚本一键部署，不是手动写 docker-compose.yml，也不是原生 Python 安装。它能自动处理镜像拉取、服务依赖、管理员创建和基础配置，避免 80% 的新手卡点。
用官方安装脚本启动（推荐所有人）
bash -c "$(curl --location --silent --show-error <a href="https://www.php.cn/link/a6cb414f9dfcc869891b29fe5a3fbf40">https://www.php.cn/link/a6cb414f9dfcc869891b29fe5a3fbf40</a>)"
这条命令会下载并执行官方维护的交互式安装脚本，全程只需按回车或输入少量选项。
- 脚本会检查本地是否已安装
docker和docker-compose，缺失时会提示你先装好 - 默认使用 PostgreSQL（比 MariaDB 更稳定，官方默认选型）
- 自动创建
.env文件并生成安全的PAPERLESS_SECRET_KEY - 启动后直接输出初始管理员账号密码（别跳过这步，否则要进容器重置）
- 端口固定映射到
8000，访问<a href="https://www.php.cn/link/496de70cdb579aa363b818cbb913d108">https://www.php.cn/link/496de70cdb579aa363b818cbb913d108</a>即可登录
常见卡点：
- 执行脚本时报
Permission denied：说明当前用户没加入docker组，运行sudo usermod -aG docker $USER，然后newgrp docker或重新登录终端 - 脚本卡在 “Pulling images…” 超过 5 分钟：大概率是网络问题，可提前手动拉镜像：
docker pull ghcr.io/paperless-ngx/paperless-ngx:latest
手动改端口或换数据库（需要自定义时）
如果你不能用 8000 端口（比如已被占用），或想用 MariaDB（例如已有现成 MariaDB 实例），就得改 docker-compose.yml。
- 修改端口：把
ports: - "8000:8000"改成- "8010:8000"，之后访问:8010 - 切换数据库：把
PAPERLESS_DBENGINE设为mariadb，同时补全PAPERLESS_DBPORT: 3306，并确保dbservice 使用的是mariadb:10镜像 - 注意环境变量名差异：
POSTGRES_PASSWORD（PostgreSQL） vsMARIADB_ROOT_PASSWORD（MariaDB），漏配会导致webserver启动失败并反复重启
别直接复制网上老教程的 yml —— ghcr.io/paperless-ngx/paperless-ngx 是当前唯一有效镜像源，paperlessngx/paperless-ngx 已弃用，拉不到镜像会静默失败。
启动后打不开页面或健康检查失败
docker-compose ps 查看各服务状态，重点关注 webserver 是否为 healthy。
-
如果是
unhealthy或restarting：- 运行
docker-compose logs webserver | tail -20，重点找django.core.exceptions.ImproperlyConfigured或Connection refused - 常见原因是
PAPERLESS_DBHOST指向错误（必须填服务名db，不能填localhost或 IP） - 或
PAPERLESS_REDIS地址写成redis://127.0.0.1:6379（容器内应指向服务名broker）
- 运行
-
如果页面打开但报
Bad Request (400)：- 检查
PAPERLESS_ALLOWED_HOSTS是否设为"*"（开发/内网可用），生产环境必须填具体域名或 IP，比如"192.168.1.100,docs.example.com"
- 检查
数据目录权限和 consume 文件夹挂载
./consume 是 Paperless-ngx 自动扫描上传文件的入口目录，权限不对会导致文档不入库。
- 创建该目录后，必须赋予与容器内用户一致的 UID/GID：
mkdir -p ./consume chmod 775 ./consume chown 1001:1001 ./consume
-
1001是paperless-ngx镜像内默认用户 ID，硬编码，不能靠猜 - 如果你用 rootless Docker 或自定义用户映射，需同步修改
user:字段并保持 UID 一致，否则 OCR 进程会因权限被拒而静默跳过文件
真正麻烦的从来不是安装，而是 consume 目录权限、Redis 连接地址写错、以及镜像源失效这三处。其他都只是敲几行命令的事。
