Montscan

在数字化办公中，扫描仪依然是将纸质文件转化为电子档案的重要工具。然而，传统的扫描工作流往往止步于生成一个个名为 scan_001.pdf 或 IMG_20240224.jpg 的无意义文件。随后，用户不得不花费大量时间手动重命名、分类并上传到云存储。

Montscan 是一款处于积极开发阶段的自动化扫描仪文档处理器。它不仅仅是一个文件搬运工，更是一个具备视觉 AI 能力的智能助手。Montscan 能够通过网络接收扫描文件，利用本地运行的 Ollama 视觉模型“看懂”文档内容，生成描述性的智能文件名，并自动上传至你的 WebDAV 云存储（如 Nextcloud、ownCloud）。

当前状态说明：Montscan 尚未完全达到生产级就绪标准，但已具备极高的可用性。在包含 1000 份文档的小型测试集中，其成功率达到了 97.5%。对于追求自动化和本地隐私的用户来说，现在正是介入体验的最佳时机。

核心功能：从接收到归档的智能化闭环

Montscan 的设计哲学是“设置一次，遗忘所有”。其核心工作流包含以下关键环节：

1. 内置 FTP 服务器：无缝对接网络扫描仪

大多数现代网络扫描仪都支持“扫描至 FTP”功能。Montscan 内置了轻量级 FTP 服务器，可直接作为扫描仪的目标地址。

• 扫描仪完成工作后，文件自动传输至 Montscan 监听目录。
• 无需人工干预，实现真正的无人值守接收。

2. 视觉 AI 处理：像人眼一样“阅读”文档

这是 Montscan 的灵魂所在。系统调用 Ollama 运行的视觉大模型（如 llava、llama3.2-vision），将 PDF 或图像转换为可理解的语义信息。

• PDF 转换：自动依赖 Poppler 或 ImageMagick 将 PDF 转为图像帧。
• 内容理解：AI 模型分析图像中的文字、版式和关键信息，理解文档的本质（如“2024 年 2 月电费账单”、“项目 A 合同签署页”）。

3. AI 驱动的智能命名

基于视觉分析结果，Montscan 利用 LLM 生成符合人类逻辑的描述性文件名。

• 告别乱码：不再使用 DSC00123.pdf，而是 2024-02-24_电费账单_国家电网.pdf。
• 多语言支持：虽然示例中展示了法语生成能力，但通过配置 LANGUAGE 变量，你可以指定 AI 使用中文、英文或其他语言进行命名，完美适配本地化需求。

4. WebDAV 自动归档

处理完成的文档将被自动推送至你的私有云或公有云存储。

• 广泛兼容：原生支持 Nextcloud、ownCloud 及任何标准 WebDAV 协议服务器。
• 路径管理：可自定义远程上传路径，确保文件落入正确的文件夹结构中。
• 安全传输：支持 TLS 验证配置，保障数据传输安全。

5. 开发者友好的部署体验

• 彩色 CLI 界面：启动时展示漂亮的横幅和配置概览，运行状态一目了然。
• Docker 原生：提供完整的 docker-compose.yml 和 Dockerfile，一键容器化部署，隔离依赖，干净清爽。
• Go 语言构建：高性能、低资源占用，单二进制文件分发（本地安装模式下）。

快速上手指南

Montscan 提供了灵活的部署方式，既支持本地二进制运行，也支持 Docker 容器化部署。

🛠️ 前提条件

在开始之前，请确保你的环境满足以下要求：

1. Ollama：已安装并运行，且拉取了视觉模型（推荐 llava 或 llama3.2-vision）。

   ollama pull llava
   

2. 转换工具：安装 Poppler (pdftoppm) 或 ImageMagick，用于处理 PDF 文件。
   • Linux: sudo apt-get install poppler-utils
   • macOS: brew install poppler
   • Windows: 下载预编译包并添加至 PATH。
3. WebDAV 服务器（可选）：如 Nextcloud 实例，用于最终存储。

📦 方案 A：本地安装（适合开发与调试）

1. 克隆仓库

   git clone https://github.com/SystemVll/Montscan.git
   cd Montscan
   

2. 构建应用
   确保已安装 Go 1.24+：

   go build -o montscan .
   

3. 配置环境变量
   你可以通过导出环境变量或直接修改启动命令来配置。核心参数包括：
   • FTP_USERNAME / FTP_PASSWORD：扫描仪连接的凭据。
   • OLLAMA_HOST：Ollama 服务地址（默认 http://localhost:11434）。
   • WEBDAV_URL / WEBDAV_USERNAME / WEBDAV_PASSWORD：云存储信息。
   • LANGUAGE：生成文件名的语言（如 chinese, english）。
4. 运行

   ./montscan
   

   看到彩色启动横幅即表示服务就绪。

🐳 方案 B：Docker 部署（推荐生产环境）

使用 Docker Compose 是最简便的方式，它能一次性解决依赖和环境隔离问题。

1. 编辑配置
   修改 docker-compose.yml 中的 environment 部分，填入你的 FTP 凭据、WebDAV 信息和 Ollama 地址。
   • 注意：若 Ollama 运行在宿主机，Docker 内访问地址通常为 http://host.docker.internal:11434。
2. 启动服务

   docker-compose up -d
   

3. 查看日志

   docker-compose logs -f
   

直接使用 Docker 命令运行示例：

docker run -d \
  -p 21:21 \
  -p 21000-21010:21000-21010 \
  -v ./scans:/app/scans \
  -e FTP_USERNAME=scanner \
  -e FTP_PASSWORD=scanner123 \
  -e WEBDAV_URL=https://your-nextcloud.com/dav/files/user \
  -e WEBDAV_USERNAME=user \
  -e WEBDAV_PASSWORD=pass \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e LANGUAGE=chinese \
  --name montscan \
  montscan

配置参数详解

Montscan 通过环境变量进行灵活配置，以下是核心参数表：

故障排除 (Troubleshooting)

在使用过程中遇到问题？以下是常见场景的解决方案：

1. FTP 连接被拒绝

• 现象：扫描仪无法连接，提示 Connection Refused。
• 排查：
  • 检查防火墙是否放行了 FTP 端口（默认 21）及被动模式端口范围（21000-21010）。
  • Windows 用户需在防火墙设置中允许 montscan.exe 或 Docker 应用通过。

2. AI 命名失败或文件名无意义

• 现象：文件名仍为默认值或乱码。
• 排查：
  • 确认 Ollama 服务正在运行：ollama list。
  • 验证是否已拉取视觉模型：ollama pull llava。
  • 检查 OLLAMA_HOST 配置是否正确，Docker 环境下需确保网络连通性。

3. WebDAV 上传失败

• 现象：日志显示 401 Unauthorized 或 404 Not Found。
• 排查：
  • 凭据错误：仔细检查用户名和密码，注意特殊字符转义。
  • 路径错误：确保 WEBDAV_UPLOAD_PATH 在服务器上真实存在。Nextcloud 用户需确认 WebDAV 入口 URL 格式（通常包含 /remote.php/dav/...）。
  • TLS 问题：若使用自签名证书，需设置 WEBDAV_INSECURE=true。

4. 找不到 Poppler/ImageMagick

• 现象：处理 PDF 时报错 executable not found。
• 排查：
  • 本地安装模式下，确保已将 Poppler 的 bin 目录添加到系统 PATH 环境变量中。
  • Docker 模式下，该依赖已内置，通常无需额外操作。