S3 sdk (#6215)

* refactor: fastgpt object storage & global proxy (#6155) * feat: migrate to fastgpt storage sdk * chore: rename env variable * chore: move to sdk dir * docs: object storage * CHORE * chore: storage mocks * chore: update docker-compose * fix: global proxy agent * fix: update COS proxy * refactor: use fetch instead of http.request * fix: axios request base url * fix: axios proxy request behavior * fix: bumps axios * fix: patch axios for proxy * fix: replace axios with proxied axios * fix: upload txt file encoding * clean code * fix: use "minio" for minio adapter (#6205) * fix: use minio client to delete files when using minio vendor (#6206) * doc * feat: filter citations and add response button control (#6170) * feat: filter citations and add response button control * i18n * fix * fix test * perf: chat api code * fix: workflow edge overlap and auto-align in folded loop nodes (#6204) * fix: workflow edge overlap and auto-align in folded loop nodes * sort * fix * fix edge * fix icon * perf: s3 file name * perf: admin get app api * perf: catch user error * fix: refactor useOrg hook to use debounced search key (#6180) * chore: comment minio adapter (#6207) * chore: filename with suffix random id * perf: s3 storage code * fix: encode filename when copy object --------- Co-authored-by: archer <545436317@qq.com> * fix: node card link * json * perf: chat index; * index * chat item soft delete (#6216) * chat item soft delete * temp * fix * remove code * perf: delete chat item --------- Co-authored-by: archer <545436317@qq.com> * feat: select wheather filter sensitive info when export apps (#6222) * fix some bugs (#6210) * fix v4.14.5 bugs * type * fix * fix * custom feedback * fix * code * fix * remove invalid function --------- Co-authored-by: archer <545436317@qq.com> * perf: test * fix file default local upload (#6223) * docs: improve object storage introduction (#6224) * doc --------- Co-authored-by: roy <whoeverimf5@gmail.com> Co-authored-by: heheer <heheer@sealos.io> Co-authored-by: Finley Ge <32237950+FinleyGe@users.noreply.github.com>
2026-02-27 01:02:22 +08:00 · 2026-01-09 18:25:02 +08:00
parent 56ec86e2fe
commit c93c3937e1
281 changed files with 11562 additions and 2527 deletions
--- a/document/content/docs/introduction/development/docker.mdx
+++ b/document/content/docs/introduction/development/docker.mdx
@@ -200,7 +200,14 @@ bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh) --region=global --ve

 ### 3. 修改环境变量

-1. 修改 yml 文件顶部的`S3_EXTERNAL_BASE_URL`变量，改成 S3 的可访问地址（要求使用者可以访问）
+1. 修改`STORAGE_EXTERNAL_ENDPOINT`变量，改成客户端和FastGPT 服务均可访问的地址。
+
+**重要：**
+
+> 填入的地址不可为`127.0.0.1`或者`localhost`等本地回环地址，可填 Docker 部署时的宿主机本地IP，但是需要把宿主机固定为静态 IP；或者统一为一个固定域名；目的是为了避免对象存储签名 URL 时，签发与上传的 URL 不一致导致的 403 错误。
+>
+> 具体查看 [对象存储配置及常见问题](/docs/introduction/development/object-storage)
+
 2. 按照您的需求自行修改环境变量，建议在生产环境修改账号密码等。
 3. 对于 Zilliz 版本 还需要获取密钥，参考 [部署 Zilliz 版本获取账号和密钥](#部署-zilliz-版本获取账号和密钥)

@@ -219,9 +226,9 @@ docker-compose up -d

 ### 6. 访问 FastGPT

-可通过第二步开放的端口/域名访问 FastGPT。  
-登录用户名为 `root`，密码为`docker-compose.yml`环境变量里设置的 `DEFAULT_ROOT_PSW`。  
-每次重启容器，都会自动初始化 root 用户，密码为 `1234`（与环境变量中的`DEFAULT_ROOT_PSW`一致）。  
+可通过第二步开放的端口/域名访问 FastGPT。
+登录用户名为 `root`，密码为`docker-compose.yml`环境变量里设置的 `DEFAULT_ROOT_PSW`。
+每次重启容器，都会自动初始化 root 用户，密码为 `1234`（与环境变量中的`DEFAULT_ROOT_PSW`一致）。

 ### 7. 配置模型

--- a/document/content/docs/introduction/development/meta.json
+++ b/document/content/docs/introduction/development/meta.json
@@ -8,6 +8,7 @@
    "intro",
    "docker",
    "configuration",
+    "object-storage",
    "faq",
    "signoz",
    "modelConfig",
--- a/document/content/docs/introduction/development/object-storage.mdx
+++ b/document/content/docs/introduction/development/object-storage.mdx
@@ -0,0 +1,98 @@
+---
+title: 对象存储配置及常见问题
+description: 如何通过环境变量配置并连接个各厂商的对象存储，以及常见的配置问题
+---
+
+import { Alert } from '@/components/docs/Alert';
+import FastGPTLink from '@/components/docs/linkFastGPT';
+
+## 对象存储服务配置介绍
+
+这里提供了 FastGPT 目前支持的对象存储厂商，包括自部署的 MinIO、AWS S3、阿里云 OSS 和腾讯云 COS 的环境变量配置说明
+
+### 通用且必需的环境变量
+
+> - 不支持对临时身份校验密钥的支持，比如 STS 等，请自行保证服务的安全性。
+> - 不支持对私有桶的复用，如果把私有桶名和公开桶名设置为同一个的话，请保证存储桶的策略至少为【公开读私有写】
+
+- `STORAGE_VENDOR` 该变量为一个枚举值，可选值为：`minio`、`aws-s3`、`oss` 和 `cos`。
+- `STORAGE_REGION` 提供的对象存储服务所在的地区如 `us-east-1` 等，具体请根据服务厂商所提供的地区来填写；如果是自部署的 MinIO 等服务这个值可随意填写。
+- `STORAGE_ACCESS_KEY_ID` 服务访问密钥的 Access Key ID
+- `STORAGE_SECRET_ACCESS_KEY` 服务访问密钥的 Secret Access Key
+- `STORAGE_PUBLIC_BUCKET` FastGPT 公开资源存储桶桶名
+- `STORAGE_PRIVATE_BUCKET` FastGPT 私有资源存储桶桶名
+
+### 自部署的 MinIO 和 AWS S3
+
+> MinIO 这类产品对 AWS S3 协议支持比较完整，因此使用 Minio 和AWS S3 配置几乎可以是相同的，只是因为服务商提供和自部署的区别，会有额外的配置。
+> 因此理论上任何对 AWS S3 协议的支持程度至少和 MinIO 相当的对象存储服务都可以使用，比如 SeaweedFS、RustFS 等。
+
+- `STORAGE_S3_ENDPOINT` 内网连接地址，可以是容器 id 连接，比如 `http://fastgpt-minio:9000`
+- `STORAGE_EXTERNAL_ENDPOINT` 一个**服务器**和**客户端**均可访问到存储桶的地址，可以是固定的宿主机 IP 或者域名，注意不要填写成 127.0.0.1 或者 localhost 等本地回环地址(因为容器里无法使用)。该地址用于签发文件上传 URL 时使用。
+- `STORAGE_S3_FORCE_PATH_STYLE` 【可选】虚拟主机风格路由或路径路由风格，其中如果厂商填写了 `minio` 的话，该值被固定为 `true`
+- `STORAGE_S3_MAX_RETRIES` 【可选】请求最大尝试次数，默认为 3 次
+
+**完整示例**
+
+> 如果使用的是 Sealos 的对象存储服务请将 `STORAGE_VENDOR` 填写为 `aws-s3`
+
+```dotenv
+STORAGE_VENDOR=minio
+STORAGE_REGION=us-east-1
+STORAGE_ACCESS_KEY_ID=your_access_key
+STORAGE_SECRET_ACCESS_KEY=your_secret_key
+STORAGE_PUBLIC_BUCKET=fastgpt-public
+STORAGE_PRIVATE_BUCKET=fastgpt-private
+STORAGE_EXTERNAL_ENDPOINT=http://127.0.0.1:9000
+STORAGE_S3_ENDPOINT=http://127.0.0.1:9000
+STORAGE_S3_FORCE_PATH_STYLE=true
+STORAGE_S3_MAX_RETRIES=3
+```
+
+### 阿里云 OSS
+
+> - [跨域配置](https://help.aliyun.com/zh/oss/user-guide/configure-cross-origin-resource-sharing/?spm=5176.8466032.console-base_help.dexternal.1bcd1450Wau6J6#b58400ec36rqf)
+
+- `STORAGE_OSS_ENDPOINT` 阿里云对象存储连接主机名，厂商提供的默认值一般都是 `{地区}.aliyuncs.com`，如 `oss-cn-hangzhou.aliyuncs.com`；注意，如果配置了自定义域名的话也填在这里，比如 `your-domain.com`
+- `STORAGE_OSS_CNAME` 是否开启自定义域名
+- `STORAGE_OSS_SECURE` 是否开启了 TLS，如果域名没有认证证书的话，请关闭该选项
+- `STORAGE_OSS_INTERNAL` 【可选】是否开启内网访问，如果你的服务也在阿里云的话可以开启并节省流量，默认关闭
+
+**完整示例**
+
+```dotenv
+STORAGE_VENDOR=oss
+STORAGE_REGION=oss-cn-hangzhou
+STORAGE_ACCESS_KEY_ID=your_access_key
+STORAGE_SECRET_ACCESS_KEY=your_secret_key
+STORAGE_PUBLIC_BUCKET=fastgpt-public
+STORAGE_PRIVATE_BUCKET=fastgpt-private
+STORAGE_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
+STORAGE_OSS_CNAME=false
+STORAGE_OSS_SECURE=false
+STORAGE_OSS_INTERNAL=false
+```
+
+### 腾讯云 COS
+
+> - [跨域配置](https://cloud.tencent.com/document/product/436/13318)
+
+- `STORAGE_COS_PROTOCOL` 枚举可选值 `https:`、`http:`，注意不要忘记 `:`；如果自定义域名没有上传证书的话，请不要设置为 `https:`
+- `STORAGE_COS_USE_ACCELERATE` 【可选】是否启用全球加速域名，默认为 false。若改为 true，需要存储桶开启全球加速功能
+- `STORAGE_COS_CNAME_DOMAIN` 【可选】自定义域名，如 `your-domain.com`
+- `STORAGE_COS_PROXY` 【可选】代理服务器，如 `http://localhost:7897`
+
+**完整示例**
+
+```dotenv
+STORAGE_VENDOR=cos
+STORAGE_REGION=ap-shanghai
+STORAGE_ACCESS_KEY_ID=your_access_key
+STORAGE_SECRET_ACCESS_KEY=your_secret_key
+STORAGE_PUBLIC_BUCKET=fastgpt-public
+STORAGE_PRIVATE_BUCKET=fastgpt-private
+STORAGE_COS_PROTOCOL=http:
+STORAGE_COS_USE_ACCELERATE=false
+STORAGE_COS_CNAME_DOMAIN=
+STORAGE_COS_PROXY=
+```