Standard Operating Procedures (SOPs)¶
Версия: 1.0 Дата: 13.01.2026 Контракт: order-001-phase1-ru Задача: 2.2.4 SOPs документация (A4A-22)
1. Обзор¶
Этот документ описывает стандартные операционные процедуры для системы CalmTrader. SOPs обеспечивают консистентность операций и минимизируют риски при управлении production средой.
1.1 Область применения¶
- Deployment и rollback
- Incident response
- Backup и restore
- Мониторинг и alerting
- Change management
1.2 Ответственные¶
| Роль | Ответственность |
|---|---|
| DevOps | Deployment, мониторинг, инфраструктура |
| Developer | Code changes, bug fixes |
| Product Owner | Approval изменений |
2. Deployment¶
2.1 Автоматический деплой (CI/CD)¶
Триггер: Push в main branch
Pipeline (.github/workflows/deploy.yml):
Шаги:
- Lint —
ruff check+ruff format --check - Test —
pytestдля API и Bot - Deploy — SSH на сервер,
git pull,docker compose up -d --build - Migrations —
alembic upgrade head - Health Check —
curl https://api.calmtrader.ai/health - Notify — Broadcast release notes пользователям
Время: ~3-5 минут
2.2 Manual Deployment¶
При необходимости ручного деплоя:
# 1. Подключение к серверу
ssh trader-psy
# 2. Переход в директорию проекта
cd /opt/trader-psy
# 3. Pull последних изменений
git pull origin main
# 4. Rebuild и restart сервисов
docker compose -f infrastructure/docker-compose.yml up -d --build
# 5. Применение миграций
docker compose -f infrastructure/docker-compose.yml exec api alembic upgrade head
# 6. Проверка health
curl https://api.calmtrader.ai/health
# 7. Проверка логов
docker compose -f infrastructure/docker-compose.yml logs -f --tail=100
2.3 Pre-deployment Checklist¶
- Все тесты проходят локально
- VERSION файл обновлён
- CHANGELOG.md обновлён
- Commit message соответствует формату
- PR approved (если применимо)
- Миграции протестированы локально
3. Rollback¶
3.1 Автоматический Rollback¶
CI/CD pipeline автоматически откатывается при: - Падении health check - Ошибках миграции
3.2 Manual Rollback¶
# 1. Подключение к серверу
ssh trader-psy
cd /opt/trader-psy
# 2. Просмотр истории коммитов
git log --oneline -10
# 3. Откат на предыдущий коммит
git checkout HEAD~1
# 4. Rebuild сервисов
docker compose -f infrastructure/docker-compose.yml up -d --build
# 5. Откат миграции (если нужно)
docker compose -f infrastructure/docker-compose.yml exec api alembic downgrade -1
# 6. Проверка
curl https://api.calmtrader.ai/health
3.3 Rollback на конкретную версию¶
# По тегу версии
git checkout v1.26.0
# По коммиту
git checkout abc1234
# Rebuild
docker compose -f infrastructure/docker-compose.yml up -d --build
4. Incident Response¶
4.1 Severity Levels¶
| Level | Описание | Response Time | Примеры |
|---|---|---|---|
| P1 (Critical) | Полный outage | < 15 мин | Бот не отвечает, API down |
| P2 (High) | Частичная недоступность | < 1 час | Голосовые сообщения не работают |
| P3 (Medium) | Degraded performance | < 4 часа | Медленные ответы |
| P4 (Low) | Minor issues | < 24 часа | Косметические баги |
4.2 Incident Response Process¶
1. Detection - Мониторинг (health checks) - User reports - Alerts от Sentry (когда настроено)
2. Triage
- Определить severity
- Назначить ответственного
- Создать incident в Linear (label: incident)
3. Containment - Если критично — rollback - Если изолировано — disable feature flag
4. Investigation
# Проверить логи
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs -f api --tail=500"
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs -f bot --tail=500"
# Проверить ресурсы
ssh trader-psy "docker stats --no-stream"
# Проверить диск
ssh trader-psy "df -h"
5. Resolution - Implement fix - Test - Deploy
6. Post-mortem - Документировать в Linear - Update runbooks если нужно - Implement preventive measures
4.3 Контакты¶
| Роль | Контакт |
|---|---|
| Primary On-call | @achernykh |
| Escalation | — |
5. Backup & Restore¶
5.1 Что бэкапится¶
| Компонент | Тип | Частота | Retention |
|---|---|---|---|
| PostgreSQL | Full dump | Daily | 7 days |
| MinIO | Object sync | Daily | 30 days |
| .env | Manual | On change | Indefinite |
5.2 PostgreSQL Backup¶
# Создание бэкапа
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml exec postgres pg_dump -U trader trader_psy > /opt/backups/db_$(date +%Y%m%d).sql"
# Список бэкапов
ssh trader-psy "ls -la /opt/backups/"
5.3 PostgreSQL Restore¶
# Восстановление из бэкапа
ssh trader-psy "cat /opt/backups/db_20260113.sql | docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml exec -T postgres psql -U trader trader_psy"
5.4 MinIO Backup¶
# Sync to local (mc клиент)
mc mirror storage/voice-messages ./backups/voice-messages
mc mirror storage/breathing-audio ./backups/breathing-audio
6. Monitoring¶
6.1 Health Checks¶
| Сервис | Endpoint | Интервал |
|---|---|---|
| API | GET /health | 30s |
| PostgreSQL | pg_isready | 10s |
| Redis | redis-cli ping | 10s |
| MinIO | /minio/health/live | 30s |
6.2 Manual Health Check¶
# API
curl https://api.calmtrader.ai/health
# All services
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml ps"
6.3 Logs¶
# Все сервисы
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs -f"
# Конкретный сервис
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs -f api --tail=100"
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs -f bot --tail=100"
6.4 Метрики¶
# Docker stats
ssh trader-psy "docker stats --no-stream"
# Disk usage
ssh trader-psy "df -h"
# Memory
ssh trader-psy "free -h"
7. Change Management¶
7.1 Change Types¶
| Тип | Approval | Процесс |
|---|---|---|
| Standard | Auto (CI/CD) | Push to main |
| Normal | PR review | PR → Review → Merge |
| Emergency | Post-facto | Direct push, document after |
7.2 Standard Change Procedure¶
- Create branch from
main - Implement changes
- Write tests
- Update VERSION и CHANGELOG
- Create PR
- Get review
- Merge to main
- CI/CD deploys automatically
7.3 Emergency Change Procedure¶
- Push directly to main
- Monitor deployment
- If fails — rollback immediately
- Create post-mortem ticket
- Document in CHANGELOG
7.4 Configuration Changes¶
.env изменения:
# 1. Backup current .env
ssh trader-psy "cp /opt/trader-psy/infrastructure/.env /opt/trader-psy/infrastructure/.env.backup"
# 2. Edit .env
ssh trader-psy "nano /opt/trader-psy/infrastructure/.env"
# 3. Restart affected services
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml restart api bot"
8. Security Operations¶
8.1 Secrets Rotation¶
| Secret | Частота | Процедура |
|---|---|---|
| TELEGRAM_BOT_TOKEN | On compromise | BotFather → regenerate → update .env |
| POSTGRES_PASSWORD | Annually | Update .env → restart postgres |
| API keys | On compromise | Regenerate in provider → update .env |
8.2 Access Management¶
# Добавить SSH ключ
ssh trader-psy "echo 'ssh-rsa AAAA...' >> ~/.ssh/authorized_keys"
# Удалить SSH ключ
ssh trader-psy "nano ~/.ssh/authorized_keys" # Remove line
8.3 Security Updates¶
# System updates
ssh trader-psy "apt update && apt upgrade -y"
# Docker images
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml pull && docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml up -d"
9. Troubleshooting¶
9.1 Common Issues¶
Бот не отвечает:
# Проверить статус
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml ps bot"
# Проверить логи
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs bot --tail=100"
# Restart
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml restart bot"
API возвращает 500:
# Проверить логи API
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml logs api --tail=100"
# Проверить подключение к БД
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml exec postgres pg_isready"
Диск заполнен:
# Очистить Docker
ssh trader-psy "docker system prune -af"
# Проверить логи
ssh trader-psy "du -sh /var/lib/docker/containers/*"
9.2 Restart Services¶
# Один сервис
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml restart api"
# Все сервисы
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml restart"
# Full rebuild
ssh trader-psy "docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml down && docker compose -f /opt/trader-psy/infrastructure/docker-compose.yml up -d --build"
Приложения¶
A. Useful Commands Cheatsheet¶
# SSH
ssh trader-psy
# CD to project
cd /opt/trader-psy
# Docker compose shortcut
DC="docker compose -f infrastructure/docker-compose.yml"
# Common commands
$DC ps # Status
$DC logs -f # Logs
$DC restart # Restart all
$DC down # Stop all
$DC up -d # Start all
B. Contact Information¶
| Ресурс | URL |
|---|---|
| Bot | https://t.me/ai_calm_trader_bot |
| API | https://api.calmtrader.ai |
| Docs | https://docs.calmtrader.ai |
| Linear | https://linear.app/a4ai-cyprus |
| GitHub | https://github.com/a4ai-cyprus/a4ai-trader-phsycologist |
Документ создан в рамках выполнения контракта order-001-phase1-ru