Skip to content

lllcho/folark

BranchesTags

Repository files navigation

folark

本地优先的个人文档管理工具

folark 是一个本地优先的文档管理 Web 应用，支持多种文件格式的上传、格式转换、预览、搜索和标签管理。所有数据存储在你自己的机器上，无需依赖任何云服务。

Python License

目录

功能特性

  • 📄 多格式支持 — PDF、DOCX、XLSX、PPTX、EPUB、纯文本、图片、音视频、压缩包等 50+ 种文件格式
  • 🔍 全文搜索 — 基于 SQLite FTS5 的全文索引，快速检索文档内容
  • 🏷️ 标签管理 — 自定义标签，灵活分类和过滤文档
  • 👁️ 在线预览 — 支持文档（PDF/DOCX/EPUB）、图片、音频、视频、压缩包等多种格式在线预览
  • 📦 批量导入 — 支持拖拽/点击上传和目录批量导入
  • 🔄 格式转换 — TXT 转 EPUB、DOCX 转 PDF、PPTX 转 PDF，一键转换下载或预览
  • 🔌 插件系统 — 可扩展的插件架构，方便添加新的文件处理器
  • 🔒 可选认证 — 可配置的密码认证，保护你的文档库
  • 🐳 Docker 部署 — 一键 Docker 部署
  • 🌙 深色模式 — 一键切换，状态持久化到本地存储

应用截图

PC 端

文件列表/搜索功能 设置页面 导入页面
文件列表 设置页面 导入页面

移动端

文档列表 设置 后台任务 txt转epub预览
文档列表 设置 后台任务 txt转epub预览

支持的格式

类别 格式
文档 PDF, DOCX, XLSX, PPTX
电子书 EPUB
文本 TXT, Markdown, JSON, YAML, XML, TOML, HTML, CSS, JS, TS, 代码文件等
图片 JPG, PNG, GIF, BMP, WebP, SVG, TIFF
音频 MP3, WAV, FLAC, AAC, M4A
视频 MP4, WebM, OGG, MOV, M4V
压缩包 ZIP, RAR, 7z, TAR, GZ, BZ2, XZ

部署指南

1. Docker 部署（推荐）

这是最简单、最推荐的方式，无需安装 Python 和任何系统依赖。

前置要求

步骤

# 1. 克隆仓库
git clone https://github.com/lllcho/folark.git
cd folark

# 2. （可选）配置环境变量
cp .env.example .env
# 编辑 .env 设置登录密码等（详见下方"配置认证"章节）

# 3. 一键启动
docker compose up -d

服务启动后，浏览器访问 http://localhost:8890 即可使用。

从源码构建

默认会从 ghcr.io 拉取预构建的 Docker 镜像。如果你想从本地 Dockerfile 构建：

docker compose up -d --build

常用管理命令

# 查看容器运行状态
docker compose ps

# 查看实时日志
docker compose logs -f

# 重启服务
docker compose restart

# 停止服务
docker compose down

# 停止服务并删除数据卷（⚠️ 会删除所有数据！）
docker compose down -v

导入宿主机目录中的已有文档

如果你在宿主机上已有大量文档想导入，可以通过卷挂载将目录映射到容器内：

编辑 docker-compose.yml，在 volumes 中添加映射：

volumes:
  - ./data:/app/data
  - /path/to/your/documents:/docs:ro   # 只读挂载，安全导入

然后在 folark 的导入页面中使用服务端目录导入功能，路径填写 /docs。

2. 本地部署（开发/调试）

适合需要在本地开发和调试的场景。

前置要求

  • Python 3.12+
  • uv（推荐，极速包管理器）或 pip

步骤

# 1. 克隆仓库
git clone https://github.com/lllcho/folark.git
cd folark

# 2. 创建虚拟环境并安装依赖
uv venv
uv sync

# 3. （可选）配置环境变量
cp .env.example .env

# 4. 启动服务
./run.sh

服务启动后，访问 http://localhost:8890 即可使用。

提示：日志文件存储在 data/logs/ 目录下，包含 folark.log（所有日志）、folark.access.log（HTTP 请求日志）和 folark.error.log（错误日志）。

