149 lines
8.0 KiB
Markdown
149 lines
8.0 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Основная цель проекта
|
||
|
||
ServerManager — Desktop GUI (CustomTkinter + Paramiko) для управления удалёнными серверами. Создан чтобы **Claude Code мог управлять серверами через глобальный скилл `/ssh`**, зная только алиасы.
|
||
|
||
```
|
||
Claude Code → /ssh investor "uptime" → ssh.py → servers.json (encrypted) → SSH
|
||
↑ ↓
|
||
Видит только alias + команду Пароли остаются локально Результат
|
||
```
|
||
|
||
## БЕЗОПАСНОСТЬ — ГЛАВНЫЙ ПРИНЦИП
|
||
|
||
**Claude НИКОГДА не видит и не должен видеть:**
|
||
- IP-адреса серверов
|
||
- Логины (user)
|
||
- Пароли
|
||
- Порты
|
||
- TOTP-секреты
|
||
|
||
Всё это остаётся в зашифрованном `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
|
||
|
||
## Команды разработки
|
||
|
||
```bash
|
||
# Запуск приложения
|
||
python main.py
|
||
|
||
# Сборка exe (автоматически бампит patch-версию)
|
||
python build.py
|
||
|
||
# Сборка без бампа версии
|
||
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/ # Загрузить файл
|
||
/ssh investor --download /remote/file /local/ # Скачать файл
|
||
/ssh investor --ping # Проверить доступность
|
||
/ssh investor --info # Безопасная информация о сервере (без creds)
|
||
/ssh investor --set-note "описание сервера" # Обновить заметки сервера
|
||
/ssh tor --info # Поиск по ключевому слову (fuzzy search)
|
||
/ssh investor --no-sudo "whoami" # Выполнить без sudo
|
||
```
|
||
|
||
## Версионирование
|
||
|
||
**Автоматическое.** `build.py` инкрементирует patch в `version.py` → `__version__` при каждой сборке.
|
||
|
||
Semver: **MAJOR** (ломающие) | **MINOR** (новая фича) | **PATCH** (автобамп при сборке)
|
||
|
||
Для minor/major бампа — вручную изменить `version.py` перед `python build.py --no-bump`.
|
||
|
||
## Git — коммит и пуш
|
||
|
||
**ОБЯЗАТЕЛЬНО:** После завершения изменений — коммить и пуши:
|
||
```bash
|
||
git add <изменённые файлы>
|
||
git commit -m "vX.Y.Z: описание"
|
||
git push sensey master
|
||
```
|
||
|
||
- Remote: `sensey` (https://git.sensey24.ru/aibot777/server-manager.git)
|
||
- Ветка: `master`
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
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
|
||
```
|
||
|
||
**Ключевые паттерны:**
|
||
- Терминал использует **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
|
||
|
||
## Настройка на новой машине
|
||
|
||
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`
|
||
|
||
Setup устанавливает: `ssh.py` + `encryption.py` → `~/.server-connections/`, скилл `/ssh` → `~/.claude/commands/ssh.md`, SSH-ключ ed25519.
|
||
|
||
## Конфигурация
|
||
|
||
- Серверы: `~/.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/`)
|