跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.fim.ai/llms.txt

Use this file to discover all available pages before exploring further.

FIM One 支持两个数据库后端：SQLite（默认，零配置）和 PostgreSQL（推荐用于生产环境）。后端由 DATABASE_URL 环境变量决定。 
# SQLite (default — no configuration needed)
DATABASE_URL=sqlite+aiosqlite:///./data/fim_one.db

# PostgreSQL (production)
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/fim_one
表会在首次启动时自动创建 — 无需手动迁移步骤。

​
SQLite vs PostgreSQL

SQLitePostgreSQL
设置零配置，基于文件需要单独的服务器
并发性单写入器（全局锁）完整 MVCC，行级锁定
多工作进程不支持（WORKERS 必须为 1）完全支持
SSE 流式传输流式传输期间保持的连接可能会阻止其他请求并发读写不受影响
备份复制 .db 文件pg_dump 或流式复制
最适合开发、单用户、演示生产、多用户、团队
本地开发： SQLite 开箱即用 — 无需数据库服务器、无需 Redis、无需配置任何内容。直接开始编码。生产环境： 使用 Docker Compose 部署，PostgreSQL + Redis 会自动配置。无需手动设置数据库。

​
已知限制：SQLite 并发流式传输

SQLite 在并发负载下可能成为瓶颈。FIM One 使用服务器发送事件 (SSE) 来流式传输 AI 响应。在流式传输期间，每个活跃的 SSE 连接在流式传输期间会占用连接池中的一个数据库连接。SQLite 强制执行全局写入锁，这意味着一次只能进行一个写入操作——所有其他写入操作都排队等待。尽管连接池支持最多 30 个并发连接（pool_size=20 + max_overflow=10），但瓶颈是锁本身，而不是连接池。当多个用户同时聊天时，他们的写入操作（保存消息、更新令牌计数）会相互序列化。您可能观察到的症状：
  • 当另一个用户正在流式传输时，对话列表加载缓慢
  • 在活跃聊天会话期间，设置页面感觉反应迟缓
  • 当多个流处于活跃状态时，API 响应延迟
建议： 如果您有 2-3 个以上的并发用户，请切换到 PostgreSQL。PostgreSQL 使用 MVCC（多版本并发控制）和行级锁定，因此并发读取和写入可以独立进行，不会相互阻塞。

​
连接池配置

FIM One 为每个后端内部配置 SQLAlchemy 连接池设置。这些是经过调整的默认值，不需要环境变量 — 它们会根据 DATABASE_URL 方案自动应用。了解它们有助于解释运行时行为。

​
SQLite 连接池设置

设置值描述
pool_size20连接池中的基础持久连接数
max_overflow10在负载下创建的额外连接（总计最多 30 个）
WAL 日志模式已启用预写日志允许在写入进行时进行并发读取，显著降低锁争用
busy_timeout30s当写入锁被持有时，其他写入者最多等待 30 秒后才会抛出错误，而不是立即失败
synchronousNORMAL与 WAL 模式兼容；提供比默认 FULL 更好的写入吞吐量
WAL 模式和 30 秒忙碌超时通过 SQLite PRAGMA 在每个新连接上设置。这种组合确保短期读取（加载对话列表、获取设置）不会被长时间运行的写入事务阻止，并且并发写入会优雅地排队而不是失败。

​
PostgreSQL 连接池设置

设置值描述
pool_size10连接池中持久连接的基础数量
max_overflow20在负载下创建的额外连接（总计最多 30 个）
pool_timeout30s从连接池等待可用连接的最长时间，超时后抛出错误
pool_recycle1800s连接每 30 分钟回收一次，以防止陈旧连接（对于会关闭空闲连接的云托管数据库很重要）
PostgreSQL 通过 MVCC 原生处理并发，因此连接池设置主要控制资源使用而非竞争。30 分钟的回收间隔可以避免防火墙、负载均衡器或托管数据库服务无声地丢弃空闲 TCP 连接的问题。

​
切换到 PostgreSQL

​
第 1 步：启动 PostgreSQL 实例

最快的方式是使用 Docker： 
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=fim_one \
  -p 5432:5432 \
  postgres:16-alpine

​
第 2 步：设置 DATABASE_URL

在你的 .env 文件中添加或更新以下行： 
DATABASE_URL=postgresql+asyncpg://postgres:secret@localhost:5432/fim_one

​
第 3 步：重启 FIM One

# Local development
./start.sh portal

# Or restart your process manager / systemd service
表会在首次启动时自动创建。无需手动进行架构迁移。
现有 SQLite 数据不会自动迁移。 将 DATABASE_URL 从 SQLite 切换到 PostgreSQL 会使用全新数据库启动。如果您在 SQLite 中有需要保留的现有对话、智能体或连接器，请参阅下面的数据迁移部分。

​
Docker Compose（推荐用于生产环境）

如果使用 Docker Compose 部署，PostgreSQL 和 Redis 已包含并自动配置 — 无需额外设置。docker-compose.yml 在内部设置 DATABASE_URL — 你的 .env 值会被覆盖： 
environment:
  DATABASE_URL: postgresql+asyncpg://fim:fim@postgres:5432/fim_one
使用 Docker Compose 时无需额外的数据库设置。

​
数据迁移

SQLite 到 PostgreSQL 没有内置的迁移工具。对于大多数部署，推荐的方法取决于您的情况： 全新部署（无现有数据）： 只需将 DATABASE_URL 设置为您的 PostgreSQL 连接字符串并启动 FIM One。所有表都会自动创建。 必须保留现有数据： 需要手动导出/导入。一般方法：
  1. 使用 sqlite3 CLI 或 Python 脚本等工具从 SQLite 导出数据
  2. 根据需要转换数据（SQLite 和 PostgreSQL 有细微的类型差异）
  3. 使用 psql、pg_restore 或应用级别的插入脚本导入到 PostgreSQL
对于大多数从开发设置升级到生产环境的用户，使用 PostgreSQL 重新开始会更简单，并通过 UI 重新创建您的智能体和连接器。对话历史通常不重要到足以保证手动迁移的必要性。