API VEGA

pgEdge Natural Language Agent — Руководство по развёртыванию в контейнерах

В этом документе описано, как развернуть pgEdge Natural Language Agent с помощью Docker-контейнеров и Kubernetes (Helm).

Содержание

  • Docker-образы

    • Варианты образов

  • Хранение данных

  • Развёртывание с Docker Compose

  • Развёртывание в Kubernetes (Helm)

  • Реестр контейнеров

  • Рекомендации по безопасности

  • Мониторинг и устранение неполадок

Docker-образы

pgEdge Natural Language Agent предоставляет готовые Dockerfile для всех компонентов.

Доступные Dockerfile

В корне репозитория доступны следующие Dockerfile:

Все образы собираются в несколько этапов (multi-stage build), что обеспечивает минимальный размер, и запускаются от имени непривилегированного пользователя (non-root) в целях безопасности.

Сборка образов

# Build all images
docker build -f Dockerfile.server -t ghcr.io/pgedge/mcp-server:latest .
docker build -f Dockerfile.cli -t ghcr.io/pgedge/nla-cli:latest .
docker build -f Dockerfile.web -t ghcr.io/pgedge/nla-web:latest .

# Tag for versioning
VERSION=$(git describe --tags --always)
docker tag ghcr.io/pgedge/mcp-server:latest ghcr.io/pgedge/mcp-server:${VERSION}
docker tag ghcr.io/pgedge/nla-cli:latest ghcr.io/pgedge/nla-cli:${VERSION}
docker tag ghcr.io/pgedge/nla-web:latest ghcr.io/pgedge/nla-web:${VERSION}

# Build with BuildKit for better performance
DOCKER_BUILDKIT=1 docker build -f Dockerfile.server -t ghcr.io/pgedge/mcp-server:latest .

Варианты образов

Образ MCP-сервера доступен в двух вариантах:

Базовый образ (без базы знаний)

Базовый образ содержит только MCP-сервер без предустановленной базы знаний. Используйте этот вариант, если:

  • вам нужен образ минимально возможного размера (~50 МБ);

  • вы планируете подключать собственную базу знаний через монтирование тома;

  • функция поиска по базе знаний вам не требуется.

docker pull ghcr.io/pgedge/mcp-server:latest
Образ с базой знаний

Вариант -with-kb включает готовую базу знаний с документацией по PostgreSQL, продуктам pgEdge и сопутствующим инструментам. Используйте его, если:

  • хотите, чтобы поиск по базе знаний работал сразу «из коробки»;

  • для вас простота важнее размера образа (~300–500 МБ);

  • вы разворачиваете быстрое демо или среду разработки.

docker pull ghcr.io/pgedge/mcp-server:latest-with-kb
Доступные теги
ТегОписание
latestПоследний базовый образ (без базы знаний)
latest-with-kbПоследний образ с предустановленной базой знаний
v1.0.0Базовый образ версии 1.0.0
v1.0.0-with-kbОбраз версии 1.0.0 с базой знаний
Сборка образа с базой знаний

Собственный образ с пользовательской базой знаний можно собрать с помощью аргумента сборки KB_SOURCE:

Из локального файла:

# First, build or obtain your KB database using the standalone
# pgEdge AI Knowledgebase Builder project. See
# https://github.com/pgEdge/pgedge-ai-kb for installation and a
# Quick Start.

# Place the database in the kb/ directory
cp pgedge-ai-kb.db kb/kb.db

# Build the image (automatically includes kb/kb.db if present)
docker build -f Dockerfile.server -t mcp-server:custom-kb .

По URL:

docker build -f Dockerfile.server \
    --build-arg KB_SOURCE=https://example.com/path/to/kb.db \
    -t mcp-server:custom-kb .
Использование базы знаний в контейнерах

При работе с образом -with-kb включите поиск по базе знаний следующим образом:

docker run -d \
  -e PGEDGE_KB_ENABLED=true \
  -e PGEDGE_KB_EMBEDDING_PROVIDER=voyage \
  -e PGEDGE_KB_VOYAGE_API_KEY=${VOYAGE_API_KEY} \
  ghcr.io/pgedge/mcp-server:latest-with-kb

