2d1d942ddc
- Fix --info/--set-note syntax in CLAUDE.md (global flags, not per-alias) - Add --remove, --install-key to CLAUDE.md examples - Replace minimal fallback skill generator with full version (security rules, all commands, progress, SFTP double-slash) - Add upload/download progress reporting to skill-ssh.md and README - Fix outdated v1.5.4 version in README build examples Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
491 lines
22 KiB
Markdown
491 lines
22 KiB
Markdown
# ServerManager
|
||
|
||
<p align="center">
|
||
<strong>Desktop GUI for managing remote servers</strong><br>
|
||
CustomTkinter + Paramiko | Dark Theme | Claude Code Integration
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="#english">English</a> |
|
||
<a href="#русский">Русский</a> |
|
||
<a href="#中文">中文</a>
|
||
</p>
|
||
|
||
---
|
||
|
||
## English
|
||
|
||
### Features
|
||
|
||
- **Server CRUD** — add, edit, delete servers (SSH, Telnet, RDP, MariaDB, MSSQL, PostgreSQL)
|
||
- **SSH Terminal** — execute commands with auto-sudo (password via stdin, invisible in `ps`)
|
||
- **SFTP Transfer** — upload/download files with progress bar
|
||
- **SSH Keys** — generate ed25519, install on server, copy to clipboard
|
||
- **Status Monitor** — background check every 60 sec (online/offline badges)
|
||
- **Claude Code Integration** — one-click setup, shared config with `/ssh` skill
|
||
- **TOTP / 2FA** — Google Authenticator compatible codes with live countdown, one-click copy
|
||
- **Encryption** — servers.json encrypted with Fernet (passwords never stored in plaintext)
|
||
- **Backups** — manual and automatic backups with one-click restore
|
||
- **Configurable Config Path** — change servers.json location via GUI
|
||
- **Localization** — GUI in English, Russian, Chinese with language switcher
|
||
- **About Dialog** — app info, features, quick start guide
|
||
- **Dark Theme** — modern CustomTkinter interface
|
||
|
||
### Installation
|
||
|
||
#### From source
|
||
```bash
|
||
git clone https://git.sensey24.ru/aibot777/server-manager.git
|
||
cd server-manager
|
||
pip install -r requirements.txt
|
||
python main.py
|
||
```
|
||
|
||
#### Pre-built binary
|
||
Download from [`releases/`](releases/) folder — standalone `.exe` (Windows) or binary (Linux/Mac).
|
||
No Python installation required.
|
||
|
||
### Building
|
||
|
||
Build for your current platform:
|
||
```bash
|
||
pip install pyinstaller
|
||
python build.py
|
||
```
|
||
|
||
Output goes to `releases/ServerManager-vX.Y.Z-{platform}.exe`
|
||
|
||
### Usage
|
||
|
||
1. **Launch** — `python main.py` or run the executable
|
||
2. **Add server** — click "+ Add" in sidebar, fill alias, IP, port, user, password, type
|
||
3. **Terminal** — select server → Terminal tab → type command → Run
|
||
4. **Files** — select server → Files tab → set paths → Upload/Download
|
||
5. **Keys** — Keys tab → Generate Key → Install on Server
|
||
6. **Setup** — Setup tab → "Install Everything" → Claude Code ready
|
||
7. Status badges update automatically (green = online, red = offline)
|
||
|
||
### Claude Code Integration
|
||
|
||
ServerManager and Claude Code share the same config file: `~/.server-connections/servers.json`
|
||
|
||
**How it works:**
|
||
```
|
||
ServerManager GUI ←→ ~/.server-connections/servers.json ←→ ssh.py (Claude Code)
|
||
↕ ↕
|
||
Add/edit/delete /ssh skill
|
||
servers in GUI executes commands
|
||
```
|
||
|
||
- Add a server in GUI → Claude Code sees it immediately via `/ssh list`
|
||
- Both use the same `ssh.py` + `servers.json`
|
||
- Passwords **never** pass through the AI API
|
||
|
||
**New SSH Commands:**
|
||
- `ssh.py --info ALIAS` — safe server information (no credentials)
|
||
- `ssh.py --set-note ALIAS "desc"` — update server notes
|
||
- `ssh.py --list` now shows Notes column
|
||
- Fuzzy alias search: search by keyword (e.g., "tor" finds "API TOR contabo..."), word-boundary priority
|
||
- SFTP path fix: remote path normalization for Windows/Git Bash with double slash //
|
||
- `--no-sudo` flag for commands that don't need elevation
|
||
- Upload/download progress: files >=1MB show 25/50/75% milestones with size, time, and speed
|
||
|
||
**Setup on a new machine:**
|
||
1. Install ServerManager (clone repo or download binary)
|
||
2. Open Setup tab → click "Install Everything"
|
||
3. Done. Claude Code now has `/ssh` skill and access to your servers
|
||
|
||
The Setup tab installs:
|
||
- `ssh.py` → `~/.server-connections/` (SSH utility)
|
||
- `encryption.py` → `~/.server-connections/` (encryption module for CLI)
|
||
- `/ssh` skill → `~/.claude/commands/ssh.md` (Claude Code skill)
|
||
- SSH key (ed25519) — if not exists
|
||
- Checks for duplicates — safe to run multiple times
|
||
|
||
### Configuration
|
||
|
||
Shared config location: `~/.server-connections/servers.json` (encrypted with Fernet).
|
||
|
||
The config path can be changed via Setup tab → Configuration → "Change Path".
|
||
|
||
Settings are stored in `~/.server-connections/settings.json`.
|
||
|
||
**Backups:**
|
||
- Automatic backups every 10 minutes (on save)
|
||
- Manual backup via Setup tab → "Backup Now"
|
||
- Restore from any backup via dropdown + "Restore"
|
||
- Backups stored in `~/.server-connections/backups/`
|
||
- Pre-encryption backup created automatically on first migration
|
||
|
||
### Auto-sudo
|
||
|
||
The app automatically handles privilege escalation:
|
||
|
||
- If `user: "root"` — commands execute directly, no sudo needed
|
||
- If `user` is non-root — the app automatically wraps the command in `sudo -S` and feeds the password from `servers.json` via stdin
|
||
- The password is **never** passed as a command-line argument (invisible in `ps aux`)
|
||
- You just type the command (e.g. `systemctl restart nginx`) — the app decides whether sudo is needed and handles it
|
||
- In the GUI terminal, the "sudo" checkbox is enabled by default for non-root users; uncheck it for commands that don't need elevation
|
||
|
||
```
|
||
You type: systemctl restart nginx
|
||
App executes: sudo -S -p '' bash -c 'systemctl restart nginx'
|
||
(password fed automatically via stdin from servers.json)
|
||
```
|
||
|
||
### Security
|
||
|
||
- `servers.json` is **encrypted** (Fernet symmetric encryption) — passwords not readable in plaintext
|
||
- `servers.json` is in `.gitignore` — never committed
|
||
- Passwords stored locally only, **never sent to any AI/API**
|
||
- SSH keys (ed25519) — recommended auth method
|
||
- sudo password sent via stdin (not visible in process list)
|
||
- When used with Claude Code: only alias + command are passed through the AI API, passwords stay in the local encrypted file
|
||
- Automatic pre-encryption backup on first migration
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
ServerManager/
|
||
├── main.py # Entry point
|
||
├── version.py # Version info
|
||
├── build.py # PyInstaller build script
|
||
├── core/ # Business logic
|
||
│ ├── server_store.py # CRUD + encrypted JSON + observer + backups
|
||
│ ├── encryption.py # Fernet encryption module
|
||
│ ├── ssh_client.py # Paramiko SSH/SFTP wrapper
|
||
│ ├── claude_setup.py # Claude Code integration installer
|
||
│ ├── status_checker.py # Background monitoring
|
||
│ ├── totp.py # TOTP/2FA module (pyotp)
|
||
│ ├── logger.py # Rotating file logger
|
||
│ └── connection_factory.py
|
||
├── gui/ # CustomTkinter UI
|
||
│ ├── app.py # Main window
|
||
│ ├── sidebar.py # Server list + search
|
||
│ ├── server_dialog.py # Add/Edit modal
|
||
│ ├── tabs/ # Terminal, Files, Info, Keys, Setup
|
||
│ └── widgets/ # StatusBadge
|
||
├── tools/ # CLI tools (installed to ~/.server-connections/)
|
||
│ ├── ssh.py # SSH utility for Claude Code
|
||
│ └── skill-ssh.md # /ssh skill template
|
||
├── config/ # Example configs
|
||
├── releases/ # Built executables
|
||
└── README.md # This file (EN/RU/ZH)
|
||
```
|
||
|
||
### Deploy on a new machine
|
||
|
||
```bash
|
||
# 1. Clone
|
||
git clone https://git.sensey24.ru/aibot777/server-manager.git
|
||
cd server-manager
|
||
|
||
# 2. Install deps
|
||
pip install -r requirements.txt
|
||
|
||
# 3. Launch and setup
|
||
python main.py
|
||
# → Setup tab → Install Everything
|
||
# → Add your servers via + Add
|
||
# → Done! Both GUI and Claude Code are ready
|
||
```
|
||
|
||
---
|
||
|
||
## Русский
|
||
|
||
### Возможности
|
||
|
||
- **Управление серверами** — добавление, редактирование, удаление (SSH, Telnet, RDP, MariaDB, MSSQL, PostgreSQL)
|
||
- **SSH-терминал** — выполнение команд с авто-sudo (пароль через stdin, не виден в `ps`)
|
||
- **SFTP** — загрузка и скачивание файлов с прогресс-баром
|
||
- **SSH-ключи** — генерация ed25519, установка на сервер, копирование
|
||
- **Мониторинг** — фоновая проверка каждые 60 сек (бейджи online/offline)
|
||
- **Интеграция с Claude Code** — установка в один клик, общий конфиг со скиллом `/ssh`
|
||
- **TOTP / 2FA** — коды Google Authenticator с обратным отсчётом, копирование в один клик
|
||
- **Шифрование** — servers.json зашифрован Fernet (пароли не хранятся в открытом виде)
|
||
- **Бэкапы** — ручные и автоматические с восстановлением в один клик
|
||
- **Настраиваемый путь конфига** — смена расположения servers.json через GUI
|
||
- **Локализация** — интерфейс на английском, русском, китайском с переключателем
|
||
- **О программе** — информация о приложении, возможности, быстрый старт
|
||
- **Тёмная тема** — современный интерфейс CustomTkinter
|
||
|
||
### Установка
|
||
|
||
#### Из исходников
|
||
```bash
|
||
git clone https://git.sensey24.ru/aibot777/server-manager.git
|
||
cd server-manager
|
||
pip install -r requirements.txt
|
||
python main.py
|
||
```
|
||
|
||
#### Готовый бинарник
|
||
Скачайте из папки [`releases/`](releases/) — автономный `.exe` (Windows) или бинарник (Linux/Mac).
|
||
Python не требуется.
|
||
|
||
### Сборка
|
||
|
||
Сборка под текущую платформу:
|
||
```bash
|
||
pip install pyinstaller
|
||
python build.py
|
||
```
|
||
|
||
Результат в `releases/ServerManager-vX.Y.Z-{платформа}.exe`
|
||
|
||
### Использование
|
||
|
||
1. **Запуск** — `python main.py` или запустите скомпилированный файл
|
||
2. **Добавить сервер** — нажмите "+ Add" в боковой панели, заполните alias, IP, порт, пользователь, пароль, тип
|
||
3. **Терминал** — выберите сервер → вкладка Terminal → введите команду → Run
|
||
4. **Файлы** — выберите сервер → вкладка Files → укажите пути → Upload/Download
|
||
5. **Ключи** — вкладка Keys → Generate Key → Install on Server
|
||
6. **Настройка Claude** — вкладка Setup → "Install Everything" → Claude Code готов
|
||
7. Бейджи статуса обновляются автоматически (зелёный = online, красный = offline)
|
||
|
||
### Интеграция с Claude Code
|
||
|
||
ServerManager и Claude Code используют **один и тот же файл конфигурации**: `~/.server-connections/servers.json`
|
||
|
||
**Как это работает:**
|
||
```
|
||
ServerManager GUI ←→ ~/.server-connections/servers.json ←→ ssh.py (Claude Code)
|
||
↕ ↕
|
||
Добавил/изменил скилл /ssh
|
||
сервер в GUI выполняет команды
|
||
```
|
||
|
||
- Добавил сервер в GUI → Claude Code сразу видит его через `/ssh list`
|
||
- Оба используют один `ssh.py` + `servers.json`
|
||
- Пароли **никогда** не проходят через API нейронки
|
||
|
||
**Новые SSH команды:**
|
||
- `ssh.py --info ALIAS` — безопасная информация о сервере (без учетных данных)
|
||
- `ssh.py --set-note ALIAS "desc"` — обновление заметок сервера
|
||
- `ssh.py --list` теперь показывает колонку Notes
|
||
- Нечеткий поиск по алиасу: поиск по ключевому слову (например, "tor" находит "API TOR contabo..."), приоритет границ слова
|
||
- Исправление пути SFTP: нормализация удаленного пути для Windows/Git Bash с двойным слешем //
|
||
- Флаг `--no-sudo` для команд, не требующих повышения привилегий
|
||
- Прогресс upload/download: файлы >=1MB показывают 25/50/75% с размером, временем и скоростью
|
||
|
||
**Настройка на новой машине:**
|
||
1. Установить ServerManager (клонировать репо или скачать бинарник)
|
||
2. Открыть вкладку Setup → нажать "Install Everything"
|
||
3. Готово. Claude Code теперь имеет скилл `/ssh` и доступ к серверам
|
||
|
||
Вкладка Setup устанавливает:
|
||
- `ssh.py` → `~/.server-connections/` (SSH-утилита)
|
||
- `encryption.py` → `~/.server-connections/` (модуль шифрования для CLI)
|
||
- скилл `/ssh` → `~/.claude/commands/ssh.md` (скилл Claude Code)
|
||
- SSH-ключ (ed25519) — если ещё не создан
|
||
- Проверяет дубли — безопасно запускать повторно
|
||
|
||
### Конфигурация
|
||
|
||
Общий конфиг: `~/.server-connections/servers.json` (зашифрован Fernet).
|
||
|
||
Путь к конфигу можно изменить: вкладка Setup → Configuration → "Change Path".
|
||
|
||
Настройки хранятся в `~/.server-connections/settings.json`.
|
||
|
||
**Бэкапы:**
|
||
- Автоматические бэкапы каждые 10 минут (при сохранении)
|
||
- Ручной бэкап: вкладка Setup → "Backup Now"
|
||
- Восстановление из любого бэкапа через dropdown + "Restore"
|
||
- Бэкапы хранятся в `~/.server-connections/backups/`
|
||
- Пред-шифровальный бэкап создаётся автоматически при первой миграции
|
||
|
||
### Авто-sudo
|
||
|
||
Приложение автоматически повышает привилегии:
|
||
|
||
- Если `user: "root"` — команды выполняются напрямую, sudo не нужен
|
||
- Если пользователь не root — приложение автоматически оборачивает команду в `sudo -S` и само вводит пароль из `servers.json` через stdin
|
||
- Пароль **никогда** не передаётся как аргумент командной строки (не виден в `ps aux`)
|
||
- Вы просто вводите команду (например `systemctl restart nginx`) — приложение само решает, нужен sudo или нет, и само всё делает
|
||
- В GUI-терминале checkbox "sudo" включён по умолчанию для non-root; отключите для команд, не требующих повышения
|
||
|
||
```
|
||
Вы вводите: systemctl restart nginx
|
||
Приложение делает: sudo -S -p '' bash -c 'systemctl restart nginx'
|
||
(пароль подставляется автоматически из servers.json через stdin)
|
||
```
|
||
|
||
### Безопасность
|
||
|
||
- `servers.json` **зашифрован** (Fernet симметричное шифрование) — пароли не читаемы в открытом виде
|
||
- `servers.json` в `.gitignore` — никогда не коммитится
|
||
- Пароли хранятся только локально, **никогда не передаются в AI/API**
|
||
- SSH-ключи (ed25519) — рекомендуемый метод аутентификации
|
||
- sudo-пароль передаётся через stdin (не виден в списке процессов)
|
||
- При использовании с Claude Code: через API нейронки проходят только alias + команда, пароли остаются в зашифрованном локальном файле
|
||
- Автоматический пред-шифровальный бэкап при первой миграции
|
||
|
||
### Развёртывание на новой машине
|
||
|
||
```bash
|
||
# 1. Клонировать
|
||
git clone https://git.sensey24.ru/aibot777/server-manager.git
|
||
cd server-manager
|
||
|
||
# 2. Установить зависимости
|
||
pip install -r requirements.txt
|
||
|
||
# 3. Запустить и настроить
|
||
python main.py
|
||
# → Вкладка Setup → Install Everything
|
||
# → Добавить серверы через + Add
|
||
# → Готово! GUI и Claude Code работают с одним конфигом
|
||
```
|
||
|
||
---
|
||
|
||
## 中文
|
||
|
||
### 功能特点
|
||
|
||
- **服务器管理** — 添加、编辑、删除服务器（SSH、Telnet、RDP、MariaDB、MSSQL、PostgreSQL）
|
||
- **SSH终端** — 自动sudo执行命令（密码通过stdin传递，在`ps`中不可见）
|
||
- **SFTP传输** — 带进度条的文件上传/下载
|
||
- **SSH密钥** — 生成ed25519、安装到服务器、复制到剪贴板
|
||
- **状态监控** — 每60秒后台检查（在线/离线徽标）
|
||
- **Claude Code集成** — 一键设置，与`/ssh`技能共享配置
|
||
- **TOTP / 2FA** — 兼容Google Authenticator的验证码，实时倒计时，一键复制
|
||
- **加密** — servers.json使用Fernet加密（密码不再以明文存储）
|
||
- **备份** — 手动和自动备份，一键恢复
|
||
- **可配置路径** — 通过GUI更改servers.json位置
|
||
- **多语言** — 支持英语、俄语、中文界面切换
|
||
- **关于对话框** — 应用信息、功能特点、快速入门
|
||
- **深色主题** — 现代CustomTkinter界面
|
||
|
||
### 安装
|
||
|
||
#### 从源码安装
|
||
```bash
|
||
git clone https://git.sensey24.ru/aibot777/server-manager.git
|
||
cd server-manager
|
||
pip install -r requirements.txt
|
||
python main.py
|
||
```
|
||
|
||
#### 预编译版本
|
||
从 [`releases/`](releases/) 文件夹下载 — 独立的 `.exe`（Windows）或二进制文件（Linux/Mac）。
|
||
无需安装Python。
|
||
|
||
### 编译
|
||
|
||
为当前平台编译：
|
||
```bash
|
||
pip install pyinstaller
|
||
python build.py
|
||
```
|
||
|
||
输出至 `releases/ServerManager-vX.Y.Z-{平台}.exe`
|
||
|
||
### 使用方法
|
||
|
||
1. **启动** — `python main.py` 或运行可执行文件
|
||
2. **添加服务器** — 点击侧栏 "+ Add"，填写别名、IP、端口、用户名、密码、类型
|
||
3. **终端** — 选择服务器 → Terminal标签 → 输入命令 → Run
|
||
4. **文件** — 选择服务器 → Files标签 → 设置路径 → Upload/Download
|
||
5. **密钥** — Keys标签 → Generate Key → Install on Server
|
||
6. **设置Claude** — Setup标签 → "Install Everything" → Claude Code就绪
|
||
7. 状态徽标自动更新（绿色 = 在线，红色 = 离线）
|
||
|
||
### Claude Code集成
|
||
|
||
ServerManager和Claude Code共享**同一个配置文件**：`~/.server-connections/servers.json`
|
||
|
||
**工作原理：**
|
||
```
|
||
ServerManager GUI ←→ ~/.server-connections/servers.json ←→ ssh.py (Claude Code)
|
||
↕ ↕
|
||
在GUI中添加/编辑 /ssh技能
|
||
服务器 执行命令
|
||
```
|
||
|
||
- 在GUI中添加服务器 → Claude Code立即通过 `/ssh list` 看到
|
||
- 两者使用相同的 `ssh.py` + `servers.json`
|
||
- 密码**绝不**通过AI API传递
|
||
|
||
**在新机器上设置：**
|
||
1. 安装ServerManager（克隆仓库或下载二进制文件）
|
||
2. 打开Setup标签 → 点击 "Install Everything"
|
||
3. 完成。Claude Code现在拥有 `/ssh` 技能并可访问您的服务器
|
||
|
||
Setup标签安装：
|
||
- `ssh.py` → `~/.server-connections/`（SSH工具）
|
||
- `encryption.py` → `~/.server-connections/`（CLI加密模块）
|
||
- `/ssh` 技能 → `~/.claude/commands/ssh.md`（Claude Code技能）
|
||
- SSH密钥（ed25519）— 如果不存在
|
||
- 检查重复 — 可安全重复运行
|
||
|
||
### 配置
|
||
|
||
共享配置位置：`~/.server-connections/servers.json`（Fernet加密）。
|
||
|
||
可通过 Setup标签 → Configuration → "Change Path" 更改配置路径。
|
||
|
||
设置存储在 `~/.server-connections/settings.json`。
|
||
|
||
**备份：**
|
||
- 每10分钟自动备份（保存时）
|
||
- 手动备份：Setup标签 → "Backup Now"
|
||
- 从任何备份恢复：下拉菜单 + "Restore"
|
||
- 备份存储在 `~/.server-connections/backups/`
|
||
- 首次迁移时自动创建加密前备份
|
||
|
||
### 自动sudo
|
||
|
||
应用自动处理权限提升：
|
||
|
||
- 如果 `user: "root"` — 命令直接执行，无需sudo
|
||
- 如果用户不是root — 应用自动将命令包装在 `sudo -S` 中，并从 `servers.json` 通过stdin自动输入密码
|
||
- 密码**绝不**作为命令行参数传递（在 `ps aux` 中不可见）
|
||
- 您只需输入命令（例如 `systemctl restart nginx`）— 应用自动判断是否需要sudo并处理
|
||
- 在GUI终端中，"sudo"复选框默认为非root用户启用；对于不需要提权的命令可以取消勾选
|
||
|
||
```
|
||
您输入: systemctl restart nginx
|
||
应用执行: sudo -S -p '' bash -c 'systemctl restart nginx'
|
||
(密码从servers.json通过stdin自动输入)
|
||
```
|
||
|
||
### 安全性
|
||
|
||
- `servers.json` **已加密**（Fernet对称加密）— 密码无法以明文读取
|
||
- `servers.json` 在 `.gitignore` 中 — 永不提交
|
||
- 密码仅存储在本地，**绝不发送到任何AI/API**
|
||
- SSH密钥（ed25519）— 推荐的认证方式
|
||
- sudo密码通过stdin传递（在进程列表中不可见）
|
||
- 与Claude Code配合使用时：只有别名和命令通过AI API传递，密码保留在本地加密文件中
|
||
- 首次迁移时自动创建加密前备份
|
||
|
||
### 在新机器上部署
|
||
|
||
```bash
|
||
# 1. 克隆
|
||
git clone https://git.sensey24.ru/aibot777/server-manager.git
|
||
cd server-manager
|
||
|
||
# 2. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 3. 启动并设置
|
||
python main.py
|
||
# → Setup标签 → Install Everything
|
||
# → 通过 + Add 添加服务器
|
||
# → 完成！GUI和Claude Code使用同一个配置
|
||
```
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT
|
||
|
||
## Author
|
||
|
||
[aibot777](https://git.sensey24.ru/aibot777)
|