آموزش نصب LiteLLM با Docker Compose روی VPS

نگارنوین

آموزش نصب LiteLLM با Docker Compose روی VPS

https://negarnovin.com/docs/install-litellm-docker/ · آخرین به‌روزرسانی: 2026-10-08 · نویسنده: نگارنوین · سایت: نگارنوین · 20 دقیقه مطالعه

📌 خلاصه (TL;DR)

آموزش نصب LiteLLM با Docker Compose روی VPS — LiteLLM یک AI Gateway متن‌باز است که یک API سازگار با OpenAI در اختیار شما قرار می‌دهد تا بتوانید مدل‌ها و سرویس‌های مختلف هوش مصنوعی را پشت یک درگاه واحد مدیریت کنید. با اجرای LiteLLM روی یک VPS، می‌توانید احراز هویت،…

📊 حقایق کلیدی

URL	https://negarnovin.com/docs/install-litellm-docker/
تاریخ انتشار	2026-10-08
آخرین به‌روزرسانی	2026-10-08
نویسنده	نگارنوین
ناشر	نگارنوین
زبان	فارسی (fa-IR)
تعداد کلمات	3802
نوع صفحه	برگه

📄 محتوای کامل

آموزش نصب LiteLLM با Docker Compose روی VPS

LiteLLM یک AI Gateway متن‌باز است که یک API سازگار با OpenAI در اختیار شما قرار می‌دهد تا بتوانید مدل‌ها و سرویس‌های مختلف هوش مصنوعی را پشت یک درگاه واحد مدیریت کنید. با اجرای LiteLLM روی یک VPS، می‌توانید احراز هویت، Virtual Key، محدودیت بودجه، ثبت مصرف، مسیریابی درخواست‌ها و دسترسی برنامه‌ها به مدل‌های مختلف را از یک نقطه کنترل کنید.

در این آموزش، LiteLLM را روی یک سرور لینوکسی با Docker Compose اجرا می‌کنیم و برای ذخیره‌سازی اطلاعات از PostgreSQL، برای HTTPS از Traefik + Let’s Encrypt و برای پایش متریک‌ها از Prometheus استفاده خواهیم کرد.

سرور مجازی خارج

نسخه این آموزش: LiteLLM 1.104.0
آخرین بازبینی: ۸ اکتبر ۲۰۲۶

معماری نهایی

پس از پایان نصب، ساختار سرویس به این شکل خواهد بود:

Client / Application
        |
        | HTTPS :443
        v
     Traefik
        |
        v
   LiteLLM :4000
      /        \
     /          \
PostgreSQL     LLM Provider
   :5432
     
Prometheus
   :9090
   داخلی

در این معماری، کاربران و برنامه‌ها مستقیماً با LiteLLM ارتباط دارند. Traefik درخواست‌های HTTPS را دریافت می‌کند و به LiteLLM می‌فرستد. PostgreSQL اطلاعات مربوط به کلیدها، کاربران، مصرف و تنظیمات را نگه می‌دارد و Prometheus متریک‌های LiteLLM را جمع‌آوری می‌کند.

PostgreSQL برای قابلیت‌هایی مانند Virtual Key، مدیریت کاربران و ثبت هزینه و مصرف اهمیت دارد؛ در deployment بدون دیتابیس، این قابلیت‌ها در دسترس نخواهند بود. Redis نیز برای یک نصب تک‌سروری ضروری نیست و زمانی اهمیت بیشتری پیدا می‌کند که چند نمونه LiteLLM، rate limiting توزیع‌شده، routing state یا cache مشترک داشته باشید.

LiteLLM چه کاربردی دارد؟

فرض کنید یک برنامه دارید که امروز از OpenAI استفاده می‌کند و فردا قصد دارید از Anthropic، Gemini، مدل داخلی یا یک سرویس دیگر نیز استفاده کنید.

بدون Gateway، معمولاً باید منطق احراز هویت، مدیریت کلیدها، مسیریابی و کنترل هزینه را در خود برنامه پیاده کنید.

LiteLLM این لایه را جدا می‌کند:

Application
     |
     v
 LiteLLM
  / | \
 /  |  \
AI  AI  AI

در نتیجه، برنامه شما به‌جای اینکه مستقیماً به هر Provider متصل شود، با یک API مرکزی کار می‌کند.

یکی از ویژگی‌های مهم LiteLLM این است که API آن با الگوی OpenAI سازگار است؛ بنابراین بسیاری از برنامه‌هایی که از OpenAI SDK استفاده می‌کنند، فقط با تغییر base_url و API Key می‌توانند از Gateway شما استفاده کنند.

پیش‌نیازهای نصب LiteLLM

