Skip to content

About

轻量文档分发管理工具:多目录扫描、自动分类、全类型预览、多用户授权,适合团队在 NAS 上共享资料

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

QDD · 文档分发管理(QDocument Distributor)

为飞牛 fnOS 打造的本地文档分发管理工具:把散落在各个目录里的资料集中索引,用一个页面完成 「搜索 → 分类 → 预览 → 下载 / 导出 / 收集新文件」。

纯本地运行:不上传任何文件到外网,索引、账号、配置全部保存在本机 / NAS 的应用数据目录里。


项目来历

工作中经常要查各种资料,几位同事也有同样需求,而且大家查的往往是同一批文件。于是想做一个窗口: 能搜索现有资料、能导出资料清单、也能收集新收到的资料 —— 这就是 QDD。

功能

索引与查找

  • 多目录扫描:界面上添加多个资料目录,后台扫描合并展示,支持扫描深度限制、排除隐藏文件、定时自动扫描
  • 自动分类:按扩展名归类为 文档 / 图片 / 视频 / 音频 / 压缩包 / 代码 / 安装包(归属可配置)
  • 关键词分类:按文件名关键词归类,内置 15 组常用规则(合同、证书、发票、身份证、标书方案、测算预算、请示汇报、表格台账、会议纪要、通知公告、车辆设备、考核验收、现场图片、招标采购、专利证书),全部可增删改
  • 多条件筛选:文件名/路径搜索、类型分类、关键词分类、日期范围,输入即筛
  • 文件夹导航:搜索时列出名字匹配的文件夹,点击直接进入;列表展示每个文件所属目录
  • 分类统计:顶部卡片展示各类数量,点卡片即筛选该类别
  • 表头排序:文件名 / 所属文件夹 / 类型 / 关键词分类 / 大小 / 修改时间

预览与获取

  • 全类型在线预览:图片、PDF、Word(docx)、Excel(xlsx)、PPT(pptx)、文本/代码、音视频,预览库全部本地化,无需外网
  • 单文件下载:带路径白名单校验,防目录穿越
  • 批量打包下载:勾选多个文件 → 服务端后台打包,右下角实时显示「打包中 x/y」,完成后自动下载,可取消
  • 导出 Excel:勾选了就只导出勾选的资料;未勾选时导出当前筛选结果(文件名、相对路径、扩展名、类型分类、关键词分类、大小、修改时间)

收集与协作

  • 文件上传:上传到独立「上传目录」,不污染源目录;大文件显示上传进度(百分比、已传/总大小、当前第几个),可取消
  • 账号与权限:管理员 / 普通用户两级;普通用户仅能看到被授权的目录
  • 改密码:任何账号都可在界面自助修改密码
  • 帮助与关于:界面右上角「❓ 帮助」内置使用说明与版本信息

界面入口

入口 说明
飞牛桌面图标 端口模式 iframe(<当前主机>:9585),局域网 IP、公网域名:端口、飞牛统一中继都可用
🌐 网页打开 在浏览器新标签页打开直连地址 http://当前主机:9585
局域网直连 http://NAS_IP:9585(管理员可在「目录配置 → 网页端口」另设直连端口,保存即生效)
公网 / 中继 路由器端口转发 9585 后 http://域名:9585 直开(IPv4 / IPv6 双栈都支持);或开启飞牛 fnConnect 中继随桌面远程访问

目录结构

QDocument Distributor/
├── run.bat / run.sh / 启动QDD.vbs   # Windows / Linux 直跑启动脚本
├── requirements.txt
├── VERSION                          # fpk 发版版本号(唯一来源)
├── LICENSE                          # MIT
├── README.md / 使用说明.md / CHANGELOG.md
├── runtime/py/                      # 内置便携 Python(仅 Windows 直跑用,打包时剔除)
├── backend/
│   ├── server.py                    # 服务入口:IPv4+IPv6 双栈 TCP + Unix 套接字双监听
│   ├── main.py                      # FastAPI 应用(路由 / 鉴权 / 网关前缀 / 打包任务)
│   ├── config.py                    # 配置读写 + 内置默认关键词规则
│   ├── scanner.py                   # 目录扫描 & 分类
│   ├── exporter.py                  # Excel 导出
│   ├── users.py                     # 用户、密码(sha256)
│   └── static/
│       ├── index.html               # 前端单页(Vue3 + Element Plus)
│       ├── favicon.png
│       └── vendor/                  # 本地前端依赖(vue / element-plus / axios / 预览库)
├── fpk/                             # 飞牛 fpk 打包模板(manifest / cmd / config / ui / wizard)
├── scripts/build-fpk.sh             # 双架构 fpk 构建脚本
└── dist/                            # fpk 产物

运行后生成的数据文件(Windows 在 backend/,fpk 在应用数据目录):

文件 内容
qdd_config.json 扫描目录、类型映射、关键词规则等
users.json 账号与授权目录
scan_cache.json 扫描结果缓存(带关键词规则指纹,规则变化自动重扫)

快速启动(Windows)

双击 run.bat(或 启动QDD.vbs),脚本会自动检测 Python、首次安装依赖、后台静默启动服务, 浏览器打开 http://localhost:9585 即可。

拷给同事:整个文件夹复制过去即可,目标电脑无需安装 Python(自带 runtime\py 便携环境)。 启动后在「⚙ 目录配置」里改成自己电脑上的资料目录即可。

部署到飞牛 NAS(fpk)

构建

# 需要 fnpack(默认取 D:/CODE/fnpack/fnpack.exe,可用 FNPACK 指定)
./scripts/build-fpk.sh          # x86 + arm 双架构
./scripts/build-fpk.sh x86      # 仅 x86
./scripts/build-fpk.sh arm      # 仅 arm64

