为飞牛 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 |
扫描结果缓存(带关键词规则指纹,规则变化自动重扫) |
双击 run.bat(或 启动QDD.vbs),脚本会自动检测 Python、首次安装依赖、后台静默启动服务,
浏览器打开 http://localhost:9585 即可。
拷给同事:整个文件夹复制过去即可,目标电脑无需安装 Python(自带 runtime\py 便携环境)。
启动后在「⚙ 目录配置」里改成自己电脑上的资料目录即可。
# 需要 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、不需要联网。
- 应用中心 → 手动安装 → 选择对应架构的
.fpk - 桌面出现「QDD 文档分发」图标,点开即用
- 首次登录默认管理员账号 → 立即点右上角「🔑 改密码」
- 「⚙ 目录配置」→「浏览」选择 NAS 资料目录(如
/vol1/1000/文档)→ 保存后自动后台扫描
| 内容 | 路径 |
|---|---|
| 配置 / 用户 / 扫描缓存 | ${TRIM_PKGVAR}/data/(升级、重装不丢) |
| 运行日志 | ${TRIM_PKGVAR}/server.log |
| Python 依赖 | 包内 app/vendor/ |
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)