PapaTramp/security-alert-center
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: native Ubuntu install as primary; systemd and nginx

Browse Source 
- install-ubuntu-24.04-native.md (production) and -docker.md (alternative)

- deploy/systemd/sac-api.service, nginx/sac.conf.example, env.native.example

- deployment, README, INDEX, work-plan, TZ updated
This commit is contained in:
PTah
2026-05-26 20:28:05 +10:00
parent 69a232d08a
commit 9203af90d5
14 changed files with 582 additions and 427 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+4 -3
View File
@@ -12,9 +12,9 @@
## Статус проекта ## Статус проекта
**Фаза 1B:** backend (FastAPI ingest), Docker Compose. Параллельно — интеграция `UseSAC` в агентах (фаза 1A). **Фаза 1B:** backend (FastAPI ingest), развёртывание **native** (systemd + PostgreSQL + nginx). Параллельно — `UseSAC` в агентах (фаза 1A).
**Подготовка сервера:** [docs/install-ubuntu-24.04.md](docs/install-ubuntu-24.04.md) **Подготовка сервера Ubuntu:** [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md)
## Документация ## Документация
@@ -26,7 +26,8 @@
| [docs/agent-integration.md](docs/agent-integration.md) | Интеграция агентов, режим `UseSAC` | | [docs/agent-integration.md](docs/agent-integration.md) | Интеграция агентов, режим `UseSAC` |
| [docs/work-plan.md](docs/work-plan.md) | План работ (этапы разработки) | | [docs/work-plan.md](docs/work-plan.md) | План работ (этапы разработки) |
| [docs/roadmap.md](docs/roadmap.md) | Дорожная карта продуктовых фаз | | [docs/roadmap.md](docs/roadmap.md) | Дорожная карта продуктовых фаз |
| [docs/install-ubuntu-24.04.md](docs/install-ubuntu-24.04.md) | Установка софта на Ubuntu 24.04 (пошагово) | | [docs/install-ubuntu-24.04-native.md](docs/install-ubuntu-24.04-native.md) | **Ubuntu 24.04 — native (основной)** |
| [docs/install-ubuntu-24.04-docker.md](docs/install-ubuntu-24.04-docker.md) | Ubuntu 24.04 — Docker (альтернатива) |
| [docs/deployment.md](docs/deployment.md) | Развёртывание и эксплуатация | | [docs/deployment.md](docs/deployment.md) | Развёртывание и эксплуатация |
| [docs/workspace-three-repos.md](docs/workspace-three-repos.md) | Multi-root workspace для трёх репо | | [docs/workspace-three-repos.md](docs/workspace-three-repos.md) | Multi-root workspace для трёх репо |
backend/README.md
+20 -14
View File
@@ -2,29 +2,37 @@
FastAPI + PostgreSQL + Alembic. FastAPI + PostgreSQL + Alembic.
## Локальная разработка (без Docker) ## Production (native на Ubuntu 24.04)
См. **[docs/install-ubuntu-24.04-native.md](../docs/install-ubuntu-24.04-native.md)**.
Кратко:
```bash
cd /opt/security-alert-center/backend
python3.12 -m venv .venv && .venv/bin/pip install -r requirements.txt
# /etc/security-alert-center/sac-api.env — см. deploy/env.native.example
alembic upgrade head
systemctl start sac-api
```
## Локальная разработка
```bash ```bash
cd backend cd backend
python3.12 -m venv .venv python3.12 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate source .venv/bin/activate
pip install -r requirements.txt pip install -r requirements.txt
export DATABASE_URL=postgresql+psycopg2://sac:sac@localhost:5432/sac export DATABASE_URL=postgresql+psycopg2://sac:sac@localhost:5432/sac
export SAC_BOOTSTRAP_API_KEY=sac_dev_test_key_change_me export SAC_BOOTSTRAP_API_KEY=sac_dev_test_key
export EVENT_SCHEMA_PATH=../schemas/event-schema-v1.json
alembic upgrade head alembic upgrade head
uvicorn app.main:app --reload --port 8000 uvicorn app.main:app --reload --port 8000
``` ```
## Docker (из корня репозитория) ## Docker (альтернатива)
```bash [docs/install-ubuntu-24.04-docker.md](../docs/install-ubuntu-24.04-docker.md)
cd deploy
cp .env.example .env
# отредактировать .env
docker compose up -d
docker compose run --rm migrate
curl http://127.0.0.1:8000/health
```
## API ## API
@@ -32,5 +40,3 @@ curl http://127.0.0.1:8000/health
|-------|------|------| |-------|------|------|
| GET | `/health` | нет | | GET | `/health` | нет |
| POST | `/api/v1/events` | Bearer API key | | POST | `/api/v1/events` | Bearer API key |
См. [docs/agent-integration.md](../docs/agent-integration.md) и [docs/event-schema-v1.json](../docs/event-schema-v1.json).
deploy/.env.example
+2 -1
View File
@@ -1,4 +1,5 @@
# Скопировать: cp .env.example .env (или в /etc/security-alert-center/.env) # Только для Docker Compose (см. docs/install-ubuntu-24.04-docker.md).
# Production native: deploy/env.native.example → /etc/security-alert-center/sac-api.env
# PostgreSQL # PostgreSQL
POSTGRES_USER=sac POSTGRES_USER=sac
deploy/README.md
+12 -4
View File
@@ -1,10 +1,18 @@
# Deploy # Deploy
## Production (native) — основной путь
1. [docs/install-ubuntu-24.04-native.md](../docs/install-ubuntu-24.04-native.md)
2. `deploy/env.native.example` → `/etc/security-alert-center/sac-api.env`
3. `deploy/systemd/sac-api.service` → `/etc/systemd/system/`
4. `deploy/nginx/sac.conf.example` → `/etc/nginx/sites-available/sac`
## Альтернатива: Docker
Только для стенда. См. [docs/install-ubuntu-24.04-docker.md](../docs/install-ubuntu-24.04-docker.md).
```bash ```bash
cp .env.example .env cp .env.example .env # docker-only
nano .env
docker compose up -d --build docker compose up -d --build
docker compose run --rm migrate docker compose run --rm migrate
``` ```
Полная инструкция для Ubuntu 24.04: [../docs/install-ubuntu-24.04.md](../docs/install-ubuntu-24.04.md)
deploy/env.native.example
+19
View File
@@ -0,0 +1,19 @@
# Native (systemd): скопировать в /etc/security-alert-center/sac-api.env
# chmod 600 /etc/security-alert-center/sac-api.env
# chown root:sac /etc/security-alert-center/sac-api.env
DATABASE_URL=postgresql+psycopg2://sac:CHANGE_ME_POSTGRES_PASSWORD@127.0.0.1:5432/sac
SAC_PUBLIC_URL=https://sac.example.com
JWT_SECRET=CHANGE_ME_openssl_rand_hex_32
# API key для агентов: Authorization: Bearer <ключ>
# python3.12 -c "import secrets; print('sac_'+secrets.token_urlsafe(32))"
SAC_BOOTSTRAP_API_KEY=sac_replace_with_generated_key
EVENT_SCHEMA_PATH=/opt/security-alert-center/schemas/event-schema-v1.json
SAC_ADMIN_USERNAME=admin
SAC_ADMIN_PASSWORD=
CORS_ORIGINS=*
deploy/nginx/sac.conf.example
+44
View File
@@ -0,0 +1,44 @@
# /etc/nginx/sites-available/sac
# Замените sac.example.com на ваш FQDN.
# API слушает только 127.0.0.1:8000 (systemd sac-api).
upstream sac_api {
server 127.0.0.1:8000;
keepalive 8;
}
server {
listen 80;
listen [::]:80;
server_name sac.example.com;
location /.well-known/acme-challenge/ {
root /var/www/html;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name sac.example.com;
# После certbot пути подставятся автоматически, либо укажите вручную:
# ssl_certificate /etc/letsencrypt/live/sac.example.com/fullchain.pem;
# ssl_certificate_key /etc/letsencrypt/live/sac.example.com/privkey.pem;
client_max_body_size 2m;
location / {
proxy_pass http://sac_api;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
}
}
deploy/systemd/sac-api.service
+21
View File
@@ -0,0 +1,21 @@
[Unit]
Description=Security Alert Center API (FastAPI)
Documentation=https://git.kalinamall.ru/PapaTramp/security-alert-center
After=network-online.target postgresql.service
Wants=network-online.target
Requires=postgresql.service
[Service]
Type=simple
User=sac
Group=sac
WorkingDirectory=/opt/security-alert-center/backend
EnvironmentFile=/etc/security-alert-center/sac-api.env
Environment=PYTHONPATH=/opt/security-alert-center/backend
ExecStart=/opt/security-alert-center/backend/.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
docs/INDEX.md
+4 -2
View File
@@ -9,8 +9,10 @@
| [event-schema-v1.json](event-schema-v1.json) | JSON Schema событий | | [event-schema-v1.json](event-schema-v1.json) | JSON Schema событий |
| [work-plan.md](work-plan.md) | План работ по фазам | | [work-plan.md](work-plan.md) | План работ по фазам |
| [roadmap.md](roadmap.md) | Дорожная карта версий | | [roadmap.md](roadmap.md) | Дорожная карта версий |
| [install-ubuntu-24.04.md](install-ubuntu-24.04.md) | **Подготовка сервера:** Docker, git, firewall, первый запуск | | [install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md) | **Подготовка сервера (native)** |
| [deployment.md](deployment.md) | Ubuntu 24.04, backup, TLS | | [install-ubuntu-24.04-docker.md](install-ubuntu-24.04-docker.md) | Подготовка сервера (Docker, альтернатива) |
| [install-ubuntu-24.04.md](install-ubuntu-24.04.md) | Указатель |
| [deployment.md](deployment.md) | Эксплуатация, backup, TLS |
| [workspace-three-repos.md](workspace-three-repos.md) | Cursor multi-root | | [workspace-three-repos.md](workspace-three-repos.md) | Cursor multi-root |
## Порядок чтения ## Порядок чтения
docs/TZ.md
+1 -1
View File
@@ -235,7 +235,7 @@ flowchart LR
| Frontend | Vue 3 + Vite, UI-kit (Naive UI / PrimeVue), ECharts | | Frontend | Vue 3 + Vite, UI-kit (Naive UI / PrimeVue), ECharts |
| Realtime | Server-Sent Events (приоритет MVP) | | Realtime | Server-Sent Events (приоритет MVP) |
| Reverse proxy | nginx | | Reverse proxy | nginx |
| Развёртывание | Docker Compose **или** native systemd (на выбор при реализации) | | Развёртывание | **Native:** PostgreSQL + systemd + nginx (production). Docker Compose — альтернатива для стенда |
Детали — [architecture.md](architecture.md). Детали — [architecture.md](architecture.md).
docs/deployment.md
+55 -135
View File
@@ -1,9 +1,23 @@
# Развёртывание на Ubuntu 24.04 # Развёртывание на Ubuntu 24.04
Руководство для эксплуатации SAC. Эксплуатация SAC: **native** (PostgreSQL + systemd + nginx). Docker — только альтернатива.
> **Подготовка чистого сервера (установка Docker, git, firewall, первый запуск):** ## Руководства по установке
> **[install-ubuntu-24.04.md](install-ubuntu-24.04.md)** — пошаговые команды для администратора.
| Документ | Назначение |
|----------|------------|
| **[install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md)** | **Production** — пошаговая подготовка сервера |
| [install-ubuntu-24.04-docker.md](install-ubuntu-24.04-docker.md) | Стенд / отладка (Compose) |
| [install-ubuntu-24.04.md](install-ubuntu-24.04.md) | Указатель |
## Артефакты native в репозитории
```
deploy/
env.native.example → /etc/security-alert-center/sac-api.env
systemd/sac-api.service → /etc/systemd/system/
nginx/sac.conf.example → /etc/nginx/sites-available/sac
```
--- ---
@@ -14,136 +28,65 @@
| ОС | Ubuntu 24.04 LTS | Ubuntu 24.04 LTS | | ОС | Ubuntu 24.04 LTS | Ubuntu 24.04 LTS |
| CPU | 2 vCPU | 4 vCPU | | CPU | 2 vCPU | 4 vCPU |
| RAM | 4 GB | 8 GB | | RAM | 4 GB | 8 GB |
| Диск | 50 GB SSD | 100+ GB SSD (отдельный том для PostgreSQL) | | Диск | 50 GB SSD | 100+ GB SSD |
| Сеть | Статический IP или DNS | TLS-сертификат (Let's Encrypt / внутренний CA) |
**Порты:** **Порты снаружи:** 443 (nginx), 80 (редирект). API `8000` — только `127.0.0.1`. PostgreSQL — только localhost.
| Порт | Назначение |
|------|------------|
| 443 | HTTPS (UI + API ingest) |
| 80 | Редирект на 443 (опционально) |
PostgreSQL **не** публикуется наружу.
--- ---
## 2. Сетевые правила ## 2. Сетевые правила
**Исходящие с агентов:** **Агенты →** `https://sac.example.com/api/v1/events`
**SAC →** Telegram, SMTP (исходящие)
- Linux (ssh-monitor) → `https://sac.example.com:443` **Админы →** 443 (UI/API через nginx)
- Windows (RDP-monitor) → тот же URL
**Исходящие с SAC:**
- `api.telegram.org` (если Telegram)
- SMTP-сервер организации
**Входящие на SAC:**
- 443 от сетей, где расположены агенты и админы UI
--- ---
## 3. Вариант A: Docker Compose (рекомендуется) ## 3. Вариант A: Native (production)
Целевая структура (фаза 1): Компоненты на хосте:
``` | Компонент | Как |
deploy/ |-----------|-----|
docker-compose.yml | PostgreSQL 16 | `apt`, БД `sac` |
.env.example | SAC API | Python 3.12 venv, **systemd** `sac-api` |
nginx/ | TLS / proxy | **nginx** |
sac.conf | UI (позже) | static в `/var/www/sac/` |
```
Сервисы: Полная инструкция: **[install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md)**.
- `postgres:16` Кратко:
- `api` (FastAPI)
- `worker` (тот же образ, другая command)
- `nginx` (static + proxy)
### 3.1. Установка Docker
```bash ```bash
sudo apt update systemctl status sac-api
sudo apt install -y ca-certificates curl curl -sS http://127.0.0.1:8000/health
# Официальная инструкция Docker CE для Ubuntu 24.04 curl -sS https://sac.example.com/health
```
### 3.2. Конфигурация
```bash
sudo mkdir -p /etc/security-alert-center
sudo cp deploy/.env.example /etc/security-alert-center/.env
sudo chmod 600 /etc/security-alert-center/.env
# Заполнить: POSTGRES_PASSWORD, JWT_SECRET, TELEGRAM_*, SAC_PUBLIC_URL
```
### 3.3. Запуск
```bash
cd /opt/security-alert-center/deploy
sudo docker compose up -d
sudo docker compose exec api alembic upgrade head
```
### 3.4. Обновление
```bash
git pull
sudo docker compose build
sudo docker compose up -d
sudo docker compose exec api alembic upgrade head
``` ```
--- ---
## 4. Вариант B: Native systemd ## 4. Вариант B: Docker Compose (альтернатива)
Пакеты: См. [install-ubuntu-24.04-docker.md](install-ubuntu-24.04-docker.md) и `deploy/docker-compose.yml`.
**Не используется** для production KalinaMall.
```bash
sudo apt install -y postgresql nginx python3.12 python3.12-venv
```
- PostgreSQL: БД `sac`, пользователь `sac`
- venv в `/opt/security-alert-center/.venv`
- Units: `sac-api.service`, `sac-worker.service`
- Static UI в `/var/www/sac/`
- nginx site `/etc/nginx/sites-available/sac`
Детальные unit-файлы — при реализации фазы 1.
--- ---
## 5. TLS ## 5. TLS
- Публичный: **certbot** + nginx - **certbot** + nginx (Let's Encrypt)
- Внутренний: корпоративный CA, полный chain в nginx - Внутренний CA — сертификаты в nginx, доверие на агентах Windows/Linux
Агенты должны доверять CA (или `SAC_TLS_SKIP_VERIFY=1` только для dev — **запрещено в prod**).
--- ---
## 6. Резервное копирование ## 6. Резервное копирование (native)
### 6.1. Ежедневный pg_dump
```bash ```bash
# /etc/cron.d/sac-backup (пример) # /etc/cron.d/sac-backup
0 3 * * * postgres pg_dump -Fc sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump 0 3 * * * postgres pg_dump -Fc -U sac sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump
``` ```
Ротация: 14 daily + 4 weekly. Восстановление: `pg_restore -d sac_restored /var/backups/sac/sac_YYYYMMDD.dump`
### 6.2. Восстановление (тест раз в месяц)
```bash
pg_restore -d sac_restored /var/backups/sac/sac_YYYYMMDD.dump
```
--- ---
@@ -151,48 +94,25 @@ pg_restore -d sac_restored /var/backups/sac/sac_YYYYMMDD.dump
| Задача | Периодичность | | Задача | Периодичность |
|--------|---------------| |--------|---------------|
| `unattended-upgrades` security | автоматически | | `unattended-upgrades` | автоматически |
| Проверка диска PostgreSQL | еженедельно | | `journalctl -u sac-api` | по инцидентам |
| Ротация логов nginx/app | logrotate | | `/health` | каждые 5 мин |
| Проверка `/health` | каждые 5 мин (Uptime Kuma / cron) |
| Review Problems «хост мёртв» | ежедневно |
| Тест restore БД | ежемесячно | | Тест restore БД | ежемесячно |
--- ---
## 8. Мониторинг самого SAC ## 8. Обновление (native)
- `GET https://sac.example.com/health` → `200`, `"database": "ok"` ```bash
- Алерт если нет ingest с активного хоста &gt; 90 мин (настраивается) cd /opt/security-alert-center && sudo -u sac git pull
- Диск &gt; 85% — алерт ОС sudo -u sac backend/.venv/bin/pip install -r backend/requirements.txt
sudo -u sac bash -c 'set -a; source /etc/security-alert-center/sac-api.env; set +a; cd backend && .venv/bin/alembic upgrade head'
--- sudo systemctl restart sac-api
```
## 9. Создание API key для хоста
(После реализации UI)
1. Войти как admin → Hosts → Add / Generate API key.
2. Скопировать ключ в `/etc/ssh-monitor.conf` или RDP-конфиг.
3. `UseSAC=exclusive`, перезапуск агента.
4. `--check-sac` на хосте.
---
## 10. Чеклист первого prod-развёртывания
- [ ] Ubuntu 24.04, hostname, DNS A-record
- [ ] TLS работает
- [ ] PostgreSQL backup настроен
- [ ] `.env` не в git, chmod 600
- [ ] Создан admin-пользователь
- [ ] Telegram test notification
- [ ] Тестовый ingest с одного Linux и одного Windows
- [ ] Firewall: только нужные порты
--- ---
## См. также ## См. также
- [TZ.md](TZ.md) §5, §9 - [TZ.md](TZ.md)
- [agent-integration.md](agent-integration.md) - [agent-integration.md](agent-integration.md)
docs/install-ubuntu-24.04-docker.md
+105
View File
@@ -0,0 +1,105 @@
# Ubuntu 24.04 — установка SAC (Docker Compose)
**Альтернативный** способ. В KalinaMall для production используется **[native](install-ubuntu-24.04-native.md)**.
Docker удобен для локальной отладки или изолированного стенда.
---
## 0. Исходные данные
| Параметр | Пример |
|----------|--------|
| Каталог | `/opt/security-alert-center` |
---
## 1. Базовая ОС и ufw
Как в [native-руководстве](install-ubuntu-24.04-native.md) §1 (без PostgreSQL/nginx на хосте, если всё в контейнерах — nginx можно на хосте для TLS).
---
## 2. Git и клон
```bash
sudo apt install -y git
sudo git clone https://git.kalinamall.ru/PapaTramp/security-alert-center.git /opt/security-alert-center
sudo chown -R "$USER:$USER" /opt/security-alert-center
```
---
## 3. Docker Engine + Compose
```bash
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker "$USER"
# перелогиниться
docker compose version
```
---
## 4. Конфигурация
```bash
sudo mkdir -p /etc/security-alert-center
cp /opt/security-alert-center/deploy/.env.example /etc/security-alert-center/.env
chmod 600 /etc/security-alert-center/.env
nano /etc/security-alert-center/.env
ln -sf /etc/security-alert-center/.env /opt/security-alert-center/deploy/.env
```
Заполнить: `POSTGRES_PASSWORD`, `JWT_SECRET`, `SAC_PUBLIC_URL`, `SAC_BOOTSTRAP_API_KEY`.
---
## 5. Запуск
```bash
cd /opt/security-alert-center/deploy
docker compose up -d --build
docker compose run --rm migrate
docker compose ps
curl -sS http://127.0.0.1:8000/health
```
---
## 6. Бэкап (Docker)
```bash
sudo tee /etc/cron.d/sac-backup <<'EOF'
0 3 * * * root docker compose -f /opt/security-alert-center/deploy/docker-compose.yml exec -T postgres pg_dump -U sac -Fc sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump
EOF
```
---
## 7. Обновление
```bash
cd /opt/security-alert-center
git pull
cd deploy
docker compose build
docker compose up -d
docker compose run --rm migrate
```
---
## См. также
- [install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md) — основной путь
- [../deploy/docker-compose.yml](../deploy/docker-compose.yml)
docs/install-ubuntu-24.04-native.md
+281
View File
@@ -0,0 +1,281 @@
# Ubuntu 24.04 — установка SAC (native, без Docker)
Пошаговое руководство: **PostgreSQL + Python venv + systemd + nginx**.
Рекомендуемый путь для production.
---
## 0. Исходные данные
| Параметр | Пример |
|----------|--------|
| FQDN | `sac.kalinin.example` |
| IP | `10.0.0.50` |
| Каталог | `/opt/security-alert-center` |
| Пользователь сервиса | `sac` |
| API только на localhost | `127.0.0.1:8000` |
| Снаружи | nginx → 443 → API |
---
## 1. Базовая настройка ОС
```bash
sudo apt update
sudo apt upgrade -y
sudo timedatectl set-timezone Europe/Moscow
```
### Firewall (ufw)
```bash
sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
```
---
## 2. Пакеты
```bash
sudo apt install -y \
git \
postgresql \
postgresql-contrib \
nginx \
python3.12 \
python3.12-venv \
python3-pip \
jq \
certbot \
python3-certbot-nginx
```
Проверка:
```bash
python3.12 --version
psql --version
nginx -v
```
---
## 3. Клонирование репозитория
```bash
sudo mkdir -p /opt
sudo git clone https://git.kalinamall.ru/PapaTramp/security-alert-center.git /opt/security-alert-center
```
---
## 4. PostgreSQL
Создать пользователя и БД (пароль сохраните для `.env`):
```bash
sudo -u postgres psql <<'SQL'
CREATE USER sac WITH PASSWORD 'ЗАМЕНИТЕ_НА_ДЛИННЫЙ_ПАРОЛЬ';
CREATE DATABASE sac OWNER sac;
GRANT ALL PRIVILEGES ON DATABASE sac TO sac;
SQL
```
PostgreSQL по умолчанию слушает `127.0.0.1` — для SAC этого достаточно.
Проверка:
```bash
psql "postgresql://sac@127.0.0.1/sac" -c 'SELECT 1'
```
Каталог бэкапов:
```bash
sudo mkdir -p /var/backups/sac
sudo chown postgres:postgres /var/backups/sac
```
---
## 5. Пользователь `sac` и Python venv
```bash
sudo useradd --system --home /opt/security-alert-center --shell /usr/sbin/nologin sac || true
sudo chown -R sac:sac /opt/security-alert-center
cd /opt/security-alert-center/backend
sudo -u sac python3.12 -m venv .venv
sudo -u sac .venv/bin/pip install --upgrade pip
sudo -u sac .venv/bin/pip install -r requirements.txt
```
---
## 6. Конфигурация `/etc/security-alert-center`
```bash
sudo mkdir -p /etc/security-alert-center
sudo chmod 750 /etc/security-alert-center
sudo cp /opt/security-alert-center/deploy/env.native.example /etc/security-alert-center/sac-api.env
sudo chmod 600 /etc/security-alert-center/sac-api.env
sudo nano /etc/security-alert-center/sac-api.env
```
Обязательно задать:
- `DATABASE_URL` — с паролем PostgreSQL из шага 4
- `JWT_SECRET` — `openssl rand -hex 32`
- `SAC_PUBLIC_URL` — `https://sac.kalinin.example` (как будет с nginx)
- `SAC_BOOTSTRAP_API_KEY` — `python3.12 -c "import secrets; print('sac_'+secrets.token_urlsafe(32))"`
- `EVENT_SCHEMA_PATH=/opt/security-alert-center/schemas/event-schema-v1.json`
---
## 7. Миграции БД
```bash
cd /opt/security-alert-center/backend
sudo -u sac bash -c 'set -a; source /etc/security-alert-center/sac-api.env; set +a; .venv/bin/alembic upgrade head'
```
---
## 8. systemd
```bash
sudo cp /opt/security-alert-center/deploy/systemd/sac-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable sac-api
sudo systemctl start sac-api
sudo systemctl status sac-api --no-pager
```
Логи:
```bash
journalctl -u sac-api -f
```
---
## 9. nginx и TLS
```bash
sudo cp /opt/security-alert-center/deploy/nginx/sac.conf.example /etc/nginx/sites-available/sac
sudo ln -sf /etc/nginx/sites-available/sac /etc/nginx/sites-enabled/sac
# убрать default при необходимости: sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
```
В `sac.conf` замените `server_name` на ваш FQDN.
Let's Encrypt:
```bash
sudo certbot --nginx -d sac.kalinin.example
```
---
## 10. Проверка
Локально на сервере:
```bash
curl -sS http://127.0.0.1:8000/health | jq .
```
Через nginx (после TLS):
```bash
curl -sS https://sac.kalinin.example/health | jq .
```
Тест ingest (подставьте `SAC_BOOTSTRAP_API_KEY`):
```bash
API_KEY="ваш_ключ_из_sac-api.env"
curl -sS -X POST http://127.0.0.1:8000/api/v1/events \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"schema_version": "1.0",
"event_id": "00000000-0000-4000-8000-000000000002",
"occurred_at": "2026-05-26T12:00:00+03:00",
"source": {"product": "ssh-monitor", "product_version": "test"},
"host": {"hostname": "test-host", "os_family": "linux"},
"category": "agent",
"type": "agent.test",
"severity": "info",
"title": "Test",
"summary": "Native install check"
}'
```
Ожидается HTTP **202** и `"status": "accepted"`.
---
## 11. Резервное копирование
```bash
sudo tee /etc/cron.d/sac-backup <<'EOF'
0 3 * * * postgres pg_dump -Fc -U sac sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump
EOF
```
Для `pg_dump` без пароля в cron настройте `~postgres/.pgpass` (см. документацию PostgreSQL).
---
## 12. Обновление SAC
```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 /etc/security-alert-center/sac-api.env; set +a; cd backend && .venv/bin/alembic upgrade head'
sudo systemctl restart sac-api
```
---
## 13. Чеклист
- [ ] Ubuntu 24.04, timezone
- [ ] ufw: 22, 80, 443
- [ ] PostgreSQL: БД `sac`, пользователь `sac`
- [ ] venv, зависимости установлены
- [ ] `/etc/security-alert-center/sac-api.env`, chmod 600
- [ ] `alembic upgrade head` без ошибок
- [ ] `sac-api` active (systemd)
- [ ] nginx + TLS
- [ ] `/health` ok, ingest 202
- [ ] cron backup
---
## 14. Устранение неполадок
| Симптом | Действие |
|---------|----------|
| `database: error` | `journalctl -u sac-api`; проверить `DATABASE_URL`, `systemctl status postgresql` |
| 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 |
---
## См. также
- [install-ubuntu-24.04.md](install-ubuntu-24.04.md) — указатель
- [install-ubuntu-24.04-docker.md](install-ubuntu-24.04-docker.md) — альтернатива (не prod)
- [deployment.md](deployment.md)
docs/install-ubuntu-24.04.md
+13 -266
View File
@@ -1,277 +1,24 @@
# Подготовка сервера Ubuntu 24.04 для Security Alert Center # Подготовка сервера Ubuntu 24.04 для SAC
Пошаговое руководство: установка софта на **чистый** или обновлённый хост перед развёртыванием SAC. В эксплуатации KalinaMall используется **только native** (без Docker): PostgreSQL, Python venv, systemd, nginx.
Целевой способ запуска — **Docker Compose** (рекомендуется). В конце — проверка и ссылка на [deployment.md](deployment.md).
--- ## Руководства
## 0. Исходные данные | Путь | Когда использовать |
|------|-------------------|
| **[install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md)** | **Основной** — подготовка и запуск SAC |
| [install-ubuntu-24.04-docker.md](install-ubuntu-24.04-docker.md) | Альтернатива (Docker Compose), не для prod |
Запишите до начала: ## Быстрый старт (native)
| Параметр | Пример |
|----------|--------|
| FQDN | `sac.kalinin.example` |
| IP | `10.0.0.50` |
| Пользователь sudo | `deploy` |
| Каталог установки | `/opt/security-alert-center` |
---
## 1. Базовая настройка ОС
```bash ```bash
sudo apt update # см. полный чеклист в native-руководстве
sudo apt upgrade -y sudo apt update && sudo apt install -y git postgresql nginx python3.12 python3.12-venv
sudo timedatectl set-timezone Europe/Moscow # или ваша IANA-зона
timedatectl status
```
Опционально — hostname:
```bash
sudo hostnamectl set-hostname sac-01
```
### 1.1. Firewall (ufw)
```bash
sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
```
SSH оставьте только с доверенных подсетей, если политика безопасности требует:
```bash
# пример: только внутренняя сеть
# sudo ufw allow from 10.0.0.0/8 to any port 22
```
---
## 2. Установка Git
```bash
sudo apt install -y git
git --version
```
Клонирование (после доступа к репозиторию):
```bash
sudo mkdir -p /opt
sudo git clone https://git.kalinamall.ru/PapaTramp/security-alert-center.git /opt/security-alert-center sudo git clone https://git.kalinamall.ru/PapaTramp/security-alert-center.git /opt/security-alert-center
sudo chown -R "$USER:$USER" /opt/security-alert-center # … PostgreSQL, venv, /etc/security-alert-center/sac-api.env, systemd, nginx
``` ```
---
## 3. Установка Docker Engine + Compose plugin
Официальный репозиторий Docker для Ubuntu 24.04 (noble):
```bash
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```
Добавить пользователя в группу `docker` (перелогиниться после):
```bash
sudo usermod -aG docker "$USER"
```
Проверка:
```bash
docker --version
docker compose version
sudo docker run --rm hello-world
```
---
## 4. Каталоги данных и конфигурации
```bash
sudo mkdir -p /etc/security-alert-center
sudo mkdir -p /var/lib/sac/postgres
sudo mkdir -p /var/backups/sac
sudo chown -R "$USER:docker" /var/lib/sac
```
Права на секреты:
```bash
sudo chmod 750 /etc/security-alert-center
```
---
## 5. Конфигурация SAC (.env)
```bash
cd /opt/security-alert-center/deploy
cp .env.example /etc/security-alert-center/.env
chmod 600 /etc/security-alert-center/.env
nano /etc/security-alert-center/.env
```
Обязательно задать (см. комментарии в `.env.example`):
- `POSTGRES_PASSWORD` — длинный случайный пароль
- `JWT_SECRET` — `openssl rand -hex 32`
- `SAC_PUBLIC_URL` — публичный URL, например `https://sac.kalinin.example`
- `SAC_ADMIN_PASSWORD` — пароль первого admin (только первый запуск)
Симлинк для compose (удобно):
```bash
ln -sf /etc/security-alert-center/.env /opt/security-alert-center/deploy/.env
```
---
## 6. Первый запуск SAC
```bash
cd /opt/security-alert-center/deploy
docker compose build
docker compose up -d --build
docker compose run --rm migrate
docker compose ps
```
Проверка health (пока без TLS — с хоста):
```bash
curl -sS http://127.0.0.1:8000/health | jq .
```
Ожидается JSON с `"status": "ok"` и `"database": "ok"`.
Тест ingest (подставьте ключ из `.env` — `SAC_BOOTSTRAP_API_KEY` или созданный в UI):
```bash
curl -sS -X POST http://127.0.0.1:8000/api/v1/events \
-H "Authorization: Bearer ВАШ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"schema_version": "1.0",
"event_id": "00000000-0000-4000-8000-000000000001",
"occurred_at": "2026-05-26T12:00:00+03:00",
"source": {"product": "ssh-monitor", "product_version": "test"},
"host": {"hostname": "test-host", "os_family": "linux"},
"category": "agent",
"type": "agent.test",
"severity": "info",
"title": "Test",
"summary": "Install check"
}'
```
---
## 7. Nginx и TLS (production)
Установка nginx на хосте **или** использование контейнера из `docker compose` (см. `deploy/docker-compose.yml`).
### 7.1. Certbot (Let's Encrypt), если есть публичный DNS
```bash
sudo apt install -y nginx certbot python3-certbot-nginx
# после настройки server_name в nginx:
sudo certbot --nginx -d sac.kalinin.example
```
### 7.2. Внутренний CA
Используйте корпоративный сертификат в `deploy/nginx/certs/` и смонтируйте в compose.
Агентам (ssh-monitor / Windows) нужно доверять этому CA.
---
## 8. Автозапуск после перезагрузки
Docker Compose с `restart: unless-stopped` в `docker-compose.yml` — сервисы поднимутся сами.
Проверка:
```bash
sudo reboot
# после входа:
docker compose -f /opt/security-alert-center/deploy/docker-compose.yml ps
```
---
## 9. Резервное копирование PostgreSQL
```bash
sudo tee /etc/cron.d/sac-backup <<'EOF'
0 3 * * * root docker compose -f /opt/security-alert-center/deploy/docker-compose.yml exec -T postgres pg_dump -U sac -Fc sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump
EOF
```
Ротация старых дампов — `logrotate` или скрипт по политике (14 daily).
---
## 10. Обновление SAC
```bash
cd /opt/security-alert-center
git pull
cd deploy
docker compose build
docker compose up -d
docker compose exec api alembic upgrade head
```
---
## 11. Чеклист готовности сервера
- [ ] Ubuntu 24.04, время и timezone верные
- [ ] ufw: 22 (по политике), 80, 443
- [ ] Docker и compose работают
- [ ] Репозиторий в `/opt/security-alert-center`
- [ ] `/etc/security-alert-center/.env` заполнен, chmod 600
- [ ] `docker compose up` — все контейнеры healthy
- [ ] `GET /health` — ok
- [ ] Тестовый `POST /api/v1/events` — 202
- [ ] TLS настроен (prod)
- [ ] cron backup
---
## 12. Устранение неполадок
| Симптом | Действие |
|---------|----------|
| `database: error` в /health | `docker compose logs postgres api`, проверить `DATABASE_URL` |
| 401 на ingest | неверный API key; см. `SAC_BOOTSTRAP_API_KEY` в .env |
| Нет места на диске | `df -h`, очистка journal/docker: `docker system prune` |
| Порт 8000 занят | изменить mapping в compose или остановить конфликтующий сервис |
---
## См. также ## См. также
- [deployment.md](deployment.md) — архитектура, порты, эксплуатация - [deployment.md](deployment.md)
- [agent-integration.md](agent-integration.md) — настройка агентов после поднятия SAC - [../deploy/README.md](../deploy/README.md)
- [TZ.md](TZ.md) — требования
docs/work-plan.md
+1 -1
View File
@@ -38,7 +38,7 @@
| 1B.1 | Scaffold backend FastAPI | 🔄 | | 1B.1 | Scaffold backend FastAPI | 🔄 |
| 1B.2 | PostgreSQL + Alembic (hosts, events, api_keys) | 🔄 | | 1B.2 | PostgreSQL + Alembic (hosts, events, api_keys) | 🔄 |
| 1B.3 | `POST /api/v1/events`, `GET /health` | 🔄 | | 1B.3 | `POST /api/v1/events`, `GET /health` | 🔄 |
| 1B.4 | docker-compose + [install-ubuntu-24.04.md](install-ubuntu-24.04.md) | 🔄 | | 1B.4 | systemd + nginx + [install-ubuntu-24.04-native.md](install-ubuntu-24.04-native.md) | 🔄 |
| 1B.5 | Валидация JSON Schema v1 | ⏳ | | 1B.5 | Валидация JSON Schema v1 | ⏳ |
**Выход:** сервер Ubuntu принимает события от curl и от агентов в `dual`. **Выход:** сервер Ubuntu принимает события от curl и от агентов в `dual`.