FreeLLMAPI Docker 部署实战Compose 快速启动、加密密钥管理与持久化配置【免费下载链接】freellmapi7.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.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapiFreeLLMAPI 是一个将多家免费 LLM 提供商统一收敛到单一/v1兼容接口的自托管网关本项目仓库根目录为GitHub_Trending/fr/freellmapi。本文基于 docker/README.md 展开结合仓库内的 Dockerfile、docker-compose.yml 与 docker-entrypoint.sh 源码系统讲解如何用 Docker Compose 完成单机部署、加密密钥生成、SQLite 持久化、声明式配置注入与数据库备份恢复。读完本文你将能够从零拉起一个可用的 FreeLLMAPI 实例并为升级、迁移与容灾做好准备。一、部署架构单容器同时提供 API 与 DashboardDocker Compose 是 FreeLLMAPI 官方推荐的个人使用部署方式。根据 docker/README.md 的描述容器用同一个进程同时承载两件事Express API 服务对外提供/v1/chat/completions等 OpenAI 兼容接口以及/api/ping等健康检查端点内置 React Dashboard编译好的前端静态资源client/dist由同一服务托管用于在浏览器中配置提供商密钥、查看模型状态与用量。数据层采用SQLite通过命名卷freellmapi-data持久化到容器内/app/server/data目录。服务默认监听3001端口。Dockerfile 揭示了这一架构的构建细节多阶段构建deps→build→runtime基于node:20-bookworm-slim构建阶段安装python3 make g用于本地编译better-sqlite3这类原生模块运行时阶段只拷贝已编译产物server/dist与client/dist同时被复制进镜像并在末尾通过HEALTHCHECK定期请求/api/ping验证服务存活与 docker-compose.yml 中声明的 healthcheck 参数间隔 30s、超时 5s、启动宽限 15s、重试 3 次保持一致。二、前置条件与快速开始2.1 环境要求依赖用途Docker容器运行时Docker Compose编排服务、卷与端口映射OpenSSL生成 32 字节64 字符十六进制的ENCRYPTION_KEY2.2 生成加密密钥并写入 .envFreeLLMAPI 使用AES-256-GCM在数据库中以密文形式保存各提供商的 API Key见 server/src/lib/crypto.ts 的加解密实现ENCRYPTION_KEY是这一切的根密钥必须由部署者生成并妥善保管。生成并写入.env的命令如下ENCRYPTION_KEY$(openssl rand -hex 32) printf ENCRYPTION_KEY%s\nPORT3001\n $ENCRYPTION_KEY .envopenssl rand -hex 32会输出 64 个十六进制字符32 字节。PORT3001同时被写入与 docker-compose.yml 中env_file: .env的加载方式对应。关键事实务必遵守升级或迁移时必须保留同一个freellmapi-data卷和同一个ENCRYPTION_KEY。因为数据库中的提供商 Key 是用该密钥加密的更换密钥后已存在的密文将无法解密所有已保存的 Key 都会失效。2.3 启动服务docker compose up -d启动后打开http://localhost:3001在Keys页面添加各提供商的 API Key。系统会生成一个freellmapi-...前缀的统一密钥unified key之后任何 OpenAI 兼容客户端都可以用它访问聚合后的接口。2.4 首次调用示例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: Say hello from FreeLLMAPI.}] }model: auto表示交给网关的智能路由routing决定由哪个模型/提供商响应当所选提供商不可用或触发限流时自动故障转移failover机制会继续尝试链上的其他模型。三、日常运维命令操作命令查看服务状态docker compose ps跟踪日志docker compose logs -f freellmapi停止服务docker compose down拉取最新镜像并重启docker compose pull docker compose up -d从本地源码重新构建docker compose up -d --build其中--build模式会执行 Dockerfile 中npm ci、npm run build、npm prune --omitdev的完整流水线适合在发布周期内使用最新源码调试的场景。四、配置项详解环境变量表下表完整覆盖 docker/README.md 的环境变量说明并补充了默认值来源变量必填默认值说明ENCRYPTION_KEY是无64 字符十六进制密钥用于加密存储提供商 API Key。生成一次后保持稳定不要轮换。PORT否3001Compose 暴露到宿主机的端口。容器内部始终监听 3001。FREEAPI_DB_PATH否/app/server/data/freellmapi.dbSQLite 文件路径。当宿主机只持久化一个挂载目录时把该变量指向这个目录。FREEAPI_DB_BACKUP_PATH否无本地加密备份文件。若数据库文件缺失启动时自动恢复应用运行期间周期性刷新。FREEAPI_DB_BACKUP_URL否无HTTP(S) 加密备份目标。启动时用GET拉取周期性备份用PUT上传。FREEAPI_DB_BACKUP_TOKEN否无访问FREEAPI_DB_BACKUP_URL时的可选 Bearer Token。FREEAPI_DB_BACKUP_KEY否ENCRYPTION_KEY备份文件加密所用的 64 字符十六进制密钥。条件允许时建议使用独立的稳定密钥。FREEAPI_CONFIG_PATH否无JSON 配置文件路径。每次启动在数据库迁移完成后以幂等方式应用。FREEAPI_CONFIG_JSON否无内联 JSON 配置。优先级高于FREEAPI_CONFIG_PATH。这些变量在 server/src/lib/config.ts 中被解析PORT默认3001FREEAPI_DB_PATH为空时使用getDefaultDbPath()的默认路径NODE_ENV在 Dockerfile 中固定为production并额外注入FREELLMAPI_INSTALL_METHODdocker以标记安装来源。4.1 端口绑定与局域网访问docker-compose.yml 中的端口映射值得注意ports: - ${HOST_BIND:-127.0.0.1}:${PORT:-3001}:3001默认绑定127.0.0.1仅本机可访问——FreeLLMAPI 是单用户工具官方明确要求不要直接暴露到公网。如需从局域网访问在.env中设置HOST_BIND0.0.0.0即可。此外Compose 文件通过extra_hosts注册了host.docker.internal:host-gateway使容器内可直接解析宿主机地址。这意味着你可以把宿主机上的代理如http://host.docker.internal:7890配置为PROXY_URL容器内的出站请求即可走该代理——Docker Desktop 原生支持该主机名而 Linux 上的普通 Docker 不提供此配置专门补齐了这个差异。4.2 健康检查与重启策略restart: unless-stopped healthcheck: test: [CMD, node, -e, fetch(http://127.0.0.1:3001/api/ping)...] interval: 30s timeout: 5s start_period: 15s retries: 3容器异常退出会自动重启/api/ping返回非 200 会被视为不健康。健康检查逻辑与 Dockerfile 内置的HEALTHCHECK保持一致。五、声明式配置用 JSON 实现幂等初始化FREEAPI_CONFIG_PATH/FREEAPI_CONFIG_JSON对应服务端的声明式配置引擎server/src/services/declarative-config.ts。每次启动时server/src/index.ts 在initDb()之后调用applyDeclarativeConfigFromEnv()将配置以事务方式幂等写入数据库因此反复重启不会产生重复数据非常适合 Docker 场景下的「一键初始化」。官方示例freellmapi.config.json{ keys: [ { platform: groq, key: gsk_..., label: main } ], customProviders: [ { baseUrl: http://host.docker.internal:11434/v1, label: Ollama, models: [ { model: llama3.1:8b, displayName: Local Llama, supportsTools: true } ] } ], routing: { strategy: balanced } }从 declarative-config.ts 的 Zod schema 可以看出完整配置支持五大区块均可按需组合keys批量注入提供商 Key字段包括platform、key、label、baseUrlcustom平台必填、enabled。写入前会对 Key 进行 AES-256-GCM 加密encryptedKey。customProviders注册自建/本地端点如 OllamabaseUrl必填可声明多个模型未声明的智能/速度排名会以中位种子值填充模型身份按(platform, model_id, endpoint_scope)唯一区分因此同一个模型 id 可以在不同 baseUrl 下各自注册。models对已有模型做覆盖编辑displayName、intelligenceRank、speedRank、sizeLabel、rpmLimit/rpdLimit/tpmLimit/tpdLimit、monthlyTokenBudget、contextWindow、enabled、supportsVision、supportsTools、fallbackEnabled。若同一模型存在于多个端点必须显式指定endpoint消除歧义。fallback按priority编排故障转移链条目引用platformmodelId必要时加endpoint。routing路由策略strategy可选priority、balanced、smartest、fastest、reliable、customweights支持自定义可靠性/速度/智能权重custom策略时生效keySelectionStrategy可选auto或least-remaining同一平台多 Key 的选取方式。配置顺序提示models区块只能编辑已存在的模型——若要新建模型应先通过customProviders注册再在models中细化参数。对缺 Key 的条目如pollinations这类已转为付费的平台引擎会输出警告并跳过该条目而不会导致整个启动流程失败对应 server/src/services/declarative-config.ts 中的 skip 降级逻辑。使用方式# 方式一挂载文件 FREEAPI_CONFIG_PATH/app/config/freellmapi.config.json # 方式二内联 JSON优先级更高 FREEAPI_CONFIG_JSON{routing:{strategy:fastest}}六、数据持久化与备份恢复6.1 命名卷与数据位置volumes: - freellmapi-data:/app/server/data卷freellmapi-data将 SQLite 数据挂在/app/server/data。Dockerfile 刻意不声明VOLUME指令若在镜像内声明PaaS 平台Railway、Render、Coolify 等会为每次重新部署静默创建匿名卷导致数据看起来「丢失」持久化职责明确交给部署侧Compose 命名卷或docker run -v。6.2 PaaS 场景的权限处理docker-entrypoint.sh 解决了 PaaS 上最常见的权限坑这些平台把持久化卷以root 属主挂载进来而应用以node用户运行better-sqlite3便无法在其中创建数据库。入口脚本的处理策略是以 root 启动时对/app/server/data以及FREEAPI_DB_PATH、FREEAPI_DB_BACKUP_PATH所在目录执行chown -R node:node用setpriv降权回node用户再执行CMDnode server/dist/index.js保证 node 仍是 PID 1信号可达chown 失败如--cap-dropCHOWN、CIFS/NFS 固定属主时只告警不中断因为应用本身也能感知写失败并自行报告。6.3 自动备份与恢复机制配置FREEAPI_DB_BACKUP_PATH本地文件或FREEAPI_DB_BACKUP_URLHTTP(S) 端点后服务会启用一套完整的「加密备份 → 启动恢复 → 周期刷新」流程实现细节位于 server/src/lib/db-backup.ts加密格式备份内容先gzip压缩再用 AES-256-GCM密钥取FREEAPI_DB_BACKUP_KEY缺省回退到ENCRYPTION_KEY加密文件头带FAPIBK1魔数标记版本启动恢复仅当目标数据库文件不存在或为空时才会从备份源GET并解密、解压恢复避免误覆盖已有数据周期上传应用启动后立即执行一次backupDbNow()之后每 5 分钟FREEAPI_DB_BACKUP_INTERVAL_MS可调增量刷新写入前先做wal_checkpoint(TRUNCATE)保证读取一致性HTTP 目标GET用于恢复、PUT用于上传可用FREEAPI_DB_BACKUP_TOKEN携带 Bearer Token上传 Hugging Face 仓库时会自动改走其 commit API下载 URL 是只读的。另外server/src/services/backups.ts 提供的是面向 Dashboard 的 SQL dump 备份体系可在界面中手动/定时生成、下载、恢复恢复时校验 dump 格式版本、数据库 schema 版本以及ENCRYPTION_KEY指纹三者任一不匹配都会拒绝恢复并明确报错——这也再次印证了「升级时不要更换加密密钥」的必要性。七、镜像发布与更新FreeLLMAPI 的官方镜像发布在 GitHub Container Registrydocker pull ghcr.io/tashfeenahmed/freellmapi:latest仓库的 Docker 工作流在拉取请求构建时只构建不推送当main分支推送或打版本标签时才会自动发布镜像到 GHCR。升级流程就是标准的拉取-重启两步docker compose pull docker compose up -d八、常见问题速查升级后 Key 全部失效 / 无法解密确认卷freellmapi-data与ENCRYPTION_KEY都未变更二者任一改变都会使存量密文无法解密。局域网无法访问默认绑定127.0.0.1请在.env中设置HOST_BIND0.0.0.0后重启。容器内无法解析宿主机代理Compose 已默认注册host.docker.internal直接用http://host.docker.internal:7890作为PROXY_URL即可Docker Desktop 与 Linux Docker 均适用。PaaS 上每次重新部署数据变空不要依赖镜像内匿名卷务必显式挂载一个持久卷到/app/server/data或使用FREEAPI_DB_PATH指向唯一的持久目录。配置未生效确认 JSON 通过FREEAPI_CONFIG_JSON优先或FREEAPI_CONFIG_PATH注入且字段符合上述五区块的 schema未知字段会被strict()拒绝并报错。【免费下载链接】freellmapi7.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.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考