aibot777/server-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 36 Wiki Activity

v1.8.25: update CLAUDE.md — full multi-type architecture docs

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
chrome-storm-c442
2026-02-24 09:44:24 -05:00
parent 65a71c4947
commit 1b3fb30680
3 changed files with 107 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

223
CLAUDE.md
View File

@@ -1,159 +1,148 @@
# 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`**, зная только алиасы.
## Поддерживаемые типы серверов
```
Claude Code → /ssh investor "uptime" → ssh.py → servers.json (encrypted) → SSH
↑ ↓
Видит только alias + команду Пароли остаются локально Результат
```
| Тип | Клиент | GUI-табы | CLI-команды |
|-----|--------|----------|-------------|
| ssh | `ssh_client.py` (Paramiko) | Terminal, Files, Info, Keys, 2FA, Setup | `ALIAS "cmd"`, `--upload`, `--download` |
| 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 НИКОГДА не видит и не должен видеть:**
- IP-адреса серверов
- Логины (user)
- Пароли
- Порты
- TOTP-секреты
**Claude НИКОГДА не видит:** IP, логины, пароли, порты, TOTP-секреты. Всё в зашифрованном `servers.json`, скрипт `ssh.py` сам читает credentials.
Всё это остаётся в зашифрованном `servers.json`. Скрипт `ssh.py` сам читает credentials и подключается. Claude работает **только через алиасы**.
**ЗАПРЕЩЕНО:**
- Читать файлы в `~/.server-connections/` напрямую
- Использовать `ssh.py --list-full` (выводит IP/логины) — имеет WARNING
- Добавлять IP/логины/пароли в memory bank, контекст, логи
- Использовать `ssh.py --add` — не показывает user@ip:port, но всё равно безопасность важна
- Для получения информации о сервере использовать `ssh.py --info ALIAS` — безопасно, без credentials
**ЗАПРЕЩЕНО:** читать `~/.server-connections/` напрямую, использовать `--list-full`, добавлять credentials в контекст/логи.
## Команды разработки
```bash
# Запуск приложения
python main.py
# Сборка exe (автоматически бампит patch-версию)
python build.py
# Сборка без бампа версии
python build.py --no-bump
# Очистка артефактов + сборка
python build.py --clean
# Установка зависимостей
pip install -r requirements.txt
python main.py # Запуск
python build.py # Сборка exe (auto-bump patch)
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 — билд → тест → коммит → пуш
**ОБЯЗАТЕЛЬНО** после каждого изменения кода:
1. **Билд** — собрать exe:
1. `python build.py` — собрать exe
2. Запустить exe из `releases/`, убедиться что GUI работает
3. Коммит + пуш:
```bash
python build.py
```
2. **Тест** — запустить exe из `releases/`, убедиться что GUI работает, новые фичи на месте
3. **Коммит + пуш**:
```bash
git add <изменённые файлы> version.py releases/ServerManager-vX.Y.Z-win-x64.exe
git add <файлы> version.py releases/ServerManager-vX.Y.Z-win-x64.exe
git commit -m "vX.Y.Z: описание"
git push sensey master
```
**НЕ коммить без билда и теста.** Новый exe добавляется в `releases/` вместе с кодом. Старые exe периодически чистить — оставлять первый + последние 5.
Старые exe в `releases/` периодически чистить — оставлять первый + последние 5.
- Remote: `sensey` (https://git.sensey24.ru/aibot777/server-manager.git)
- Ветка: `master`
- Remote: `sensey`, ветка: `master`
## Версионирование
`build.py` автоинкрементирует patch в `version.py`. Semver: MAJOR (ломающие) | MINOR (фича) | PATCH (автобамп). Для minor/major — вручную изменить `version.py` перед `build.py --no-bump`.
## Архитектура
```
ServerManager/
├── main.py # Entry point → gui/app.py
├── version.py # __version__ (auto-bumped by build.py)
├── build.py # PyInstaller + auto version bump
├── core/ # Business logic
│ ├── server_store.py # CRUD + encrypted JSON + observer pattern + backups
│ ├── encryption.py # Fernet symmetric encryption
│ ├── ssh_client.py # Paramiko: ShellSession + SFTPSession
│ ├── session_pool.py # LRU session pool (max 5 concurrent)
│ ├── claude_setup.py # Claude Code integration installer
│ ├── status_checker.py # Background monitoring (every 60s)
│ ├── totp.py # TOTP/2FA (pyotp)
│ ├── i18n.py # EN/RU/ZH translations, t(key) API
│ ├── logger.py # Rotating file logger
│ └── connection_factory.py # Connection factory for different protocols
├── gui/ # CustomTkinter UI
│ ├── app.py # Main window: sidebar + tabview
│ ├── sidebar.py # Server list + session indicators + search
│ ├── tabs/ # Terminal, Files, Info, Keys, TOTP, Setup
│ └── widgets/ # TerminalWidget (pyte), FileList, StatusBadge
├── tools/ # CLI tools (installed to ~/.server-connections/)
│ ├── ssh.py # SSH utility for Claude Code
│ └── skill-ssh.md # /ssh skill template
└── releases/ # Built executables
core/ # Бизнес-логика
├── server_store.py # CRUD + encrypted JSON + observer + backups
├── encryption.py # Fernet
├── ssh_client.py # ShellSession + SFTPSession (Paramiko)
├── sql_client.py # MariaDB/MSSQL/PostgreSQL
├── redis_client.py # Redis (SCAN, авто-тип ключей)
├── grafana_client.py # Grafana REST API
├── prometheus_client.py # Prometheus REST API
├── telnet_client.py # Telnet (тот же интерфейс что ShellSession)
├── winrm_client.py # PowerShell/CMD через WinRM
├── remote_desktop.py # RDP/VNC (запуск внешнего клиента)
├── connection_factory.py # Фабрика: тип → клиент (lazy imports)
├── session_pool.py # LRU пул сессий (max 5)
├── status_checker.py # Фоновый мониторинг всех типов
├── i18n.py # EN/RU/ZH, ~300 ключей, t(key) API
├── claude_setup.py # Установщик интеграции Claude Code
├── totp.py # TOTP/2FA
└── logger.py # Rotating file logger
gui/
├── app.py # TAB_REGISTRY + TAB_CLASSES → условные табы по типу
├── sidebar.py # Список серверов + цветные бейджи типов
├── server_dialog.py # Адаптивная форма (поля по типу сервера)
├── 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`
2. `pip install -r requirements.txt`
3. `python main.py` → вкладка Setup → "Install Everything"
4. Добавить серверы через GUI → Claude Code видит их через `/ssh --list`
## Как пользоваться /ssh
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/settings.json`
- Бэкапы: `~/.server-connections/backups/`
- Путь конфига можно сменить через GUI: Setup → Configuration → "Change Path"
## Дополнительная документация
Читай эти файлы **по необходимости**, а не заранее:
- `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/`)
Читай **по необходимости**: `README.md`, `CHANGELOG.md`, `TERMINAL_AUDIT.md`, `plans/`, `tools/skill-ssh.md`.

BIN
releases/ServerManager-v1.8.25-win-x64.exe Normal file
View File

Binary file not shown.

2
version.py
View File

@@ -1,6 +1,6 @@
"""Version info for ServerManager."""
__version__ = "1.8.24"
__version__ = "1.8.25"
__app_name__ = "ServerManager"
__author__ = "aibot777"
__description__ = "Desktop GUI for managing remote servers"