从“能启动”到“可验证” ，一条命令在 Anolis OS 拉起统一大模型网关

（图 1/ 统一入口、安全路由和容器化运行的概念封面）

专注于 Infra 层的 AI Agent 技能平台——龙蜥社区 SkillHub 已收到数百个技能，当前陆续上线中。我们每周也会收到一些技能的最佳实践分享，本期给大家推荐的是王紫妍贡献的 LiteLLM 统一大模型网关一键部署 Skill 实践文章。以下是他们的实战经验分享：

为什么需要统一大模型网关

应用同时接入多个大模型服务时，最先出现的问题通常不是模型能力，而是接口和运维方式不统一：不同供应商使用不同的模型名称、密钥和地址；业务代码需要反复适配；服务健康状态、鉴权和升级也缺少统一入口。

LiteLLM Proxy 提供 OpenAI 兼容接口，可把不同上游模型映射成稳定的客户端模型别名。基于这个能力，我将部署流程整理成 LiteLLM 统一大模型网关一键部署 Skill，希望解决四个问题：

1、在 Anolis OS 上以可重复方式部署 LiteLLM Proxy；

2、使用 Podman 隔离运行环境，并交由 systemd 管理生命周期；

3、默认只监听本机地址，避免管理接口意外暴露；

4、将“服务启动”“网关鉴权”和“上游模型可用”拆成不同验证层级。

整体架构

（图 2/业务应用通过 OpenAI 兼容接口访问 LiteLLM，模型路由、运行环境和密钥文件彼此分离）

这里有两个关键边界：

LiteLLM 默认绑定 127.0.0.1:4000，不直接暴露到公网；
模型密钥和网关主密钥存放在受保护的环境文件中，不写入 YAML、命令行或公开日志。

Skill 的设计思路

1、先检查，再安装

部署前先运行无特权预检：

bash scripts/preflight.sh

预检会确认：

当前系统是否为 Anolis OS；
CPU 架构是否属于已覆盖范围；
Podman 是否已经安装或可从 DNF 仓库获取；
可用内存和根文件系统空间是否满足基础要求；
TCP 4000 端口是否被占用；
安装时是否需要交互式 sudo 授权。

预检只读取系统状态，不安装软件，也不更改防火墙。

2. 镜像使用不可变摘要

部署脚本不使用容易漂移的 latest 标签。本次验证使用固定摘要：

ghcr.io/berriai/litellm@sha256:caee7ffd8ae5ff84d4d37610a1871367eb037d5349ace155b2f9fd9e44cb5e1f

固定摘要可以保证重复部署拉取的是同一份镜像。升级时应先核对新摘要、记录旧摘要，再执行验证；需要回滚时重新指定旧摘要即可。

3. 配置与密钥分离

模型路由写入 /etc/litellm/config.yaml：

model_list:
- model_name: default
litellm_params:
model: openai/gpt-4o-mini
api_key: os.environ/OPENAI_API_KEY

general_settings:
master_key: os.environ/LITELLM_MASTER_KEY

文件中只有环境变量名称，没有真实密钥。真实值存放于：
/etc/litellm/litellm.env

安装脚本将其权限设为 0600。添加供应商密钥时使用 sudoedit，避免密钥进入命令历史：

sudoedit /etc/litellm/litellm.env
sudo chmod 600 /etc/litellm/litellm.env
sudo systemctl restart litellm-gateway

4. systemd 管理容器生命周期

Skill 创建 litellm-gateway.service，由 systemd 负责开机启动、停止和失败重启。容器配置文件以只读卷挂载，密钥通过环境文件注入。

这种方式保留了 Podman 的容器隔离，同时让运维人员可以使用熟悉的命令管理服务：

sudo systemctl status litellm-gateway
sudo systemctl restart litellm-gateway
sudo journalctl -u litellm-gateway

一键部署流程

（图 3/从无特权预检到分层验证，每一步都有明确的授权边界）

完成预检并确认镜像摘要、监听地址、端口、模型别名和维护窗口后，执行：

 sudo bash scripts/install.sh

如需更换客户端看到的模型别名和上游模型，可以通过环境变量覆盖：

 sudo env \ MODEL_ALIAS=default \ UPSTREAM_MODEL=openai/gpt-4o-mini \ bash scripts/install.sh

安装过程会：