برای این آموزش پیشنهاد می‌شود از یک VPS لینوکسی استفاده کنید.

حداقل پیشنهادی برای شروع:

مورد	مقدار پیشنهادی
سیستم‌عامل	Ubuntu ۲۲.۰۴ یا Ubuntu ۲۴.۰۴
CPU	حداقل ۴ هسته
RAM	حداقل 8GB
دسترسی	کاربر معمولی با `sudo`
Docker	نصب‌شده
Docker Compose	نصب‌شده
دامنه	دارای DNS A Record
API Key	حداقل یک Provider هوش مصنوعی

حداقل منابع ۴ CPU و 8GB RAM در آموزش Vultr نیز به‌عنوان پیش‌نیاز معرفی شده است.

توجه: LiteLLM خودش مدل زبانی را اجرا نمی‌کند. این Gateway درخواست را به Provider یا مدل شما ارسال می‌کند. بنابراین مقدار CPU و RAM موردنیاز به نوع استفاده، تعداد درخواست‌ها، logging، routing و سرویس‌های جانبی نیز بستگی دارد.

مرحله اول: نصب Docker و Docker Compose

ابتدا سیستم را به‌روزرسانی کنید:

sudo apt update
sudo apt upgrade -y

سپس ابزارهای پایه را نصب کنید:

sudo apt install -y ca-certificates curl gnupg openssl python3 python3-venv

اگر Docker روی سرور نصب نیست، می‌توانید از اسکریپت رسمی نصب Docker استفاده کنید:

curl -fsSL https://get.docker.com | sudo sh

سرویس Docker را فعال کنید:

sudo systemctl enable --now docker

کاربر فعلی را به گروه Docker اضافه کنید:

sudo usermod -aG docker $USER

برای اعمال گروه جدید:

newgrp docker

نسخه Docker و Compose را بررسی کنید:

docker --version
docker compose version

اگر هر دو دستور خروجی معتبر برگردانند، محیط برای ادامه نصب آماده است.

مرحله دوم: ساخت پوشه LiteLLM

پوشه اصلی پروژه را ایجاد کنید:

mkdir -p ~/litellm/{letsencrypt,postgres,prometheus}
cd ~/litellm

Prometheus در کانتینر خود با UID مشخصی اجرا می‌شود. برای اینکه بتواند اطلاعات متریک‌ها را در پوشه مربوطه ذخیره کند، مجوز مناسب را تنظیم کنید:

sudo chown -R 65534:65534 prometheus

برای فایل گواهی Traefik نیز فایل ACME را ایجاد و محدود کنید:

touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.json

در این مرحله ساختار پوشه باید تقریباً به این شکل باشد:

~/litellm/
├── letsencrypt/
├── postgres/
└── prometheus/

مرحله سوم: ساخت کلیدهای امنیتی LiteLLM

LiteLLM به یک Master Key نیاز دارد. این کلید برای احراز هویت مدیریتی Gateway استفاده می‌شود.

آموزش نصب LiteLLM با Docker Compose

یک کلید تصادفی بسازید:

openssl rand -hex 32

خروجی را ذخیره کنید.

دوباره همین دستور را اجرا کنید تا کلید دوم ساخته شود:

openssl rand -hex 32

کلید اول برای:

LITELLM_MASTER_KEY

و کلید دوم برای:

LITELLM_SALT_KEY

استفاده خواهد شد.

پیشوند sk- را می‌توانید به مقادیر اضافه کنید:

sk-xxxxxxxxxxxxxxxx

هشدار مهم درباره LITELLM_SALT_KEY

LITELLM_SALT_KEY فقط یک رمز معمولی نیست. این مقدار برای رمزنگاری اطلاعات Provider در دیتابیس استفاده می‌شود.

بعد از اضافه‌شدن مدل‌ها و اطلاعات Provider، تغییر این مقدار می‌تواند باعث شود credentialهای ذخیره‌شده در PostgreSQL دیگر قابل خواندن نباشند. بنابراین آن را در محل امنی نگهداری کنید و هیچ‌گاه داخل Git یا فایل عمومی قرار ندهید.

مرحله چهارم: ساخت فایل .env

فایل متغیرهای محیطی را بسازید:

nano .env

محتوای زیر را قرار دهید:

DOMAIN=llm.example.com
[email protected]

LITELLM_MASTER_KEY=sk-YOUR_MASTER_KEY
LITELLM_SALT_KEY=sk-YOUR_SALT_KEY

LLM_PROVIDER_API_KEY=YOUR_LLM_PROVIDER_API_KEY

POSTGRES_PASSWORD=YOUR_STRONG_DATABASE_PASSWORD

UI_USERNAME=admin
UI_PASSWORD=YOUR_STRONG_UI_PASSWORD

