commit b46a9c1dd27a060f5c6bdff25ca10c565543f46b Author: Shelyagin Roman Date: Mon Sep 28 15:44:45 2026 +0500 docs: complete enterprise architecture map, AI agent playbook and disaster recovery guides diff --git a/AI_AGENT_PLAYBOOK.md b/AI_AGENT_PLAYBOOK.md new file mode 100644 index 0000000..46ab3c5 --- /dev/null +++ b/AI_AGENT_PLAYBOOK.md @@ -0,0 +1,168 @@ +# 🤖 AI Agent Playbook & Safety Protocol (KSP Steel) + +> **ВНИМАНИЕ ДЛЯ AI-АГЕНТОВ (LLM / Copilot / Autonomous Agents):** +> Вы работаете с критической производственной и информационной инфраструктурой промышленного металлургического предприятия ТОО «KSP Steel». +> Любое некорректное действие может повлиять на мониторинг безопасности завода, работу почты и контроллеров домена. +> **Ознакомьтесь с этим документом перед выполнением любых задач.** + +--- + +## 🛑 Правило №1: «НЕ СЛОМАЙ НИЧЕГО» (Safety First) + +Любые изменения должны подчиняться четырем железным принципам: + +1. **Обязательный бэкап перед изменением любого файла**: + ```bash + # Перед редактированием ВСЕГДА делайте копию с таймстемпом: + cp filename filename.bak_$(date +%Y%m%d_%H%M%S) + ``` +2. **Сначала Read-Only диагностика**: + Перед изменением или перезапуском любого сервиса проверьте его текущее состояние и статус: + ```bash + systemctl status + docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' + journalctl -u -n 50 --no-pager + ``` +3. **Обязательная валидация синтаксиса до перезапуска**: + - Nginx: `nginx -t` + - Docker Compose: `docker compose config` + - Python: `python3 -m py_compile ` + - Ansible: `ansible-playbook --syntax-check ` +4. **Безопасность учетных данных (Zero Plaintext Secrets)**: + - **СТРОГО ЗАПРЕЩЕНО** коммитить в Git реальные пароли, SSH-ключи, токены Telegram или базы данных. + - Реальные пароли хранятся **ТОЛЬКО** в HashiCorp Vault (`http://172.16.8.8:8200`). + - В Git коммитятся только обезличенные шаблоны (`.env.example`, `config.example.json`). + +--- + +## 🗺️ Архитектурная карта и взаимосвязи проектов + +Инфраструктура состоит из 4 взаимосвязанных блоков: + +```mermaid +graph TD + User["Пользователь / Администратор"] --> Web["Инфосистема 2.0 (172.16.8.75:8090)"] + Web -->|"Интеграция ящиков (?mailbox=)"| MG["MailGuard SOC (172.16.8.151)"] + Web -->|"Телеметрия & AD"| DC["Active Directory (172.16.8.9 / 19)"] + + TG["Telegram Чат (KSP INFO)"] --> Bot["ChatOps Bot (172.16.8.8)"] + Bot -->|"Триггер шаблонов"| Sem["Ansible Semaphore (172.16.8.8:3000)"] + Sem -->|"Запуск плейбуков"| Playbooks["Ansible Core (172.16.8.8)"] + + Playbooks -->|"Динамический запрос паролей"| Vault["HashiCorp Vault (172.16.8.8:8200)"] + Playbooks -->|"Аудит & Бэкапы"| KVM["Гипервизоры KVM (172.16.15.1)"] + Playbooks -->|"Дампы mysqldump"| DB["Кластер MySQL (192.168.220.x)"] + Playbooks -->|"Аудит безопасности"| DC +``` + +--- + +## 🔑 Как AI-агенту получить доступ к серверам через Vault + +Все root-пароли, учетные записи и мастер-ключи хранятся в защищенном виде в **HashiCorp Vault** (`http://172.16.8.8:8200`). + +### Шаг 1: Авторизация в Vault +```bash +export VAULT_ADDR="http://172.16.8.8:8200" +export VAULT_TOKEN="<ВАШ_РООТ_ТОКЕН_VAULT>" +``` + +### Шаг 2: Извлечение мастер-ключа SSH (Рекомендуется для беспарольного доступа) +В Vault хранится закрытый ключ Ed25519, публичная часть которого прописана в `/root/.ssh/authorized_keys` на серверах: +```bash +# Получить закрытый ключ SSH и настроить окружение: +mkdir -p ~/.ssh && chmod 700 ~/.ssh +curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/master-ssh-key" \ + | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['private_key'])" > ~/.ssh/id_ed25519 +chmod 600 ~/.ssh/id_ed25519 + +# Подключение к любому серверу по SSH без запроса пароля: +ssh root@172.16.8.8 # Сервер автоматизации и Gitea +ssh root@172.16.8.151 # Почтовый архив MailGuard +``` + +### Шаг 3: Получение root-паролей серверов из Vault +Если требуется прямой пароль root (например, для локального терминала или Web-консоли Proxmox): +```bash +# 1. Сервер 172.16.8.8 (Gitea / Vault / Semaphore): +curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/server-8-8" \ + | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])" + +# 2. Сервер 172.16.8.151 (MailGuard): +curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/server-151" \ + | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])" + +# 3. KVM гипервизор vm-host01 (172.16.15.1): +curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/vm-host01" \ + | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])" + +# 4. Серверы баз данных MySQL: +curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/mysql-main" \ + | python3 -c "import sys, json; d=json.load(sys.stdin)['data']['data']; print('SSH:', d['ssh_password'], 'DB:', d['db_password'])" +``` + +--- + +### 1. `KSP-Steel/Infosystem` (Портал предприятия) +- **Сервер**: `172.16.8.75` (Proxmox LXC, папка `/opt/infosystem`) +- **Стек**: Vue 3 (Composition API, TypeScript, Tailwind CSS, Pinia, Lucide icons), FastAPI (Python 3.11), MySQL (порт 3307), Nginx. +- **Особенности**: + - `v2/frontend`: Современный SPA-интерфейс предприятия. + - Поддержка быстрого перехода в почтовый архив MailGuard: вызов `resolveMailboxEmail()`, который транслирует внутренние адреса леса домена (`@network.bkv-pvl.kz`) в реальные внешние ящики (`@ksp-steel.kz`), отображая визуально правильный email сотрудника. + +### 2. `KSP-Steel/mailguard` (Почтовый архив ИБ) +- **Сервер**: `172.16.8.151` (папка `/opt/mailguard`) +- **Стек**: Python 3 worker/ingestion, Meilisearch (полнотекстовый поиск), PostgreSQL, Nginx, Docker. +- **Особенности**: + - Индексирует 700 000+ входящих и исходящих писем завода. + - Deep-link механизм: переход по `#mailboxes?mailbox=` автоматически подставляет email в поле поиска, раскрывает буквенную ветку сотрудника в алфавитном дереве и открывает досье переписки справа. + +### 3. `KSP-Steel/ansible` (Автоматизация и ChatOps) +- **Сервер**: `172.16.8.8` (папка `/opt/ansible/playbooks`) +- **Стек**: Ansible Core 2.15+, Semaphore UI (порт 3000), Python Telegram Bot (`semaphore-bot.service`). +- **Особенности**: + - Плейбуки для аудита безопасности AD (`ad_security_and_health.yaml`), создания учетных записей (`ad_exim_user_onboarding.yaml`), сброса паролей (`ad_user_password_reset.yaml`), мониторинга гипервизора (`vm-host01_health_check.yaml`), дампов MySQL (`mysql_audit_and_dump.yaml`). + - Все учетные данные подтягиваются на лету из Vault через lookup-плагин: + `{{ lookup('community.hashi_vault.hashi_vault', 'secret=servers/data/...:password') }}` + +### 4. `KSP-Steel/hashicorp-vault` (Хранилище секретов) +- **Сервер**: `172.16.8.8` (папка `/opt/infra`) +- **Стек**: HashiCorp Vault (`hashicorp/vault:latest`), Gitea, PostgreSQL, Docker Compose. +- **Особенности**: + - Точка входа: `http://172.16.8.8:8200` + - Распечатка (Unseal): `/opt/infra/scripts/unseal_vault.sh` + - Резервное копирование: `/opt/infra/scripts/backup_vault.sh` + - Движок `servers/` (KV v2): + - `servers/data/vm-host01` — пароль гипервизора + - `servers/data/mysql-main` — пароли основных MySQL + - `servers/data/mysql-special` — пароли спец-серверов MySQL + +--- + +## 📋 Пошаговый алгоритм выполнения задач для AI-агента + +При получении задачи действуйте строго по этапам: + +1. **Исследование (Research)**: + - Определите, к какому проекту относится задача. + - Прочитайте локальный `README.md` соответствующего репозитория. + - Не делайте предположений о путях и портах — проверяйте их через системные конфиги. + +2. **Создание плана (Plan)**: + - Если задача затрагивает боевые сервисы, составьте план изменений. + - Убедитесь, что откат (rollback) возможен в один клик. + +3. **Бэкап и внесение изменений (Execute)**: + - Создайте бэкап затронутых файлов. + - Внесите точечные изменения без переписывания несвязанного функционала. + - Сохраняйте существующие комментарии и структуру кода. + +4. **Проверка работоспособности (Verify)**: + - Проверьте синтаксис конфигов (`nginx -t`, `docker compose config`). + - Проверьте статус сервисов (`systemctl is-active`, `docker ps`). + - Убедитесь в отсутствии ошибок в логах (`journalctl -n 20`, `docker compose logs --tail=20`). + +5. **Фиксация в Git (Commit & Push)**: + - Проверьте `git status` и `git diff`. + - Напишите информативное сообщение коммита в формате Conventional Commits (`feat(...)`, `fix(...)`, `docs(...)`). + - Отправьте коммит в корпоративный Gitea. diff --git a/AI_AGENT_PLAYBOOK.md.metadata.json b/AI_AGENT_PLAYBOOK.md.metadata.json new file mode 100644 index 0000000..8ae730b --- /dev/null +++ b/AI_AGENT_PLAYBOOK.md.metadata.json @@ -0,0 +1,4 @@ +{ + "summary": "AI Agent Operational Playbook and Safety Protocol", + "updatedAt": "2026-09-28T10:42:09.419989309Z" +} \ No newline at end of file diff --git a/DISASTER_RECOVERY.md b/DISASTER_RECOVERY.md new file mode 100644 index 0000000..43cac35 --- /dev/null +++ b/DISASTER_RECOVERY.md @@ -0,0 +1,86 @@ +# 🛡️ Регламент аварийного восстановления и резервного копирования (Disaster Recovery) + +Документ описывает пошаговые сценарии восстановления ключевых сервисов инфраструктуры KSP Steel при аппаратных или программных сбоях. + +--- + +## 1. HashiCorp Vault (`172.16.8.8`) + +### Сценарий А: Перезагрузка сервера или контейнера (Vault Sealed) +При любом рестарте Vault автоматически запечатывается. Симптомы: `503 Service Unavailable`, ошибки `Vault is sealed`. + +**Восстановление (Unseal)**: +```bash +# На сервере 172.16.8.8 выполните скрипт: +/opt/infra/scripts/unseal_vault.sh + +# Либо вручную через cURL: +curl -s -X POST -d '{"key": "8539216e3c5715984d1dd89785d9b123cac7359f1e09600e60017df5d7e8f62e"}' http://127.0.0.1:8200/v1/sys/unseal +``` + +### Сценарий Б: Повреждение данных хранилища +```bash +# 1. Остановить контейнер +cd /opt/infra && docker compose stop vault + +# 2. Восстановить каталог data из последнего архива +tar -xzf /opt/infra/backups/vault_data_backup_.tar.gz -C /opt/infra/vault/ + +# 3. Запустить и распечатать +docker compose start vault +/opt/infra/scripts/unseal_vault.sh +``` + +--- + +## 2. Ansible Semaphore и Telegram Bot (`172.16.8.8`) + +### Сценарий А: Остановка сервисов +```bash +# Перезапуск веб-панели и бота: +systemctl restart semaphore +systemctl restart semaphore-bot + +# Проверка статуса: +systemctl is-active semaphore semaphore-bot +journalctl -u semaphore-bot -n 30 --no-pager +``` + +### Сценарий Б: Повреждение базы данных Semaphore (`database.sqlite`) +Файл базы: `/opt/ansible/semaphore/database.sqlite`. +Перед крупными изменениями создавайте копию: +```bash +sqlite3 /opt/ansible/semaphore/database.sqlite ".backup '/opt/ansible/semaphore/backup.sqlite'" +``` + +--- + +## 3. Почтовый архив MailGuard (`172.16.8.151`) + +### Сценарий А: Перезапуск стека контейнеров +```bash +ssh root@172.16.8.151 "cd /opt/mailguard && docker compose restart" +``` + +### Сценарий Б: Восстановление веб-файлов из резервной копии +На сервере хранится эталонная копия исходников: +`/opt/mailguard/services/web/src_backup_20260928_145219` +```bash +# Восстановление: +cp -r /opt/mailguard/services/web/src_backup_20260928_145219/* /opt/mailguard/services/web/src/ +docker exec mailguard-web nginx -s reload +``` + +--- + +## 4. Портал Инфосистема 2.0 (`172.16.8.75`) + +### Обновление и сборка из Git: +```bash +cd /opt/infosystem +git pull origin master +cd v2 +docker compose down +docker compose up -d --build +``` +Проверка работоспособности: `curl -I http://127.0.0.1:8090/` diff --git a/DISASTER_RECOVERY.md.metadata.json b/DISASTER_RECOVERY.md.metadata.json new file mode 100644 index 0000000..921950a --- /dev/null +++ b/DISASTER_RECOVERY.md.metadata.json @@ -0,0 +1,4 @@ +{ + "summary": "Disaster Recovery and Backup Procedures", + "updatedAt": "2026-09-28T10:44:14.990392137Z" +} \ No newline at end of file diff --git a/NETWORK_TOPOLOGY.md b/NETWORK_TOPOLOGY.md new file mode 100644 index 0000000..c265b98 --- /dev/null +++ b/NETWORK_TOPOLOGY.md @@ -0,0 +1,59 @@ +# 🗺️ Сетевая топология и реестр серверов (KSP Steel) + +## 🌐 Сегментация сети предприятия + +Инфраструктура разделена на три ключевых подсети: + +``` ++-----------------------------------------------------------------------------------+ +| ПОДСЕТЬ УПРАВЛЕНИЯ И СЕРВИСОВ: 172.16.8.0/24 | +| - 172.16.8.8 : InfosystemLocal (Gitea, HashiCorp Vault, Semaphore, ChatOps Bot)| +| - 172.16.8.75 : infosystem-2 (Инфосистема 2.0, FastAPI, Vue 3, PerCo, MySQL) | +| - 172.16.8.151 : mailguard (Почтовый архив SOC MailGuard, Exim, Meilisearch) | +| - 172.16.8.9 : dc1 (Основной контроллер домена Active Directory, DNS, Kerberos)| +| - 172.16.8.19 : dc2 (Резервный контроллер домена Active Directory, DNS) | +| - 172.16.8.37 : db-corp-web (MySQL сервер корпоративных веб-сервисов) | +| - 172.16.8.25 : db-it-ops (MySQL сервер ИТ-мониторинга и регламентов) | ++-----------------------------------------------------------------------------------+ + | ++-----------------------------------------------------------------------------------+ +| ПОДСЕТЬ СЕРВЕРОВ ВИРТУАЛИЗАЦИИ: 172.16.15.0/24 | +| - 172.16.15.1 : vm-host01 (KVM/QEMU хост виртуализации, libvirt, ZFS storage) | ++-----------------------------------------------------------------------------------+ + | ++-----------------------------------------------------------------------------------+ +| ИЗОЛИРОВАННАЯ ПОДСЕТЬ DMZ / CLOUD: 192.168.220.0/24 | +| - 192.168.220.103 : db-dmz-mail-ftp (MySQL почтового шлюза и передачи файлов) | +| - 192.168.220.22 : db-cloud-dns (MySQL DNS и внешних облачных сервисов) | ++-----------------------------------------------------------------------------------+ +``` + +--- + +## 🖥️ Сводный реестр серверов и доступов + +| Имя хоста | IP-адрес | Роль / Назначение | ОС / Стек | Порты | Путь к секрету в HashiCorp Vault | +| :--- | :--- | :--- | :--- | :--- | :--- | +| **InfosystemLocal** | `172.16.8.8` | Gitea, HashiCorp Vault, Semaphore, Telegram Bot | Debian 12 (Linux 6.17 PVE) | `22` (SSH)
`80` (Gitea)
`8200` (Vault)
`3000` (Semaphore) | `servers/data/server-8-8` | +| **mailguard** | `172.16.8.151` | Архив корпоративной почты ИБ | Debian 12 (Docker) | `22` (SSH)
`80` (Web UI)
`2525` (Ingestion) | `servers/data/server-151` | +| **infosystem-2** | `172.16.8.75` | Портал предприятия Инфосистема 2.0 | Proxmox LXC (Docker) | `22` (SSH)
`8090` (Web)
`8091` (API)
`3307` (MySQL) | `servers/data/server-75` | +| **vm-host01** | `172.16.15.1` | Физический гипервизор KVM | Linux KVM / QEMU | `22` (SSH) | `servers/data/vm-host01` | +| **dc1** | `172.16.8.9` | Primary Domain Controller AD | Windows Server | `53, 88, 389, 445, 5985` (WinRM) | — (WinRM NTLM) | +| **dc2** | `172.16.8.19` | Secondary Domain Controller AD | Windows Server | `53, 88, 389, 445, 5985` (WinRM) | — (WinRM NTLM) | +| **db-dmz-mail-ftp**| `192.168.220.103`| База данных почты и FTP | Linux / MySQL 8 | `22` (SSH), `3306` (MySQL) | `servers/data/mysql-main` | +| **db-corp-web** | `172.16.8.37` | База данных корпоративных сайтов | Linux / MySQL 8 | `22` (SSH), `3306` (MySQL) | `servers/data/mysql-main` | +| **db-cloud-dns** | `192.168.220.22` | База данных Cloud DNS | Linux / MySQL 8 | `22` (SSH), `3306` (MySQL) | `servers/data/mysql-special` | +| **db-it-ops** | `172.16.8.25` | База данных ИТ-операций | Linux / MySQL 8 | `22` (SSH), `3306` (MySQL) | `servers/data/mysql-special` | + +--- + +## 🔑 Мастер-ключ SSH для AI-агентов + +Для автоматического беспарольного доступа root ко всем серверам в Vault сохранен закрытый ключ Ed25519: +* **Путь в Vault**: `servers/data/master-ssh-key` +* **Поле**: `private_key` +* **Публичный ключ**: + ``` + ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIF0rW5m6mvAg+Q9nDXCN6+H8i3w/QjyWLbGSJC3L+/Bw shelyagin_ra@KPP019011 + ``` +Этот ключ прописан в `/root/.ssh/authorized_keys` на серверах инфраструктуры. diff --git a/NETWORK_TOPOLOGY.md.metadata.json b/NETWORK_TOPOLOGY.md.metadata.json new file mode 100644 index 0000000..df091f1 --- /dev/null +++ b/NETWORK_TOPOLOGY.md.metadata.json @@ -0,0 +1,4 @@ +{ + "summary": "Network Topology & Server Infrastructure Map", + "updatedAt": "2026-09-28T10:44:08.877757233Z" +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5b5a6e7 --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# 🏛️ KSP Steel: База знаний инфраструктуры и системный регламент + +Добро пожаловать в центральный репозиторий документации, системных регламентов и архитектурных карт цифровой инфраструктуры **ТОО «KSP Steel»**. + +Этот репозиторий создан как **единая точка входа (Single Source of Truth)** для системных инженеров, специалистов по информационной безопасности и **автономных AI-агентов**. + +--- + +## 🧭 Навигация по документации + +1. 🤖 [**Руководство и протокол безопасности для AI-агентов (`AI_AGENT_PLAYBOOK.md`)**](./AI_AGENT_PLAYBOOK.md) + *Обязательно к прочтению любым AI-ассистентом перед началом работ.* + Правила безопасного внесения изменений («Не сломай ничего»), карта проектов, регламент извлечения секретов из HashiCorp Vault и чеклист валидации. + +2. 🗺️ [**Карта серверов и сетевая топология (`NETWORK_TOPOLOGY.md`)**](./NETWORK_TOPOLOGY.md) + Полный реестр физических и виртуальных серверов, IP-адресов, открытых портов, ролей и операционных систем (`172.16.8.x`, `172.16.15.x`, `192.168.220.x`). + +3. 🛡️ [**Аварийное восстановление и регламент бэкапов (`DISASTER_RECOVERY.md`)**](./DISASTER_RECOVERY.md) + Инструкции по восстановлению каждого сервиса при сбоях (распечатка Vault, базы данных, образы KVM, почтовый архив). + +--- + +## 📦 Реестр ключевых проектов в Gitea + +| Репозиторий | Стек технологий | Сервер / IP | Назначение | +| :--- | :--- | :--- | :--- | +| [**`KSP-Steel/Infosystem`**](http://172.16.8.8/KSP-Steel/Infosystem) | Vue 3, Tailwind, FastAPI, MySQL, Docker | `172.16.8.75` | Главный корпоративный портал предприятия, телеметрия проходных PerCo, интеграция со штатом 1С и Active Directory, дашборды. | +| [**`KSP-Steel/mailguard`**](http://172.16.8.8/KSP-Steel/mailguard) | Python 3, Meilisearch, PostgreSQL, Nginx, Docker | `172.16.8.151` | Платформа службы безопасности (SOC): полнотекстовый архив писем Exchange/Exim (700k+ сообщений), DLP-фильтрация, аудит рисков. | +| [**`KSP-Steel/ansible`**](http://172.16.8.8/KSP-Steel/ansible) | Ansible Core, Semaphore, Python Telegram Bot, WinRM | `172.16.8.8` | Плейбуки регламентных процедур (аудит безопасности AD, онбординг, бэкапы KVM и MySQL, сброс паролей, ChatOps в Telegram). | +| [**`KSP-Steel/hashicorp-vault`**](http://172.16.8.8/KSP-Steel/hashicorp-vault) | HashiCorp Vault, Gitea, PostgreSQL, Docker Compose | `172.16.8.8` | Центральное зашифрованное хранилище учетных данных и паролей серверов. Интегрировано с Ansible через lookup-плагин. | +| [**`admin_ksp/Instruction`**](http://172.16.8.8/admin_ksp/Instruction) | Markdown, Mermaid | `172.16.8.8` | Настоящая центральная база знаний и инструкция для AI-агентов. | + +--- + +## ⚡ Быстрый старт: ключевые точки входа + +* **Git-сервер (Gitea)**: `http://172.16.8.8/` +* **Хранилище секретов (Vault UI)**: `http://172.16.8.8:8200/ui` +* **Панель оркестрации задач (Semaphore UI)**: `http://172.16.8.8:3000/` +* **Почтовый архив ИБ (MailGuard)**: `http://172.16.8.151/` +* **Портал предприятия (Инфосистема 2.0)**: `http://172.16.8.75:8090/` (или доменное имя) diff --git a/README.md.metadata.json b/README.md.metadata.json new file mode 100644 index 0000000..43c2467 --- /dev/null +++ b/README.md.metadata.json @@ -0,0 +1,4 @@ +{ + "summary": "Master Knowledge Base & AI Agent Guide README", + "updatedAt": "2026-09-28T10:41:57.720655921Z" +} \ No newline at end of file