DeckView

轻量级 Web 文档查看器 + Markdown 在线编辑

中文 | English

一个基于 Python 的本地文档服务器，支持在线预览 PPT、PDF、Word 和 Markdown 文件，并支持在线新建与编辑 Markdown。

可作为自部署笔记软件使用 — 将扫描目录当作你的个人笔记库或团队知识库

---

功能特性

核心功能

功能	描述
目录扫描	指定目录启动，自动扫描所有文档文件
目录树导航	左侧树形结构展示，支持搜索、折叠，宽度可拖拽调整
PPT/Word 预览	自动转换为高清 PDF 并在线预览
PDF 预览	直接预览，支持缩放、翻页、高DPI屏幕优化
Markdown 渲染	支持 GFM 语法，代码高亮
Markdown 编辑	在线新建、编辑 Markdown 文件，实时预览，自动保存
文件上传	支持上传文档到指定目录
实时监听	文件变化时自动刷新目录树（SSE 推送）

预览增强

功能	描述
首页快速预览	点击文件直接在首页右侧预览，无需打开新页面
缩略图导航	PDF/PPT 自动生成高清页面缩略图（600px）
画笔标注	在 PDF/PPT 上绘制标注，支持多种颜色和粗细
橡皮擦	擦除标注内容，支持调整大小
撤销/重做	标注操作支持撤销和重做
高清渲染	支持高 DPI 屏幕（Retina），显示清晰锐利

界面与主题

功能	描述
多主题切换	亮色、暗色、护眼绿、深蓝海洋四种主题
侧边栏调整	拖拽调整侧边栏宽度，自动保存设置
响应式布局	适配不同屏幕尺寸

高级功能

功能	描述
服务注册	可选集成 ServiceAtlas 服务注册中心
缓存管理	自动管理转换缓存，清理孤立文件
无损转换	PPT/Word 转 PDF 使用无损压缩，保持图像质量

使用场景

• 个人笔记 — 在本地或服务器部署，随时通过浏览器记录和查阅笔记
• 团队知识库 — 局域网部署，团队成员共享文档和协作编辑
• 文档资料库 — 集中管理 PDF、PPT、Word、Markdown 等多种格式的资料
• 演示文稿查看 — 在线预览 PPT，支持画笔标注进行讲解

快速开始

环境要求

• Python 3.9+
• LibreOffice（可选，用于 PPT/Word 转 PDF）

安装

# pip 安装（推荐）
pip install .

# 开发模式安装
pip install -e .

启动服务

# 基本用法 - 扫描指定目录
deckview /path/to/your/docs

# 扫描当前目录
deckview .

# 指定端口
deckview /path/to/docs -p 8080

# 允许局域网访问
deckview /path/to/docs --host 0.0.0.0

# 开发模式（代码变化自动重载）
deckview /path/to/docs --reload

启动后访问：http://localhost:8000

CLI 参数

deckview [目录] [选项]

位置参数:
  directory              要扫描的文档目录（默认为当前目录）

选项:
  -p, --port PORT        服务端口（默认: 8000）
  --host HOST            监听地址（默认: 127.0.0.1）
  --no-watch             禁用文件变化监听
  --reload               开发模式：代码变化时自动重载
  -v, --version          显示版本号
  -h, --help             显示帮助

安装 LibreOffice

PPT/Word 转换依赖 LibreOffice：

Ubuntu/Debian	macOS	Windows
sudo apt install libreoffice-core	brew install libreoffice	从 libreoffice.org 下载安装

界面预览

主要操作

• 预览文件：点击左侧文件，在右侧快速预览
• 单独查看：点击"单独查看"按钮，在新页面打开完整查看器
• 画笔标注：点击画笔图标，在 PDF/PPT 上进行标注
• 调整侧边栏：拖拽侧边栏右边缘调整宽度，双击恢复默认
• 切换主题：点击右下角主题按钮切换显示主题
• 新建文件：点击工具栏"📝"按钮新建 Markdown 文件
• 上传文件：点击工具栏"📤"按钮上传文档

项目结构

