Перейти к основному содержимому

Деплой Kalheon API

Production-деплои оркестрируются GitHub Actions в .github/workflows/deploy.yml.

Поток​

  1. Коммит уходит в main.
  2. GitHub Actions открывает SSH-сессию к claude@157.180.103.168.
  3. Удалённый репозиторий /home/claude/projects/kalheon_agents fast-forward-ится до origin/main.
  4. На сервере запускается scripts/deploy-production.sh:
    • тянет main;
    • запускает npm ci;
    • запускает npx prisma generate;
    • запускает npm run db:migrate:deploy;
    • запускает npm run build;
    • перезапускает PM2-приложение kalheon-api;
    • smoke-тестирует https://api.kalheon.cloud/health;
    • smoke-тестирует https://api.kalheon.cloud/docs/json.
  5. GitHub Actions шлёт Telegram-уведомление об успехе или ошибке, если прописаны Telegram-секреты.

Скрипт деплоя использует /tmp/kalheon-api-deploy.lock — два деплоя одновременно не запустятся.

GitHub secrets​

Обязательные:

  • DEPLOY_SSH_KEY — приватный ключ, разрешённый для деплоя на AX43.

Рекомендованные:

  • DEPLOY_KNOWN_HOSTS — закреплённая запись SSH host key для 157.180.103.168.

Опциональные override-ы:

  • DEPLOY_HOST — дефолт 157.180.103.168;
  • DEPLOY_PORT — дефолт 22;
  • DEPLOY_USER — дефолт claude;
  • DEPLOY_REPO_DIR — дефолт /home/claude/projects/kalheon_agents;
  • PM2_APP — дефолт kalheon-api;
  • SMOKE_HEALTH_URL — дефолт https://api.kalheon.cloud/health;
  • SMOKE_DOCS_URL — дефолт https://api.kalheon.cloud/docs/json.

Telegram-уведомления:

  • TG_BOT_TOKEN — токен Telegram-бота;
  • TG_CHAT_ID — ID чата или канала для уведомлений о деплое.

Если Telegram-секретов нет, деплой всё равно проходит, а про пропущенное уведомление остаётся запись в логах.

Первичный запуск на сервере​

Прогоните один раз на AX43, прежде чем включать ограниченный deploy-ключ:

ssh claude@157.180.103.168
cd /home/claude/projects/kalheon_agents
git fetch origin main
git checkout main
git pull --ff-only origin main
chmod +x scripts/deploy-production.sh
scripts/deploy-production.sh

После первого успешного прогона добавьте публичный deploy-ключ в ~/.ssh/authorized_keys.

Более безопасная ограниченная форма:

command="/home/claude/projects/kalheon_agents/scripts/deploy-production.sh",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... kalheon-deploy

С forced command GitHub Actions этим ключом может запустить только deploy-скрипт — ничего больше.

Ручной деплой​

ssh claude@157.180.103.168
cd /home/claude/projects/kalheon_agents
DEPLOY_BRANCH=main PM2_APP=kalheon-api scripts/deploy-production.sh

Ручной откат​

Предпочтительный откат — revert-коммит, запушенный в main: история production и git остаётся консистентной, и катится тот же пайплайн:

git revert <bad_commit_sha>
git push origin main

Аварийный откат на стороне сервера, когда revert не успеть:

ssh claude@157.180.103.168
cd /home/claude/projects/kalheon_agents
git fetch origin main
git checkout <last_good_sha>
npm ci
npx prisma generate
npm run db:migrate:deploy
npm run build
pm2 restart kalheon-api --update-env
curl -fsS https://api.kalheon.cloud/health > /dev/null
curl -fsS https://api.kalheon.cloud/docs/json > /dev/null

Миграции БД по умолчанию forward-only. Если плохой деплой включал миграцию схемы, для отката может потребоваться отдельная compensating-миграция.

Smoke-эндпоинты​

Публичные smoke-эндпоинты:

  • https://api.kalheon.cloud/health
  • https://api.kalheon.cloud/docs/json

Версионированный health-маршрут остаётся доступным на https://api.kalheon.cloud/api/v1/health.