常用命令

# 启动服务（端口可在 .env 中通过 PORT 变量修改）
./run.sh

# 或直接指定端口
PORT=8080 ./run.sh

# 安装开发依赖（用于测试、代码检查）
uv sync --group dev

# 运行测试
uv run pytest

# 代码格式检查
uv run ruff check

3. 配置认证

folark 支持可选的密码认证。配置后，访问任何页面都需要先登录。

方法一：通过 .env 文件（适合所有部署方式）

cp .env.example .env

编辑 .env，取消注释并修改：

AUTH_PASSWORD=your_secure_password

方法二：通过 Docker 环境变量（适合 Docker 部署）

直接编辑 docker-compose.yml：

environment:
  AUTH_PASSWORD: your_secure_password

方法三：通过系统环境变量

export AUTH_PASSWORD=your_secure_password
./run.sh

注意：密码为空字符串时，不启用认证，任何人都可以访问。

快速上手

部署完成后，打开浏览器访问 http://localhost:8890（如果启用了认证，先输入密码登录），你会看到 folark 的首页。

1. 导入文档

点击导航栏的 "导入" 按钮，进入导入页面。folark 提供两种导入方式：

方式一：拖拽或点击上传（最常用）

在导入页面的上传区域：

  • 拖拽文件：将文件从文件管理器拖拽到上传区域
  • 点击选择：点击上传区域，在文件选择器中选取文件
  • 支持多文件同时上传

上传后会显示每个文件的上传进度。上传完成后，folark 会自动在后台处理这些文件（提取文本、生成缩略图等），你可以立即返回首页浏览文档，或在"设置 → 后台任务"页面查看处理进度。

方式二：服务端目录导入

将服务器上（或通过 Docker 卷挂载的）已有目录中的文档批量导入：

  1. 在导入页面的"服务端目录导入"部分
  2. 输入服务器上的目录路径（如 /docs 或 /home/user/Documents）
  3. 点击"导入目录"

系统会扫描目录中的所有支持文件，自动入库并触发后台处理。导入进度会实时显示。

⚠️ 注意：出于安全考虑，目录导入受白名单限制。默认情况下仅允许导入 docker-compose.yml 中挂载的路径。如需自定义，可通过 IMPORT_DIR_WHITELIST 环境变量配置。

2. 浏览与管理文档

首页视图

首页以 列表 或 网格 模式展示所有文档（点击工具栏右侧的切换按钮切换视图）。

在文档上可以执行以下操作：

操作 说明
点击文档 打开详情面板，查看文档信息和预览
复选框选择 点击工具栏左侧的"批量选择"按钮进入选择模式
批量操作 选择多个文档后，可以批量添加标签或执行插件任务

筛选与排序

  • 按类型筛选：首页顶部的分类标签（全部/文档/电子书/纯文本/图片/音频/视频/压缩包）
  • 按扩展名筛选：选择大类后，下方会显示该类别下的具体格式按钮
  • 按标签筛选：如果有标签，会在标签区域显示，点击即可筛选
  • 排序：工具栏的排序按钮支持按名称、大小、日期排序（升序/降序）

分页

每页默认显示 20 个文档，底部有分页导航按钮。

3. 搜索文档

首页顶部的搜索栏支持全文搜索，基于 SQLite FTS5 引擎：

  • 输入关键词后按回车或点击搜索图标
  • 支持搜索文档的文本内容、标题、文件名、作者等
  • 搜索时仍可使用类型和标签筛选
  • 清空搜索框后按回车，回到文档列表模式

提示：搜索内容来自文档中提取的文本。上传后系统会自动提取文本，因此新上传的文档可能需要等待后台任务完成才能搜到。

4. 标签管理

标签是组织文档的灵活方式。

创建标签

在 "设置 → 标签管理" 页面：

  1. 输入标签名称
  2. 选择颜色（可选）
  3. 点击"添加"

也可在文档详情面板中直接创建标签。

为文档添加标签