产物:dist/qdd-<版本>-<arch>.fpk。版本号取自 VERSION,发版后必须把 patch +1 (飞牛对同版本号覆盖安装会走「跳过」路径并报 10016)。

Python 依赖以离线 wheel 打进包内 app/vendor/(按 cp311 / manylinux 下载),NAS 侧不需要 pip、不需要联网。

安装

  1. 应用中心 → 手动安装 → 选择对应架构的 .fpk
  2. 桌面出现「QDD 文档分发」图标,点开即用
  3. 首次登录默认管理员账号 → 立即点右上角「🔑 改密码」
  4. 「⚙ 目录配置」→「浏览」选择 NAS 资料目录(如 /vol1/1000/文档)→ 保存后自动后台扫描

数据与日志位置

内容 路径
配置 / 用户 / 扫描缓存 ${TRIM_PKGVAR}/data/(升级、重装不丢)
运行日志 ${TRIM_PKGVAR}/server.log
Python 依赖 包内 app/vendor/

手动部署(不用 fpk)

cd backend
pip3 install -r ../requirements.txt
python3 server.py --port 9585                      # 仅 TCP
python3 server.py --socket /path/to/qdd.sock        # 额外监听 Unix 套接字(网关入口)

server.py 支持 --port、--socket、--data-dir(或用环境变量 QDD_DATA_DIR)。

真机自检

curl http://NAS_IP:9585/api/health
curl --unix-socket /path/to/qdd.sock http://localhost/api/health

返回 {"ok":true,...,"version":"x.y.z"} 即正常。

关键实现说明(改代码前先看)

  • 网关前缀:/app/qdd 前缀由后端中间件剥离(旧版套接字接入兼容保留); 桌面入口现与 fnMonitor 同款端口模式——iframe 指向 <当前主机>:9585, 局域网 IP / 公网域名:端口 / 飞牛统一中继三条链路天然可用; 前端所有资源与 API 一律用相对路径,<head> 里有同步 <base> 守卫。
  • 双端口监听:桌面入口端口(manifest service_port)常驻保活,桌面图标永不失效; 管理员改「网页端口」只叠加/关闭额外监听(TcpManager 运行期热切换, uvicorn bind_socket 失败会 sys.exit 拖崩线程——已改手工 bind)。
  • 启动看门狗:12 秒内 Vue 未挂载即把失败的具体资源 URL、版本号、重试按钮显示在页面上,避免白屏无从排查。
  • 首屏聚合:首屏只发一个 /api/bootstrap 请求(网关并发转发不可靠,多个请求会互相悬住)。
  • 扫描不阻塞启动:服务先监听,扫描在后台线程进行,前端轮询 /api/scan_status。
  • 批量下载:POST /api/zipjob 建后台任务 → 轮询 /api/zipjob/{id} 拿进度 → /download 取包; 临时 zip 存放于数据目录,1 小时自动清理。
  • 鉴权:登录换取内存 token,前端 axios 拦截器统一加 X-QDD-Token 头; 文件下载 / 导出走 POST + blob(window.open 无法携带请求头,长 URL 还会被网关 414 拒绝)。

端口与状态码

场景 说明
默认端口 9585(管理员可在「目录配置 → 网页端口」热修改,PORT 环境变量仅作首次缺省)
/api/health 健康检查,返回版本号
401 未登录 / 会话过期 / 登录密码错误
403 无权限访问该目录
414 网关拒绝超长 URL(下载/导出已改 POST,正常不会再出现)

技术栈

  • 后端:FastAPI + uvicorn + openpyxl(纯标准库业务逻辑,无数据库)
  • 前端:Vue 3 + Element Plus + axios,单文件页面,依赖全部本地 vendor,可离线
  • 存储:直接读写文件系统,JSON 持久化配置与缓存
  • 打包:飞牛 fnpack(fpk),双架构 x86_64 / aarch64

版本历史

完整变更见 CHANGELOG.md。

版本 要点
v1.0.6 三处前端 / 打包修复合并:① 中继模式点「🌐 网页打开」不再硬拼 :9585,改为 window.location.href;② 保存配置不再误弹「端口已切换」引导(中继子域名不带端口,URL 又硬拼 HTTP,整段移除);③ 修复应用中心显示版本 1.0.0 / 发布者不一致(源 fpk/manifest 的 version 行此前从未被构建脚本更新,distributor 也已统一 Misite齊)
v1.0.5 修复公网域名 + 端口打不开 —— 后端监听改为 IPv4 / IPv6 双栈(AF_INET6 + IPV6_V6ONLY=0 单 socket 同时收 IPv4 / IPv6,fnMonitor v2.6.4 同款;系统无 IPv6 自动回退 AF_INET)
v1.0.4 修复中继 / 公网打不开 —— 移植 fnMonitor 的「桌面入口数据库同步」:启动时把监听端口回写进 fnOS PostgreSQL(appcenter.app_service + trim_sac.entry),把旧套接字模式的非端口入口整体拉齐为端口模式
v1.0.3 桌面接入改为端口模式(ui/config port: 9585,iframe 指向 <当前主机>:9585);网页直连端口可自定义(默认 9585,保存立即生效)
v1.0.2 上传进度、批量打包进度、导出所选资料、网页打开、帮助与关于;下载/导出改 POST 解决 414 / 401
v1.0.1 修复批量下载 / 导出经网关 414+401、fpk 首次安装内置关键词规则丢失、扫描缓存加规则指纹
v1.0.0 首个 fpk 版本:多目录扫描、按类型 + 关键词自动分类、全类型在线预览、批量打包导出、多用户目录授权

许可

MIT License © 2026 Misite齊(@MisiteQ)

About

轻量文档分发管理工具:多目录扫描、自动分类、全类型预览、多用户授权,适合团队在 NAS 上共享资料

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages