FreeLLMAPI 详细部署教程

FreeLLMAPI 是一个 OpenAI 兼容的聚合代理服务器，它将来自数十个 AI 提供商的免费额度汇聚到一个统一的 /v1 API 端点背后。通过它，你可以用一个统一的 API 密钥和本地地址，访问聚合后的海量免费模型资源，非常适合个人实验和原型开发。

📋 目录

  1. FreeLLMAPI 简介
  2. 系统要求
  3. 部署方式概览
  4. 方式一：一键脚本部署（推荐）
  5. 方式二：Docker Compose 部署
  6. 方式三：本地开发部署
  7. 方式四：桌面应用部署
  8. 方式五：在 Railway 上部署
  9. 配置与使用
  10. 故障排除

🧠 FreeLLMAPI 简介

FreeLLMAPI 的核心价值在于解决一个痛点：每个 AI 平台的免费额度单独看都像“玩具”，但聚合起来就是可观的算力。

特性 说明
统一端点 将数十个提供商的免费 API 整合成一个 OpenAI 兼容的 /v1 端点
智能路由 根据优先级、健康状态和速率限制自动选择最优模型
自动故障转移 遇到限流(429)或服务器错误(5xx)时，自动重试链中的下一个模型
密钥加密 所有提供商密钥使用 AES-256-GCM 加密存储
单一 API 密钥 你的应用只暴露一个统一的 freellmapi-... 令牌
自带模型目录更新 路由器会从官方源自动同步最新的模型目录

💻 系统要求

要求 说明
操作系统 Windows、macOS、Linux（x86_64 / ARM64）
Docker 对于容器化部署方式必需
Node.js 20+（用于本地开发部署）
网络 需要能够访问各 AI 提供商的 API 服务

📦 部署方式概览

部署方式 适用场景 难度
一键脚本 快速体验，自动配置 Docker 环境 ⭐ 最简单
Docker Compose 生产/长期自托管，数据持久化 ⭐⭐ 简单
本地开发 开发者，需要定制或二次开发 ⭐⭐⭐ 中等
桌面应用 图形界面，菜单栏管理 ⭐ 简单
Railway 平台 一键云端部署，无需管理服务器 ⭐ 简单

🚀 方式一：一键脚本部署（推荐）

官方提供的一键安装脚本，会自动安装依赖、生成密钥并启动 Docker 容器。

步骤 1：运行安装脚本

1
curl -fsSL https://freellmapi.co/install.sh | bash

说明：该脚本会在 ~/freellmapi 目录下设置环境，生成加密密钥，拉取 Docker 镜像并启动容器。

步骤 2：访问管理面板

脚本执行完成后，打开浏览器访问：

1
http://localhost:3001

步骤 3：完成初始配置

  1. 进入 Keys 页面，添加各个 AI 提供商的 API 密钥。
  2. 在 Fallback Chain（备用链）页面，调整模型的优先级顺序。
  3. 从 Keys 页面顶部获取你的统一 API 密钥（格式为 freellmapi-...）。

🐳 方式二：Docker Compose 部署

这是最推荐的自托管方式，便于管理、升级和数据持久化。

步骤 1：克隆仓库

1
2
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

步骤 2：生成加密密钥

macOS/Linux (Bash):

1
2
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env

Windows (PowerShell):

1
2
3
4
$Bytes = New-Object Byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($Bytes)
$ENCRYPTION_KEY = -join ($Bytes | ForEach-Object { "{0:x2}" -f $_ })
"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env

步骤 3：启动容器

1
docker compose up -d

步骤 4：暴露到局域网（可选）

默认容器只绑定在 127.0.0.1，如需从局域网其他设备访问，使用：

1
HOST_BIND=0.0.0.0 docker compose up -d

常用 Docker 操作命令

1
2
3
4
5
6
7
8
9
10
11
12
# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f freellmapi

# 停止服务
docker compose down

# 更新到最新镜像
docker compose pull
docker compose up -d

🖥️ 方式三：本地开发部署

适合需要在源码基础上进行定制或开发贡献的场景。

步骤 1：克隆与安装依赖

1
2
3
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install

步骤 2：配置环境变量

macOS/Linux:

1
2
3
cp .env.example .env
ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" >> .env

Windows (PowerShell):

1
2
3
Copy-Item .env.example .env
$ENCRYPTION_KEY = node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Add-Content -Path .env -Value "`nENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001"