مقادیر نمونه را با اطلاعات واقعی خودتان جایگزین کنید.

مثلاً:

DOMAIN=ai.example.com
[email protected]

LITELLM_MASTER_KEY=sk-xxxxxxxxxxxxxxxx
LITELLM_SALT_KEY=sk-yyyyyyyyyyyyyyyy

LLM_PROVIDER_API_KEY=YOUR_PROVIDER_KEY

POSTGRES_PASSWORD=CHANGE_THIS_TO_A_STRONG_PASSWORD

UI_USERNAME=admin
UI_PASSWORD=CHANGE_THIS_TO_A_LONG_RANDOM_PASSWORD

مجوز فایل را محدود کنید:

chmod 600 .env

مرحله پنجم: ساخت config.yaml

فایل تنظیمات اصلی LiteLLM را بسازید:

nano config.yaml

برای شروع، ساختار زیر مناسب است:

model_list:
  - model_name: my-model
    litellm_params:
      model: provider/model-name
      api_key: os.environ/LLM_PROVIDER_API_KEY

litellm_settings:
  callbacks:
    - prometheus
  require_auth_for_metrics_endpoint: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

عبارت زیر:

provider/model-name

باید با Provider و شناسه مدل واقعی شما جایگزین شود.

مثلاً ساختار نام مدل در LiteLLM به این شکل است:

provider/model-name

در نتیجه، LiteLLM می‌تواند یک نام داخلی برای برنامه شما تعریف کند:

model_name: my-model

در حالی که پشت این نام، مدل واقعی Provider قرار دارد.

این روش باعث می‌شود برنامه‌های شما به‌جای وابستگی مستقیم به نام مدل Provider، با یک alias ثابت کار کنند.

مرحله ششم: تنظیم Prometheus

فایل Prometheus را ایجاد کنید:

nano prometheus.yml

محتوای زیر را قرار دهید:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "litellm"
    static_configs:
      - targets: ["litellm:4000"]

    bearer_token: "sk-YOUR_MASTER_KEY"

مقدار:

sk-YOUR_MASTER_KEY

را با همان مقدار واقعی LITELLM_MASTER_KEY جایگزین کنید.

در این تنظیم، Prometheus متریک‌های LiteLLM را از شبکه داخلی Docker دریافت می‌کند و endpoint عمومی /metrics نیز با احراز هویت محافظت می‌شود.

مرحله هفتم: ساخت Docker Compose

فایل Compose را ایجاد کنید:

nano docker-compose.yaml

نسخه زیر را قرار دهید:

