别再手动整理文档了！paperless-ngx 让你的纸质文件秒变数字化知识库

# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version

# 创建安装目录
mkdir -p ~/paperless-ngx
cd ~/paperless-ngx

# 下载官方配置文件
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose.env
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/docker-compose.yml

# 下载傻瓜配置（包含反向代理等完整配置）
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose.sqlite.yml

# 创建数据目录
mkdir -p data

# 创建配置文件
cat > docker-compose.env << 'EOF'
# 时区配置，确保文件时间戳正确
PAPERLESS_TIME_ZONE=Asia/Shanghai

# OCR 语言配置，中文需要添加 chi_sim
PAPERLESS_OCR_LANGUAGE=chi_sim+eng

# 超级管理员账户配置
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=your_secure_password_here
PAPERLESS_ADMIN_MAIL=admin@example.com

# Redis 密码（可选但推荐）
PAPERLESS_REDIS=redis://:your_redis_password@localhost:6379

# 可选：启用全文搜索
PAPERLESS_ENABLE_FULLTEXT_SEARCH=1

# 可选：钉钉/企业微信通知（按需配置）
# PAPERLESS_NOTIFICATION_HOOKS=...
EOF

# 使用 SQLite 版本的配置
mv docker-compose.yml docker-compose.postgres.yml
mv compose.sqlite.yml docker-compose.yml

# 拉取镜像并启动
docker-compose up -d

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Docker（如果是 32 位系统，选择相应的安装脚本）
curl -fsSL https://get.docker.com | sh

# 将当前用户添加到 docker 用户组
sudo usermod -aG docker $USER

# 安装 Docker Compose
sudo apt install docker-compose -y

# 在 services.paperless.web 添加资源限制
services:
  paperless:
    web:
      deploy:
        resources:
          limits:
            memory: 1.5G
          reservations:
            memory: 512M

# 挂载外接 SSD 到 /mnt/ssd
sudo mkdir -p /mnt/ssd/paperless
sudo chown -R $USER:$USER /mnt/ssd

# 修改数据目录路径
mkdir -p /mnt/ssd/paperless/data
mkdir -p /mnt/ssd/paperless/media

# 安装基础依赖
sudo apt update
sudo apt install -y \
    python3 python3-pip python3-venv \
    postgresql postgresql-contrib \
    redis-server \
    imagemagick \
    gnupg \
    poppler-utils \
    libmagic-dev \
    mime-support \
    libreoffice \
    unpaper \
    qrencode \
    gnupg2 \
    fontconfig \
    libpq-dev

# 创建 Python 虚拟环境
python3 -m venv paperless-venv
source paperless-venv/bin/activate

# 安装 paperless-ngx
pip install paperless-ngx

# 创建 PostgreSQL 数据库和用户
sudo -u postgres psql

# 在 PostgreSQL 交互界面中执行
CREATE DATABASE paperless;
CREATE USER paperless_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE paperless TO paperless_user;
\q

# 创建配置目录
mkdir -p /etc/paperless
mkdir -p /var/lib/paperless

# 创建环境配置文件
cat > /etc/paperless/paperless.conf << 'EOF'
PAPERLESS_DBHOST=localhost
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless_user
PAPERLESS_DBPASS=your_password
PAPERLESS_OCR_LANGUAGE=chi_sim+eng
PAPERLESS_TIME_ZONE=Asia/Shanghai
PAPERLESS_SECRET_KEY=generate_a_random_secret_key_here
EOF

# 运行数据库迁移
paperless-cli migrate

# 创建超级管理员
paperless-cli createsuperuser

# 启动服务
paperless-cli consumer &
paperless-ngx &

# PAPERLESS_OCR_MODE: 控制 OCR 执行时机
# 建议设置为 "redo" 或 "skip" 而非 "always"，避免重复处理
PAPERLESS_OCR_MODE=redo

# PAPERLESS_OCR_LANGUAGE: 设置识别语言
# 多个语言用 + 分隔，如 chi_sim+eng 表示中文优先、英文辅助
PAPERLESS_OCR_LANGUAGE=chi_sim+eng

# PAPERLESS_OCR_IMAGE_DPI: 设置图像分辨率
# 300 DPI 是扫描文档的推荐值
PAPERLESS_OCR_IMAGE_DPI=300

