7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
English · 简体中文
安装与部署
把 FreeLLMAPI 跑起来所需的一切:一行命令、Docker Compose、本地开发、声明式配置、生产构建、桌面应用,以及你的数据存放在哪里。
快速开始
需要 Docker。它会建好 ~/freellmapi、生成加密密钥、拉取镜像并启动容器:
curl -fsSL https://freellmapi.co/install.sh | bash
不放心直接管道给 bash?脚本在这里。重复执行是安全的:你的 .env(以及加密密钥)会被保留,容器会更新到 :latest。可以用 FREELLMAPI_DIR、PORT 或 HOST_BIND 环境变量覆盖默认值。
在 Windows 上,最省事的方式是桌面版 Releases 里的 .exe 安装包(见下文);上面的 Docker 步骤在 WSL 或任意 bash shell 里同样可用。
在 Android 上,参见实验性的 Termux 安装指南。它使用 Node 内置的 SQLite 驱动,不需要 Android NDK。
打开 http://localhost:3001 ,在 密钥 页添加你的提供方密钥,按喜好调整 回退链 的顺序,然后在 密钥 页顶部拿到你的统一 API 密钥。这个统一密钥就是你的 OpenAI SDK 要指向的东西。
你的部署会自行从签名的目录源保持更新。当前的完整目录列在 freellmapi.co/models。
Docker Compose
在 3001 端口上同时跑起 API 和仪表盘,并把 SQLite 持久化到一个具名卷里。
前置条件: Docker、Docker Compose、OpenSSL。
在 macOS / Linux 上(Bash):
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
# 生成用于静态存储密钥的加密密钥
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
docker compose up -d
在 Windows 上(PowerShell):
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
$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
docker compose up -d
想从另一台机器访问? 默认情况下容器只发布在
127.0.0.1上,所以从别的设备打开http://<服务器 IP>:3001是加载不出来的(页面会一直卡住)。想把它暴露到局域网,比如让树莓派在http://192.168.1.x:3001上可访问,就用HOST_BIND=0.0.0.0启动:HOST_BIND=0.0.0.0 docker compose up -d只在你信任的网络里这么做:这个代理是单用户的,唯一的防护就是那把统一 API 密钥。
宿主机连得上提供方,容器里却连不上? 容器有自己独立的网络栈,所以有两件在你机器上成立的事,到了容器里并不成立:
127.0.0.1在容器里指的是容器自己,不是你的机器。 如果你是通过宿主机上的代理客户端(Clash、v2rayN、sing-box,或公司代理)访问提供方,请把 FreeLLMAPI 指向宿主机:PROXY_URL=socks5h://host.docker.internal:7890。仓库自带的docker-compose.yml已经把host.docker.internal映射到宿主网关,所以在 Linux 上的原生 Docker 里同样可用,不只是 Docker Desktop。另外代理本身也要允许来自 loopback 以外的连接(Clash 里是allow-lan: true)。- 纯 IPv6 的宿主机需要在 Docker 里开启 IPv6。 默认的 bridge 网络只有 IPv4,所以在没有 IPv4 出口的宿主机上,容器什么都连不上,连 DNS 也一样。在
/etc/docker/daemon.json里加上"ipv6": true、"ip6tables": true和一个"fixed-cidr-v6"网段,然后重启 Docker。想知道自己属于哪一种,直接问容器:
docker compose exec freellmapi node -e "fetch('https://generativelanguage.googleapis.com/').then(r=>console.log('ok',r.status)).catch(e=>console.log('fail',e.cause?.code||e.message))"
本地开发
前置条件: Node.js 20+、npm。
在 macOS / Linux 上(Bash):
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install
ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
npm run dev
在 Windows 上(PowerShell):
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install
$ENCRYPTION_KEY = node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
npm run dev
启动必须要有 ENCRYPTION_KEY。当 NODE_ENV 不是 production 且没有设置它时,服务会自动生成一个开发用的密钥,并保存到 SQLite 数据库旁边的 .encryption-key 文件(权限 0600)里,而不是存进数据库。以前把密钥存在数据库里的旧安装,会在首次启动时迁移到这个文件。不要在放着真实提供方密钥的环境里依赖这个兜底行为,请显式设置 ENCRYPTION_KEY。
轮换加密密钥
存储的密文用的是 AES-256-GCM,所以直接改 ENCRYPTION_KEY 不会重新加密任何东西——它只会让所有提供方密钥、按密钥的代理覆盖、客户端配置档凭据以及已保存的 Fetch Relay 令牌同时解不开。请先停掉服务,把它们重新加密:
# 1. 生成新密钥
NEW_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
# 2. 预演(只读,不写入任何内容)
cd server
ENCRYPTION_KEY=<旧密钥> npm run rotate-encryption-key -- \
--new-key "$NEW_KEY" --dry-run
# 3. 正式轮换
ENCRYPTION_KEY=<旧密钥> npm run rotate-encryption-key -- --new-key "$NEW_KEY"
--old-key <hex> 可以覆盖从 ENCRYPTION_KEY 读到的密钥,--db <path> 用来指向 server/data 以外的数据库。只有当每一个值都能解密时才会写入,所以旧密钥填错会以非零状态退出,数据库保持原样。
之后把新密钥写进 .env(ENCRYPTION_KEY=$NEW_KEY)并重启。使用 Docker 时,在容器内对挂载的数据库执行这条命令,然后用更新后的 .env 重启容器。轮换前请先备份数据库文件。
请求分析数据默认保留 90 天或 100000 条请求记录,以先触发的那个上限为准。在 .env 里设置 REQUEST_ANALYTICS_RETENTION_DAYS=0 或 REQUEST_ANALYTICS_MAX_ROWS=0 可以分别关掉对应的保留上限。
打开 http://localhost:5173 (Vite 开发界面),在 密钥 页添加你的提供方密钥,按喜好调整 回退链 的顺序,然后在 密钥 页顶部拿到你的统一 API 密钥。这个统一密钥就是你的 OpenAI SDK 要指向的东西。
想从局域网里的另一台设备访问开发界面? 用
npm run dev:lan。它会把--host透传给 Vite,Vite 随后会打印一个Network: http://<你的 IP>:5173的地址,你可以在手机或另一台机器上打开。(直接写npm run dev -- --host在这里不管用:根目录的dev脚本是一个concurrently包装器,这个参数根本传不到 Vite。)API 调用走 Vite 的开发代理,所以不需要额外的服务端配置。
不用 Docker 的生产构建:
npm run build
node server/dist/index.js # 服务和仪表盘都在 :3001 上提供
声明式启动配置
为了让 Docker 或服务器安装可以重复复现,FreeLLMAPI 支持在每次启动时应用一份 JSON 配置。设置 FREEAPI_CONFIG_PATH=/path/to/freellmapi.config.json,或者把同样的 JSON 放进 FREEAPI_CONFIG_JSON。这份配置是幂等的:已存在的密钥、自定义提供方、模型改动、回退链条目和路由设置会被更新,而不是重复添加。
{
"keys": [
{ "platform": "groq", "key": "gsk_...", "label": "main" },
{ "platform": "google", "key": "AIza...", "enabled": true }
],
"customProviders": [
{
"baseUrl": "http://host.docker.internal:11434/v1",
"label": "Ollama",
"models": [
{ "model": "llama3.1:8b", "displayName": "Local Llama", "supportsTools": true }
]
}
],
"models": [
{
"platform": "groq",
"modelId": "llama-3.3-70b-versatile",
"displayName": "Llama 3.3 70B",
"supportsTools": true,
"fallbackEnabled": true
}
],
"routing": { "strategy": "balanced" }
}
如果两个自定义端点提供同一个模型 id,请在 models 或 fallback 条目里加上 "endpoint" 来指明你说的是哪一个,填端点的 URL,或者仪表盘显示在它旁边的那个短标识。不加的话,一条能匹配到多个端点的条目会被直接拒绝,而不是随便挑一个应用:
{
"models": [
{ "platform": "custom", "modelId": "deepseek-v3.1", "endpoint": "https://relay-b.example.com/v1", "enabled": false }
]
}
Docker 镜像与运维
FreeLLMAPI 发布一个生产镜像,里面包含 Express 服务和构建好的 React 仪表盘:
docker pull ghcr.io/tashfeenahmed/freellmapi:latest # 也可以固定到某个版本,例如 :v1.2.3
镜像是多架构的(linux/amd64 和 linux/arm64,所以树莓派上也能跑)。发布的标签有:latest(最新发布版本)、main(默认分支)、v*.*.*(git 发布标签)和 sha-<commit>。
仓库里自带的 docker-compose.yml 是推荐的安装方式:
docker compose up -d
docker compose logs -f freellmapi
更新: 运行 docker compose pull && docker compose up -d(数据卷和 .env 会保留)。如果想直接在仪表盘里更新,请在 .env 中设置 WATCHTOWER_TOKEN(例如 openssl rand -hex 32),并用可选的 profile 启动:
docker compose --profile autoupdate up -d
之后在 设置 → 检查更新 中,有新版本时会出现 立即更新:一个 Watchtower 辅助容器会拉取镜像并重建 freellmapi 容器,仪表盘在服务恢复后自动重新加载。Watchtower 只开启受令牌保护的更新接口,不会定时更新,不对外暴露端口,也只处理 freellmapi 容器;但它需要挂载 Docker socket,这相当于宿主机的 root 权限,所以除非你主动启动该 profile,否则它不会运行。
容器端口默认绑定在 127.0.0.1(仅本机)。想从网络里的另一台机器访问仪表盘或 API,用 HOST_BIND=0.0.0.0 docker compose up -d 把它发布到所有网卡上。只在可信的局域网里这么做,因为这个代理是单用户的。
用局域网地址走纯 HTTP 是可以直接工作的:那些只对 HTTPS 生效的安全响应头(upgrade-insecure-requests、Cross-Origin-Opener-Policy、Origin-Agent-Cluster)只有在请求确实经由 TLS 到达时才会发出,或者是在 loopback 上,因为浏览器本来就把 loopback 当作安全上下文。放在 HTTPS 反向代理后面时它们会自动恢复,只要代理转发了 X-Forwarded-Proto。如果你的部署有特殊需要,CSP_UPGRADE_INSECURE_REQUESTS=true|false 可以强制开关那条升级指令。
SQLite 数据存放在 freellmapi-data 卷的 /app/server/data 下。升级时请保持 .env 里的 ENCRYPTION_KEY 和这个卷不变,因为提供方密钥是加密存储的。如果你的宿主机只持久化某个特定目录,可以设置 FREEAPI_DB_PATH=/that/path/freellmapi.db。
在磁盘不持久的宿主机上,配置一个加密备份目标:
FREEAPI_DB_BACKUP_PATH=/app/server/data/freellmapi.db.backup
# 或者:
FREEAPI_DB_BACKUP_URL=https://example.com/freellmapi.db.backup
FREEAPI_DB_BACKUP_TOKEN=optional-bearer-token
FREEAPI_DB_BACKUP_KEY=64-char-hex-backup-key
FREEAPI_DB_BACKUP_INTERVAL_MS=300000
启动时如果数据库文件不存在,FreeLLMAPI 会先恢复备份,再执行迁移。服务运行期间,它会定期上传一份新的加密备份。如果没有设置 FREEAPI_DB_BACKUP_KEY,备份信封也会使用 ENCRYPTION_KEY。
更多 Docker 运维内容和示例在 docker/README.md。
桌面应用
desktop/ 里有一个原生的菜单栏应用:整个路由器加仪表盘就在你的托盘里本地运行,还有一个玻璃质感的悬浮窗显示实时请求统计。

