LiteLLM Docker 一键部署教程：镜像拉取、端口映射与数据目录配置

为什么用Docker部署LiteLLM

LiteLLM是一类面向开发者和团队的AI网关工具，核心作用是把不同模型服务的调用方式统一起来，对外提供接近OpenAI风格的接口。对于需要同时接入多个模型、统一鉴权、记录调用日志、控制预算或做接口迁移的项目来说，它可以减少业务代码改动，也便于后续替换模型供应方。

相比直接在宿主机安装Python依赖，Docker部署更适合生产前验证和小团队落地：环境隔离清晰、版本可回退、迁移方便，出现问题时也能通过容器日志快速排查。本文以常见的单机部署为例，讲清镜像拉取、端口映射、配置文件挂载和数据目录规划，适合有基础命令行经验的用户照着执行。

部署前准备

开始前需要确认服务器或本地机器已安装Docker，并能正常执行docker --version。建议准备至少2GB可用内存，磁盘空间预留5GB以上；如果后续要保存较多调用日志或接入数据库，应根据业务量扩大存储。系统时间也要保持准确，否则部分上游接口签名、日志时间和排错结果可能出现偏差。

还需要提前准备模型服务的API Key，以及一个用于保护LiteLLM入口的管理密钥。不要把密钥直接写进公开仓库，也不要在群聊或工单截图中暴露完整内容。推荐在部署目录下建立独立文件夹，例如/opt/litellm，里面存放配置文件、环境变量文件和数据目录，后续备份与迁移会更清楚。

拉取LiteLLM镜像

LiteLLM常用镜像可从GitHub Container Registry获取。进入部署目录后执行：docker pull ghcr.io/berriai/litellm:main-latest。如果希望稳定性更强，生产环境不建议长期使用最新标签，最好在测试通过后固定到明确版本号，避免上游镜像更新导致行为变化。

镜像拉取完成后可执行docker images | grep litellm查看本地镜像。若拉取失败，先检查网络连通性、Docker服务状态和镜像地址是否输入正确。不要随意使用来源不明的第三方镜像，AI网关会处理密钥和请求内容，镜像可信度直接关系到数据安全。

编写基础配置文件

在/opt/litellm目录创建config.yaml。一个最小配置通常包含模型列表、模型别名和对应的上游参数。示例思路如下：配置一个对外显示的模型名，例如gpt-4o-mini，再在参数中填写实际调用的模型标识和API Key。API Key可以通过环境变量注入，配置文件中引用变量名，避免明文落盘。

配置文件的关键不是写得复杂，而是命名要统一。业务系统调用LiteLLM时只认网关暴露的模型名，后续要切换上游模型时，只要调整网关配置即可。建议先配置一个测试模型，确认请求链路打通后，再逐步添加更多模型和路由规则，避免一次性引入过多变量导致排错困难。

配置环境变量与管理密钥

在部署目录创建.env文件，用来保存运行时参数。常见变量包括LITELLM_MASTER_KEY和上游模型的访问密钥。LITELLM_MASTER_KEY相当于进入网关的总钥匙，建议使用足够长的随机字符串，不要使用生日、项目名、手机号等容易猜到的内容。

如果需要启用管理界面或记录更完整的调用信息，还可以配置数据库连接。初次体验可以先使用轻量方式运行，但正式使用时建议接入独立数据库，并为数据文件设置单独目录和备份策略。无论哪种方式，都应限制.env文件权限，例如只允许部署用户读取，避免其他用户误读敏感信息。

启动容器并设置端口映射

最简单的启动方式是使用docker run。示例命令为：docker run -d --name litellm --env-file /opt/litellm/.env -p 4000:4000 -v /opt/litellm/config.yaml:/app/config.yaml ghcr.io/berriai/litellm:main-latest --config /app/config.yaml --port 4000。其中-p 4000:4000表示把宿主机4000端口映射到容器4000端口，外部系统通过宿主机地址加4000端口访问。

如果4000端口已被占用，可以改成-p 14000:4000，表示宿主机使用14000端口，容器内部仍是4000端口。端口开放要遵循最小范围原则：本机调试可以只绑定本地地址；内网使用则只允许业务服务器访问；不建议把管理入口直接暴露到公网。如果必须对外提供服务，应放在反向袋里后面，配合HTTPS、访问控制和日志审计。