# PAPERLESS_OCR_CLEAN: 清理 OCR 结果中的噪点
PAPERLESS_OCR_CLEAN=clean
PAPERLESS_OCR_DESKEW: 自动纠偏倾斜的文档
PAPERLESS_OCR_DESKEW=true

# 标签命名规范建议
# 使用简短的中文关键词：发票、合同、证件、重要
# 使用状态标记：[待审]、[已处理]、[紧急]
# 使用项目关联：项目A、合同B、供应商C

# 自动标签规则示例
# 规则1：标题包含"发票" → 自动添加"财务"标签
# 规则2：correspondent 是"税务局" → 自动添加"税务"标签
# 规则3：内容包含"紧急" → 自动添加"重要"标签

# 场景1：发票管理
# 收到"京东商城"寄来的发票 → 自动匹配 correspondent 为"京东商城"
# 系统会记录你与京东的所有交易往来

# 场景2：合同管理
# 与"某科技有限公司"签订合同 → correspondent 设置为该公司
# 可以快速查看与该公司的所有历史文档

# 场景3：银行对账单
# 每月收到"中国工商银行"的对账单 → correspondent 为"工商银行"
# 便于按银行分类管理财务文档

# 标签：更灵活，可以同时属于多个标签
# 示例：一份合同可以同时拥有 ["合同", "重要", "待审", "法务部"] 等标签

# 类型：文档的单一属性，每个文档只能有一个类型
# 示例：一份合同只能是"合同"类型，不能同时是"发票"类型

# 使用路径模板来组织文件
# 可用变量：
# {created_year} - 创建年份
# {created_month} - 创建月份
# {asn} - 档案序列号
# {correspondent} - 往来单位名称
# {title} - 文档标题
# {type} - 文档类型

# 示例配置
# {correspondent}/{created_year}/{created_year}-{created_month}/{title}

# 这会生成类似这样的路径结构：
# 京东商城/2024/2024-03/2024年3月购物发票.pdf

# 基本搜索
# 直接输入关键词搜索文档内容

# 精确短语搜索
"exact phrase"  # 搜索精确匹配的短语

# 字段搜索
title:发票  # 只在标题中搜索
content:合同  # 只在内容中搜索
correspondent:京东  # 搜索来自京东的文档

# 组合搜索
title:发票 AND correspondent:京东  # 同时满足两个条件

# 日期范围搜索
created:2024-01-01..2024-03-31  # 搜索指定日期范围

# 高级搜索
# 支持使用 +（必须包含）和 -（必须不包含）操作符
+title:重要 -content:作废  # 标题包含"重要"但内容不包含"作废"

# 触发条件（可以组合多个条件）
# - 文档标题包含指定文本
# - 文档内容包含指定文本
# - 来自指定的 correspondent
# - 文档类型匹配
# - 标签匹配
# - 文件名匹配特定模式

# 执行动作
# - 添加/移除标签
# - 设置/变更 correspondent
# - 设置/变更文档类型
# - 移动到指定存储路径
# - 发送通知
# - 触发自定义脚本

# 场景1：账单自动识别
# 规则：当标题包含"账单"或"对账单"时
# 动作：自动添加"财务"和"账单"标签

# 场景2：过期合同提醒
# 规则：当文档类型为"合同"且临近到期日期时
# 动作：发送提醒通知，添加"即将到期"标签

# 场景3：特定单位文档归档
# 规则：当 correspondent 为"税务局"时
# 动作：添加"税务"标签，移动到"税务文档"路径

# 场景4：重要文件标记
# 规则：当内容包含"重要"或"紧急"字样时
# 动作：添加"重要"标签，变更视图颜色为红色

# 在 docker-compose.yml 中添加卷挂载
services:
  paperless:
    web:
      volumes:
        - ./data:/usr/src/paperless/data
        - ./media:/usr/src/paperless/media
        # 添加消费目录映射
        - /path/to/consume:/usr/src/paperless/consume

# 创建消费目录
mkdir -p ~/paperless/consume

# 如果是 Docker 环境，需要确保目录权限
# UID 33 是 paperless 容器的默认用户 www-data
sudo chown -R 33:33 ~/paperless/consume

