admin_ksp/Instruction
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete enterprise architecture map, AI agent playbook and disaster recovery guides

Browse Source
This commit is contained in:
Shelyagin Roman
2026-09-28 15:44:45 +05:00
commit b46a9c1dd2
8 changed files with 370 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AI_AGENT_PLAYBOOK.md
+168
View File
@@ -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 <service>
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
journalctl -u <service> -n 50 --no-pager
```
3. **Обязательная валидация синтаксиса до перезапуска**:
- Nginx: `nginx -t`
- Docker Compose: `docker compose config`
- Python: `python3 -m py_compile <script.py>`
- Ansible: `ansible-playbook --syntax-check <playbook.yaml>`
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>` автоматически подставляет 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.
AI_AGENT_PLAYBOOK.md.metadata.json
+4
View File
@@ -0,0 +1,4 @@
{
"summary": "AI Agent Operational Playbook and Safety Protocol",
"updatedAt": "2026-09-28T10:42:09.419989309Z"
}
DISASTER_RECOVERY.md
+86
View File
@@ -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_<TIMESTAMP>.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/`
DISASTER_RECOVERY.md.metadata.json
+4
View File
@@ -0,0 +1,4 @@
{
"summary": "Disaster Recovery and Backup Procedures",
"updatedAt": "2026-09-28T10:44:14.990392137Z"
}
NETWORK_TOPOLOGY.md
+59
View File
@@ -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)<br>`80` (Gitea)<br>`8200` (Vault)<br>`3000` (Semaphore) | `servers/data/server-8-8` |
| **mailguard** | `172.16.8.151` | Архив корпоративной почты ИБ | Debian 12 (Docker) | `22` (SSH)<br>`80` (Web UI)<br>`2525` (Ingestion) | `servers/data/server-151` |
| **infosystem-2** | `172.16.8.75` | Портал предприятия Инфосистема 2.0 | Proxmox LXC (Docker) | `22` (SSH)<br>`8090` (Web)<br>`8091` (API)<br>`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` на серверах инфраструктуры.
NETWORK_TOPOLOGY.md.metadata.json
+4
View File
@@ -0,0 +1,4 @@
{
"summary": "Network Topology & Server Infrastructure Map",
"updatedAt": "2026-09-28T10:44:08.877757233Z"
}
README.md
+41
View File
@@ -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/` (или доменное имя)
README.md.metadata.json
+4
View File
@@ -0,0 +1,4 @@
{
"summary": "Master Knowledge Base & AI Agent Guide README",
"updatedAt": "2026-09-28T10:41:57.720655921Z"
}