Skip to main content
注意：运行LangChat Pro项目之前，一定要先完成OSS存储服务的配置。
LangChat OSS 是一个统一的对象存储抽象层，基于 x-file-storage 封装，支持多种云存储和本地存储后端的无缝切换。

​
支持的存储平台

平台配置标识说明
本地存储local-plus基于 Nginx 的本地文件存储
MinIOminio开源对象存储，兼容 S3 协议
Amazon S3amazon-s3AWS S3 及所有 S3 兼容存储（RustFS、Ceph 等）
阿里云 OSSaliyun-oss阿里云对象存储
腾讯云 COStencent-cos腾讯云对象存储
七牛云 Kodoqiniu-kodo七牛云对象存储
华为云 OBShuawei-obs华为云对象存储
百度云 BOSbaidu-bos百度云对象存储
又拍云 USSupyun-uss又拍云对象存储
Azure Blobazure-blob微软 Azure Blob 存储
Google Cloudgoogle-cloud-storageGoogle 云存储
FastDFSfastdfs分布式文件系统
FTP / SFTPftp / sftp传统文件传输协议
WebDAVwebdavWebDAV 协议存储

​
快速开始

注意，应该以项目源码目录的 langchat-bootstrap/src/main/resources/application-dev.yml 配置为主，具体查看此目录的配置信息

​
私有化OSS存储

因为Minio的商业化，导致开源版本阉割许多功能，很多客户不再考虑使用Minio部署私有化OSS存储服务，因此逐步将会过渡到国产化的OSS存储平台，这里建议使用 Rustfs 官网地址：RustFS
  1. 如何部署：
LangChat Pro产品已经提供了部署rustfs的docker-compose脚本，具体查看：docs/docker/rustfs/docker-compose.yml 拷贝此文件夹到服务器，然后使用 docker compose up -d 启动此服务，启动成功后访问 http://127.0.0.1:9001/rustfs/console/auth/login 即可看到 Rustfs 控制台。 image-20260214151556681
  1. 启用并配置s3平台
在 application-dev.yml 中配置（只需启用一个平台即可）： 
langchat:
  oss:
    default-platform: amazon-s3
    amazon-s3:
      - platform: amazon-s3
        enable-storage: true
        access-key: your-access-key
        secret-key: your-secret-key
        bucket-name: langchat-oss
        end-point: http://127.0.0.1:9000   # RustFS/S3 兼容服务地址
        region: us-east-1                    # S3 兼容服务通常用 us-east-1
        base-path: langchat/                 # 可选，文件存储路径前缀
        # domain: 可选，自定义访问域名

​
各平台配置详解

​
MinIO

MinIO 是推荐的自部署方案，轻量级且兼容 S3 协议。 
langchat:
  oss:
    default-platform: minio
    minio:
      - platform: minio
        enable-storage: true
        access-key: minioadmin
        secret-key: minioadmin
        bucket-name: langchat-oss
        end-point: http://127.0.0.1:9000/
        # domain: 可选，自定义访问域名
        # base-path: 可选，文件存储的基础路径前缀

​
Amazon S3（含 RustFS 等 S3 兼容存储）

适用于 AWS S3 以及所有兼容 S3 协议的存储服务（RustFS、Ceph、DigitalOcean Spaces 等）。 
langchat:
  oss:
    default-platform: amazon-s3
    amazon-s3:
      - platform: amazon-s3
        enable-storage: true
        access-key: your-access-key
        secret-key: your-secret-key
        bucket-name: langchat-oss
        end-point: http://127.0.0.1:9000   # RustFS/S3 兼容服务地址
        region: us-east-1                    # S3 兼容服务通常用 us-east-1
        base-path: langchat/                 # 可选，文件存储路径前缀
        # domain: 可选，自定义访问域名
RustFS 接入说明：
  • RustFS 完全兼容 S3 协议，使用 amazon-s3 配置即可
  • end-point 填写 RustFS 服务地址
  • region 默认填 us-east-1
  • 需要在 RustFS 中预先创建 bucket

​
本地存储（Nginx 代理）

适合开发环境或不需要云存储的场景，文件存储到本地磁盘，通过 Nginx 提供访问。 
langchat:
  oss:
    default-platform: local-plus
    local-plus:
      - platform: local-plus
        enable-storage: true
        domain: http://127.0.0.1:80/        # Nginx 访问域名
        base-path: langchat-oss/             # Nginx 中的 URL 路径前缀
        storage-path: /data/nginx/html/      # 本地磁盘存储路径