# 也可以设置为 777，但安全性较低
chmod 777 ~/paperless/consume

# 推荐的文档命名规范
# 使用下划线分隔不同信息，便于系统识别
# 例如：2024-03-15_京东_购物发票.pdf
# 格式：日期_来源_文档描述.pdf

# 另一个例子：2024-02-28_中国银行_对账单.pdf

# 规则名称：发票自动打标签
# 匹配条件：
#   - 标题：包含 "发票"、"收据"、"账单" 中的任意一个
#   - 内容：包含 "金额"、"合计"、"¥"、"¥" 等关键词

# 执行动作：
#   - 添加标签："财务"
#   - 添加标签："发票"
#   - 设置文档类型："发票"

# 规则名称：银行文档归类
# 匹配条件：
#   - correspondent：属于 ["中国工商银行", "中国建设银行", "招商银行", "中国银行"]
#   - 或标题包含 "银行"、"对账单"、"交易明细"

# 执行动作：
#   - 添加标签："财务"
#   - 添加标签："银行"
#   - 设置文档类型："银行对账单"

# 规则名称：重要合同标记
# 匹配条件：
#   - 文档类型："合同"
#   - 标题包含 "重要"、"关键"、"核心"

# 执行动作：
#   - 添加标签："重要合同"
#   - 设置自定义字段：提醒日期（到期前30天）

# 配置参数说明
# 服务器地址：imap.gmail.com（以 Gmail 为例）
# 端口：993
# 使用 SSL：是
# 用户名：your-email@gmail.com
# 密码：应用专用密码（非登录密码）

# 高级设置
# 轮询间隔：5 分钟（建议不要设置太短，避免被封禁）
# 收件规则：只处理带附件的邮件
# 附件过滤：排除 .exe、.zip 等危险文件类型

# 规则示例：自动处理发票邮件
# 触发条件：
#   - 邮件主题包含 "发票"、"invoice"、"收据"
#   - 发件人属于 ["billing@jd.com", "invoice@alibaba.com"]

# 执行动作：
#   - 下载附件并导入
#   - 添加标签："财务"
#   - 添加标签："邮件导入"
#   - 标记为已读并移动到"已处理"文件夹
#   - 自动删除原始邮件（可选）

# 在 Web 界面中获取
# 1. 登录 paperless-ngx
# 2. 进入「管理」→「用户」
# 3. 选择你的用户或创建新用户
# 4. 在「Token」部分生成新 Token
# 5. 复制 Token 并妥善保存

import requests

# 配置 API 端点和认证
BASE_URL = "http://localhost:8000/api"
TOKEN = "your-api-token-here"

headers = {
    "Authorization": f"Token {TOKEN}",
    "Content-Type": "application/json"
}

# 上传文档
def upload_document(file_path, title=None, correspondent=None, tags=None):
    """
    上传文档到 paperless-ngx

    参数:
        file_path: 文档文件路径
        title: 文档标题（可选）
        correspondent: 往来单位 ID（可选）
        tags: 标签 ID 列表（可选）
    """
    with open(file_path, "rb") as f:
        files = {"document": f}
        data = {}

        if title:
            data["title"] = title
        if correspondent:
            data["correspondent"] = correspondent
        if tags:
            data["tags"] = tags

        response = requests.post(
            f"{BASE_URL}/documents/post_document/",
            headers=headers,
            files=files,
            data=data
        )

    return response.json()

# 示例调用
result = upload_document(
    "/path/to/invoice.pdf",
    title="2024年3月购物发票",
    correspondent=1,  # 假设京东商城的 ID 是 1
    tags=[3, 5]  # 标签 ID 列表
)
print(f"文档上传成功，ID: {result['id']}")

import os
import glob
from datetime import datetime