Примечание: даже при наличии встроенной базы знаний для запросов поиска по сходству потребуется API-ключ провайдера эмбеддингов.

При использовании базового образа с пользовательской базой знаний подключите её как том:

docker run -d \
  -v ./my-kb.db:/usr/share/pgedge/nla-kb/kb.db:ro \
  -e PGEDGE_KB_ENABLED=true \
  -e PGEDGE_KB_DATABASE_PATH=/usr/share/pgedge/nla-kb/kb.db \
  -e PGEDGE_KB_EMBEDDING_PROVIDER=voyage \
  -e PGEDGE_KB_VOYAGE_API_KEY=${VOYAGE_API_KEY} \
  ghcr.io/pgedge/mcp-server:latest

Хранение данных

MCP-сервер хранит постоянные данные в настраиваемом каталоге, путь к которому задаётся переменной окружения PGEDGE_DATA_DIR. Этот каталог содержит:

  • tokens.json — токены аутентификации API

  • users.json — учётные данные пользователей (аутентификация по логину и паролю)

  • conversations.db — база данных SQLite с историей диалогов

  • Пользовательские настройки — индивидуальные параметры и конфигурации каждого пользователя

Конфигурация Docker Compose

По умолчанию файлы Docker Compose монтируют именованный том для хранения данных:

volumes:
  - mcp-data:/app/data

environment:
  - PGEDGE_DATA_DIR=/app/data

Произвольный путь на хосте

Чтобы использовать конкретный каталог на хосте вместо тома Docker:

volumes:
  # Mount host directory
  - ./data:/app/data:rw

environment:
  - PGEDGE_DATA_DIR=/app/data

!!! warning "Права доступа"

Убедитесь, что каталог на хосте имеет подходящие права доступа (владелец — UID 1000), иначе контейнер может не смочь записать данные:

bash mkdir -p ./data && chown 1000:1000 ./data

Путь к данным в production

Для production-развёртываний используется более стандартный путь:

volumes:
  - server-data:/var/lib/pgedge/mcp-server

environment:
  - PGEDGE_DATA_DIR=/var/lib/pgedge/mcp-server

Резервное копирование и восстановление

Чтобы создать резервную копию каталога с данными:

# Stop the container first to ensure data consistency
docker-compose stop mcp-server

# Backup using docker cp
docker cp pgedge-postgres-mcp:/app/data ./backup-$(date +%Y%m%d)

# Or if using a host mount
cp -r ./data ./backup-$(date +%Y%m%d)

# Restart the container
docker-compose start mcp-server

Развёртывание с Docker Compose

Развёртывание для разработки

В репозитории есть файл docker-compose.yml для локальной разработки. Эта конфигурация собирает образы из исходного кода и подходит для тестирования и разработки.

# Start the stack
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the stack
docker-compose down

Развёртывание в production

Для production-развёртываний используйте пример конфигурации examples/docker-compose.production.yml. Эта конфигурация:

  • использует готовые образы из GitHub Container Registry;

  • включает лимиты ресурсов и проверки работоспособности (health checks);

  • предусматривает корректную настройку логирования;

  • применяет политики перезапуска, пригодные для production.

Использование:

# Copy environment example
cp examples/.env.example .env
# Edit .env with your values

# Start production stack
docker-compose -f examples/docker-compose.production.yml up -d

# View logs
docker-compose -f examples/docker-compose.production.yml logs -f

# Stop stack
docker-compose -f examples/docker-compose.production.yml down

Обязательные переменные окружения:

Все параметры конфигурации перечислены в файле examples/.env.example. Минимально необходимы:

  • POSTGRES_PASSWORD — пароль PostgreSQL

  • ANTHROPIC_API_KEY или OPENAI_API_KEY — API-ключ провайдера LLM

Развёртывание в Kubernetes (Helm-чарт)

Полноценный Helm-чарт доступен в каталоге examples/helm/pgedge-nla/.

Возможности чарта

  • Высокая доступность: поддержка нескольких реплик с pod anti-affinity

  • Автомасштабирование: поддержка Horizontal Pod Autoscaler (HPA)

  • Безопасность: контексты безопасности pod, корневые файловые системы только для чтения

  • Ingress: опциональный ingress с поддержкой TLS

  • Хранение данных: поддержка StatefulSet с постоянными томами