步骤 3：启动开发服务器

1
npm run dev

此命令会同时启动：

  • 后端 API 服务器：http://localhost:3001
  • 前端管理面板 (Vite)：http://localhost:5173

说明：开发模式下，API 请求会通过 Vite 的代理转发，可以直接从 localhost:5173 使用完整功能。

步骤 4：生产构建（可选）

1
2
npm run build
node server/dist/index.js

此命令会构建前端并启动一个单一的服务器，监听 3001 端口提供 API 和 Web UI。

🖥️ 方式四：桌面应用部署

官方提供了 macOS 和 Windows 的桌面应用，可从系统托盘/菜单栏管理。

步骤 1：下载安装包

从 Releases 页面 下载对应平台的安装包：

  • macOS: .dmg 文件
  • Windows: .exe 安装程序

步骤 2：安装与启动

  • macOS: 打开 DMG，将应用拖入 Applications 文件夹。由于应用未签名，首次启动需右键点击应用，选择“打开”。
  • Windows: 运行安装程序即可。

步骤 3：获取统一密钥

启动后，应用会驻留在系统托盘/菜单栏。点击图标，从弹出窗口中复制统一的 API 密钥即可使用。

☁️ 方式五：在 Railway 上部署

你也可以将 FreeLLMAPI 一键部署到 Railway 这样的云平台上。

步骤 1：点击部署按钮

访问 Railway 的 FreeLLMAPI 部署页面，点击 Deploy Now 按钮。

步骤 2：配置环境变量

在部署过程中，需要添加 ENCRYPTION_KEY 环境变量（64位十六进制字符串），可以用以下命令生成：

1
openssl rand -hex 32

步骤 3：完成部署

平台会自动构建并启动服务，完成后会提供一个公网 URL。你需要通过该 URL 访问管理面板，添加你的提供商密钥。

⚙️ 配置与使用

添加提供商密钥

无论哪种部署方式，都需要通过管理面板添加你的 API 密钥：

  1. 访问管理面板（如 http://localhost:3001）
  2. 进入 Keys 页面
  3. 点击 Add Key，选择提供商（如 Groq、Google、OpenRouter），并粘贴你的 API 密钥

API 调用示例

拿到统一的 API 密钥后，使用任何 OpenAI 兼容客户端：

Python (OpenAI SDK):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-your-unified-key", # 替换为你的统一密钥
)

response = client.chat.completions.create(
    model="auto",  # 自动路由
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)
# 查看实际路由到的提供商
print(response.headers.get("x-routed-via"))

cURL:

1
2
3
4
5
6
7
curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-your-unified-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

🔧 故障排除

1. 忘记管理面板密码（Docker/Server 安装）

点击登录页面的 Forgot password?。一次性重置代码会打印在服务器日志中：

1
docker compose logs -f freellmapi

2. 容器内无法访问提供商 API

容器有自己的网络栈，无法直接访问宿主机的 127.0.0.1。如果你的提供商通过本地代理访问，需配置 PROXY_URL：

1
PROXY_URL=socks5h://host.docker.internal:7890 docker compose up -d

3. 升级后密钥无法解密

ENCRYPTION_KEY 必须保持稳定。如果更换了密钥，之前存储的提供商密钥将无法解密，需要重新添加。

4. 查看日志

  • Docker: docker compose logs -f freellmapi
  • 桌面应用: 从系统托盘菜单选择 Open Logs Folder
  • 本地开发: 直接查看终端输出

5. 开启调试

在环境变量中添加 DEBUG=freellmapi:* 可以启用更详细的日志。

📚 总结

FreeLLMAPI 提供了一个极具吸引力的方案，让开发者能以零成本体验和测试多种前沿模型。部署方式非常灵活：

你的需求 推荐方案
快速尝鲜，不想深入配置 一键脚本
长期自托管，对数据有控制要求 Docker Compose
需要修改代码或参与贡献 本地开发部署
追求无服务器管理的便捷性 Railway 部署
偏好图形界面操作 桌面应用

⚠️ 重要提示
此项目专为个人实验和学习设计，不适用于生产环境。免费层级的限制意味着性能和可用性不稳定，在构建真实应用前，请务必换成付费 API。

更多详细信息，请访问官方仓库：github.com/tashfeenahmed/freellmapi。