# Руководство по развёртыванию Krona Control Center на VPS

## 1. Целевая инфраструктура и топология

| Параметр | Значение | Описание |
| :--- | :--- | :--- |
| **Домен** | `https://kccdemo.ochenstarik.ru` | Публичный защищённый домен демонстрационного стенда |
| **IP-адрес VPS** | `178.212.13.102` | Целевой сервер развёртывания |
| **Системный пользователь** | `kcc` | Изолированный непривилегированный Linux-пользователь |
| **Директория релизов** | `/srv/kccdemo/releases/<TIMESTAMP>` | Версионированные каталоги сборок |
| **Символическая ссылка** | `/srv/kccdemo/current` | Указывает на активный релиз (atomic switch) |
| **Логи Nginx** | `/var/log/nginx/kccdemo_access.log` | Доступ и аудит веб-сервера |

---

## 2. Статус внешнего подключения и диагностика доступа (Pre-flight Blocker)

В ходе подготовки развёртывания была выполнена сетевая диагностика хоста `178.212.13.102`:

1. **Сетевая доступность (Ping & Port 22)**:
   - Хост `178.212.13.102` доступен, порт 22 (OpenSSH) открыт и принимает TCP-соединения.
2. **Аутентификация по SSH**:
   - Попытка подключения: `ssh -i ~/.ssh/id_rsa kcc@178.212.13.102`
   - Ответ сервера: `Permission denied (publickey)`.
3. **Причина блокировки**:
   - Сервер VPS настроен на строгую аутентификацию исключительно по SSH-ключам (`PasswordAuthentication no`).
   - Публичный ключ агента/рабочей станции не добавлен в файл `/home/kcc/.ssh/authorized_keys` на удаленном сервере.
4. **Решение для администратора / владельца платформы**:
   - Вариант А: Добавить публичный ключ локальной машины в `/home/kcc/.ssh/authorized_keys` на VPS `178.212.13.102`.
   - Вариант Б: Скопировать подготовленный каталог `deploy/kcc/` и директорию `dist/` на сервер через локальный доступ администратора и запустить `/srv/kccdemo/deploy-kcc.sh`.

---

## 3. Автоматизированный скрипт развёртывания (`deploy/kcc/deploy-kcc.sh`)

Скрипт обеспечивает атомарный деплой с нулевым временем простоя:

```bash
#!/usr/bin/env bash
set -euo pipefail

APP_DIR="/srv/kccdemo"
RELEASES_DIR="$APP_DIR/releases"
CURRENT_LINK="$APP_DIR/current"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
NEW_RELEASE_DIR="$RELEASES_DIR/$TIMESTAMP"

echo "=== [KCC Deploy] Starting atomic release $TIMESTAMP ==="

mkdir -p "$NEW_RELEASE_DIR"
cp -r ./dist/* "$NEW_RELEASE_DIR/"

# Atomic switch
ln -sfn "$NEW_RELEASE_DIR" "$CURRENT_LINK"

# Keep last 3 releases
echo "=== [KCC Deploy] Pruning older releases (retaining last 3) ==="
cd "$RELEASES_DIR"
ls -1dt 20* | tail -n +4 | xargs -r rm -rf

echo "=== [KCC Deploy] Verifying local health ==="
curl -sk https://127.0.0.1/control/gate -H "Host: kccdemo.ochenstarik.ru" | grep -q "Krona Control Center" && echo "Health check: PASSED"

echo "=== [KCC Deploy] Release $TIMESTAMP successfully active! ==="
```

---

## 4. Конфигурация Nginx (`deploy/kcc/nginx-kccdemo.conf`)

Конфигурация включает заголовки безопасности, поддержку SPA маршрутизации и SSL:

```nginx
server {
    listen 80;
    server_name kccdemo.ochenstarik.ru;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name kccdemo.ochenstarik.ru;

    ssl_certificate /etc/letsencrypt/live/kccdemo.ochenstarik.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kccdemo.ochenstarik.ru/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    root /srv/kccdemo/current;
    index index.html;

    # Security Headers
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Gzip Compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;

    # Static Assets Caching
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # SPA Routing Fallback
    location / {
        try_files $uri $uri/ /index.html;
    }

    access_log /var/log/nginx/kccdemo_access.log;
    error_log /var/log/nginx/kccdemo_error.log;
}
```

---

## 5. Процедура мгновенного отката (Instant Rollback)

В случае необходимости немедленного отката к предыдущей стабильной версии:

```bash
cd /srv/kccdemo
PREVIOUS_RELEASE=$(ls -1dt releases/20* | sed -n '2p')
if [ -n "$PREVIOUS_RELEASE" ]; then
    echo "Rolling back to: $PREVIOUS_RELEASE"
    ln -sfn "/srv/kccdemo/$PREVIOUS_RELEASE" /srv/kccdemo/current
    systemctl reload nginx
    echo "Rollback completed."
else
    echo "No previous release found to rollback."
fi
```