docs: prod status, sac-deploy.sh; update install and deployment guides

2026-05-26 22:03:10 +10:00
parent bdfc7016e6
commit a4bbc14448
9 changed files with 217 additions and 28 deletions
@@ -12,9 +12,9 @@

 ## Статус проекта

-**Фаза 1B:** ingest на prod (`sac.kalinamall.ru`) — готово.  
-**Фаза 1C (в работе):** Vue UI (события, хосты), JWT-вход.  
-**Фаза 1A (в работе):** `UseSAC` / `--check-sac` в [ssh-monitor](https://git.kalinamall.ru/PapaTramp/ssh-monitor).
+**Prod:** `https://sac.kalinamall.ru` — ingest, UI (события/хосты), JWT.  
+**Деплой:** `sudo /opt/sac-deploy.sh` (см. `deploy/sac-deploy.sh`).  
+**Дальше:** Problems/Telegram (1C), `UseSAC=dual` на ssh-monitor (1A).

 **Подготовка сервера Ubuntu:** [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md)

@@ -7,6 +7,13 @@
 3. `deploy/systemd/sac-api.service` → `/etc/systemd/system/`
 4. `deploy/nginx/sac.conf.tls.example` → `/etc/nginx/sites-available/sac` (wildcard TLS)  
   или `sac.conf.example` — только HTTP / отладка
+5. `deploy/sac-deploy.sh` → `/opt/sac-deploy.sh` — полное обновление после `git pull`
+
+```bash
+sudo cp deploy/sac-deploy.sh /opt/sac-deploy.sh
+sudo chmod 755 /opt/sac-deploy.sh
+sudo /opt/sac-deploy.sh
+```

 ## Альтернатива: Docker

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Полное обновление SAC на сервере (native).
+# Установка: sudo cp /opt/security-alert-center/deploy/sac-deploy.sh /opt/sac-deploy.sh
+#            sudo chmod 755 /opt/sac-deploy.sh
+# Запуск:    sudo /opt/sac-deploy.sh
+#
+# Выполняет от пользователя sac: git pull, pip, alembic, npm build.
+# От root: systemctl restart sac-api.
+
+set -euo pipefail
+
+APP_ROOT="${SAC_APP_ROOT:-/opt/security-alert-center}"
+APP_USER="${SAC_APP_USER:-sac}"
+SERVICE_NAME="${SAC_SERVICE:-sac-api}"
+CONFIG_FILE="${SAC_CONFIG_FILE:-${APP_ROOT}/config/sac-api.env}"
+
+log() { printf '[sac-deploy] %s\n' "$*"; }
+die() { printf '[sac-deploy] ERROR: %s\n' "$*" >&2; exit 1; }
+
+if [ "$(id -u)" -ne 0 ]; then
+ die "Запускайте от root: sudo /opt/sac-deploy.sh"
+fi
+
+id "$APP_USER" &>/dev/null || die "Пользователь ${APP_USER} не существует"
+
+if [ ! -d "${APP_ROOT}/.git" ]; then
+ die "Не найден git-репозиторий: ${APP_ROOT}"
+fi
+
+log "Выравнивание владельца ${APP_ROOT} → ${APP_USER}:${APP_USER}"
+chown -R "${APP_USER}:${APP_USER}" "${APP_ROOT}"
+
+log "git pull"
+sudo -u "${APP_USER}" git -C "${APP_ROOT}" pull --ff-only
+
+if [ ! -f "${CONFIG_FILE}" ]; then
+ die "Нет конфига: ${CONFIG_FILE}"
+fi
+
+VENV="${APP_ROOT}/backend/.venv"
+if [ ! -x "${VENV}/bin/pip" ]; then
+ die "Нет venv: ${VENV} — сначала установите по install-ubuntu-24.04-native.md"
+fi
+
+log "pip install -r requirements.txt"
+sudo -u "${APP_USER}" "${VENV}/bin/pip" install -q -r "${APP_ROOT}/backend/requirements.txt"
+
+log "alembic upgrade head"
+sudo -u "${APP_USER}" bash -c "
+  set -a
+  # shellcheck source=/dev/null
+  source '${CONFIG_FILE}'
+  set +a
+  cd '${APP_ROOT}/backend' && '${VENV}/bin/alembic' upgrade head
+"
+
+if [ -f "${APP_ROOT}/frontend/package.json" ]; then
+ if ! command -v npm >/dev/null 2>&1; then
+  log "npm не найден — пропуск сборки UI (apt install nodejs npm)"
+ else
+  log "frontend: npm ci / build"
+  sudo -u "${APP_USER}" bash -c "
+    cd '${APP_ROOT}/frontend'
+    if [ -f package-lock.json ]; then npm ci; else npm install; fi
+    npm run build
+  "
+  if [ ! -f "${APP_ROOT}/frontend/dist/index.html" ]; then
+   die "Сборка UI не создала frontend/dist/index.html"
+  fi
+ fi
+fi
+
+if [ -f "${APP_ROOT}/deploy/systemd/${SERVICE_NAME}.service" ]; then
+ log "systemd unit (при необходимости скопируйте вручную в /etc/systemd/system/)"
+fi
+
+log "systemctl restart ${SERVICE_NAME}"
+systemctl daemon-reload 2>/dev/null || true
+systemctl restart "${SERVICE_NAME}"
+systemctl is-active --quiet "${SERVICE_NAME}" || die "${SERVICE_NAME} не active"
+
+sleep 1
+if curl -sf "http://127.0.0.1:8000/health" >/dev/null 2>&1; then
+ log "health: OK (http://127.0.0.1:8000/health)"
+else
+ log "WARN: локальный /health не ответил — проверьте journalctl -u ${SERVICE_NAME}"
+fi
+
+log "Готово."
@@ -13,7 +13,8 @@
 | [install-ubuntu-24.04-docker.md](install-ubuntu-24.04-docker.md) | Подготовка сервера (Docker, альтернатива) |
 | [install-ubuntu-24.04.md](install-ubuntu-24.04.md) | Указатель |
 | [ssl-certificate.md](ssl-certificate.md) | Wildcard TLS: формат, scp, пути `/etc/ssl/sac/` |
-| [deployment.md](deployment.md) | Эксплуатация, backup, TLS |
+| [deployment.md](deployment.md) | Эксплуатация, backup, TLS, `sac-deploy.sh` |
+| [operations-prod-status.md](operations-prod-status.md) | **Статус prod** и следующие шаги |
 | [workspace-three-repos.md](workspace-three-repos.md) | Cursor multi-root |

 ## Порядок чтения
@@ -16,9 +16,15 @@
 deploy/
  env.native.example      → /opt/security-alert-center/config/sac-api.env
  systemd/sac-api.service → /etc/systemd/system/
-  nginx/sac.conf.example  → /etc/nginx/sites-available/sac
+  nginx/sac.conf.example  → /etc/nginx/sites-available/sac (HTTP)
+  nginx/sac.conf.tls.example → HTTPS + wildcard
+  sac-deploy.sh           → /opt/sac-deploy.sh (полное обновление)
 ```

+**Production URL:** `https://sac.kalinamall.ru`  
+**Конфиг:** `/opt/security-alert-center/config/sac-api.env` (владелец `sac:sac`, chmod 600).  
+**UI:** статика `frontend/dist`, раздаётся через FastAPI (после `npm run build`).
+
 ---

 ## 1. Требования к серверу
@@ -51,7 +57,7 @@ deploy/
 | PostgreSQL 16 | `apt`, БД `sac` |
 | SAC API | Python 3.12 venv, **systemd** `sac-api` |
 | TLS / proxy | **nginx** |
-| UI (позже) | static в `/var/www/sac/` |
+| UI | `frontend/dist`, сборка `npm run build`, раздача из API |

 Полная инструкция: **[install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md)**.

@@ -104,12 +110,13 @@ curl -sS https://sac.kalinamall.ru/health
 ## 8. Обновление (native)

 ```bash
-cd /opt/security-alert-center && sudo -u sac git pull
-sudo -u sac backend/.venv/bin/pip install -r backend/requirements.txt
-sudo -u sac bash -c 'set -a; source /opt/security-alert-center/config/sac-api.env; set +a; cd backend && .venv/bin/alembic upgrade head'
-sudo systemctl restart sac-api
+sudo /opt/sac-deploy.sh
 ```

+Установка скрипта (один раз): `sudo cp /opt/security-alert-center/deploy/sac-deploy.sh /opt/sac-deploy.sh && sudo chmod 755 /opt/sac-deploy.sh`
+
+Подробности: [install-ubuntu-24.04-native.md §13](install-ubuntu-24.04-native.md#13-обновление-sac-деплой).
+
 ---

 ## См. также
@@ -360,16 +360,44 @@ EOF

 ---

-## 13. Обновление SAC
+## 13. Обновление SAC (деплой)
+
+### Рекомендуется: скрипт `/opt/sac-deploy.sh`
+
+После первой установки один раз:

 ```bash
-cd /opt/security-alert-center
-sudo -u sac git pull
-sudo -u sac backend/.venv/bin/pip install -r backend/requirements.txt
-sudo -u sac bash -c 'set -a; source /opt/security-alert-center/config/sac-api.env; set +a; cd backend && .venv/bin/alembic upgrade head'
+sudo cp /opt/security-alert-center/deploy/sac-deploy.sh /opt/sac-deploy.sh
+sudo chmod 755 /opt/sac-deploy.sh
+```
+
+Каждое обновление с git:
+
+```bash
+sudo /opt/sac-deploy.sh
+```
+
+Скрипт: `chown sac:sac` → `git pull` (от **sac**) → `pip` → `alembic` → `npm run build` → `systemctl restart sac-api` → проверка `/health`.
+
+### Вручную (если без скрипта)
+
+```bash
+sudo chown -R sac:sac /opt/security-alert-center
+sudo -u sac git -C /opt/security-alert-center pull
+cd /opt/security-alert-center/frontend && sudo -u sac npm ci && sudo -u sac npm run build
+sudo -u sac /opt/security-alert-center/backend/.venv/bin/pip install -r /opt/security-alert-center/backend/requirements.txt
+sudo -u sac bash -c 'set -a; source /opt/security-alert-center/config/sac-api.env; set +a; cd /opt/security-alert-center/backend && .venv/bin/alembic upgrade head'
 sudo systemctl restart sac-api
 ```

+### Git: только от пользователя `sac`
+
+Не выполняйте `sudo git pull` в `/opt/security-alert-center` — `.git` станет root и появится:
+
+`error: cannot open '.git/FETCH_HEAD': Permission denied`
+
+Исправление: `sudo chown -R sac:sac /opt/security-alert-center`.
+
 ---

 ## 14. Чеклист
@@ -399,6 +427,11 @@ sudo systemctl restart sac-api
 | 401 ingest | ключ в `Authorization: Bearer`; проверить `SAC_BOOTSTRAP_API_KEY` |
 | 502 от nginx | API не слушает: `ss -lntp \| grep 8000`, `systemctl restart sac-api` |
 | Schema errors 422 | путь `EVENT_SCHEMA_PATH`, наличие файла schema |
+| `FETCH_HEAD: Permission denied` | `sudo chown -R sac:sac /opt/security-alert-center`; далее `sudo -u sac git pull` |
+| UI 404 / пустая главная | `cd frontend && sudo -u sac npm run build`; `restart sac-api` |
+| 503 на `/auth/login` | задать `SAC_ADMIN_PASSWORD` в `config/sac-api.env` |
+| `test -r privkey.pem` без вывода | каталог `/etc/ssl/sac` → `root:ssl-cert`, `www-data` в группе `ssl-cert` — [ssl-certificate.md](ssl-certificate.md) §3 |
+| PFX `RC2-40-CBC unsupported` | `openssl pkcs12 -legacy` — [ssl-certificate.md](ssl-certificate.md) §4.4 |

 ---

@@ -0,0 +1,50 @@
+# SAC production — текущий статус (KalinaMall)
+
+Ориентир для продолжения работ. Обновляйте при смене этапа.
+
+**Сервер:** Ubuntu 24.04, FQDN `sac.kalinamall.ru`  
+**Каталог:** `/opt/security-alert-center`  
+**Пользователь сервиса:** `sac` (git, venv, npm — только от него)  
+**Конфиг:** `/opt/security-alert-center/config/sac-api.env`
+
+---
+
+## Что уже работает (2026-05-26)
+
+| Компонент | Статус |
+|-----------|--------|
+| PostgreSQL + Alembic | ✅ |
+| `POST /api/v1/events` (ingest 202) | ✅ |
+| `GET /health` | ✅ |
+| nginx + wildcard TLS (`/etc/ssl/sac/`) | ✅ |
+| JWT UI: Events, Hosts | ✅ |
+| `SAC_ADMIN_PASSWORD` + вход в браузере | ✅ |
+
+---
+
+## Деплой обновлений
+
+```bash
+sudo /opt/sac-deploy.sh
+```
+
+См. `deploy/sac-deploy.sh`, [install-ubuntu-24.04-native.md §13](install-ubuntu-24.04-native.md#13-обновление-sac-деплой).
+
+**Не делать:** `sudo git pull` в каталоге приложения (ломает права `.git` для `sac`).
+
+---
+
+## Следующие шаги
+
+1. **1A** — ssh-monitor на тестовом Linux: `UseSAC=dual`, `SAC_API_KEY`, `--check-sac`
+2. **1C** — Problems, Telegram из SAC, dashboard
+3. **1A** — маппинг всех типов событий через `notify_or_sac`
+4. RDP-login-monitor — аналог UseSAC
+
+---
+
+## Ссылки
+
+- [agent-integration.md](agent-integration.md)
+- [ssl-certificate.md](ssl-certificate.md)
+- [work-plan.md](work-plan.md)
@@ -8,8 +8,8 @@

 **Цель:** ingest на сервере; агенты в `dual` по мере готовности фазы 1A.

- Ingest API + PostgreSQL (**в работе — фаза 1B**)
- Events, Hosts, базовый UI
+- Ingest API + PostgreSQL (**prod**)
+- Events, Hosts, базовый UI (**prod**)
 - Problems (2 правила)
 - Telegram из SAC
 - 3 виджета dashboard
@@ -31,17 +31,17 @@

 ---

-## Фаза 1B. SAC — минимальный ingest (текущая разработка)
+## Фаза 1B. SAC — минимальный ingest ✅ (prod)

 | # | Задача | Статус |
 |---|--------|--------|
 | 1B.1 | Scaffold backend FastAPI | ✅ |
 | 1B.2 | PostgreSQL + Alembic (hosts, events, api_keys) | ✅ |
-| 1B.3 | `POST /api/v1/events`, `GET /health` | ✅ (prod) |
-| 1B.4 | systemd + nginx + [install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md) | ✅ |
+| 1B.3 | `POST /api/v1/events`, `GET /health` | ✅ prod `sac.kalinamall.ru` |
+| 1B.4 | systemd + nginx + TLS | ✅ |
 | 1B.5 | Валидация JSON Schema v1 | ✅ |

-**Выход:** сервер Ubuntu принимает события от curl и от агентов в `dual`.
+**Выход:** ingest с curl и UI на prod — достигнут.

 ---

@@ -49,11 +49,11 @@

 | # | Задача | Статус |
 |---|--------|--------|
-| 1C.1 | Frontend Vue: Events, Hosts | 🔄 |
-| 1C.2 | Auth JWT, admin bootstrap | 🔄 |
-| 1C.3 | Problems (базовые правила) |
-| 1C.4 | Telegram из SAC |
-| 1C.5 | Dashboard (3 виджета), SSE |
+| 1C.1 | Frontend Vue: Events, Hosts | ✅ prod |
+| 1C.2 | Auth JWT, admin bootstrap | ✅ prod |
+| 1C.3 | Problems (базовые правила) | ⏳ |
+| 1C.4 | Telegram из SAC | ⏳ |
+| 1C.5 | Dashboard (3 виджета), SSE | ⏳ |

 **Выход:** тег `v0.1.0-mvp`.

@@ -86,8 +86,9 @@ gantt
  section Документы
  Фаза 0            :done, 2026-05-26, 1d
  section SAC
-  1B ingest+deploy  :active, 2026-05-26, 7d
-  1C UI+notify      :2026-06-02, 14d
+  1B ingest+deploy  :done, 2026-05-26, 1d
+  1C UI базовый     :done, 2026-05-26, 1d
+  1C notify+dash    :active, 2026-05-27, 14d
  section Агенты
  1A UseSAC dual     :2026-05-26, 10d
  section Prod
@@ -99,5 +100,6 @@ gantt
 ## См. также

 - [install-ubuntu-24.04.md](install-ubuntu-24.04.md) — подготовка сервера
+- [operations-prod-status.md](operations-prod-status.md) — статус prod и деплой
 - [roadmap.md](roadmap.md)
 - [TZ.md](TZ.md)