Notion Files Management
Notion Files Management 是一个面向 Notion 文件管理的 Web 工具。它可以批量下载 Notion 页面里的附件，也可以把本地文件或文件夹批量上传到 Notion，并提供页面大小统计、数据源迁移、批量清理标题后缀等辅助工具。
项目采用浏览器界面 + 本地或服务器后端的方式运行。你可以把它部署在自己的服务器上，通过浏览器访问；也可以使用 Windows exe 在本机启动后端和 Web Console。
适合谁使用
- 想把 Notion 页面里的图片、视频、PDF、音频、文档等文件集中备份到本地的人
- 需要把大量本地文件整理上传到 Notion 页面或数据库的人
- 需要统计 Notion 页面或数据源中文件体积的人
- 想用自动化脚本调用 NFM 后端 API 的高级用户
主要功能
| 功能 | 说明 |
|---|---|
| 批量下载 | 扫描 Notion 页面中的文件，选择后下载单文件或打包 ZIP |
| 批量上传 | 上传文件或文件夹，保留目录结构并写入 Notion |
| 页面大小查询 | 统计单个页面中的文件数量和总大小 |
| 页面大小自动更新 | 扫描数据源页面，并把文件大小写入指定数字属性 |
| 数据源迁移 | 按映射把一个数据源的属性复制到另一个数据源 |
| 批量去后缀 | 移除一批页面标题中的相同尾巴 |
| 任务看板 | 查看扫描、上传、下载等长任务的状态和进度 |
| API 密钥 | 为第三方程序创建带权限范围的 API Key |
推荐阅读顺序
- 快速开始：安装、启动、登录和第一次连接 Notion。
- 配置说明：端口、数据目录、密码、Notion Token、缓存和 API Key。
- 常见问题：端口占用、忘记密码、Windows exe 数据位置、第三方 API 等问题。
部署方式
| 方式 | 适合场景 |
|---|---|
| Docker | 推荐给服务器部署，升级和迁移最省心 |
| systemd + Python venv | 适合熟悉 Linux 运维、希望手动管理运行环境的用户 |
| Windows exe | 适合从旧桌面版迁移，或只想在 Windows 本机临时使用 |
| 本地开发模式 | 适合开发者调试前后端 |
默认后端/API 端口统一为 18765。本地开发时，前端 Vite 默认运行在 5173，并把 /api 请求代理到 127.0.0.1:18765。
数据和隐私
NFM 是自部署工具。你的 Notion Token、登录密码、缓存文件、日志和 API Key hash 默认保存在自己的运行环境中，不会上传到 NFM 项目维护者的服务器。
API Key 明文只在创建时显示一次，之后只保存 hash。第三方调用应使用 Authorization: Bearer nfm_... 请求头，不要把长期 API Key 放进 URL。
用户文档与开发文档
这里的 docs/ 面向普通用户，说明如何安装、配置和使用 NFM。
仓库里的 AI/ 目录是给开发协作和 Agent 交接使用的工程文档，不作为用户文档入口。