def batch_import(folder_path, correspondent_id=None, tag_ids=None):
    """
    批量导入文件夹中的所有文档

    参数:
        folder_path: 要扫描的文件夹路径
        correspondent_id: 默认往来单位 ID
        tag_ids: 默认标签 ID 列表
    """
    # 支持的文件格式
    extensions = ["*.pdf", "*.jpg", "*.jpeg", "*.png", "*.tiff", "*.docx"]

    files = []
    for ext in extensions:
        files.extend(glob.glob(os.path.join(folder_path, ext)))

    results = []
    for file_path in files:
        # 自动生成标题（使用文件名作为标题）
        title = os.path.splitext(os.path.basename(file_path))[0]

        try:
            result = upload_document(
                file_path,
                title=title,
                correspondent=correspondent_id,
                tags=tag_ids
            )
            results.append({
                "file": file_path,
                "status": "success",
                "id": result.get("id")
            })
            print(f"✓ 成功导入: {title}")
        except Exception as e:
            results.append({
                "file": file_path,
                "status": "error",
                "error": str(e)
            })
            print(f"✗ 导入失败: {title} - {e}")

    return results

# 使用示例
# 将文件夹中所有文档批量导入，设置默认往来单位为"财务部"，添加"待审"标签
batch_import(
    "/path/to/pending/documents",
    correspondent_id=2,
    tag_ids=[8]  # "待审"标签的 ID
)

def search_documents(query, limit=50, tags=None, correspondent=None):
    """
    搜索文档

    参数:
        query: 搜索关键词
        limit: 返回结果数量限制
        tags: 按标签过滤（标签 ID 列表）
        correspondent: 按往来单位过滤（往来单位 ID）
    """
    params = {
        "query": query,
        "page_size": limit
    }

    if tags:
        params["tags__id__in"] = ",".join(map(str, tags))

    if correspondent:
        params["correspondent__id"] = correspondent

    response = requests.get(
        f"{BASE_URL}/documents/",
        headers=headers,
        params=params
    )

    return response.json()["results"]

# 示例：搜索所有发票
invoices = search_documents("发票", limit=100)
print(f"找到 {len(invoices)} 份发票文档")

# 示例：搜索来自京东的所有文档
jd_docs = search_documents("", correspondent=1)  # 京东的 ID
print(f"找到 {len(jd_docs)} 份来自京东的文档")

def update_document(doc_id, title=None, tags=None, correspondent=None, 
                    document_type=None, archive_serial_number=None):
    """
    更新文档元数据

    参数:
        doc_id: 文档 ID
        title: 新标题
        tags: 新标签列表
        correspondent: 新往来单位 ID
        document_type: 新文档类型 ID
        archive_serial_number: 新档案编号
    """
    data = {}

    if title is not None:
        data["title"] = title
    if tags is not None:
        data["tags"] = tags
    if correspondent is not None:
        data["correspondent"] = correspondent
    if document_type is not None:
        data["document_type"] = document_type
    if archive_serial_number is not None:
        data["archive_serial_number"] = archive_serial_number

    response = requests.patch(
        f"{BASE_URL}/documents/{doc_id}/",
        headers=headers,
        json=data
    )

    return response.json()

# 示例：更新文档标签
update_document(123, tags=[1, 2, 3])

# 示例：为文档分配档案编号
update_document(123, archive_serial_number="2024-001")

# 在管理界面配置 Webhook URL
# URL 格式：http://your-server.com/webhook
# 触发事件：
#   - 文档创建
#   - 文档修改
#   - 文档删除
#   - 文档消费（从消费目录导入）

# 可选：添加自定义 HTTP headers（如认证信息）
# Headers: Authorization: Bearer your-token

# 启用 SSL 验证（生产环境建议开启）
# 开始：https://your-server.com/webhook

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def handle_paperless_webhook():
    """
    处理 paperless-ngx 发来的 webhook 通知
    """
    # 验证请求来源（建议实现验证逻辑）
    # if request.headers.get("X-Paperless-Token") != "expected-token":
    #     return jsonify({"error": "Unauthorized"}), 401

    # 解析 webhook 数据
    event_data = request.json

    event_type = event_data.get("event")
    document = event_data.get("document", {})

    # 根据事件类型处理
    if event_type == "document_added":
        # 新文档导入
        doc_id = document.get("id")
        doc_title = document.get("title")
        doc_content = document.get("content_text", "")

        print(f"新文档: {doc_title} (ID: {doc_id})")
        print(f"内容预览: {doc_content[:200]}...")

        # 在这里添加你的自定义逻辑
        # 比如发送通知、更新其他系统等

    elif event_type == "document_modified":
        # 文档被修改
        print(f"文档被修改: {document.get('title')}")

    elif event_type == "document_deleted":
        # 文档被删除
        print(f"文档已删除: {document.get('id')}")

    return jsonify({"status": "ok"}), 200

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