对应的 Nginx 配置： 
server {
    listen 80;
    location /langchat-oss/ {
        alias /data/nginx/html/langchat-oss/;
    }
}

​
阿里云 OSS

langchat:
  oss:
    default-platform: aliyun-oss
    aliyun-oss:
      - platform: aliyun-oss
        enable-storage: true
        access-key: ${ALIYUN_OSS_ACCESS_KEY}
        secret-key: ${ALIYUN_OSS_SECRET_KEY}
        bucket-name: your-bucket-name
        end-point: oss-cn-hangzhou.aliyuncs.com   # 根据实际区域修改
        domain: ${ALIYUN_OSS_DOMAIN}               # 可选，CDN 域名
        base-path: langchat/                        # 可选

​
腾讯云 COS

langchat:
  oss:
    default-platform: tencent-cos
    tencent-cos:
      - platform: tencent-cos
        enable-storage: true
        secret-id: ${TENCENT_COS_SECRET_ID}
        secret-key: ${TENCENT_COS_SECRET_KEY}
        region: ap-guangzhou                        # 根据实际区域修改
        bucket-name: your-bucket-1250000000
        domain: ${TENCENT_COS_DOMAIN}               # 可选
        base-path: langchat/                        # 可选

​
七牛云 Kodo

langchat:
  oss:
    default-platform: qiniu-kodo
    qiniu-kodo:
      - platform: qiniu-kodo
        enable-storage: true
        access-key: ${QINIU_ACCESS_KEY}
        secret-key: ${QINIU_SECRET_KEY}
        bucket-name: your-bucket-name
        domain: ${QINIU_DOMAIN}                     # CDN 域名
        base-path: langchat/                        # 可选

​
模块目录结构

cn.langchat.common.oss/
├── CommonOssAutoConfiguration.java      # 模块自动配置入口
├── component/
│   └── OssComponent.java               # 核心业务组件（上传、签名URL）
├── config/
│   ├── EnableFileStorage.java           # @EnableFileStorage 注解
│   ├── FileStorageAutoConfiguration.java # 文件存储服务自动配置
│   ├── OssConfig.java                   # 缓存与下载配置
│   └── SpringFileStorageProperties.java # 存储平台配置属性
├── dto/
│   ├── OssPlatformEnum.java            # 平台枚举
│   └── OssR.java                       # 文件信息响应对象
├── exception/
│   └── OssException.java               # OSS 操作异常
├── util/
│   ├── ContentTypeUtil.java            # MIME 类型识别工具
│   └── OssUtil.java                    # URL 验证、文件下载、缓存管理
└── wrapper/
    ├── MultipartFileWrapper.java        # MultipartFile 文件包装
    └── MultipartFileWrapperAdapter.java # MultipartFile 适配器

​
核心 API

​
OssComponent

方法说明返回值
upload(file, originalFilename)上传文件FileInfo
uploadAndGetUrl(file, originalFilename)上传并返回签名 URLString
getPrivateUrl(OssR)生成临时签名 URL（24h 有效）String
file 参数支持：MultipartFile、File、byte[]、InputStream。

​
OssUtil

方法说明
downloadAsFile(url)下载远程文件（自动缓存）
downloadAsBytes(url)下载为字节数组
isValidUrl(url)验证 URL 有效性
saveBufferedImageAsFile(image)保存 BufferedImage 为临时文件
createTempFile(prefix, suffix)创建受管理的临时文件
clearCache()清理所有缓存

​
ContentTypeUtil

方法说明
getContentType(fileName)根据文件名获取 MIME 类型
isPreviewable(fileName)判断文件是否可在线预览
isOfficeFile(fileName)判断是否为 Office 文档

​
注意事项

  1. 同时只启用一个平台：虽然可以配置多个平台，但 default-platform 只能指定一个作为默认上传平台
  2. Bucket 需预先创建：MinIO/RustFS/S3 等需要提前创建好 bucket
  3. 环境变量：生产环境建议使用环境变量存储 access-key 和 secret-key，避免明文写入配置文件
  4. 临时文件清理：OssUtil 会自动清理过期临时文件（默认 24 小时），缓存目录位于系统临时目录下的 langchat-oss/