v1.8.25: update CLAUDE.md — full multi-type architecture docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
chrome-storm-c442
223
CLAUDE.md
223
CLAUDE.md
@@ -1,159 +1,148 @@
|
|||||||
# CLAUDE.md
|
# CLAUDE.md
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
## Проект
|
||||||
|
|
||||||
## Основная цель проекта
|
ServerManager — Desktop GUI (CustomTkinter) для управления удалёнными серверами **любых типов**. Claude Code управляет серверами через скилл `/ssh`, зная только алиасы.
|
||||||
|
|
||||||
ServerManager — Desktop GUI (CustomTkinter + Paramiko) для управления удалёнными серверами. Создан чтобы **Claude Code мог управлять серверами через глобальный скилл `/ssh`**, зная только алиасы.
|
## Поддерживаемые типы серверов
|
||||||
|
|
||||||
```
|
| Тип | Клиент | GUI-табы | CLI-команды |
|
||||||
Claude Code → /ssh investor "uptime" → ssh.py → servers.json (encrypted) → SSH
|
|-----|--------|----------|-------------|
|
||||||
↑ ↓
|
| ssh | `ssh_client.py` (Paramiko) | Terminal, Files, Info, Keys, 2FA, Setup | `ALIAS "cmd"`, `--upload`, `--download` |
|
||||||
Видит только alias + команду Пароли остаются локально Результат
|
| telnet | `telnet_client.py` (telnetlib3) | Terminal, Info, Setup | — |
|
||||||
```
|
| mariadb/mssql/postgresql | `sql_client.py` (pymysql/pymssql/psycopg2) | Query, Info, Setup | `--sql`, `--sql-databases`, `--sql-tables` |
|
||||||
|
| redis | `redis_client.py` (redis-py) | Console, Info, Setup | `--redis`, `--redis-info`, `--redis-keys` |
|
||||||
|
| grafana | `grafana_client.py` (requests) | Dashboards, Info, Setup | `--grafana-dashboards`, `--grafana-alerts` |
|
||||||
|
| prometheus | `prometheus_client.py` (requests) | Metrics, Info, Setup | `--prom-query`, `--prom-targets`, `--prom-alerts` |
|
||||||
|
| winrm | `winrm_client.py` (pywinrm) | PowerShell, Info, Setup | `--ps`, `--cmd` |
|
||||||
|
| rdp/vnc | `remote_desktop.py` | Launch, Info, Setup | — (запуск внешнего клиента) |
|
||||||
|
|
||||||
## БЕЗОПАСНОСТЬ — ГЛАВНЫЙ ПРИНЦИП
|
## БЕЗОПАСНОСТЬ
|
||||||
|
|
||||||
**Claude НИКОГДА не видит и не должен видеть:**
|
**Claude НИКОГДА не видит:** IP, логины, пароли, порты, TOTP-секреты. Всё в зашифрованном `servers.json`, скрипт `ssh.py` сам читает credentials.
|
||||||
- IP-адреса серверов
|
|
||||||
- Логины (user)
|
|
||||||
- Пароли
|
|
||||||
- Порты
|
|
||||||
- TOTP-секреты
|
|
||||||
|
|
||||||
Всё это остаётся в зашифрованном `servers.json`. Скрипт `ssh.py` сам читает credentials и подключается. Claude работает **только через алиасы**.
|
**ЗАПРЕЩЕНО:** читать `~/.server-connections/` напрямую, использовать `--list-full`, добавлять credentials в контекст/логи.
|
||||||
|
|
||||||
**ЗАПРЕЩЕНО:**
|
|
||||||
- Читать файлы в `~/.server-connections/` напрямую
|
|
||||||
- Использовать `ssh.py --list-full` (выводит IP/логины) — имеет WARNING
|
|
||||||
- Добавлять IP/логины/пароли в memory bank, контекст, логи
|
|
||||||
- Использовать `ssh.py --add` — не показывает user@ip:port, но всё равно безопасность важна
|
|
||||||
- Для получения информации о сервере использовать `ssh.py --info ALIAS` — безопасно, без credentials
|
|
||||||
|
|
||||||
## Команды разработки
|
## Команды разработки
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Запуск приложения
|
python main.py # Запуск
|
||||||
python main.py
|
python build.py # Сборка exe (auto-bump patch)
|
||||||
|
python build.py --no-bump # Сборка без бампа
|
||||||
# Сборка exe (автоматически бампит patch-версию)
|
python build.py --clean # Очистка + сборка
|
||||||
python build.py
|
pip install -r requirements.txt # Зависимости
|
||||||
|
|
||||||
# Сборка без бампа версии
|
|
||||||
python build.py --no-bump
|
|
||||||
|
|
||||||
# Очистка артефактов + сборка
|
|
||||||
python build.py --clean
|
|
||||||
|
|
||||||
# Установка зависимостей
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Как пользоваться /ssh
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/ssh investor "uptime" # Выполнить команду
|
|
||||||
/ssh main-ovh "systemctl status nginx" # Команда на другом сервере
|
|
||||||
/ssh --list # Список серверов (без паролей) + колонка Notes
|
|
||||||
/ssh --status # Статус всех серверов
|
|
||||||
/ssh investor --upload /local/file /remote/ # Загрузить файл (прогресс >=1MB)
|
|
||||||
/ssh investor --download /remote/file /local/ # Скачать файл (прогресс >=1MB)
|
|
||||||
/ssh investor --ping # Проверить доступность
|
|
||||||
/ssh --info investor # Безопасная информация о сервере (без creds)
|
|
||||||
/ssh --set-note investor "описание сервера" # Обновить заметки сервера
|
|
||||||
/ssh --info tor # Поиск по ключевому слову (fuzzy search)
|
|
||||||
/ssh investor --no-sudo "whoami" # Выполнить без sudo
|
|
||||||
/ssh investor --install-key # Установить SSH-ключ на сервер
|
|
||||||
/ssh --remove investor # Удалить сервер (спросит подтверждение)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Версионирование
|
|
||||||
|
|
||||||
**Автоматическое.** `build.py` инкрементирует patch в `version.py` → `__version__` при каждой сборке.
|
|
||||||
|
|
||||||
Semver: **MAJOR** (ломающие) | **MINOR** (новая фича) | **PATCH** (автобамп при сборке)
|
|
||||||
|
|
||||||
Для minor/major бампа — вручную изменить `version.py` перед `python build.py --no-bump`.
|
|
||||||
|
|
||||||
## Workflow — билд → тест → коммит → пуш
|
## Workflow — билд → тест → коммит → пуш
|
||||||
|
|
||||||
**ОБЯЗАТЕЛЬНО** после каждого изменения кода:
|
**ОБЯЗАТЕЛЬНО** после каждого изменения кода:
|
||||||
|
|
||||||
1. **Билд** — собрать exe:
|
1. `python build.py` — собрать exe
|
||||||
|
2. Запустить exe из `releases/`, убедиться что GUI работает
|
||||||
|
3. Коммит + пуш:
|
||||||
```bash
|
```bash
|
||||||
python build.py
|
git add <файлы> version.py releases/ServerManager-vX.Y.Z-win-x64.exe
|
||||||
```
|
|
||||||
2. **Тест** — запустить exe из `releases/`, убедиться что GUI работает, новые фичи на месте
|
|
||||||
3. **Коммит + пуш**:
|
|
||||||
```bash
|
|
||||||
git add <изменённые файлы> version.py releases/ServerManager-vX.Y.Z-win-x64.exe
|
|
||||||
git commit -m "vX.Y.Z: описание"
|
git commit -m "vX.Y.Z: описание"
|
||||||
git push sensey master
|
git push sensey master
|
||||||
```
|
```
|
||||||
|
|
||||||
**НЕ коммить без билда и теста.** Новый exe добавляется в `releases/` вместе с кодом. Старые exe периодически чистить — оставлять первый + последние 5.
|
Старые exe в `releases/` периодически чистить — оставлять первый + последние 5.
|
||||||
|
|
||||||
- Remote: `sensey` (https://git.sensey24.ru/aibot777/server-manager.git)
|
- Remote: `sensey`, ветка: `master`
|
||||||
- Ветка: `master`
|
|
||||||
|
## Версионирование
|
||||||
|
|
||||||
|
`build.py` автоинкрементирует patch в `version.py`. Semver: MAJOR (ломающие) | MINOR (фича) | PATCH (автобамп). Для minor/major — вручную изменить `version.py` перед `build.py --no-bump`.
|
||||||
|
|
||||||
## Архитектура
|
## Архитектура
|
||||||
|
|
||||||
```
|
```
|
||||||
ServerManager/
|
core/ # Бизнес-логика
|
||||||
├── main.py # Entry point → gui/app.py
|
├── server_store.py # CRUD + encrypted JSON + observer + backups
|
||||||
├── version.py # __version__ (auto-bumped by build.py)
|
├── encryption.py # Fernet
|
||||||
├── build.py # PyInstaller + auto version bump
|
├── ssh_client.py # ShellSession + SFTPSession (Paramiko)
|
||||||
├── core/ # Business logic
|
├── sql_client.py # MariaDB/MSSQL/PostgreSQL
|
||||||
│ ├── server_store.py # CRUD + encrypted JSON + observer pattern + backups
|
├── redis_client.py # Redis (SCAN, авто-тип ключей)
|
||||||
│ ├── encryption.py # Fernet symmetric encryption
|
├── grafana_client.py # Grafana REST API
|
||||||
│ ├── ssh_client.py # Paramiko: ShellSession + SFTPSession
|
├── prometheus_client.py # Prometheus REST API
|
||||||
│ ├── session_pool.py # LRU session pool (max 5 concurrent)
|
├── telnet_client.py # Telnet (тот же интерфейс что ShellSession)
|
||||||
│ ├── claude_setup.py # Claude Code integration installer
|
├── winrm_client.py # PowerShell/CMD через WinRM
|
||||||
│ ├── status_checker.py # Background monitoring (every 60s)
|
├── remote_desktop.py # RDP/VNC (запуск внешнего клиента)
|
||||||
│ ├── totp.py # TOTP/2FA (pyotp)
|
├── connection_factory.py # Фабрика: тип → клиент (lazy imports)
|
||||||
│ ├── i18n.py # EN/RU/ZH translations, t(key) API
|
├── session_pool.py # LRU пул сессий (max 5)
|
||||||
│ ├── logger.py # Rotating file logger
|
├── status_checker.py # Фоновый мониторинг всех типов
|
||||||
│ └── connection_factory.py # Connection factory for different protocols
|
├── i18n.py # EN/RU/ZH, ~300 ключей, t(key) API
|
||||||
├── gui/ # CustomTkinter UI
|
├── claude_setup.py # Установщик интеграции Claude Code
|
||||||
│ ├── app.py # Main window: sidebar + tabview
|
├── totp.py # TOTP/2FA
|
||||||
│ ├── sidebar.py # Server list + session indicators + search
|
└── logger.py # Rotating file logger
|
||||||
│ ├── tabs/ # Terminal, Files, Info, Keys, TOTP, Setup
|
|
||||||
│ └── widgets/ # TerminalWidget (pyte), FileList, StatusBadge
|
gui/
|
||||||
├── tools/ # CLI tools (installed to ~/.server-connections/)
|
├── app.py # TAB_REGISTRY + TAB_CLASSES → условные табы по типу
|
||||||
│ ├── ssh.py # SSH utility for Claude Code
|
├── sidebar.py # Список серверов + цветные бейджи типов
|
||||||
│ └── skill-ssh.md # /ssh skill template
|
├── server_dialog.py # Адаптивная форма (поля по типу сервера)
|
||||||
└── releases/ # Built executables
|
├── tabs/
|
||||||
|
│ ├── terminal_tab.py # SSH + Telnet терминал (pyte)
|
||||||
|
│ ├── files_tab.py # SFTP файл-менеджер
|
||||||
|
│ ├── query_tab.py # SQL-редактор + Treeview + Export CSV
|
||||||
|
│ ├── redis_tab.py # Redis-консоль + история
|
||||||
|
│ ├── grafana_tab.py # Дашборды + алерты
|
||||||
|
│ ├── prometheus_tab.py # PromQL + targets
|
||||||
|
│ ├── powershell_tab.py # PS/CMD (WinRM)
|
||||||
|
│ ├── launch_tab.py # RDP/VNC кнопка Connect
|
||||||
|
│ ├── info_tab.py # Инфо (адаптивные поля по типу)
|
||||||
|
│ ├── keys_tab.py, totp_tab.py, setup_tab.py
|
||||||
|
│ └── ...
|
||||||
|
└── widgets/ # TerminalWidget, StatusBadge, FileList
|
||||||
|
|
||||||
|
tools/
|
||||||
|
├── ssh.py # CLI для Claude Code (все типы серверов)
|
||||||
|
└── skill-ssh.md # Шаблон скилла /ssh
|
||||||
```
|
```
|
||||||
|
|
||||||
**Ключевые паттерны:**
|
## Ключевые паттерны
|
||||||
- Терминал использует **pyte** для эмуляции VT-терминала поверх tkinter Text виджета
|
|
||||||
- **Session pool** — сессии живут при переключении серверов, буфер сохраняется через pickle
|
|
||||||
- **Auto-sudo** — детекция `[sudo] password for` в выводе, автоматическая отправка пароля через stdin
|
|
||||||
- **Keyboard layout independent** — Ctrl+C/V/D/L/Z работают через keycode, не зависят от раскладки
|
|
||||||
- GUI общается с `ServerStore` через observer pattern — изменения в хранилище автоматически обновляют UI
|
|
||||||
|
|
||||||
## Настройка на новой машине
|
- **Duck typing** — все клиенты реализуют `connect/disconnect/check_connection` по соглашению, без ABC
|
||||||
|
- **Lazy imports** — отсутствие pymysql/redis/etc не ломает приложение
|
||||||
|
- **TAB_REGISTRY** — `gui/app.py` перестраивает табы при смене типа сервера
|
||||||
|
- **Observer** — `ServerStore` → UI обновляется автоматически
|
||||||
|
- **Session pool** — SSH-сессии живут при переключении серверов
|
||||||
|
- **Auto-sudo** — детекция `[sudo] password for`, автоотправка пароля
|
||||||
|
- **i18n** — все строки через `t(key)`, 3 языка
|
||||||
|
|
||||||
1. `git clone https://git.sensey24.ru/aibot777/server-manager.git`
|
## Как пользоваться /ssh
|
||||||
2. `pip install -r requirements.txt`
|
|
||||||
3. `python main.py` → вкладка Setup → "Install Everything"
|
|
||||||
4. Добавить серверы через GUI → Claude Code видит их через `/ssh --list`
|
|
||||||
|
|
||||||
Setup устанавливает: `ssh.py` + `encryption.py` → `~/.server-connections/`, скилл `/ssh` → `~/.claude/commands/ssh.md`, SSH-ключ ed25519.
|
```bash
|
||||||
|
# SSH
|
||||||
|
/ssh ALIAS "command" # Выполнить команду
|
||||||
|
/ssh ALIAS --upload local remote # SFTP upload
|
||||||
|
/ssh ALIAS --download remote local # SFTP download
|
||||||
|
# SQL
|
||||||
|
/ssh --sql ALIAS "SELECT * FROM t" # SQL-запрос
|
||||||
|
/ssh --sql-databases ALIAS # Список БД
|
||||||
|
/ssh --sql-tables ALIAS [db] # Список таблиц
|
||||||
|
# Redis
|
||||||
|
/ssh --redis ALIAS "GET key" # Redis-команда
|
||||||
|
/ssh --redis-info ALIAS # Redis INFO
|
||||||
|
/ssh --redis-keys ALIAS "pattern" # SCAN ключей
|
||||||
|
# Grafana / Prometheus
|
||||||
|
/ssh --grafana-dashboards ALIAS # Дашборды
|
||||||
|
/ssh --prom-query ALIAS "up" # PromQL
|
||||||
|
/ssh --prom-targets ALIAS # Targets
|
||||||
|
# WinRM
|
||||||
|
/ssh --ps ALIAS "Get-Process" # PowerShell
|
||||||
|
/ssh --cmd ALIAS "dir" # CMD
|
||||||
|
# Общие
|
||||||
|
/ssh --list # Все серверы
|
||||||
|
/ssh --info ALIAS # Инфо (без creds)
|
||||||
|
/ssh --status # Online/offline
|
||||||
|
```
|
||||||
|
|
||||||
## Конфигурация
|
## Конфигурация
|
||||||
|
|
||||||
- Серверы: `~/.server-connections/servers.json` (Fernet-encrypted)
|
- Серверы: `~/.server-connections/servers.json` (Fernet-encrypted)
|
||||||
- Настройки: `~/.server-connections/settings.json`
|
- Настройки: `~/.server-connections/settings.json`
|
||||||
- Бэкапы: `~/.server-connections/backups/`
|
- Бэкапы: `~/.server-connections/backups/`
|
||||||
- Путь конфига можно сменить через GUI: Setup → Configuration → "Change Path"
|
|
||||||
|
|
||||||
## Дополнительная документация
|
## Дополнительная документация
|
||||||
|
|
||||||
Читай эти файлы **по необходимости**, а не заранее:
|
Читай **по необходимости**: `README.md`, `CHANGELOG.md`, `TERMINAL_AUDIT.md`, `plans/`, `tools/skill-ssh.md`.
|
||||||
|
|
||||||
- `README.md` — полное описание фич, установка, использование (EN/RU/ZH)
|
|
||||||
- `CHANGELOG.md` — история изменений по версиям
|
|
||||||
- `TERMINAL_AUDIT.md` — аудит терминала: что сделано/не сделано для TUI-совместимости (pyte, 256-color, alternate screen и т.д.)
|
|
||||||
- `plans/` — планы реализации конкретных фич (шифрование, TOTP, undo и др.)
|
|
||||||
- `tools/skill-ssh.md` — шаблон скилла `/ssh` (устанавливается в `~/.claude/commands/`)
|
|
||||||
|
|||||||
BIN
releases/ServerManager-v1.8.25-win-x64.exe
Normal file
BIN
releases/ServerManager-v1.8.25-win-x64.exe
Normal file
Binary file not shown.
@@ -1,6 +1,6 @@
|
|||||||
"""Version info for ServerManager."""
|
"""Version info for ServerManager."""
|
||||||
|
|
||||||
__version__ = "1.8.24"
|
__version__ = "1.8.25"
|
||||||
__app_name__ = "ServerManager"
|
__app_name__ = "ServerManager"
|
||||||
__author__ = "aibot777"
|
__author__ = "aibot777"
|
||||||
__description__ = "Desktop GUI for managing remote servers"
|
__description__ = "Desktop GUI for managing remote servers"
|
||||||
|
|||||||
Reference in New Issue
Block a user