在缺少 Podman 时通过 DNF 安装；
创建/etc/litellm 配置目录；
生成或保留网关主密钥；
写入 LiteLLM 配置和 systemd 单元；
拉取固定摘要镜像；
启用并启动 litellm-gateway.service。

脚本拒绝未经审查的非回环监听地址。如果确实需要外部访问，应另行设计 TLS、网关鉴权、防火墙和云安全组，不能简单地把监听地址改成 0.0.0.0。

不要把“健康”误当成“模型可用”

这是开发过程中最重要的一次认识。一个 HTTP 200 只能证明某一层工作正常，不能直接证明整个调用链成功。

验证层级	检查内容	能证明什么
L1	systemd 服务状态	服务进程处于活动状态
L2	本机健康接口	LiteLLM Proxy 正在响应
L3	携带主密钥访问 /v1/models	网关鉴权和配置已加载
L4	发起真实 completion 请求	上游密钥、网络和模型路由全部可用

基础验证：

bash scripts/verify.sh

鉴权验证不会把主密钥放入进程参数或输出：

sudo python3 scripts/verify-auth.py

只有 L4 的真实补全请求成功后，才能声明上游模型路由可用。为了避免产生费用，本次公开验证没有执行付费 completion 请求。

Anolis OS 8.2 实机验证结果

（图 4/匿名化实机验证摘要，同时列出资源约束和未测试项目）

本次在匿名化的 Anolis OS 8.2 主机上进行了只读复核，得到以下结果：

[PASS] host=Anolis OS 8.2 [PASS] runtime=podman version 4.9.4-rhel [PASS] litellm-gateway.service is active [PASS] liveliness endpoint returned HTTP 200 [PASS] socket=127.0.0.1:4000 (loopback only) summary pass=5 warn=0 fail=0

网关鉴权验证结果：

PASS authenticated models endpoint returned HTTP 200 models=default

测试明确未覆盖：

上游供应商密钥有效性；
真实聊天补全路由；
公网 TLS 反向代理；
生产负载与并发压力。

把未测试项标成 SKIP，比给出一个不真实的“全部通过”更有价值。

资源占用与踩坑记录

验证主机只有约 1.8 GiB 内存。LiteLLM 容器启动后观察到约 1.05 GB 内存占用，主机剩余可用内存约 441 MB，且没有 Swap。

这套配置可以完成验证，但不适合直接作为持续生产规格。实际部署至少需要根据并发、日志、上游连接数和反向代理开销重新评估内存，并配置监控和容量告警。

其他容易踩坑的地方包括：

1. 使用 latest 导致重新部署后版本发生变化；

2. 把供应商 API Key 直接写进 YAML 或命令行；

3.看到健康接口返回 200 就宣布模型调用成功；

4.为了方便测试直接开放 4000 端口到公网；

5.更新镜像前没有记录旧摘要，失败后无法快速回滚。

总结

统一大模型网关不只是启动一个容器。一个可维护的方案还需要不可变镜像、密钥隔离、最小暴露、服务托管、分层验证和明确回滚路径。

LLM 统一大模型网关一键部署 Skill 把这些步骤固化成可重复流程，让 Agent 在执行部署时知道哪些操作可以自动完成，哪些操作必须经过用户确认，也让最终报告能够准确区分“服务活着”“鉴权正常”和“上游模型真正可用”。

相关链接：

LiteLLM 统一大模型网关一键部署：

https://skillhub.openanolis.cn/skill/deploy-litellm-gateway

Skillhub 官网链接：

https://skillhub.openanolis.cn

LiteLLM 官方文档：

https://docs.litellm.ai/

Podman systemd/Quadlet 官方文档：

https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html

龙蜥社区 Skill 征集活动——「Skill 创造营」上线以来响应热烈。截至目前，龙蜥 SkillHub 已收到覆盖安全、系统运维、AI 推理、数据库等多个领域，一个面向 Infra 的 AI 技能生态正在加速成型。「Skill 创造营」持续征集中，诚挚欢迎每一位开发者提交你的 Skill 与最佳实践。如果你有感兴趣的方向或者关于 SkillHub 的问题，欢迎通过下方链接反馈给我们。
SkillHub 用户需求收集链接：
https://alidocs.dingtalk.com/notable/share/form/v014jKqm0b74KdjLnw1_f22ghuX_M7AJs3D