环境准备 | Free FS

软件要求

在开始运行 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 文档预览功能，请按照以下步骤安装和配置。

Windows 环境（开箱即用）

项目根目录已包含 LibreOfficePortable 便携版（位于 项目根目录/LibreOfficePortable）
无需安装 LibreOffice，系统会自动使用内置版本
如需使用自定义路径，可通过配置项覆盖

Linux/Mac 环境（需要安装）

Linux

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libreoffice

CentOS/RHEL:

sudo yum install libreoffice

验证安装:

libreoffice --version

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

如果 LibreOffice 安装在其他位置，必须通过配置项指定。

macOS

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

如果 LibreOffice 安装在其他位置，必须通过配置项指定。

配置 LibreOffice 路径

在 application.yml 中配置 LibreOffice 的安装路径：

fs:
  preview:
    office:
      # 是否启用 Office 转换
      enabled: true
      # LibreOffice 安装路径
      # Windows 环境通常不需要配置（使用内置版本）
      # Linux/Mac 环境如果安装在默认路径也不需要配置
      # 
      # 仅在以下情况需要配置：
      # 1. Windows 环境想使用本地安装的 LibreOffice
      # 2. Linux/Mac 环境 LibreOffice 安装在非默认路径
      # Windows: C:/Program Files/LibreOffice
      # Linux: /usr/lib/libreoffice
      # Mac: /Applications/LibreOffice.app/Contents
      office-home: /opt/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 目录
转换缓存目录是否有写入权限

注意事项：

Windows 开发者：确保项目根目录下有 LibreOfficePortable 文件夹，然后直接运行即可
Linux/Mac 开发者：首次运行前请确保已安装 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 (接口测试)