# 在「管理」→「用户」→「用户组」创建新组
# 示例组：
#   - 财务组：可以管理所有财务相关文档
#   - 管理层：可以查看所有文档但不能修改
#   - 普通员工：只能查看和处理分配给自己的文档

# 为不同角色设置不同的权限

# 管理员角色（所有权限）
#   - 文档管理：全部
#   - 用户管理：是
#   - 系统设置：是
#   - 日志查看：是

# 财务专员角色
#   - 文档管理：标签 ["财务"] 下的所有文档
#   - 标签限制：只能使用 ["财务", "发票", "账单"]
#   - correspondent 限制：只能使用 ["客户公司", "供应商"]

# 访客角色（只读）
#   - 文档管理：查看所有文档（只读）
#   - 标签限制：无
#   - 下载权限：否

# 视图功能允许你创建预设的文档筛选条件
# 在「视图」页面创建新视图

# 示例：创建「我的待处理文档」视图
# 筛选条件：
#   - 已分配给我：是
#   - 状态：未完成
#   - 标签：不含 "已完成"

# 示例：创建「本月发票」视图
# 筛选条件：
#   - 创建日期：本月
#   - 标签：包含 "发票"
#   - correspondent：属于 ["所有往来单位"]

# 视图配置完成后，可以分享给其他用户
# 用户登录后会看到他们被授权的视图

# 标签设计
# 标签1：财务 - 所有财务相关文档的主标签
# 标签2：收入 - 工资条、奖金、投资收益等
# 标签3：支出 - 购物发票、收据等
# 标签4：银行 - 银行相关文档
# 标签5：保险 - 保单、理赔记录
# 标签6：投资 - 股票、基金、理财产品相关
# 标签7：重要 - 重要文件标记

# correspondent 设计
# - 中国工商银行（常用银行）
# - 中国建设银行
# - 京东商城（主要购物平台）
# - 天猫超市
# - 支付宝
# - 微信支付

# 文档类型设计
# - 发票
# - 收据
# - 银行对账单
# - 保险单
# - 合同
# - 凭证

# 1. 收到发票后立即扫描
#    → 放入消费目录或拍照上传
#    → 自动打上"财务"和"发票"标签

# 2. 每月初整理上月银行对账单
#    → 下载电子账单或扫描纸质账单
#    → 自动归类到"银行"标签，correspondent 为对应银行

# 3. 年末整理全年财务文档
#    → 使用视图筛选年度财务数据
#    → 导出全年发票汇总表

# 使用存储路径规则自动归档
# {created_year}/财务/{correspondent}/{title}

# 生成的结构示例：
# 2024/财务/中国工商银行/2024年1月对账单.pdf
# 2024/财务/京东商城/购物发票-2024-03-15.pdf
# 2024/财务/支付宝/交易记录-2024.pdf

# 年末归档后，可以创建只读视图方便查阅历史
# 同时可以考虑将历史年份的数据导出备份

# 标签设计
# 标签1：客户 - 所有客户相关文档
# 标签2：合同 - 合同协议类
# 标签3：发票 - 发票收据类
# 标签4：项目 - 项目文档
# 标签5：[客户名] - 按客户名创建专属标签
# 标签6：待收款 - 等待收款的发票
# 标签7：已收款 - 已完成收款的发票
# 标签8：重要 - 需要特别关注的文档

# correspondent 设计
# - 按客户名创建 correspondent
# - 设置每个客户的联系信息（邮件、电话等）

# 文档类型设计
# - 报价单
# - 合同
# - 发票
# - 收据
# - 项目文档
# - 沟通记录

# 规则1：新发票自动关联客户
# 条件：标题包含客户名称
# 动作：设置 correspondent 为对应客户，添加客户专属标签

# 规则2：收款后状态更新
# 条件：标题包含"收款"或"到账"
# 动作：从"待收款"标签移除，添加到"已收款"标签