Быстрый старт

# Install from local chart
helm install pgedge-nla examples/helm/pgedge-nla \
  --namespace pgedge \
  --create-namespace \
  --set secrets.postgresPassword="your-secure-password" \
  --set secrets.anthropicApiKey="your-api-key"

# Install with production values
helm install pgedge-nla examples/helm/pgedge-nla \
  --namespace pgedge \
  --create-namespace \
  -f examples/helm/pgedge-nla/values-production.yaml

# Upgrade
helm upgrade pgedge-nla examples/helm/pgedge-nla \
  --namespace pgedge \
  -f values.yaml

# Uninstall
helm uninstall pgedge-nla --namespace pgedge

Конфигурация

Helm-чарт включает два файла значений:

  • values.yaml — конфигурация по умолчанию для разработки и тестирования;

  • values-production.yaml — конфигурация, готовая к промышленной эксплуатации:

    • повышенное количество реплик;
    • лимиты ресурсов и автомасштабирование;
    • pod anti-affinity для высокой доступности;
    • Ingress с TLS.

Основные параметры конфигурации

server:
  replicaCount: 2 # Number of server replicas
  resources:
    limits:
      cpu: 1000m
      memory: 1Gi
  autoscaling:
    enabled: false # Set to true for HPA
  knowledgebase:
    enabled: true # Enable similarity search
    existingPvc: pgedge-nla-kb # PVC with knowledgebase
  persistence:
    enabled: true # Enable persistent data directory
    size: 1Gi
    # Data stored: tokens.json, users.json, conversations.db

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: nla.example.com
  tls:
    - secretName: pgedge-nla-tls
      hosts:
        - nla.example.com

Постоянное хранение данных в Kubernetes

При работе в Kubernetes каталог с данными (в нём хранятся данные аутентификации и история диалогов) необходимо сохранять с помощью PersistentVolumeClaim:

server:
  persistence:
    enabled: true
    size: 1Gi
    storageClass: "" # Use default storage class
    accessModes:
      - ReadWriteOnce
  env:
    - name: PGEDGE_DATA_DIR
      value: /var/lib/pgedge/mcp-server

Полную документацию можно найти в README Helm-чарта.

Реестр контейнеров

Образы публикуются в GitHub Container Registry (GHCR).

Скачивание образов

# Pull latest images
docker pull ghcr.io/pgedge/mcp-server:latest
docker pull ghcr.io/pgedge/nla-web:latest
docker pull ghcr.io/pgedge/nla-cli:latest

# Pull specific version
docker pull ghcr.io/pgedge/mcp-server:1.0.0

Публикация образов

# Login to GHCR
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Tag images
docker tag pgedge/mcp-server:latest ghcr.io/pgedge/mcp-server:latest
docker tag pgedge/mcp-server:latest ghcr.io/pgedge/mcp-server:${VERSION}

# Push images
docker push ghcr.io/pgedge/mcp-server:latest
docker push ghcr.io/pgedge/mcp-server:${VERSION}

# Push all tags
docker push ghcr.io/pgedge/mcp-server --all-tags

Использование GitHub Actions

Для автоматизированной сборки и публикации используйте GitHub Actions:

name: Build and Publish Images

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          file: Dockerfile.server
          push: true
          tags: |
            ghcr.io/pgedge/mcp-server:latest
            ghcr.io/pgedge/mcp-server:${{ github.ref_name }}

Рекомендации по безопасности

Безопасность образов

  • Запуск без прав root: все образы работают от непривилегированных пользователей (UID 1000)
  • Корневая файловая система только для чтения: контейнеры по возможности используют корневые файловые системы, доступные только для чтения
  • Запрет повышения привилегий: allowPrivilegeEscalation: false в Kubernetes
  • Сброс всех capabilities: требуется минимальный набор Linux capabilities

Сканирование образов

# Scan with Trivy
trivy image ghcr.io/pgedge/mcp-server:latest

# Scan with Docker Scout (if available)
docker scout cves ghcr.io/pgedge/mcp-server:latest