services:

  traefik:
    image: traefik:v3.6
    container_name: traefik
    restart: unless-stopped

    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"

      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"

      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"

      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"

    ports:
      - "80:80"
      - "443:443"

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt


  litellm:
    image: ghcr.io/berriai/litellm:v1.104.0
    container_name: litellm
    restart: unless-stopped

    env_file:
      - .env

    environment:
      DATABASE_URL: "postgresql://llmproxy:${POSTGRES_PASSWORD}@db:5432/litellm"
      STORE_MODEL_IN_DB: "True"

    volumes:
      - ./config.yaml:/app/config.yaml:ro

    command:
      - "--config=/app/config.yaml"

    expose:
      - "4000"

    depends_on:
      db:
        condition: service_healthy

    healthcheck:
      test:
        [
          "CMD-SHELL",
          "python3 -c \"import urllib.request; urllib.request.urlopen('http://localhost:4000/health/liveliness')\""
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.litellm.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.litellm.entrypoints=websecure"
      - "traefik.http.routers.litellm.tls=true"
      - "traefik.http.routers.litellm.tls.certresolver=le"
      - "traefik.http.services.litellm.loadbalancer.server.port=4000"


  db:
    image: postgres:16
    container_name: litellm_db
    restart: unless-stopped

    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: llmproxy
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

    volumes:
      - ./postgres:/var/lib/postgresql/data

    expose:
      - "5432"

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d litellm -U llmproxy"]
      interval: 5s
      timeout: 5s
      retries: 10


  prometheus:
    image: prom/prometheus:latest
    container_name: litellm_prometheus
    restart: unless-stopped

    volumes:
      - ./prometheus:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro

    expose:
      - "9090"

    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=15d"

در این معماری فقط Traefik پورت‌های عمومی ۸۰ و ۴۴۳ را منتشر می‌کند. پورت‌های PostgreSQL، Prometheus و LiteLLM مستقیماً روی اینترنت باز نمی‌شوند.

مستندات فعلی LiteLLM استفاده از image رسمی ghcr.io/berriai/litellm و pin کردن نسخه را برای deploymentهای monolithic توصیه می‌کند. همچنین نسخه ۱.۱۰۴.۰ مستقیماً در release notes رسمی به‌عنوان release قابل استقرار معرفی شده است.

سرور خارج

مرحله هشتم: بررسی فایل Compose

قبل از اجرای سرویس‌ها، فایل Compose را بررسی کنید:

docker compose config

اگر خطای YAML یا متغیر محیطی وجود نداشته باشد، خروجی نهایی Compose نمایش داده می‌شود.

سپس imageها را دریافت کنید:

docker compose pull

مرحله نهم: بررسی امنیت image LiteLLM با Cosign

LiteLLM برای imageهای Docker خود از Cosign استفاده می‌کند. بررسی امضای image قبل از اجرای سرویس، یک مرحله امنیتی مفید برای اطمینان از اصالت image است.

Cosign را دریافت کنید:

curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64"

سپس آن را نصب کنید:

sudo mv cosign-linux-amd64 /usr/local/bin/cosign
sudo chmod +x /usr/local/bin/cosign

نسخه را بررسی کنید:

cosign version

اکنون image LiteLLM را بررسی کنید:

cosign verify \
  --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
  ghcr.io/berriai/litellm:v1.104.0

در صورت موفقیت، Cosign اطلاعات مربوط به signature را نمایش می‌دهد.

مرحله دهم: اجرای LiteLLM

اکنون تمام سرویس‌ها را اجرا کنید:

docker compose up -d

وضعیت containerها را بررسی کنید:

docker compose ps

باید سرویس‌های زیر را ببینید:

traefik
litellm
litellm_db
litellm_prometheus

برای بررسی لاگ LiteLLM:

docker compose logs --tail=100 litellm

برای بررسی Traefik:

docker compose logs --tail=100 traefik

برای بررسی PostgreSQL:

docker compose logs --tail=100 db

مرحله یازدهم: ورود به پنل LiteLLM

پس از صدور گواهی SSL، آدرس پنل را در مرورگر باز کنید:

https://llm.example.com/ui

به‌جای llm.example.com دامنه خودتان را قرار دهید.

نام کاربری و رمز عبور همان مقادیری هستند که در .env تعیین کردید:

UI_USERNAME=admin
UI_PASSWORD=YOUR_STRONG_UI_PASSWORD

LiteLLM پنل مدیریتی را برای مشاهده مدل‌ها، Virtual Keyها، مصرف و هزینه در اختیار شما قرار می‌دهد.

اگر HTTPS فعال نشد

اول DNS را بررسی کنید.

باید یک A Record داشته باشید:

llm.example.com  ->  SERVER_IP

پورت‌های زیر نیز باید از اینترنت قابل دسترسی باشند:

80/tcp
443/tcp

اگر روی VPS فایروال فعال است:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

سپس:

docker compose logs traefik

یکی از خطاهای رایج، DNS اشتباه یا اشغال بودن پورت ۸۰/۴۴۳ توسط سرویس دیگری است.

اگر cPanel، Apache یا LiteSpeed روی همان VPS روی پورت‌های ۸۰ و ۴۴۳ فعال باشد، این معماری را روی همان سرور اجرا نکنید. برای LiteLLM از VPS جدا استفاده کنید.

مرحله دوازدهم: بررسی سلامت LiteLLM

وضعیت healthcheck داخلی را از داخل container بررسی کنید:

docker compose exec litellm \
python3 -c "import urllib.request; print(urllib.request.urlopen('http://localhost:4000/health/liveliness').read().decode())"

اگر سرویس سالم باشد، پاسخ HTTP معتبر دریافت می‌کنید.

وضعیت PostgreSQL را نیز بررسی کنید:

docker compose exec db \
pg_isready -U llmproxy -d litellm

خروجی سالم معمولاً شامل عبارتی مشابه زیر خواهد بود:

accepting connections

مرحله سیزدهم: تست API با Python

برای تست API سازگار با OpenAI، ابتدا محیط مجازی Python بسازید:

python3 -m venv litellm-env

آن را فعال کنید:

source litellm-env/bin/activate

سپس OpenAI SDK را نصب کنید:

pip install -U openai

کلید اصلی و دامنه Gateway را به محیط وارد کنید:

export LITELLM_MASTER_KEY="sk-YOUR_MASTER_KEY"
export LITELLM_DOMAIN="llm.example.com"

فایل تست را ایجاد کنید:

nano test_litellm.py

محتوا:

import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["LITELLM_MASTER_KEY"],
    base_url=f"https://{os.environ['LITELLM_DOMAIN']}/v1",
)


response = client.chat.completions.create(
    model="my-model",
    messages=[
        {
            "role": "user",
            "content": "LiteLLM چیست؟",
        }
    ],
)