# 规则3：合同到期提醒
# 条件：文档类型为"合同"，临近到期日期
# 动作：发送提醒通知，添加"即将到期"标签

# 用户组设计
# 组1：管理员组
#   - 成员：老板、IT 负责人
#   - 权限：所有文档完全控制

# 组2：财务组
#   - 成员：财务人员
#   - 权限：财务文档完全控制，其他文档只读

# 组3：业务组
#   - 成员：业务人员
#   - 权限：只能访问自己上传的文档

# 组4：档案组
#   - 成员：档案管理人员
#   - 权限：所有文档只读，可以进行归档操作

# 使用标签区分部门
# 标签：研发部、财务部、人事部、市场部、销售部

# 权限规则示例
# 规则1：财务部成员只能访问带"财务部"标签的文档
# 规则2：部门负责人可以访问本部门所有文档
# 规则3：跨部门协作文档需要单独授权

# 视图设计
# 视图1：我的部门文档（显示当前用户所在部门的文档）
# 视图2：待处理文档（所有未分类的新文档）
# 视图3：重要文档（所有带"重要"标签的文档）

# 启用审计日志
# PAPERLESS_AUDIT_LOG_ENABLED=1

# 配置保留策略
# 财务文档建议保留至少 7 年
# 使用到期日期功能设置自动提醒

# 数据备份策略
# 每日自动备份数据库和媒体文件
# 备份保留周期：最近 30 天
# 离线备份：每月导出一次完整备份

# 备份脚本示例
#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR=/mnt/backup/paperless

# 备份数据库
docker exec paperless-postgres pg_dump -U paperless > $BACKUP_DIR/db_$DATE.sql

# 备份媒体文件
tar -czf $BACKUP_DIR/media_$DATE.tar.gz /path/to/paperless/media

# 清理旧备份（保留30天）
find $BACKUP_DIR -mtime +30 -delete

# 标签设计
# 标签1：文献综述
# 标签2：实验数据
# 标签3：方法论文档
# 标签4：项目报告
# 标签5：[研究方向] - 如"机器学习"、"生物信息"
# 标签6：[论文标题] - 正在撰写的论文相关资料

# correspondent 设计
# - 按期刊/会议名称创建 correspondent
# - 按合著者姓名创建 correspondent

# 文档类型设计
# - 论文 PDF
# - 预印本
# - 实验记录
# - 方法说明
# - 数据文件
# - 演示文稿

# 1. 文献导入
#    → 从学术数据库下载 PDF
#    → 拖入消费目录或上传
#    → 自动识别标题、作者等信息

# 2. 笔记关联
#    → 为重要文献创建笔记标签
#    → 使用标签关联相关文献

# 3. 引用管理
#    → 使用自定义字段记录引用信息
#    → 导出 BibTeX 格式引用

# 4. 写作素材整理
#    → 为正在撰写的论文创建专属视图
#    → 收集相关文献和笔记

# 扫描仪设置建议
# 分辨率：300 DPI（最佳性价比，既保证清晰度又不过大）
# 颜色模式：灰度或黑白（文字文档不需要彩色）
# 文件格式：PDF（方便搜索和预览）或 TIFF（无损质量）

# 如果使用拍照扫描
# 注意事项：
#   - 确保光线均匀
#   - 文档平整无褶皱
#   - 避免阴影和反光
#   - 使用 APP（如 Adobe Scan）自动纠偏和增强

# 中文 OCR 语言包配置
# 默认语言包可能不包含中文，需要额外安装

# Docker 方式安装中文语言包
# 在 docker-compose.yml 中添加环境变量
environment:
  PAPERLESS_OCR_LANGUAGE: chi_sim+eng

# chi_sim：简体中文
# chi_tra：繁体中文
# eng：英语
# 如果文档混有多语言，可以组合使用
# 例如：chi_sim+eng+jpn（简体中文+英语+日语）

# 在「设置」→「OCR」页面可调整的参数

# OCR 模式选择
# always：总是执行 OCR（不建议，每次处理都会重新识别）
# skip：跳过 OCR（已有文本的 PDF 使用此模式）
# redo：重新识别（推荐，仅对图片页面重新 OCR）

# 页面方向检测
# 启用后，系统会自动检测并旋转方向错误的页面
PAPERLESS_OCR_DESKEW: true

