LobeHub 自托管怎么启用文件上传与知识库功能？-编程实验室

LobeHub 自托管怎么启用文件上传与知识库功能？

【免费下载链接】lobehub🤯 LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub

在自托管 LobeHub 数据库版时，文件上传和知识库管理不是开箱即用的单个开关，而是一组依赖配置：需要带 PGVector 的 PostgreSQL、S3 兼容的对象存储，以及用于生成向量的 Embedding 服务。这篇文章给出两条可执行路径——用官方一键脚本直接拉起完整环境，或在自定义 Docker Compose 部署中手动配置 S3 与 Embedding 相关的环境变量，并说明如何判断功能是否就绪。

适用前提：

环境为 Unix（Linux/macOS）；Windows 需通过 WSL 2 运行。
确认端口3210、9000、9001未被占用。

功能依赖的三个核心组件

按知识库 / 文件上传文档，该功能依赖：

PostgreSQL + PGVector：存储结构化数据和向量索引。文档建议用 ParadeDB Docker 镜像快速部署（同时包含 pgvector 和 pg_search 插件）：
```
docker run -p 5432:5432 -d --name pg -e POSTGRES_PASSWORD=mysecretpassword paradedb/paradedb:latest-pg17
```
S3 兼容对象存储：存储上传的原始文件。可用 AWS S3、Cloudflare R2、RustFS、ceph 或阿里云 OSS 等任何兼容 S3 API 的服务。文档同时指出 MinIO 因商业策略变化已不再被推荐。
OpenAI Embedding：默认使用text-embedding-3-small模型，你的 API Key 必须能访问该模型。

另外两个可选项：Unstructured.io 用于处理 PDF、Word 等复杂文档格式，文档建议按文档复杂度评估是否需要；以及自定义 Embedding，支持 zhipu/github/openai/bedrock/ollama 提供商，通过环境变量配置：

environment: DEFAULT_FILES_CONFIG=embedding_model=openai/text-embedding-3-small

路径一：一键脚本部署（最短路径）

这是文档推荐的初次部署方式，脚本会生成包含 RustFS（本地 S3 服务）在内的完整配置。

创建部署目录：
```
mkdir lobehub && cd lobehub
```
拉取并执行部署脚本（脚本同样存在于仓库的 setup.sh）：
```
bash <(curl -fsSL https://lobe.li/setup.sh) -l en
```
脚本提供 Local / Port / Domain 三种模式；初次体验选默认的 Local Mode 即可，其余提示直接回车接受默认值。
脚本结束后查看“配置生成报告”，其中包含 LobeHub 的访问 URL 和 RustFS 的账号密码（下方为文档中的示例输出，实际生成的密码不同）：
```
The results of the secure key generation are as follows: LobeHub: - URL: http://localhost:3210 RustFS: - URL: http://localhost:9000 - Username: admin - Password: 8c82ea41
```

启动服务并查看日志：

docker compose up -d docker logs -f lobehub

看到如下日志说明启动成功（示例输出，Ready耗时因机器而异）：

[Database] Start to migration... ✅ database migration pass. ------------------------------------- ▲ Next.js 16.x.x - Local: http://localhost:3210 - Network: http://0.0.0.0:3210 ✓ Starting... ✓ Ready in 95ms

访问http://localhost:3210进入 LobeHub，即可使用文件上传 / 知识库功能。该路径下 S3 相关环境变量已由脚本生成，无需手工填写。

路径二：自定义部署时配置 S3 与 Embedding

如果按自定义部署方式接入自有环境，以仓库中的 docker-compose.yml 为基础。该文件已内置postgresql（paradedb/paradedb:latest-pg17）、redis、rustfs服务，且lobe服务已注入以下关键变量：

environment: - 'S3_ENDPOINT=${S3_ENDPOINT}' - 'S3_BUCKET=${RUSTFS_LOBE_BUCKET}' - 'S3_ENABLE_PATH_STYLE=1' - 'S3_ACCESS_KEY_ID=${RUSTFS_ACCESS_KEY}' - 'S3_SECRET_ACCESS_KEY=${RUSTFS_SECRET_KEY}' - 'S3_SET_ACL=0' - 'LLM_VISION_IMAGE_USE_BASE64=1' - 'INTERNAL_APP_URL=http://localhost:3210'

其中rustfs-init一次性容器会自动在 RustFS 中创建名为lobe的 bucket 并应用 bucket.config.json 中的公开读策略，因此默认组合下你主要需要在.env中补齐密钥与端点。