print(response.choices[0].message.content)

اسکریپت را اجرا کنید:

python3 test_litellm.py

اگر پاسخ مدل نمایش داده شد، Gateway با موفقیت درخواست را دریافت کرده، مدل را پیدا کرده و آن را به Provider ارسال کرده است.

مرحله چهاردهم: ساخت Virtual Key

استفاده مستقیم از Master Key برای تمام برنامه‌ها کار درستی نیست.

برای هر برنامه یا کاربر بهتر است یک Virtual Key مجزا ایجاد کنید. LiteLLM امکان تعیین model access، budget و rate limit را برای کلیدها فراهم می‌کند.

ابتدا:

export LITELLM_MASTER_KEY="sk-YOUR_MASTER_KEY"
export LITELLM_DOMAIN="llm.example.com"

سپس:

curl -sS -X POST \
  "https://${LITELLM_DOMAIN}/key/generate" \
  -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "test-app-key",
    "models": ["my-model"],
    "max_budget": 5.00
  }'

در پاسخ، LiteLLM یک کلید Virtual Key در اختیار شما قرار می‌دهد.

مثلاً:

sk-xxxxxxxxxxxxxxxx

این کلید را مانند password یا API credential محرمانه نگه دارید.

مرحله پانزدهم: تست Virtual Key

کلید تولیدشده را در یک متغیر ذخیره کنید:

export LITELLM_VIRTUAL_KEY="sk-YOUR_VIRTUAL_KEY"

حالا با Virtual Key یک درخواست API ارسال کنید:

curl -X POST \
  "https://${LITELLM_DOMAIN}/v1/chat/completions" \
  -H "Authorization: Bearer ${LITELLM_VIRTUAL_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "messages": [
      {
        "role": "user",
        "content": "Hello from LiteLLM"
      }
    ]
  }'

اگر پاسخ مدل برگردد، مسیر کامل زیر با موفقیت کار می‌کند:

Application
    ↓
Virtual Key
    ↓
Traefik
    ↓
LiteLLM
    ↓
Provider
    ↓
LLM Response

مرحله شانزدهم: مشاهده مصرف و هزینه

وارد پنل LiteLLM شوید:

https://llm.example.com/ui

در پنل می‌توانید بخش‌های مرتبط با مدل‌ها، Virtual Keyها، Usage و Logs را بررسی کنید.

مزیت استفاده از PostgreSQL در این معماری این است که اطلاعات مدیریت Gateway، کلیدها و داده‌های مصرف بعد از restart یا recreate شدن containerها باقی می‌مانند، چون دیتابیس روی storage دائمی نگهداری می‌شود.

محدود کردن هزینه برای هر API Key

یکی از کاربردهای مهم Virtual Keyها، تعیین سقف هزینه است.

مثلاً:

{
  "key_alias": "website-ai",
  "models": ["my-model"],
  "max_budget": 10.00
}

در این مثال سقف بودجه کلید روی ۱۰ دلار قرار می‌گیرد.

LiteLLM همچنین امکان استفاده از budget duration، محدودیت درخواست و محدودیت token را برای کنترل بهتر مصرف فراهم می‌کند.

برای سرویس‌های واقعی، بهتر است برای هر پروژه یک Key جدا ایجاد کنید:

website-ai
customer-panel
wordpress-plugin
mobile-app
internal-tools

به این ترتیب مصرف هر برنامه جداگانه قابل ردیابی خواهد بود.

نکات امنیتی مهم

فایل .env را هرگز داخل Git قرار ندهید.

برای آن مجوز محدود تنظیم کنید:

chmod 600 .env

پورت‌های زیر را مستقیماً روی اینترنت منتشر نکنید:

4000
5432
9090

در Compose این پورت‌ها فقط با expose در شبکه داخلی Docker در دسترس هستند و تنها Traefik پورت‌های عمومی ۸۰ و ۴۴۳ را منتشر می‌کند.

Master Key را در کد برنامه قرار ندهید. برای برنامه‌ها Virtual Key بسازید.

همچنین LITELLM_SALT_KEY را به‌عنوان یک credential دائمی در نظر بگیرید و از آن backup امن داشته باشید. مستندات فعلی LiteLLM صراحتاً درباره غیرقابل‌چرخش‌بودن این کلید پس از ذخیره credentialهای Provider هشدار می‌دهند.

چرا نباید از LiteLLM v1.۸۹.۱ استفاده کنیم؟

آموزش قدیمی Vultr از v1.89.1 استفاده می‌کند، اما این نسخه مربوط به چند نسل قبل از LiteLLM فعلی است.