在文档详情面板中：

  1. 点击标签区域的"+"按钮
  2. 从已有标签中选择，或输入新标签名称后回车
  3. 标签会立即添加到文档上

删除标签

  • 从文档移除：在文档详情中点击标签上的 ✕ 按钮
  • 全局删除：在"设置 → 标签管理"中点击标签旁的删除按钮（会同时从所有文档中移除）

5. 格式转换

folark 支持一键将文档转换为其他格式，方便在不同场景下使用。当前支持以下格式转换：

源格式 目标格式 说明
TXT EPUB 纯文本转电子书，自动识别章节并生成目录
DOCX PDF Word 文档转 PDF，保留原始排版
PPTX PDF PowerPoint 转 PDF，保留原始排版

转换后下载

在文档详情面板中，点击 下载 按钮旁的下拉菜单，选择目标格式即可完成转换并下载：

  • TXT 文档可选择下载 EPUB 格式
  • DOCX 文档可选择下载 PDF 格式
  • PPTX 文档可选择下载 PDF 格式

转换后预览

对于暂不支持直接预览的格式，folark 会自动先将其转换为可预览的格式后再展示，无需手动操作。例如 TXT 文件会自动转换为 EPUB 后进行预览。

6. 文档预览与下载

点击任意文档打开详情面板，可以：

  • 查看元数据：文件名、类型、大小、创建时间、文件哈希等
  • 在线预览：点击"预览"按钮，在浏览器中直接查看文档内容
    • PDF：分页预览
    • EPUB：电子书阅读
    • DOCX：文档预览
    • 图片：直接显示
    • 音频/视频：内嵌播放器
    • 压缩包：列出文件清单
    • 文本文件：语法高亮显示
  • 下载：点击"下载"按钮保存原文件
  • 格式转换下载：部分格式支持转换为其他格式下载（如 DOCX 可转换为 PDF，TXT 可转换为 EPUB）

编辑文档信息

在详情面板中，可以直接点击以下字段进行编辑：

  • 标题：修改文档显示标题
  • 摘要：添加或修改文档摘要
  • 作者：编辑作者信息

更新缩略图

支持上传自定义缩略图图片，替代系统自动生成的缩略图。

7. 批量处理任务

folark 使用后台任务系统处理文档（文本提取、缩略图生成、预览生成等）。

查看任务进度

在 "设置 → 后台任务" 页面：

  • 查看所有任务的列表（状态、进度、创建时间）
  • 点击任务查看详情（每个文档的处理状态）

任务控制

  • 暂停：暂停正在运行的任务
  • 恢复：恢复已暂停的任务
  • 取消：取消任务（未处理的文档会跳过）

手动创建任务

在文档列表中选择多个文档后，可以手动触发批量处理任务，如重新提取文本、生成缩略图等。

8. 设置中心

点击导航栏的 "设置 ⚙" 进入设置中心，包含以下功能：

设置项 说明
通用设置 查看存储路径（只读）、修改服务配置（日志级别、上传大小限制、文件类型启用/禁用等）
标签管理 创建、编辑、删除标签
插件管理 查看已注册的插件和处理器，启用/禁用特定处理器
后台任务 查看和管理批量处理任务
关于 查看应用版本、文档统计、数据库大小等

注意：在"通用设置"中修改的配置会保存到数据库中，重启后仍然生效。环境变量中的配置优先级更高。

配置项

所有配置项可通过环境变量或 .env 文件设置：

变量 默认值 说明
PORT 8890 服务端口
DATA_ROOT ./data 数据存储根目录
AUTH_PASSWORD "" 登录密码（为空则不启用认证）
LOG_LEVEL INFO（Docker）/ DEBUG（本地） 日志级别
MAX_UPLOAD_SIZE 524288000 单次上传最大大小（500MB）
IMPORT_DIR_WHITELIST [] 服务端目录导入白名单（JSON 数组格式）

常见问题（FAQ）

Q: 数据存储在哪里？会不会丢失？

所有数据默认存储在项目目录下的 data/ 文件夹中：

  • data/library/ — 上传的文档文件
  • data/folark.db — SQLite 数据库（包含文档索引、标签、设置等）
  • data/logs/ — 日志文件