.env中与文件上传 / 知识库直接相关的变量（完整定义见 S3 环境变量文档）：

变量	是否必填	说明
`S3_ACCESS_KEY_ID`/`S3_SECRET_ACCESS_KEY`	必填	S3 服务的访问密钥
`S3_ENDPOINT`	必填	存储桶请求端点，不能包含 bucket 名称后缀
`S3_BUCKET`	必填	存储桶名称
`S3_REGION`	可选	存储桶区域，个别服务商要求配置
`S3_SET_ACL`	可选	仅显式设为`1`时上传才设置`public-read`ACL
`S3_ENABLE_PATH_STYLE`	可选	S3 服务商使用 path-style 模式时设为`1`

RustFS 场景下的.env示例（来自 RustFS 配置文档，<YOUR_ACCESS_KEY>、<YOUR_SECRET_KEY>替换为你在 RustFS 中创建的 Access Key / Secret Key，S3_ENDPOINT替换为你的 S3 API 域名）：

# RustFS Access Key / Secret Key S3_ACCESS_KEY_ID=<YOUR_ACCESS_KEY> S3_SECRET_ACCESS_KEY=<YOUR_SECRET_KEY> # RustFS API endpoint S3_ENDPOINT=https://lobe-s3-api.example.com # Bucket name S3_BUCKET=lobe S3_ENABLE_PATH_STYLE=1

配置时注意三条来自文档的硬约束：

S3_ENDPOINT必须去掉 suffix path（bucket 名），否则上传的文件将无法访问。
公共云 S3 一般默认virtual-host模式；RustFS 等自部署服务默认path-style，需设S3_ENABLE_PATH_STYLE=1。
S3_ENDPOINT必须能被浏览器解析。直接使用http://rustfs:9000这种容器内名称会导致会话图片上传失败（头像上传不受影响）。
INTERNAL_APP_URL是 Docker Compose 部署的必填项，异步功能（如 AI 图片生成）依赖容器向自身发起 HTTP 请求，建议用http://localhost:3210或http://lobe:3210。

Embedding 侧需要有效的 OpenAI API Key（配置见模型提供商环境变量文档），确保其可访问默认的text-embedding-3-small模型。若想改用其他提供商，才需要DEFAULT_FILES_CONFIG方式指定。

验证与排查

启动后按以下顺序确认文件存储链路：

主服务启动成功：docker logs -f lobehub中出现✅ database migration pass.与✓ Ready（示例输出，见上节）。
RustFS 健康检查：compose 文件对 rustfs 容器配置了健康检查wget -qO- http://localhost:9000/health，docker compose ps中 rustfs 状态为 healthy 即正常；也可打开 RustFS WebUI（http://localhost:9001/，账号密码见生成报告或 compose 中的RUSTFS_ACCESS_KEY/RUSTFS_SECRET_KEY）确认 bucket 已创建。
文件上传失败时，按 Docker Compose 文档的排查入口检查 RustFS：
```
docker compose logs rustfs docker compose logs rustfs-init
```
并确认 bucket 存在：docker compose exec rustfs ls /data/lobe。
会话中上传图片报 plain http 错误：若模型侧返回如下错误（文档示例）：
```
Route: [xai] ProviderBizError: Fetching images over plain http:// is not supported.
```
将LLM_VISION_IMAGE_USE_BASE64设为1，LobeHub 会把图片转为 base64 编码后传给模型（视频同理用LLM_VISION_VIDEO_USE_BASE64）。

限制与边界

服务资源参考（来自 Docker Compose 文档）：最低 2 核 CPU / 4 GB 内存 / 20 GB 存储；生产环境建议 4 核以上 / 8 GB 以上 / 50 GB 以上（取决于文件上传量）。
S3_SET_ACL默认关闭；若存储服务商不支持单文件 ACL（所有文件继承 bucket 的 ACL），显式开启该项可能导致请求错误。
官方 Docker 镜像会在启动前自动执行数据库迁移，文档建议数据库实例使用空库，避免手工维护表结构。
本文只覆盖服务端数据库方案的文件上传 / 知识库启用；文档中未给出知识库检索效果的具体验收指标，功能是否生效以主服务启动成功、bucket 可读、上传链路日志无报错为准。

主要参考文档：知识库 / 文件上传、配置 S3 存储服务、Docker Compose 部署、RustFS 配置。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考