در حال حاضر نسخه stable منتشرشده v1.104.0 است و LiteLLM در فاصله کوتاه بین نسخه‌ها تغییرات متعدد امنیتی، Gateway و routing دریافت کرده است. علاوه بر این، صفحه امنیت رسمی پروژه در سال ۲۰۲۶ چندین advisory با severity بالا و بحرانی را ثبت کرده است.

بنابراین برای یک نصب جدید، استفاده از نسخه بسیار قدیمی فقط برای اینکه آموزش اصلی از آن استفاده کرده، توصیه نمی‌شود. نسخه را pin کنید، release notes را بررسی کنید و قبل از ارتقا از PostgreSQL backup بگیرید.

آپدیت LiteLLM

قبل از هر به‌روزرسانی:

cd ~/litellm

از دیتابیس backup تهیه کنید.

سپس release notes نسخه مقصد را بررسی کنید.

بعد image جدید را دریافت کنید:

docker compose pull

و سرویس را مجدداً اجرا کنید:

docker compose up -d

وضعیت را بررسی کنید:

docker compose ps

و لاگ LiteLLM:

docker compose logs --tail=100 litellm

در deploymentهای بزرگ‌تر، LiteLLM برای migrationهای PostgreSQL روال جداگانه‌ای دارد و در معماری production، migration job از proxy instanceها جدا می‌شود. برای نصب‌های چندنمونه‌ای و productionهای حساس، قبل از upgrade باید مستندات migration نسخه مقصد بررسی شود.

خطاهای رایج LiteLLM

خطای ۵۰۲ Bad Gateway

اگر Traefik پاسخ ۵۰۲ برگرداند:

docker compose ps

سپس:

docker compose logs --tail=100 litellm

و:

docker compose logs --tail=100 traefik

همچنین healthcheck LiteLLM را بررسی کنید.

خطای اتصال PostgreSQL

این دستور را اجرا کنید:

docker compose exec db \
pg_isready -U llmproxy -d litellm

اگر PostgreSQL سالم است، لاگ LiteLLM را بررسی کنید:

docker compose logs --tail=200 litellm

مدل پیدا نمی‌شود

مقدار model_name در config.yaml باید دقیقاً با مقداری که در درخواست API ارسال می‌کنید یکسان باشد.

مثلاً اگر دارید:

model_name: my-model

در درخواست نیز باید بنویسید:

{
  "model": "my-model"
}

Provider API Key اشتباه است

اطمینان حاصل کنید که:

LLM_PROVIDER_API_KEY=...

مقدار صحیح دارد و در config.yaml از همان environment variable استفاده شده است:

api_key: os.environ/LLM_PROVIDER_API_KEY

HTTPS صادر نمی‌شود

سه مورد را بررسی کنید:

DNS A Record
Port 80
Port 443

سپس:

docker compose logs traefik

را بررسی کنید.

پنل `/ui` باز نمی‌شود

ابتدا وضعیت container را بررسی کنید:

docker compose ps

سپس:

docker compose logs --tail=200 litellm

همچنین مقادیر زیر در .env را بررسی کنید:

UI_USERNAME=admin
UI_PASSWORD=YOUR_STRONG_PASSWORD

LiteLLM در نسخه‌های فعلی همچنان امکان ورود Admin UI با UI_USERNAME و UI_PASSWORD را دارد؛ اگر UI_PASSWORD تنظیم نشده باشد، رفتار ورود می‌تواند به Master Key وابسته شود. برای محیط‌های حساس، از credential مستقل برای UI و Virtual Keyهای جدا برای برنامه‌ها استفاده کنید.

آیا LiteLLM بدون PostgreSQL هم اجرا می‌شود؟

بله، LiteLLM می‌تواند به‌صورت بدون دیتابیس نیز برای سناریوهای ساده اجرا شود؛ اما در آن حالت قابلیت‌هایی مانند Virtual Key و budget tracking که به دیتابیس متکی هستند در دسترس نخواهند بود.

برای Gatewayای که قرار است چند برنامه یا کاربر از آن استفاده کنند، PostgreSQL انتخاب مناسب‌تری است.

آیا Redis برای LiteLLM لازم است؟

برای یک نصب تک‌سروری ساده، Redis الزام نیست.

اما وقتی LiteLLM را در چند instance اجرا می‌کنید، یا به rate limiting توزیع‌شده، router state و cache مشترک نیاز دارید، Redis وارد معماری می‌شود. در معماری production رسمی LiteLLM نیز Redis به‌عنوان جزء زیرساختی deploymentهای چندنمونه‌ای معرفی شده است.

آیا می‌توان LiteLLM را روی VPS اجرا کرد؟