# Scan for high/critical vulnerabilities only
trivy image --severity HIGH,CRITICAL ghcr.io/pgedge/mcp-server:latest

Управление секретами

Никогда не сохраняйте секреты в системе контроля версий. Используйте один из следующих подходов:

Docker Compose:

# Use environment files (not committed to git)
docker-compose --env-file .env up -d

Kubernetes:

# Use kubectl to create secrets
kubectl create secret generic pgedge-secrets \
  --from-literal=postgres-password='your-password' \
  --from-literal=anthropic-api-key='your-key' \
  --namespace pgedge

# Or use external secret managers
# - AWS Secrets Manager
# - HashiCorp Vault
# - Google Secret Manager

Сетевые политики

В Kubernetes ограничивайте сетевой трафик с помощью NetworkPolicies:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: pgedge-postgres-mcp
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/component: server
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app.kubernetes.io/component: web
      ports:
        - protocol: TCP
          port: 8080
  egress:
    - to:
        - podSelector:
            matchLabels:
              app: postgres
      ports:
        - protocol: TCP
          port: 5432

Мониторинг и устранение неполадок

Просмотр логов

Docker Compose:

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f pgedge-postgres-mcp

# Last 100 lines
docker-compose logs --tail=100 pgedge-postgres-mcp

Kubernetes:

# Server logs
kubectl logs -f deployment/pgedge-postgres-mcp -n pgedge

# Web UI logs
kubectl logs -f deployment/pgedge-nla-web -n pgedge

# Previous container logs (after crash)
kubectl logs deployment/pgedge-postgres-mcp -n pgedge --previous

# All pods with label
kubectl logs -l app.kubernetes.io/component=server -n pgedge --tail=100

Проверки работоспособности

Docker:

# Check container health status
docker ps

# Inspect health check
docker inspect pgedge-postgres-mcp | jq '.[0].State.Health'

# Manual health check
curl http://localhost:8080/health

Kubernetes:

# Check pod status
kubectl get pods -n pgedge

# Describe pod (includes events)
kubectl describe pod pgedge-postgres-mcp-xxx -n pgedge

# Port forward and test
kubectl port-forward svc/pgedge-postgres-mcp 8080:8080 -n pgedge
curl http://localhost:8080/health

Отладка контейнера

Docker:

# Execute shell in running container
docker exec -it pgedge-postgres-mcp sh

# Check processes
docker exec pgedge-postgres-mcp ps aux

# Check network connectivity
docker exec pgedge-postgres-mcp wget -O- http://postgres:5432

Kubernetes:

# Execute shell in pod
kubectl exec -it deployment/pgedge-postgres-mcp -n pgedge -- sh

# Debug with ephemeral container (Kubernetes 1.23+)
kubectl debug -it pgedge-postgres-mcp-xxx -n pgedge --image=alpine --target=server

# Check connectivity to postgres
kubectl exec deployment/pgedge-postgres-mcp -n pgedge -- \
  wget -qO- http://postgres-postgresql:5432 || echo "Cannot connect"

Типичные проблемы

Сервер не запускается:

# Check logs for errors
kubectl logs deployment/pgedge-postgres-mcp -n pgedge | grep -i error

# Verify database connection
kubectl exec deployment/pgedge-postgres-mcp -n pgedge -- \
  env | grep POSTGRES

# Check if config is mounted
kubectl exec deployment/pgedge-postgres-mcp -n pgedge -- \
  cat /etc/pgedge/mcp-server.yaml

Проблемы с подключением к базе данных:

# Test PostgreSQL connectivity
kubectl run -it --rm debug --image=postgres:17-alpine -- \
  psql postgresql://postgres:password@postgres-postgresql:5432/postgres

# Check DNS resolution
kubectl exec deployment/pgedge-postgres-mcp -n pgedge -- \
  nslookup postgres-postgresql

Нехватка ресурсов:

# Check resource usage
kubectl top pods -n pgedge

# Describe pod to see events
kubectl describe pod pgedge-postgres-mcp-xxx -n pgedge | grep -A 5 Events

# Increase resources in values.yaml and upgrade
helm upgrade pgedge-nla examples/helm/pgedge-nla -f values.yaml