从 Releases 下载 —— macOS 的 .dmg 和 Windows 的 .exe 安装包由 desktop-release 工作流在每个版本发布时构建并附带。你也可以花几分钟从本仓库自己构建:
Mac 下载: Apple Silicon 请选择 arm64,Intel 请选择 x64。两者都要求 macOS 12 Monterey 或更高版本,并提供 DMG 和 ZIP 下载。
更新: 已安装的应用在 macOS、Windows(Setup 安装版)和 Linux AppImage 上可以自动更新。⋯ → 设置 → 检查更新(或托盘菜单的 检查更新…)会下载新版本并提供 重启以更新;安装前会先写入一份完整的数据库备份,在备份页面中标记为「更新前」。开启 自动检查更新 后,新版本会在后台下载,并在下次重启或退出时安装;应用不会自行重启。Linux 的 .deb/.rpm/.tar.xz 和 Windows 便携版 .zip 请下载新版本来更新。
Windows 用户从源码构建的注意事项: 构建桌面应用需要为 Electron 编译原生 SQLite 模块。在执行
npm install之前,你必须先装好 Visual Studio Build Tools(具体来说是「使用 C++ 的桌面开发」工作负载)以及 Python。
npm install
npm install --prefix desktop # 安装桌面端依赖
npm run desktop:dist # macOS → desktop/dist-electron/FreeLLMAPI-…-arm64.dmg
npm run desktop:dist:mac:x64 # Intel Mac → desktop/dist-electron/FreeLLMAPI-…-x64.dmg
npm run desktop:dist:win # Windows → "desktop/dist-electron/FreeLLMAPI-Setup-….exe"
本地构建出来的应用没有签名,所以 Windows SmartScreen 首次运行时可能会警告(点「更多信息」→「仍要运行」);macOS 构建则不会触发 Gatekeeper 提示。 完整说明见 desktop/README.md。
凭据与数据存放位置
桌面应用 不需要设置用户名或密码。服务器版会用邮箱加密码的账号把仪表盘挡在登录后面,而桌面版不同:它用一个隐藏的本地账号自动登录仪表盘,所以你永远不会被要求输入凭据,也不需要有一个。
你唯一需要的凭据是那把 统一 API 密钥,也就是你的 OpenAI/Anthropic 客户端要指向的 freellmapi-… 令牌。可以从这两个地方拿到:
- 托盘悬浮窗:点击托盘图标,然后点 复制密钥;或者
- 仪表盘 密钥 页的顶部(托盘 → 打开仪表盘)。
你不需要手动打开或编辑 freeapi.db。
你的设置和数据按操作系统存放在一个文件夹里(迁移到另一台机器或搬进容器时,复制它就行):
| 操作系统 | 位置 |
|---|---|
| Windows | %APPDATA%\FreeLLMAPI\(例如 C:\Users\<你>\AppData\Roaming\FreeLLMAPI\) |
| macOS | ~/Library/Application Support/FreeLLMAPI/ |
| Linux | ~/.config/FreeLLMAPI/ |
这个文件夹里有 freeapi.db(全部密钥、模型和设置,加密存储)和 config.json(窗口、主题、端口、局域网偏好)。搬迁安装时两个都要复制。对于服务器(非桌面)部署,对应的状态是 .env 文件和位于 server/data/freeapi.db(或者 FREEAPI_DB_PATH 指向的位置)的 SQLite 数据库。