بله. VPS یکی از ساده‌ترین محیط‌ها برای اجرای LiteLLM است، به‌خصوص زمانی که قصد دارید Docker Compose، PostgreSQL و reverse proxy را روی یک ماشین اجرا کنید.

برای workloadهای بزرگ‌تر، high availability و چند نمونه Gateway، بهتر است معماری به سمت سرورهای مستقل برای دیتابیس و Redis و در ادامه Kubernetes یا زیرساخت مشابه حرکت کند.

LiteLLM برای چه پروژه‌هایی مناسب است؟

LiteLLM می‌تواند برای سناریوهایی مانند این موارد مناسب باشد:

ساخت AI Gateway اختصاصی
اتصال چند Provider از طریق یک API
مدیریت API Key برای چند پروژه
اعمال سقف بودجه
ثبت مصرف توکن
مسیریابی درخواست‌ها بین مدل‌ها
ساخت لایه مرکزی بین اپلیکیشن و سرویس‌های LLM
اتصال نرم‌افزارهایی که از OpenAI SDK استفاده می‌کنند به Gateway داخلی

پرسش‌های متداول

LiteLLM چیست؟

LiteLLM یک AI Gateway متن‌باز است که درخواست‌های مدل‌های زبانی را از طریق یک API یکپارچه مدیریت و به Providerهای مختلف ارسال می‌کند.

آیا LiteLLM رایگان است؟

نسخه Open Source LiteLLM قابل self-host است و هسته Gateway امکاناتی مانند API سازگار با OpenAI، Virtual Key، spend tracking، budget و logging را ارائه می‌کند. قابلیت‌های Enterprise امکانات مدیریتی و سازمانی بیشتری اضافه می‌کنند.

حداقل RAM برای نصب LiteLLM چقدر است؟

برای این سناریو حداقل 8GB RAM و ۴ هسته CPU به‌عنوان نقطه شروع مناسب است؛ مقدار واقعی موردنیاز به تعداد درخواست‌ها و سرویس‌های جانبی وابسته است.

آیا برای LiteLLM به GPU نیاز داریم؟

خیر، اگر LiteLLM فقط به‌عنوان Gateway برای APIهای خارجی استفاده شود، GPU لازم نیست. GPU زمانی مطرح می‌شود که خودتان بخواهید مدل‌های محلی را روی همان سرور اجرا کنید.

Virtual Key در LiteLLM چیست؟

Virtual Key یک credential محدودشده برای دسترسی یک کاربر یا برنامه به Gateway است. می‌توان دسترسی مدل، بودجه و محدودیت درخواست را برای آن تعیین کرد.

آیا LiteLLM با OpenAI SDK کار می‌کند؟

بله. یکی از اهداف LiteLLM ارائه API سازگار با OpenAI است؛ بنابراین در بسیاری از پروژه‌ها با تغییر base_url و API Key می‌توان درخواست‌ها را از Gateway عبور داد.

پورت پیش‌فرض LiteLLM چیست؟

LiteLLM به‌صورت پیش‌فرض سرویس Gateway را روی پورت 4000 ارائه می‌کند. در این معماری، پورت ۴۰۰۰ به اینترنت منتشر نمی‌شود و Traefik از داخل شبکه Docker به آن دسترسی دارد.

جمع‌بندی

با این ساختار، یک LiteLLM AI Gateway مستقل و قابل توسعه روی VPS دارید:

HTTPS
  ↓
Traefik
  ↓
LiteLLM
  ↓
PostgreSQL
  ↓
Virtual Keys / Usage / Budgets

LiteLLM
  ↓
LLM Provider

در کنار آن، Prometheus برای جمع‌آوری متریک‌ها فعال است و PostgreSQL داده‌های مدیریتی و مصرف را به‌صورت دائمی نگهداری می‌کند.

برای استفاده واقعی، توصیه می‌شود LiteLLM را روی VPS جداگانه اجرا کنید، نسخه را pin نگه دارید، .env و کلیدها را امن نگه دارید، از Master Key برای اپلیکیشن‌ها استفاده نکنید و برای هر برنامه Virtual Key جدا بسازید.

در این آموزش از LiteLLM v1.104.0 استفاده شده است؛ در صورت انتشار نسخه stable جدیدتر، پیش از تغییر نسخه release notes و migrationهای PostgreSQL را بررسی کنید.

🖼️ تصاویر

آموزش نصب LiteLLM با Docker Compose

🏷️ کلمات کلیدی

آموزش نصب LiteLLM، نصب LiteLLM، نصب LiteLLM روی VPS، LiteLLM Docker Compose، LiteLLM AI Gateway، راه‌اندازی LiteLLM

🔗 لینک‌های مرتبط

🧩 JSON-LD