# 噪点清理
# 清理扫描产生的噪点和杂质，提高识别准确率
PAPERLESS_OCR_CLEAN: clean

# 页面合并
# 如果扫描仪输出了多页图片，启用此选项可合并为单页 PDF
PAPERLESS_OCR_CONCAT_PDF: true

# 定期执行数据库优化
# 可以通过管理界面的「工具」页面执行

# 手动执行命令
docker exec paperless-web /entrypoint.sh document_create_classifier
# 重新训练分类器，提高自动分类准确率

# 数据库维护脚本
docker exec paperless-postgres psql -U paperless -c "VACUUM ANALYZE;"

# 清理孤立文件（谨慎使用）
docker exec paperless-web /entrypoint.sh document_thumbnails删除
# 删除孤立的缩略图（某些情况下可能导致缩略图丢失）

# 重建搜索索引
docker exec paperless-web /entrypoint.sh document_index
# 重建后的搜索索引通常更紧凑

# 压缩策略
# 缩略图：默认使用 JPEG 格式，已进行压缩
# 原始文件：PDF 通常已压缩，TIFF 建议使用 LZW 压缩

# 磁盘空间监控
# 定期检查存储使用情况
df -h /path/to/paperless/data

# 批量导出旧文档到离线存储
# 创建归档视图，筛选出不需要频繁访问的文档
# 导出后删除这些文档释放空间

# Docker 卷空间回收
# 当删除大量文件后，Docker 卷可能不会自动释放空间
docker volume ls
docker volume prune

# 在 docker-compose.yml 中调整资源限制

services:
  paperless:
    web:
      deploy:
        resources:
          limits:
            memory: 2G  # 根据可用内存调整
          reservations:
            memory: 512M

    celery:
      deploy:
        resources:
          limits:
            memory: 1G
            cpus: '2.0'
          reservations:
            memory: 256M
            cpus: '0.5'

# 3 份副本：原始数据 + 2 份备份
# 2 种介质：本地存储 + 云端存储
# 1 份异地：至少一份备份存放在不同地理位置

# 备份方案示例

# 方案1：本地 + 云端双重备份
# 本地：每日备份到外接硬盘
# 云端：每日备份到阿里云 OSS / AWS S3 / Google Cloud Storage

# 方案2：定时备份到 NAS
# 配置 NAS 的定时任务每日同步 paperless 数据目录

# 方案3：使用 rclone 同步到多种云存储
# 配置 rclone 定时任务，同时同步到多个云服务提供商

#!/bin/bash
# paperless-ngx 备份脚本

# 配置
BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_ROOT="/mnt/backups/paperless"
DATA_DIR="/path/to/paperless"
KEEP_DAYS=30

# 创建备份目录
mkdir -p $BACKUP_ROOT

# 备份数据库
echo "正在备份数据库..."
docker exec paperless-postgres pg_dump -U paperless > $BACKUP_ROOT/db_$BACKUP_DATE.sql
gzip $BACKUP_ROOT/db_$BACKUP_DATE.sql

# 备份媒体文件
echo "正在备份媒体文件..."
tar -czf $BACKUP_ROOT/media_$BACKUP_DATE.tar.gz -C $(dirname $DATA_DIR) paperless/media

# 备份配置文件
echo "正在备份配置文件..."
tar -czf $BACKUP_ROOT/config_$BACKUP_DATE.tar.gz $DATA_DIR/docker-compose.yml $DATA_DIR/docker-compose.env

# 创建备份清单
cat > $BACKUP_ROOT/manifest_$BACKUP_DATE.txt << EOF
Backup Date: $BACKUP_DATE
Database Size: $(du -h $BACKUP_ROOT/db_$BACKUP_DATE.sql.gz | cut -f1)
Media Size: $(du -h $BACKUP_ROOT/media_$BACKUP_DATE.tar.gz | cut -f1)
Documents Count: $(docker exec paperless-web python manage.py shell -c "from documents.models import Document; print(Document.objects.count())")
EOF

# 清理旧备份
echo "正在清理 $KEEP_DAYS 天前的备份..."
find $BACKUP_ROOT -mtime +$KEEP_DAYS -delete

