> ## 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 — 或立即尝试云版本。

<Tip>
  **☁️ 选项 0：云版本（零配置）**
  不想自托管？立即在 [**cloud.fim.ai**](https://cloud.fim.ai/) 尝试 FIM One — 无需 Docker、无需 API 密钥、无需配置。登录即可开始使用。*早期访问。*
</Tip>

## 选项 A：Docker（推荐）

无需本地 Python 或 Node.js — 所有内容都在容器内构建。

```bash theme={null}
git clone https://github.com/fim-ai/fim-one.git
cd fim-one

# Configure — only LLM_API_KEY is required
cp example.env .env
# Edit .env: set LLM_API_KEY (and optionally LLM_BASE_URL, LLM_MODEL)

# Build and run (first time, or after pulling new code)
docker compose up --build -d
```

打开 [http://localhost:3000](http://localhost:3000) — 首次启动时，您将被引导创建管理员账户。就这样。

初始构建后，后续启动只需要：

```bash theme={null}
docker compose up -d          # start (skip rebuild if image unchanged)
docker compose down           # stop
docker compose logs -f        # view logs
```

数据持久化在 Docker 命名卷（`fim-data`、`fim-uploads`）中，容器重启后数据保留。

**注意：** Docker 模式不支持热重载。代码更改需要重新构建镜像（`docker compose up --build -d`）。如需进行带实时重载的活跃开发，请使用下面的**选项 B**。

## 选项 B：本地开发

前置条件：Python 3.11+、[uv](https://docs.astral.sh/uv/)、Node.js 18+、pnpm。

```bash theme={null}
git clone https://github.com/fim-ai/fim-one.git
cd fim-one

cp example.env .env
# Edit .env: set LLM_API_KEY

# Install
uv sync --all-extras
cd frontend && pnpm install && cd ..

# Launch (with hot reload)
./start.sh
```

| 命令                   | 启动内容                                     | URL                                                               |
| -------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| `./start.sh`         | Next.js + FastAPI                        | [http://localhost:3000](http://localhost:3000) (UI) + :8000 (API) |
| `./start.sh dev`     | 相同，带热重载（Python `--reload` + Next.js HMR） | 相同                                                                |
| `./start.sh dev:api` | 仅 API，开发模式（`--reload`）                   | [http://localhost:8000/api](http://localhost:8000/api)            |
| `./start.sh dev:ui`  | 仅 Next.js，开发模式（HMR）                      | [http://localhost:3000](http://localhost:3000)                    |
| `./start.sh api`     | 仅 FastAPI（无界面，用于集成或测试）                   | [http://localhost:8000/api](http://localhost:8000/api)            |

## 配置

FIM One 与**任何 OpenAI 兼容的 LLM 提供商**配合使用 — OpenAI、DeepSeek、Anthropic、Qwen、Ollama、vLLM 等。

| 提供商             | `LLM_API_KEY` | `LLM_BASE_URL`                 | `LLM_MODEL`         |
| --------------- | ------------- | ------------------------------ | ------------------- |
| **OpenAI**      | `sk-...`      | *(default)*                    | `gpt-4o`            |
| **DeepSeek**    | `sk-...`      | `https://api.deepseek.com/v1`  | `deepseek-chat`     |
| **Anthropic**   | `sk-ant-...`  | `https://api.anthropic.com/v1` | `claude-sonnet-4-6` |
| **Ollama** (本地) | `ollama`      | `http://localhost:11434/v1`    | `qwen2.5:14b`       |

**[Jina AI](https://jina.ai/)** 解锁网络搜索/获取、嵌入和完整的 RAG 管道（提供免费层）。

最小化 `.env`：

```bash theme={null}
LLM_API_KEY=sk-your-key
# LLM_BASE_URL=https://api.openai.com/v1   # default — change for other providers
# LLM_MODEL=gpt-4o                         # default — change for other models

JINA_API_KEY=jina_...                       # unlocks web tools + RAG
```

有关所有配置选项的完整列表，请参阅[环境变量](/configuration/environment-variables)参考。

## 生产部署

### Docker（推荐）

`docker compose up -d` 启动您需要的所有服务 — **无需手动配置服务**：

| 服务          | 用途        | 配置方式               |
| ----------- | --------- | ------------------ |
| **fim-one** | API + 前端  | `.env`（您的 LLM 密钥等） |
| **Redis**   | 跨工作进程中断中继 | 由 compose 自动配置     |

```bash theme={null}
docker compose up --build -d   # first time / after code changes
docker compose up -d           # subsequent starts
docker compose logs -f         # view logs
docker compose down            # stop all services
```

#### 使用 Workers 扩展

默认情况下，API 运行单个 worker 进程。要处理更多并发用户，请通过 `.env` 增加 workers：

```bash theme={null}
WORKERS=4   # number of Uvicorn worker processes
```

多 worker 要求：

* **PostgreSQL** — SQLite 是单写入器，不支持并发写入。将 `DATABASE_URL` 设置为 PostgreSQL 连接字符串。
* **Redis** — 已包含在 Docker Compose 中（自动配置）。处理跨 worker 中断/注入中继。

使用 `WORKERS=1`（默认值）时，不需要 Redis 或 PostgreSQL — SQLite 可以正常工作。

#### Nginx 反向代理

对于 HTTPS 和自定义域名，在前面放置一个 Nginx 反向代理：

```
User → Nginx (443/HTTPS) → localhost:3000
```

API 在内部运行在端口 8000 — Next.js 自动代理 `/api/*` 请求。只需要暴露端口 3000。

#### 代码执行沙箱

如果您使用代码执行沙箱（`CODE_EXEC_BACKEND=docker`），请挂载 Docker 套接字：

```yaml theme={null}
# docker-compose.yml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

#### Cloudflare Tunnel

对于零开放端口的设置，使用 [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) 代替 Nginx。所有流量都通过 Cloudflare 的边缘节点流动 — 无需暴露 80/443 端口、管理 SSL 证书或配置防火墙规则。

<Warning>
  **中国大陆用户**：Cloudflare Free/Pro/Business 计划在中国大陆**没有 PoP（存在点）**。来自中国大陆的流量被路由到海外边缘节点（通常是美国西部），导致频繁的 502 错误和高延迟。如果您的主要用户在中国大陆，**不要**使用 Cloudflare Tunnel。需要 Cloudflare Enterprise with China Network（JD Cloud 合作）才能可靠地访问中国大陆。
</Warning>

```
User → Cloudflare Edge (SSL) → Tunnel → cloudflared → fim-one:3000
```

**设置：**

<Steps>
  <Step title="创建隧道">
    前往 [Cloudflare Zero Trust](https://one.dash.cloudflare.com/) → Networks → Tunnels → **Create a tunnel**。
    选择 **Cloudflared** 作为连接器类型。
  </Step>

  <Step title="配置公共主机名">
    在隧道配置中，添加一个公共主机名：

    | 字段       | 值              |
    | -------- | -------------- |
    | **Type** | `HTTP`         |
    | **URL**  | `fim-one:3000` |

    将所有其他设置（HTTP Host Header、Chunked Encoding、Timeouts、Access）保留为默认值。

    <Note>URL 使用 Docker 服务名称 `fim-one`，而不是 `localhost`，因为 `cloudflared` 作为同一 Docker 网络中的单独容器运行。</Note>
  </Step>

  <Step title="复制隧道令牌">
    在隧道的 **Configure** 页面中，找到安装命令 — 它包含一个以 `eyJ...` 开头的令牌。复制它。
  </Step>

  <Step title="将令牌添加到 .env">
    ```bash theme={null}
    # Add to your .env file on the server
    CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiNj...
    ```
  </Step>

  <Step title="使用隧道覆盖层部署">
    ```bash theme={null}
    docker compose -f docker-compose.yml -f docker-compose.tunnel.yml build
    docker compose -f docker-compose.yml -f docker-compose.tunnel.yml up -d
    ```

    `docker-compose.tunnel.yml` 覆盖层添加了一个 `cloudflared` sidecar 容器。基础 `docker-compose.yml` 保持不变 — 没有 Cloudflare 的社区用户可以继续使用 `docker compose up -d`。
  </Step>

  <Step title="删除旧的 DNS 记录">
    如果您的域名之前有一条 A 记录指向您的服务器 IP，**在 Cloudflare DNS 中删除它**。隧道会自动创建一条 CNAME 记录指向其边缘端点。
  </Step>

  <Step title="关闭服务器端口">
    从服务器上的 `docker-compose.yml` 中删除（或注释掉）`ports` 部分。流量现在完全通过隧道流动 — 无需入站端口。
  </Step>
</Steps>

<Tip>
  Cloudflare Tunnel 在所有计划（包括 Free）上都是免费的。没有带宽或流量限制。
</Tip>

### 脚本部署（裸机）

对于裸机服务器或自定义进程管理器，直接使用 `./start.sh`：

```bash theme={null}
./start.sh           # production mode
./start.sh portal    # same as above (explicit)
./start.sh api       # API only (headless)
```

在此模式下，Redis **不会**自动包含。系统默认以单工作进程、进程内模式运行——适合低流量部署。

要在本地启用带 Redis 的多工作进程：

```bash theme={null}
# Start a Redis instance (Docker or system package)
docker run -d --name redis -p 6379:6379 redis:7-alpine

# Add to .env
REDIS_URL=redis://localhost:6379/0
WORKERS=4
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/fim_one
```