{"@context":"https://schema.org","@type":"WebPage","headline":"آموزش نصب LiteLLM با Docker Compose روی VPS","url":"https://negarnovin.com/docs/install-litellm-docker/","datePublished":"2026-10-08T10:02:50+03:30","dateModified":"2026-10-08T10:02:50+03:30","author":{"@type":"Person","name":"نگارنوین"},"publisher":{"@type":"Organization","name":"نگارنوین"},"inLanguage":"fa-IR","description":"آموزش نصب LiteLLM روی VPS با Docker Compose؛ راه‌اندازی AI Gateway، PostgreSQL، HTTPS، Virtual Key و تست API مرحله‌به‌مرحله."}

📈 آمار و ارقام قابل استناد

CPU حداقل ۴ هسته
حداقل منابع ۴ CPU و 8GB RAM در آموزش Vultr نیز به‌عنوان پیش‌نیاز معرفی شده است.
در این معماری فقط Traefik پورت‌های عمومی ۸۰ و ۴۴۳ را منتشر می‌کند.
یکی از خطاهای رایج، DNS اشتباه یا اشغال بودن پورت ۸۰/۴۴۳ توسط سرویس دیگری است.
اگر cPanel، Apache یا LiteSpeed روی همان VPS روی پورت‌های ۸۰ و ۴۴۳ فعال باشد، این معماری را روی همان سرور اجرا نکنید.
در Compose این پورت‌ها فقط با expose در شبکه داخلی Docker در دسترس هستند و تنها Traefik پورت‌های عمومی ۸۰ و ۴۴۳ را منتشر می‌کند.

📄 نحوهٔ استناد به این صفحه

متن ساده:

آموزش نصب LiteLLM با Docker Compose — نگارنوین (https://negarnovin.com/docs/install-litellm-docker/)، آخرین به‌روزرسانی 2026-10-08

Markdown:

[آموزش نصب LiteLLM با Docker Compose](https://negarnovin.com/docs/install-litellm-docker/) — نگارنوین (به‌روزرسانی 2026-10-08)

📌 خلاصه (TL;DR)

📊 حقایق کلیدی

📄 محتوای کامل

معماری نهایی

LiteLLM چه کاربردی دارد؟

پیش‌نیازهای نصب LiteLLM

مرحله اول: نصب Docker و Docker Compose

مرحله دوم: ساخت پوشه LiteLLM

مرحله سوم: ساخت کلیدهای امنیتی LiteLLM

هشدار مهم درباره LITELLM_SALT_KEY

مرحله چهارم: ساخت فایل .env

مرحله پنجم: ساخت config.yaml

مرحله ششم: تنظیم Prometheus

مرحله هفتم: ساخت Docker Compose

مرحله هشتم: بررسی فایل Compose

مرحله نهم: بررسی امنیت image LiteLLM با Cosign

مرحله دهم: اجرای LiteLLM

مرحله یازدهم: ورود به پنل LiteLLM

اگر HTTPS فعال نشد

مرحله دوازدهم: بررسی سلامت LiteLLM

مرحله سیزدهم: تست API با Python

مرحله چهاردهم: ساخت Virtual Key

مرحله پانزدهم: تست Virtual Key

مرحله شانزدهم: مشاهده مصرف و هزینه

محدود کردن هزینه برای هر API Key

نکات امنیتی مهم

چرا نباید از LiteLLM v1.۸۹.۱ استفاده کنیم؟

آپدیت LiteLLM

خطاهای رایج LiteLLM

خطای ۵۰۲ Bad Gateway

خطای اتصال PostgreSQL

مدل پیدا نمی‌شود

Provider API Key اشتباه است

HTTPS صادر نمی‌شود

پنل /ui باز نمی‌شود

آیا LiteLLM بدون PostgreSQL هم اجرا می‌شود؟

آیا Redis برای LiteLLM لازم است؟

آیا می‌توان LiteLLM را روی VPS اجرا کرد؟

LiteLLM برای چه پروژه‌هایی مناسب است؟

پرسش‌های متداول

LiteLLM چیست؟

آیا LiteLLM رایگان است؟

حداقل RAM برای نصب LiteLLM چقدر است؟

آیا برای LiteLLM به GPU نیاز داریم؟

Virtual Key در LiteLLM چیست؟

آیا LiteLLM با OpenAI SDK کار می‌کند؟

پورت پیش‌فرض LiteLLM چیست؟

جمع‌بندی

🖼️ تصاویر

🏷️ کلمات کلیدی

🔗 لینک‌های مرتبط

🧩 JSON-LD

📈 آمار و ارقام قابل استناد

📄 نحوهٔ استناد به این صفحه

پنل `/ui` باز نمی‌شود