# 上传到云端（可选）
# rclone copy $BACKUP_ROOT gdrive:paperless-backups/

echo "备份完成: $BACKUP_DATE"

# 定期进行恢复演练，确保备份可用

# 恢复步骤
# 1. 停止服务
docker-compose down

# 2. 清理数据目录
rm -rf data/*

# 3. 恢复数据库
gunzip -c db_20240101_120000.sql.gz | docker exec -i paperless-postgres psql -U paperless

# 4. 恢复媒体文件
tar -xzf media_20240101_120000.tar.gz

# 5. 重启服务
docker-compose up -d

# 6. 验证数据完整性
# 检查文档数量、缩略图、搜索功能等

# 财务场景
# 字段1：金额（数字类型，单位：元）
# 字段2：付款方式（下拉列表：现金、银行卡、支付宝、微信）
# 字段3：发票号码（文本类型）

# 合同场景
# 字段1：合同金额（数字类型）
# 字段2：签约日期（日期类型）
# 字段3：到期日期（日期类型）
# 字段4：对方联系人（文本类型）
# 字段5：合同编号（文本类型）

# 资产场景
# 字段1：资产编号（文本类型）
# 字段2：购置日期（日期类型）
# 字段3：保修截止日期（日期类型）
# 字段4：使用人（文本类型）

# 项目场景
# 字段1：项目编号（文本类型）
# 字段2：项目阶段（下拉列表：立项、执行、验收、归档）
# 字段3：负责人（文本类型）

# 配置自动填充自定义字段的规则

# 规则示例：根据文档类型自动添加字段
# 规则：文档类型为"发票"
# 动作：
#   - 设置自定义字段"金额"（需要手动输入）
#   - 设置自定义字段"付款方式"（自动尝试从内容识别）

# 规则示例：合同到期提醒
# 规则：文档类型为"合同"
# 动作：
#   - 添加"到期提醒"标签
#   - 计算并设置自定义字段"剩余天数"

# Nextcloud 的支持文件同步功能可以与 paperless-ngx 配合使用

# 配置步骤
# 1. 在 Nextcloud 安装 paperless 应用（如果可用）
# 2. 配置同步文件夹
# 3. 将同步文件夹设置为 paperless-ngx 的消费目录

# 或者使用 WebDAV
# 在 paperless-ngx 中添加 WebDAV 源

# 配置示例
# URL: https://your-nextcloud.com/remote.php/dav/files/username/paperless/
# 用户名: your-username
# 密码: your-app-password

# 使用 Webhooks 功能与自动化平台集成

# Zapier 配置
# 触发器：Webhook Catch Hook
# 操作：根据 Webhook 数据执行各种动作

# 场景示例：
# 触发器：手机扫描文档自动上传到 Dropbox
#   → Dropbox 新文件触发 Zapier
#   → Zapier 转发到 paperless-ngx Webhook
#   → paperless-ngx 自动处理文档

# 触发器：paperless-ngx 新文档包含"待办"标签
#   → Zapier 接收 Webhook
#   → 创建 Todoist 任务

# GitHub 仓库
https://github.com/paperless-ngx/paperless-ngx

# 官方文档
https://paperless-ngx.readthedocs.io/

# Discord 社区
https://discord.gg/paperless

# Reddit 社区
https://www.reddit.com/r/PaperlessNgX/

# 本教程的 GitHub Issues 反馈
# https://github.com/your-repo/issues

# QQ 交流群（可搜索 paperless-ngx 中文用户群）

# CSDN/博客园等平台的专题文章

# 扫描仪固件和驱动
# SANE: 扫描仪开源驱动
# https://sane-project.org/

# 文档处理工具
# pdfcpu: Go 语言 PDF 处理工具
# https://pdfcpu.io/

# OCR 引擎
# Tesseract: 开源 OCR 引擎
# https://github.com/tesseract-ocr/tesseract

# 文档识别（基于深度学习）
# PaddleOCR: 百度开源的 OCR 工具包
# https://github.com/PaddlePaddle/PaddleOCR

# 知识管理工具（可与 paperless-ngx 配合使用）
# Obsidian: 本地笔记和知识管理
# https://obsidian.md/

# Logseq: 大纲笔记和知识管理
# https://logseq.com/