数据目录如何配置

很多用户只挂载配置文件，却忽略数据目录。LiteLLM本身的配置可通过config.yaml维护，但日志、数据库文件、缓存或扩展组件产生的数据也需要有明确归属。建议在/opt/litellm下创建data、logs、backup三个目录，用于区分运行数据、日志文件和备份文件。

如果使用容器内置的轻量存储，需通过-v /opt/litellm/data:/app/data一类参数把容器内目录挂载到宿主机，防止删除容器后数据丢失。更推荐的方式是使用外部数据库，将数据库的数据卷也挂载到固定目录。这样升级LiteLLM镜像时，只需要停止旧容器、启动新容器，配置和数据仍保留在宿主机。

使用Docker Compose管理

长期运行时，Docker Compose比单条命令更易维护。可以把镜像、端口、环境变量、配置挂载、数据目录和重启策略写入同一个编排文件。核心配置思路包括：服务名设为litellm，镜像使用固定版本，端口映射为4000:4000，环境变量从.env读取，配置文件挂载到/app/config.yaml，数据目录挂载到/app/data，并设置restart: unless-stopped。

采用Compose后，启动可使用docker compose up -d，查看状态使用docker compose ps，查看日志使用docker compose logs -f litellm。当需要升级镜像时，先备份配置和数据，再拉取新镜像，最后重新创建服务。生产环境升级前应在测试环境验证配置兼容性，不要在业务高峰期直接替换。

连通性测试与调用验证

容器启动后先执行docker ps确认状态为运行中，再用docker logs litellm --tail 100查看是否加载配置成功。若日志中间出现配置文件路径错误、密钥缺失或模型参数错误，应先修正配置再重启容器。

接口测试可以使用curl或接口调试工具，请求地址一般为http://服务器地址:4000/v1/chat/completions，请求头中携带Authorization: Bearer 你的LITELLM_MASTER_KEY。测试时使用短提示词即可，重点观察返回是否正常、模型名是否匹配、耗时是否稳定。不要在测试请求中放入真实客户资料、内部文档或不可公开的业务数据。

常见问题排查

第一类问题是端口无法访问。常见原因包括容器未启动、端口映射写反、宿主机防火墙未放行、云服务器安全规则未配置，或服务只绑定在容器内部地址。排查顺序建议从docker ps开始，再看容器日志，最后检查宿主机端口监听和网络规则。

第二类问题是鉴权失败。通常是请求头没有带Bearer前缀、使用了错误的管理密钥，或服务重启后读取了旧的环境变量。修改.env后必须重新创建容器，仅重启不一定能让所有参数生效。第三类问题是模型调用失败，可能是上游密钥无效、模型名称写错、额度不足、请求格式不符合目标模型要求，应结合LiteLLM日志和上游返回信息定位。

安全边界与运维建议

LiteLLM是统一入口，便利性越高，越要重视边界。不要把所有模型密钥都交给不可信人员维护；不要让业务方绕过网关直接使用上游密钥；不要在日志中长期保存完整提示词和响应内容，除非已获得明确授权并做好脱敏。对于多人团队，建议按环境区分密钥，例如开发、测试、生产分别使用不同配置。

运维上建议固定镜像版本、保留最近几次可用配置、定期备份数据目录，并记录每次变更内容。上线前准备回滚方案：保留旧镜像标签、旧配置文件和旧数据备份，一旦新版本异常，可快速停止新容器并恢复旧版本。对于承载正式业务的网关，还应配置健康检查、监控告警和请求限流，避免异常流量拖垮后端模型服务。

适用场景总结

Docker部署LiteLLM适合模型调用量逐步增长、需要统一API入口、希望降低业务代码耦合的团队。个人开发者可以用它快速验证多模型切换；中小团队可以用它集中管理密钥和调用日志；企业内部项目则可结合数据库、权限策略和监控系统，把它作为AI能力接入层的一部分。

实际落地时，先跑通最小可用版本，再补齐数据持久化、端口访问控制、日志策略和备份机制，是最稳妥的路线。部署命令并不复杂，真正影响稳定性的往往是配置管理和安全习惯。只要把镜像来源、端口边界、数据目录和密钥保护这几件事做好，LiteLLM就能成为可靠的AI网关基础组件。