filewizard

环境要求

• Docker 与 docker compose（推荐方式，镜像支持 linux/amd64 和 linux/arm64）
• 手动部署需 Python 3.12
• 手动部署需自行在 PATH 中准备所需转换工具：LibreOffice、Pandoc、Ghostscript、Tesseract、FFmpeg 等（完整列表见
• 使用 GPU 转写需 NVIDIA 显卡并选用 cuda 镜像（仅 amd64）

安装与启动步骤

1. 1获取项目文件

   从 GitHub 克隆仓库，后续要用到仓库里的 docker-compose.yml 模板

   git clone https://github.com/LoredCast/filewizard.git
   cd filewizard

   复制

2. 2调整 compose 配置

   按需修改 docker-compose.yml，将 PUID/PGID 设为挂载目录的所有者（Unraid 常用 99/100）

3. 3启动 Docker 容器

   在 docker-compose.yml 所在目录执行，镜像会从 Docker Hub 拉取并后台运行

   docker compose up -d

   复制

4. 4（可选）手动部署准备

   不使用 Docker 时，需先克隆仓库并进入目录，同时确认转换工具已在 PATH 中

   git clone https://github.com/LoredCast/filewizard.git
   cd filewizard

   复制

5. 5创建虚拟环境

   在项目目录下创建 Python 3.12 虚拟环境，避免污染系统环境

   python3 -m venv venv

   复制

6. 6激活虚拟环境

   Linux/macOS 用 source；Windows 改用 venv\\Scripts\\activate

   source venv/bin/activate

   复制

7. 7安装 Python 依赖

   安装全部依赖；若不需要 TeX、Inkscape、Docling 可改用 requirements_small.txt

   pip install -r requirements.txt

   复制

8. 8手动启动服务

   执行项目自带启动脚本，默认监听 127.0.0.1:8000

   ./run.sh

   复制

关键配置

如何确认成功

浏览器打开 http://localhost:6969（Docker）或 http://127.0.0.1:8000（手动），能看到拖拽上传界面即成功。

常见问题

注意事项

• LOCAL_ONLY 模式下任何人只要能访问端口就能使用应用并修改设置，务必限制网络访问。
• 转换器会处理不受信任的文件，运行容器时只挂载必要的卷。
• 手动部署更新时执行 git pull，再重跑 pip install 并重启，设置与任务历史会保留。
• Docker 与手动部署的端口不同：Docker 默认 6969，手动启动为 8000。