Документация: README.md, ARCHITECTURE.md, DEPLOY.md, .github/copilot-instructions.md

2026-07-12 08:37:51 +04:00
parent 7a005f7b06
commit 0707d53b37
4 changed files with 591 additions and 0 deletions
@@ -0,0 +1,139 @@
+# Деплой, ВМ и переменные окружения
+
+---
+
+## Платформа
+
+**Штурвал** — Managed Flask на pythonk8s (Kubernetes).
+
+- Запускает Flask **сам** — без Dockerfile, без gunicorn
+- Точка входа: `site/app.py` → глобальная переменная `app`
+- Деплой: `git push origin master` → авто-деплой через UI Штурвала
+
+---
+
+## Деплой
+
+```bash
+cd /home/naeel/nubes/drhider
+git add -A
+git commit -m "описание изменений"
+git push origin master
+```
+
+После пуша — зайти в UI Штурвала и нажать ** Redeploy** для `drhider`.
+
+---
+
+## Переменные окружения (настраиваются в UI Штурвала)
+
+| Переменная | Значение | Для чего |
+|---|---|---|
+| `LLM_API_KEY` | `sk-ucI5YvOticoOQ9Kuj5K9mQ` | Ключ доступа к LLM API |
+| `LLM_URL` | `https://api.aillm.ru/v1/chat/completions` | URL LLM API |
+| `LLM_MODEL` | `gpt-oss-120b` | Модель для NER |
+
+Без `LLM_API_KEY` LLM-сканирование не работает (только regex).
+
+---
+
+## ВМ contracts (legacy)
+
+Старый сервер contracts.kube5s.ru. DrHider там — standalone HTTP-сервер на порту 8767.
+
+### SSH
+
+```bash
+ssh -i ~/.ssh/naeel_vm_id_ed25519 naeel@5.172.178.213
+```
+
+### Где лежит старый drhider
+
+```
+/home/naeel/contracts/drhider/
+├── drhider.py           # Ядро обфускации (отсюда скопировано в этот проект)
+├── drhider_server.py    # HTTP-сервер :8767 (НЕ ИСПОЛЬЗУЕТСЯ в новом проекте)
+└── __init__.py
+```
+
+### Сервисы на ВМ
+
+| Сервис | Порт | systemd unit |
+|---|---|---|
+| drhider | 8767 | `contracts-drhider` |
+| convert_server | 8766 | `contracts` |
+| Flask UI | 5001 | — (start.sh) |
+| nginx | 443 | `nginx` |
+| PostgreSQL | 5432 | — |
+
+### Управление drhider на ВМ
+
+```bash
+# Статус
+systemctl status contracts-drhider
+
+# Логи
+journalctl -u contracts-drhider -f
+
+# Перезапуск
+sudo systemctl restart contracts-drhider
+```
+
+---
+
+## Локальная разработка
+
+```bash
+cd /home/naeel/nubes/drhider
+
+# Установка зависимостей
+pip install -r requirements.txt
+
+# Запуск Flask (dev-сервер)
+cd site && python3 app.py
+
+# Проверка синтаксиса ВСЕХ файлов
+python3 -c "
+import py_compile, os
+for root, dirs, files in os.walk('.'):
+    for f in files:
+        if f.endswith('.py'):
+            path = os.path.join(root, f)
+            py_compile.compile(path, doraise=True)
+            print(f'OK: {path}')
+"
+
+# Проверка импорта
+python3 -c "from drhider import obfuscate_files, LLMClient; print('OK')"
+```
+
+---
+
+## Как править код
+
+1. Понять что меняем → **описать план**
+2. Получить **«делай»**
+3. Внести изменения
+4. `python3 -c "import py_compile; py_compile.compile('файл.py', doraise=True)"` — КАЖДЫЙ изменённый .py
+5. `python3 -c "from drhider import obfuscate_files, LLMClient"` — проверка импорта
+6. `git add -A && git commit -m "подробно что и зачем" && git push`
+7. Записать в `History/` что сделано
+8. Зайти в UI Штурвала → Redeploy
+
+---
+
+## Как добавить новый генератор
+
+1. Создать `drhider/generators/новый_тип.py` с функцией `generate_xxx(original: str) -> str`
+2. Добавить regex-паттерн в `drhider/config.py` → `ENTITY_PATTERNS`
+3. Добавить импорт и маппинг в `drhider/generators/__init__.py` → `ENTITY_GENERATORS`
+4. Проверить синтаксис → commit → push → Redeploy
+
+---
+
+## История версий
+
+| Версия | Дата | Что |
+|---|---|---|
+| 2.0.0 | 2026-07-12 | Модульный рефакторинг (22 модуля вместо монолита) |
+| 1.0.0 | 2026-07-11 | Начальная версия (monolith drhider.py + Flask) |