DeckView/
├── pyproject.toml           # 包配置
└── src/deckview/            # Python 包
    ├── main.py              # FastAPI 入口
    ├── cli.py               # CLI 入口
    ├── api/library.py       # API 路由
    ├── core/config.py       # 配置管理
    ├── services/            # 业务逻辑层
    │   ├── library.py       # 文件扫描服务
    │   ├── watcher.py       # 文件监听服务
    │   ├── conversion.py    # PPT/Word → PDF（无损压缩）
    │   ├── thumbnail.py     # 缩略图生成
    │   ├── cache_manager.py # 缓存管理
    │   └── registry.py      # ServiceAtlas 服务注册
    └── web/                 # 前端资源
        ├── templates/       # HTML 模板
        └── static/          # CSS/JS

API 接口

API 文档：http://localhost:8000/api/docs

接口	方法	说明
/api/library/tree	GET	获取目录树
/api/library/files/{id}	GET	获取文件信息
/api/library/files/{id}/pdf	GET	获取 PDF 文件
/api/library/files/{id}/thumbnails/{page}	GET	获取缩略图
/api/library/files/{id}/content	GET/PUT	获取/更新 Markdown 内容
/api/library/upload	POST	上传文件
/api/library/create	POST	新建 Markdown 文件
/api/library/events	GET	SSE 事件流（文件变化通知）
/health	GET	健康检查

环境变量

变量	默认值	说明
DECKVIEW_HOST	127.0.0.1	监听地址
DECKVIEW_PORT	8000	服务端口
DECKVIEW_DATA_DIR	~/.deckview	数据目录（缓存 PDF 和缩略图）
LIBREOFFICE_PATH	soffice	LibreOffice 路径
CONVERSION_TIMEOUT	120	转换超时时间（秒）
DECKVIEW_BASE_PATH	（空）	URL 前缀，用于反向代理场景

反向代理配置（Base Path）

当 DeckView 通过认证网关（如 Aegis）代理访问时，需要设置 DECKVIEW_BASE_PATH 环境变量，使静态资源和 API 请求正确工作。

场景说明：

• 直接访问：http://localhost:8080/ → 不需要设置
• 通过网关代理访问：http://aegis:8000/s/deckview/ → 需要设置 DECKVIEW_BASE_PATH=/s/deckview

启动示例：

# 直接访问模式（不设置）
deckview /path/to/docs --host 127.0.0.1 --port 8080

# 通过 Aegis 网关代理访问（设置 BASE_PATH）
DECKVIEW_BASE_PATH=/s/deckview deckview /path/to/docs --host 127.0.0.1 --port 8080

注意：设置 DECKVIEW_BASE_PATH 后，直接访问 http://localhost:8080/ 将无法正常工作，因为静态资源和 API 路径会变成 /s/deckview/static/... 和 /s/deckview/api/...。请根据实际访问方式选择是否设置

数据目录

DeckView 的缓存数据存储在 ~/.deckview/ 目录：

~/.deckview/
├── converted/      # PPT/Word 转换后的 PDF 文件
├── thumbnails/     # 页面缩略图
├── cache/          # 其他缓存
└── lo_profile/     # LibreOffice 高质量导出配置

清除缓存：

# 清除所有缓存（重新转换所有文件）
rm -rf ~/.deckview/converted/* ~/.deckview/thumbnails/*

注意事项

• 默认只监听 127.0.0.1，仅本地访问
• 使用 --host 0.0.0.0 允许外部访问时请注意安全
• 作为笔记软件使用时：建议仅在内网部署，或配合反向代理添加认证
• 确保扫描目录具有写权限，以支持新建和编辑功能
• PPT/Word 转换依赖 LibreOffice，首次转换可能较慢
• 转换使用无损压缩，生成的 PDF 文件较大但图像质量高
• 建议定期备份笔记目录中的重要文件

未来计划

PPT 动画播放支持

当前 PPT 文件通过转换为 PDF 进行预览，无法保留动画和转场效果。未来可能的改进方案：

方案	说明	优点	缺点
OnlyOffice	集成 OnlyOffice Document Server	开源免费，支持演示模式	部署复杂，资源占用大
Collabora Online	基于 LibreOffice 的在线版本	开源，支持演示模式	复杂动画支持有限
PPTX → 视频	将 PPT 导出为 MP4 视频	动画效果完整保留	失去交互性
商业 SDK	Aspose.Slides 等商业方案	高还原度，HTML5 输出	需要付费授权

如有需要，欢迎提交 Issue 讨论具体需求。

许可证

MIT License

---

如果这个项目对你有帮助，欢迎 Star 支持！