开发配置 | Free FS

1. 拉取代码并导入ide

git pull https://gitee.com/dromara/free-fs.git

导入项目

2. Maven配置

Ctrl + Alt + S 打开配置项，搜索Maven，依次配置如图所示。

Maven配置

Maven的安装和修改配置这里不多赘述，不会的同学可以参考：https://cloud.tencent.com/developer/article/2389319

3. JDK配置

Ctrl + Alt + SHIFT + S 打开配置项，修改项目JDK。

JDK配置

Free FS 使用 jdk17 作为核心开发环境，不支持17以下版本的Java环境。

4. 数据库配置

Free FS 使用 MyBatis Flex 作为 ORM 框架，支持 MySQL 8.0+ 和 PostgreSQL 14+。

创建数据库

在您的 MySQL 实例中创建一个新的数据库：

CREATE DATABASE `free-fs` CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_general_ci';

在您的 PostgreSQL 实例中创建一个新的数据库：

CREATE DATABASE free-fs ENCODING 'UTF8' LC_COLLATE='zh_CN.UTF-8' LC_CTYPE='zh_CN.UTF-8';

初始化数据

导入项目根目录下对应的 SQL 文件到刚创建的数据库中：

MySQL: _sql/mysql/free-fs.sql
PostgreSQL: _sql/postgresql/free-fs_pg.sql

数据库表

修改连接信息

在 fs-admin 模块的 src/main/resources/application-dev.yml 中修改连接信息：

spring:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    url: jdbc:mysql://127.0.0.1:3306/free-fs?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&useSSL=false&zeroDateTimeBehavior=convertToNull&serverTimezone=Asia/Shanghai
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

spring:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    url: jdbc:postgresql://127.0.0.1:5432/free-fs?useUnicode=true&characterEncoding=utf8&useSSL=true&autoReconnect=true&reWriteBatchedInserts=true
    username: postgres
    password: postgres
    driver-class-name: org.postgresql.Driver

注意：使用 PostgreSQL 时，注释掉 MySQL 配置，启用 PostgreSQL 配置即可。两种数据库配置互斥，只能选择其中一种。

5. Redis 配置

在 application-dev.yml 中配置 Redis 连接：

spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: your_password


# Redisson 配置
redisson:
  config: |
    singleServerConfig:
      address: "redis://127.0.0.1:6379"
      password: "your_password"
      database: 0
      timeout: 3000 
      connectionPoolSize: 64
      connectionMinimumIdleSize: 10

6. 存储配置

Free FS 采用插件化存储架构。您可以在管理后台动态切换，但是默认的本地存储是需要配置的。

fs:
  storage:
    local:
      # 本地文件保存地址（物理路径）
      base-path: D:/fs/upload
      # 本地文件映射路径（访问 URL）
      base-url: http://localhost:8080/files

存储配置

本地存储配置详解

本地存储配置包含两个关键参数，它们共同实现了文件的存储和访问：

`base-path` - 文件物理存储路径

作用：指定文件在服务器上的实际存储位置（物理路径）。

配置说明：

Windows 系统：使用绝对路径，如 D:/fs/upload 或 D:\fs\upload
Linux/Mac 系统：使用绝对路径，如 /var/fs/upload 或 /home/user/fs/upload
路径必须存在或应用有权限创建该目录
建议使用绝对路径，避免相对路径带来的不确定性

示例：

# Windows
base-path: D:/fs/upload

# Linux
base-path: /var/fs/upload

# Mac
base-path: /Users/username/fs/upload

`base-url` - 文件访问 URL

作用：指定文件在浏览器中的访问地址（URL 路径）。

配置说明：

格式：http://域名:端口/路径前缀
系统会自动从 base-url 中提取最后一个 / 之后的内容作为 URL 路径前缀
例如：http://localhost:8080/files → 路径前缀为 files
例如：http://example.com/static/uploads → 路径前缀为 uploads

资源映射机制：

系统通过 Spring MVC 的资源处理器将 URL 路径映射到物理路径：

URL 提取：从 base-url 中提取路径前缀（最后一个 / 之后的内容）
- http://localhost:8080/files → 提取 files
- http://localhost:8080/static/uploads → 提取 uploads
路径映射：将 URL 路径映射到物理路径
- 访问 http://localhost:8080/files/2024/01/01/example.jpg
- 实际读取 D:/fs/upload/2024/01/01/example.jpg
配置示例：

fs:
  storage:
    local:
      base-path: D:/fs/upload
      base-url: http://localhost:8080/files

映射关系：

URL：http://localhost:8080/files/2024/01/01/example.jpg
物理路径：D:/fs/upload/2024/01/01/example.jpg

配置示例

开发环境（本地）：

fs:
  storage:
    local:
      base-path: D:/fs/upload
      base-url: http://localhost:8080/files

生产环境（Linux 服务器）：

fs:
  storage:
    local:
      base-path: /var/fs/upload
      base-url: https://example.com/files

使用 Nginx 反向代理：

fs:
  storage:
    local:
      base-path: /var/fs/upload
      base-url: https://example.com/static/files

注意：如果使用 Nginx 反向代理，确保 Nginx 配置了对应的静态文件路径映射。

注意事项

路径权限：
- 确保应用有权限读取和写入 base-path 指定的目录
- Linux/Mac 系统可能需要设置目录权限：chmod 755 /var/fs/upload
路径格式：
- Windows 可以使用 / 或 \，但建议使用 /（更通用）
- Linux/Mac 必须使用 /
- 路径末尾不要加 /
URL 配置：
- base-url 中的域名和端口应与实际访问地址一致
- 如果使用反向代理，应配置代理后的地址
- 路径前缀建议使用简洁的名称（如 files、uploads）
文件访问：
- 上传的文件会按照日期等规则组织在 base-path 目录下
- 通过 base-url 配置的 URL 路径可以访问这些文件
- 系统会自动处理路径映射，无需手动配置
跨平台兼容：
- 开发环境（Windows）和生产环境（Linux）的路径格式不同
- 建议使用环境变量或配置文件区分不同环境

验证配置

配置完成后，可以通过以下方式验证：

启动应用：检查日志中是否有存储配置加载信息
上传文件：在管理后台上传一个测试文件
访问文件：使用浏览器访问文件 URL，确认可以正常访问

关于存储插件的更多配置，以及如何快速开发一个存储平台插件，请参考存储插件页面。

7. 预览配置

关于文件预览插件的配置，请参考文件预览页面。

8. 其他配置

日志配置

可以在 application.yml 中调整日志级别：

logging:
  level:
    com.xdd.fs: debug

MyBatis Flex 配置

如果需要开启 SQL 打印：

mybatis-flex:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

swagger接口文档

#接口文档 配置
springdoc:
  swagger-ui:
    # 文档访问地址
    path: /swagger-ui.html