Notion Files Management v2.0.0-Beta

v2.0.0-Beta 是一次从 Windows 桌面程序到 Web 应用的重构版本。原 WPF 客户端已迁移为 FastAPI 后端 + Vue 3 前端，支持浏览器访问、Docker 部署、systemd 部署、Windows 单文件迁移包，以及面向第三方系统的开放 API。

这是 Beta 版本，适合自用、内测和小范围部署。正式公网使用前，建议先完成自己的 Notion Integration、反向代理、访问密码和备份策略配置。

主要变化

Web 版重构

• 移除旧版 C# / WPF 桌面 UI，改为浏览器访问的 Web 控制台。
• 后端统一使用 FastAPI，默认监听 18765 端口。
• 前端使用 Vue 3 + Element Plus，提供暗色界面、侧栏导航和响应式页面。
• 配置、日志、缓存和临时文件统一存放在 ${NFM_DATA_DIR}。

核心功能

• 批量扫描并下载 Notion 页面中的图片、视频、PDF、音频和文档。
• 批量上传本地文件或文件夹到 Notion 页面。
• 页面大小查询：统计单个页面中的文件大小。
• 页面大小自动更新：扫描数据源页面并写入指定数字属性。
• 数据源迁移：按属性映射复制源数据源页面到目标数据源。
• 批量去除页面标题后缀。
• 公告、版本检查、设置页和日志查看。

全局任务看板

• 新增统一任务中心，可查看扫描、上传、下载和工具任务。
• 任务支持进度展示、取消、重试和详情展开。
• 下载任务展示文件级进度、速度、ETA 和性能诊断信息。
• 扫描任务可在详情中查看已发现文件列表。

缓存管理

• 上传缓存、下载产物和生成的 zip 统一落到 staging 缓存区。
• 新增缓存页面，可查看、下载、删除、按 TTL 策略清理缓存。
• 缓存项同时显示可读名称和底层存储名，便于排查。
• 自动清理会跳过运行中的任务缓存，避免误删任务正在使用的文件。

开放 API 与 API Key

• 新增第三方开放 API，支持 Authorization: Bearer nfm_... 调用。
• API Key 支持名称、scope 权限、过期时间、启停、删除、限流和最后使用时间。
• API Key 明文只在创建时显示一次，服务端只保存 sha256 hash。
• 长期 API Key 不支持 URL query 参数，避免明文进入日志或 Referer。
• SSE 订阅使用短期 nfmsse_ token：先换 token，再通过 events_token 订阅任务事件。
• CORS 白名单可在 API 密钥页配置，修改后立即生效。

安全加固

• 修复下载 URL 和文件大小探测中的 SSRF 风险。
• 修复上传会话路径越界问题。
• 登录密码比较改为常量时间比较。
• 为主要路由增加 Pydantic 输入边界。
• Session cookie 使用独立名称、24 小时过期，并支持 HTTPS secure cookie 开关。
• API Key scope 严格校验，未知 scope 直接拒绝。

部署与发布

• Docker 多阶段构建：前端构建后由 FastAPI 托管静态文件。
• 提供 docker/docker-compose.yml，默认映射 18765:18765。
• 提供 systemd + venv 部署样例。
• 新增 Windows PyInstaller 单文件打包入口，默认数据目录为 %LOCALAPPDATA%\Notion-Files-Management。
• GitHub Actions 支持在 Windows runner 上构建真正可运行的 Windows exe。
• 新增 VitePress 文档站，覆盖用户指南、部署、开放 API 和版本记录。

获取与启动

Docker

docker compose -f docker/docker-compose.yml up -d --build
docker logs -f nfm

访问：

http://<服务器地址>:18765

首次启动如果没有设置 NFM_PASSWORD，后端会生成初始密码并打印到日志。

源码运行

NFM_DATA_DIR=/tmp/nfm-run NFM_PASSWORD=admin123 \
  .venv/bin/python -m uvicorn app.main:app \
  --app-dir backend --host 127.0.0.1 --port 18765

前端开发模式：

cd frontend
npm run dev

Windows 迁移包

Windows exe 由 GitHub Actions 在 windows-latest 上构建。运行后会启动本地 Web 服务并自动打开浏览器。

默认路径：

• 配置：%LOCALAPPDATA%\Notion-Files-Management\config.json
• 日志：%LOCALAPPDATA%\Notion-Files-Management\logs
• 缓存：%LOCALAPPDATA%\Notion-Files-Management\staging
• 地址：http://127.0.0.1:18765

升级说明

• v2.0.0-Beta 是 Web 重构版，不再复用旧 WPF 桌面界面。
• 默认端口统一为 18765，请同步检查反向代理、防火墙、Docker 端口映射和 systemd 配置。
• Notion API 版本统一为 2025-09-03，包含 Data Sources API。
• 单租户设计保持不变：一个服务实例共享一个 Notion Integration Token 和一个管理员密码。
• Settings 页不暴露发布渠道字段；需要切换 Beta / Status 时使用 NFM_CHANNEL 环境变量。
• API Key 明文无法找回，创建后请立即保存。丢失后只能删除并重新创建。

已验证

• 后端测试：61 passed
• Python 编译检查：通过
• 前端生产构建：通过
• 文档站构建：通过
• 登录、设置、静态资源、基础鉴权和任务 SSE 404 冒烟检查：通过
• 前端生产依赖 audit：无生产依赖漏洞

已知限制

• 目前没有跨任务全局 Notion API 限流；同时运行多个大任务时可能触发 Notion 429 Too Many Requests。
• 下载和上传暂不支持断点续传，大文件中断后需要重新开始。
• 后端暂未对 Notion 页面 URL 做 page id normalize；浏览器页面已有输入规范化，第三方 API 建议传 32 位 page id 或 UUID。
• 单租户模型下，已登录管理员可以读取和修改全局 Notion Token。
• Session cookie 认证接口暂未内置 CSRF token；公网部署建议使用 HTTPS 反向代理，并限制可信访问来源。
• Vite/VitePress 开发服务器依赖链存在 dev server 级 audit 提示；不要把 npm run dev 或 npm run docs:dev 暴露到公网。生产构建产物不受该开发服务器问题影响。