Paperless-ngx v2.18.4在Ubuntu 24.04上的完整离线安装步骤（非Docker）

​​1. 系统准备与依赖安装​​

首先更新系统并安装基础工具，确保后续步骤顺利进行：

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential

安装Python环境及开发工具（Paperless-ngx基于Python 3开发）：

sudo apt install -y python3 python3-pip python3-dev python3-venv

安装数据库（PostgreSQL，推荐用于生产环境，性能更优）：

sudo apt install -y postgresql postgresql-contrib libpq-dev

安装OCR工具链（用于文档文字识别，支持中文等多语言）：

sudo apt install -y imagemagick fonts-liberation gnupg libmagic-dev libzbar0 poppler-utils unpaper ghostscript icc-profiles-free qpdf liblept5 libxml2 pngquant zlib1g tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-chi-tra

安装Redis（消息队列，提升文档处理性能）：

sudo apt install -y redis-server
sudo systemctl enable --now redis-server  # 启用并启动Redis服务

​​2. 上传Paperless-ngx源码​​

将​​能联网的机器​​上下载的Paperless-ngx v2.18.4源码包（如paperless-ngx-v2.18.4.zip）解压后，通过U盘、SFTP等工具上传到目标服务器的/opt目录。例如：

# 在能联网的机器上打包源码
cd ~/paperless-ngx-v2.18.4
zip -r ../paperless-ngx-v2.18.4.zip .# 传输到目标服务器（假设U盘挂载在/mnt/usb）
sudo mount /dev/sdb1 /mnt/usb
cp ../paperless-ngx-v2.18.4.zip /mnt/usb/
sudo umount /mnt/usb# 在目标服务器上解压
cd /opt
sudo unzip paperless-ngx-v2.18.4.zip
sudo mv paperless-ngx-v2.18.4 paperless-ngx  # 重命名目录
sudo chown -R paperless:paperless /opt/paperless-ngx  # 设置目录所有权

​​3. 下载并安装系统依赖​​

在目标服务器上，使用apt下载Paperless-ngx所需的系统依赖（确保网络畅通）：

sudo apt install -y python3 python3-pip python3-dev python3-venv \postgresql postgresql-contrib libpq-dev \imagemagick fonts-liberation gnupg libmagic-dev libzbar0 poppler-utils unpaper ghostscript icc-profiles-free qpdf liblept5 libxml2 pngquant zlib1g tesseract-ocr \redis-server

​​4. 配置数据库​​

切换至PostgreSQL用户，创建数据库及专用用户（避免使用默认用户）：

sudo -u postgres psql

在PostgreSQL交互界面中执行以下命令（替换your_secure_password为强密码，注意密码中不要有@符号，会导致后面数据库密码验证出问题）：

CREATE DATABASE paperless WITH ENCODING='UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8';
CREATE USER paperless WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE paperless TO paperless;
\q  # 退出PostgreSQL

​​5. 处理配置文件位置变更（v2.18.4默认根目录）​​

Paperless-ngx v2.18.4将paperless.conf文件默认放在​​项目根目录​​（即/opt/paperless-ngx/）下，而非之前的config/目录。进入项目目录，复制配置模板（若源码中无paperless.conf.example，需从其他已下载的源码中获取）：

cd /opt/paperless-ngx
cp paperless.conf.example paperless.conf  # 若无example文件，需手动创建（见下一步）

​​若源码中无paperless.conf.example​​，手动创建paperless.conf并填入以下基本配置（根据你的环境修改）：

# ===== 数据库配置（PostgreSQL） =====
PAPERLESS_DBENGINE=postgres
PAPERLESS_DBHOST=localhost
PAPERLESS_DBPORT=5432
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=your_secure_password  # 替换成你的PostgreSQL密码# ===== Redis配置 =====
PAPERLESS_REDIS=redis://localhost:6379/0# ===== 存储路径 =====
PAPERLESS_CONSUMPTION_DIR=/opt/paperless/consume  # 文档扫描/导入目录
PAPERLESS_MEDIA_ROOT=/opt/paperless/media         # 文档存储目录
PAPERLESS_EXPORT_DIR=/opt/paperless/export        # 导出目录# ===== 安全配置 =====
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)  # 生成随机密钥（或手动设置一个）
PAPERLESS_TIME_ZONE=Asia/Shanghai             # 时区（中国）# ===== 其他可选配置 =====
PAPERLESS_ALLOW_REGISTRATION=False  # 是否允许新用户注册（生产环境建议False）
PAPERLESS_AUTO_LOGIN=False          # 是否自动登录（生产环境建议False）

​​6. 创建必要目录并设置权限​​

创建文档存储、导入及导出目录，并设置正确的权限（确保paperless用户可访问）：

sudo mkdir -p /opt/paperless/{consume,media,export}
sudo chown -R paperless:paperless /opt/paperless

​​7. 安装Python依赖​​

使用虚拟环境隔离项目依赖，避免污染系统环境：

# 创建虚拟环境
sudo -u paperless python3 -m venv /opt/paperless-ngx/venv# 激活虚拟环境并升级pip
source /opt/paperless-ngx/venv/bin/activate
pip install --upgrade pip setuptools wheel# 安装Python依赖（从requirements.txt）
pip install -r /opt/paperless-ngx/requirements.txt

​​8. 初始化数据库与创建管理员​​

执行数据库迁移（创建表结构）：

cd /opt/paperless-ngx/src
sudo -u paperless python3 manage.py migrate

创建超级用户（用于登录Web界面，按提示输入用户名、密码及邮箱）：

sudo -u paperless python3 manage.py createsuperuser

​​9. 配置系统服务（开机自启）​​

创建systemd服务文件（paperless提供样本在scripts文件夹中，可以直接复制过来然后修改对应的路径参数等），实现Paperless-ngx的自动启动与管理：

sudo nano /etc/systemd/system/paperless.service

写入以下内容（替换/opt/paperless-ngx/src为你的项目路径）：

[Unit]
Description=Paperless-ngx Document Management System
After=network.target redis.service postgresql.service[Service]
User=paperless
Group=paperless
WorkingDirectory=/opt/paperless-ngx/src
Environment="PATH=/opt/paperless-ngx/src/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/opt/paperless-ngx/src/venv/bin/python3 manage.py runserver 0.0.0.0:8000
Restart=always  # 服务崩溃时自动重启[Install]
WantedBy=multi-user.target

启用并启动服务：

sudo systemctl start 服务名
sudo systemctl enable --now 服务名  # 设置开机自启并立即启动

或者

sudo systemctl daemon-reload
sudo systemctl enable --now paperless  # 设置开机自启并立即启动

​​10. 访问Web界面​​

等待服务启动完成后（可通过sudo systemctl status paperless查看状态），通过浏览器访问http://your_server_ip:8000（若未配置域名，可使用服务器IP）。首次登录时，使用之前创建的超级用户账号和密码进行登录。

​​后续操作建议​​：

• 将/opt/paperless/consume（文档元数据）和/opt/paperless/media（文档文件）目录加入定期备份计划（如使用rsync或cron）。
• 若需更高性能，可调整Redis缓存大小（修改/etc/redis/redis.conf中的maxmemory参数）或升级服务器硬件（推荐SSD存储）。
• 配置邮件通知（如文档上传提醒），需修改paperless.conf中的邮件相关参数（如PAPERLESS_MAIL_HOST、PAPERLESS_MAIL_USER等）。