LiteLLM Azure Container Apps 部署

本项目用于在 Azure Container Apps 上部署 LiteLLM 代理服务器，支持 Taiji AI Cloud、OpenRouter 和 XMind 三个模型供应商。

架构概览

┌─────────────────────────────────────────────────────────────────┐
│                    Azure Container Apps                          │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   LiteLLM Proxy                          │    │
│  │                   (Port 4000)                            │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │    │
│  │  │  Swagger UI │  │  Admin UI   │  │   API       │      │    │
│  │  │     /       │  │    /ui      │  │  /v1/*      │      │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Azure Redis    │  │ Azure PostgreSQL│  │ Model Providers │
│  Cache (SSL)    │  │    (SSL)        │  │                 │
│  Port 10000     │  │    Port 5432    │  │ • Taiji AI Cloud│
└─────────────────┘  └─────────────────┘  │ • OpenRouter    │
                                          │ • XMind         │
                                          └─────────────────┘

功能特性

• ✅ 多模型供应商支持: Taiji AI Cloud、OpenRouter 和 XMind
• ✅ 通配符路由: 支持 taiji/* 和 openrouter/* 动态模型路由
• ✅ Redis SSL 连接: 安全连接 Azure Redis Cache
• ✅ PostgreSQL 数据库: 持久化存储 API 密钥和使用记录
• ✅ Admin UI: 可视化管理界面
• ✅ JSON 日志: 结构化日志输出
• ✅ 健康检查禁用: 避免不必要的 API 调用
• ✅ 生产优化: 批量写入、连接池、Worker 回收

现有资源

资源	名称	说明
资源组	taiji-ai-pda	Azure 资源组
Container App	litellm	LiteLLM 容器应用
FQDN	litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io	访问地址

快速开始

前置条件

• Azure CLI 已安装并登录
• Docker 已安装
• 已有 Azure Container App（已创建）

1. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入实际值
vim .env

2. 构建并推送镜像

方法一：使用快速脚本（推荐）

# 赋予脚本执行权限
chmod +x build-and-push.sh

# 构建并推送到 ACR（使用 latest 标签）
./build-and-push.sh

# 或指定标签
./build-and-push.sh v1.0.0

方法二：使用完整部署脚本

# 赋予脚本执行权限
chmod +x deploy.sh

# 构建镜像
./deploy.sh build

# 推送到 ACR
./deploy.sh push

3. 部署到 Azure Container Apps

# 更新 secrets 和容器配置
./deploy.sh deploy

# 或者一键完成所有步骤
./deploy.sh all

4. 验证部署

# 查看状态
./deploy.sh status

# 测试健康检查
./deploy.sh test

# 测试 API
./deploy.sh test-api

配置说明

模型调用示例

使用 Taiji AI Cloud 模型

# 通配符路由
curl -X POST https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/chat/completions \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "taiji/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# 直接使用别名
curl -X POST https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/chat/completions \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

使用 OpenRouter 模型

# 通配符路由
curl -X POST https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/chat/completions \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/anthropic/claude-3.5-sonnet",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

使用 XMind 模型

# OpenAI 兼容模型
curl -X POST https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/chat/completions \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xmind/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Anthropic 兼容模型
curl -X POST https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/chat/completions \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xmind/claude-3.7-sonnet",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Vertex AI 兼容模型
curl -X POST https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/chat/completions \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xmind/gemini-2.5-pro",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

环境变量说明

变量	说明	必需
LITELLM_MASTER_KEY	代理管理密钥（必须以 sk- 开头）	✅
LITELLM_SALT_KEY	数据库加密密钥	✅
DATABASE_URL	PostgreSQL 连接字符串	✅
REDIS_HOST	Redis 主机地址	✅
REDIS_PORT	Redis 端口（默认 10000）	✅
REDIS_PASSWORD	Redis 密码	✅
REDIS_SSL	启用 Redis SSL（true/false）	✅
TAIJI_API_KEY	Taiji AI Cloud API 密钥	✅
OPENROUTER_API_KEY	OpenRouter API 密钥	✅
XMIND_API_KEY_OPENAI	XMind OpenAI 兼容 API 密钥（有默认值）	❌
XMIND_API_KEY_ANTHROPIC	XMind Anthropic 兼容 API 密钥（有默认值）	❌
XMIND_API_KEY_VERTEX_AI	XMind Vertex AI 兼容 API 密钥（有默认值）	❌
ACR_PASSWORD	Azure Container Registry 密码（用于推送镜像）	✅
UI_USERNAME	Admin UI 用户名	❌
UI_PASSWORD	Admin UI 密码	❌

访问端点

端点	说明
/	Swagger UI 文档
/ui	Admin UI 管理界面
/health/liveliness	存活检查
/health/readiness	就绪检查
/v1/chat/completions	Chat Completions API
/v1/models	模型列表

部署脚本命令

./deploy.sh build      # 构建 Docker 镜像
./deploy.sh push       # 推送镜像到 ACR
./deploy.sh secrets    # 更新 Container App Secrets
./deploy.sh update     # 更新 Container App 配置和镜像
./deploy.sh deploy     # 完整部署 (secrets + update)
./deploy.sh status     # 查看 Container App 状态
./deploy.sh logs       # 查看 Container App 日志
./deploy.sh restart    # 重启 Container App
./deploy.sh test       # 测试健康检查端点
./deploy.sh test-api   # 测试 Chat API
./deploy.sh info       # 显示 Container App 详细信息
./deploy.sh all        # 执行 build + push + deploy
./deploy.sh help       # 显示帮助信息

生产最佳实践

本配置已应用以下 LiteLLM 生产最佳实践：

1. ✅ 使用 redis_host/port/password 而非 redis_url（性能更好）
2. ✅ 启用 Redis SSL 连接
3. ✅ 设置 LITELLM_MODE=PRODUCTION
4. ✅ 设置 LITELLM_LOG=ERROR
5. ✅ 启用 JSON 日志格式
6. ✅ 设置 LITELLM_SALT_KEY 用于加密
7. ✅ 禁用模型健康检查
8. ✅ 配置数据库连接池限制
9. ✅ 启用批量写入优化
10. ✅ 使用 Gunicorn 运行，支持 Worker 回收

故障排除

查看日志

# 实时日志
./deploy.sh logs

# 或使用 Azure CLI
az containerapp logs show \
  --name litellm \
  --resource-group taiji-ai-pda \
  --follow

检查健康状态

# 存活检查
curl https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/health/liveliness

# 就绪检查
curl https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/health/readiness

常见问题

1. Redis 连接失败: 确保 REDIS_SSL=true 且端口为 10000
2. 数据库连接失败: 检查 DATABASE_URL 中的 sslmode=require
3. 模型调用失败: 检查对应的 API 密钥是否正确

文件结构

litellm/
├── config.yaml          # LiteLLM 主配置文件
├── Dockerfile           # Docker 构建文件
├── .env.example         # 环境变量示例
├── deploy.sh            # 完整部署脚本（构建、推送、部署）
├── build-and-push.sh    # 快速构建并推送镜像脚本
└── README.md            # 本文档

相关链接

• LiteLLM 官方文档
• LiteLLM 生产最佳实践
• Azure Container Apps 文档
• OpenRouter 文档