环境准备

软件要求

在开始运行 Free FS 服务端之前，请确保你的系统已安装以下软件：

• JDK 17+ (推荐使用 OpenJDK 或 Oracle JDK)
• Maven 3.8+ (用于依赖管理和构建)
• MySQL 8.0+ 或 PostgreSQL 14+ (核心关系型数据库，二选一)
• Redis (用于缓存、Session 和分片上传状态存储)
• LibreOffice (可选，用于 Office 文档预览功能)

LibreOffice 安装与配置

LibreOffice 是用于 Office 文档（Word、Excel、PowerPoint）转 PDF 预览的必需组件。如果你需要使用 Office 文档预览功能，请按照以下步骤安装和配置。

安装 LibreOffice

Windows

1. 访问 LibreOffice 官网 下载 Windows 版本
2. 运行安装程序，按照提示完成安装
3. 默认安装路径：C:/Program Files/LibreOffice

Linux

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libreoffice

CentOS/RHEL:

sudo yum install libreoffice

验证安装:

libreoffice --version

默认安装路径：/usr/lib/libreoffice

macOS

1. 访问 LibreOffice 官网 下载 macOS 版本
2. 将 LibreOffice.app 拖拽到 Applications 文件夹
3. 默认安装路径：/Applications/LibreOffice.app/Contents

配置 LibreOffice 路径

安装完成后，需要在 application.yml 中配置 LibreOffice 的安装路径：

fs:
  preview:
    office:
      # 是否启用 Office 转换
      enabled: true
      # LibreOffice 安装路径（根据你的系统选择）
      # Windows: C:/Program Files/LibreOffice
      # Linux: /usr/lib/libreoffice
      # Mac: /Applications/LibreOffice.app/Contents
      office-home: C:/Program Files/LibreOffice
      # 进程池大小（建议根据服务器性能调整）
      pool-size: 2
      # 任务执行超时（毫秒）
      task-execution-timeout: 120000
      # 任务队列超时（毫秒）
      task-queue-timeout: 30000
      # 最大任务数
      max-tasks-per-process: 200
      # 转换缓存目录
      cache-path: /tmp/office-convert

验证配置

启动应用后，检查日志确认 LibreOffice 是否成功启动：

LibreOffice 进程池启动成功: home=C:/Program Files/LibreOffice, poolSize=2

如果启动失败，请检查：

• LibreOffice 安装路径是否正确
• 路径中是否包含中文字符（建议使用英文路径）
• 应用是否有权限访问 LibreOffice 目录
• 转换缓存目录是否有写入权限

常见问题

Q: 为什么需要 LibreOffice？

A: LibreOffice 用于将 Office 文档（Word、Excel、PowerPoint）转换为 PDF 格式，以便在浏览器中预览。如果不使用 Office 文档预览功能，可以不安装 LibreOffice。

Q: 可以禁用 Office 转换功能吗？

A: 可以，在配置文件中设置 fs.preview.office.enabled=false 即可禁用。

Q: 转换失败怎么办？

A: 检查：

• LibreOffice 是否正确安装
• 配置路径是否正确
• 转换缓存目录是否有写入权限
• 查看应用日志中的详细错误信息

Q: 如何提高转换性能？

A: 可以调整以下参数：

• 增加 pool-size（进程池大小）
• 增加 max-tasks-per-process（每个进程的最大任务数）
• 使用 SSD 存储作为转换缓存目录

开发工具推荐

• IntelliJ IDEA (安装 Lombok 插件)
• Navicat 或 DBeaver (数据库管理)
• Postman 或 Apifox (接口测试)