Docker 部署时，这些数据保存在宿主机 ./data 目录（已在 docker-compose.yml 中配置卷挂载），容器删除后数据依然保留。如果需要备份，直接备份整个 data/ 目录即可。

Q: 如何升级到新版本？

Docker 部署：

# 拉取最新镜像
docker compose pull

# 重新创建容器
docker compose up -d

本地部署：

git pull
uv sync
./run.sh

Q: 上传的文件能保存在其他位置吗？

可以。修改 DATA_ROOT 环境变量指向你想要的目录即可。例如：

# Docker 部署：修改 docker-compose.yml 中的卷映射
volumes:
  - /your/custom/path:/app/data

Q: 如何修改端口号？

设置 PORT 环境变量：

# 本地运行
PORT=8080 ./run.sh

# Docker 部署：修改 docker-compose.yml
ports:
  - "8080:8890"
environment:
  PORT: "8890"

注意 Docker 部署时要同时修改端口映射和 PORT 环境变量。

Q: 文档上传后搜不到？

新上传的文档需要经过后台任务处理（文本提取、索引建立）后才能被搜索到。请到 "设置 → 后台任务" 页面查看处理进度。如果任务一直处于"运行中"状态，请检查日志。

Q: 搜索支持中文吗？

支持。SQLite FTS5 对中文分词基于字符级匹配。中英文混合搜索均可正常工作。

Q: 忘记登录密码怎么办？

如果使用 Docker 部署，修改 docker-compose.yml 中的 AUTH_PASSWORD 环境变量，然后重启：

docker compose restart

如果使用 .env 文件，修改后重启服务即可。

Q: 如何完全重置所有数据？

停止服务后，删除 data/ 目录即可：

# Docker 部署
docker compose down
rm -rf data/
docker compose up -d

# 本地部署
# 先停止服务
rm -rf data/
./run.sh

⚠️ 注意：此操作不可恢复，会删除所有文档和索引数据！

Q: Docker 部署后如何在浏览器访问？

容器启动后，在浏览器地址栏输入 http://服务器IP:8890 即可。如果是本机部署，直接访问 http://localhost:8890。

Q: 同一台机器能跑多个实例吗？

可以。复制项目目录，修改每个实例的 PORT 和 DATA_ROOT 环境变量确保不冲突即可。

🛠️ 技术栈

  • 后端框架: Litestar — 高性能异步 Python Web 框架
  • 数据库: SQLite + aiosqlite + FTS5 全文索引
  • 模板引擎: Jinja2
  • 前端: Alpine.js + HTMX
  • 文档处理: PyMuPDF、python-docx、openpyxl、python-pptx、ebooklib 等
  • 部署: Docker / Docker Compose

项目结构

folark/
├── app/
│   ├── main.py              # 应用入口
│   ├── config.py            # 配置管理
│   ├── database.py          # 数据库管理（SQLite）
│   ├── api/                 # API 路由
│   │   ├── documents.py     # 文档 CRUD
│   │   ├── search.py        # 全文搜索
│   │   ├── tags.py          # 标签管理
│   │   ├── batch_jobs.py    # 批量任务
│   │   ├── plugins.py       # 插件管理
│   │   └── settings.py      # 设置管理
│   ├── plugins/             # 插件系统
│   │   ├── core.py          # 插件核心
│   │   ├── manager.py       # 插件管理器
│   │   └── builtin_plugin/  # 内置插件
│   ├── services/            # 业务逻辑层
│   │   ├── documents.py
│   │   ├── search.py
│   │   ├── ingestion.py
│   │   └── batch_jobs.py
│   └── templates/           # Jinja2 模板
├── static/                  # 静态文件
├── Dockerfile               # Docker 构建
├── docker-compose.yml       # Docker Compose
├── run.sh                   # 启动脚本
└── pyproject.toml           # 项目配置

许可证

本项目基于 AGPL-3.0 许可证开源。

About

电子书文档管理

Resources

Readme
AGPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages