357 lines
11 KiB
Markdown
357 lines
11 KiB
Markdown
# Knocker Desktop - Electron приложение
|
||
|
||
Независимое десктопное приложение для Port Knocker с полным функционалом веб-версии.
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### Установка и запуск
|
||
|
||
```bash
|
||
cd desktop
|
||
npm install
|
||
npm run start
|
||
```
|
||
|
||
### Сборка для продакшена
|
||
|
||
```bash
|
||
# Сборка для текущей платформы
|
||
npm run build
|
||
|
||
# Сборка для конкретных платформ
|
||
npm run build:win # Windows
|
||
npm run build:linux # Linux
|
||
npm run build:mac # macOS
|
||
|
||
# Упаковка без установщика (для тестирования)
|
||
npm run pack
|
||
```
|
||
|
||
## 🏗️ Архитектура приложения
|
||
|
||
### Структура проекта
|
||
|
||
``` text
|
||
desktop/
|
||
├── src/
|
||
│ ├── main/ # Основной процесс Electron
|
||
│ │ ├── main.js # Точка входа, управление окнами
|
||
│ │ └── main.ts # TypeScript версия (опционально)
|
||
│ ├── preload/ # Preload скрипты (мост между main и renderer)
|
||
│ │ ├── preload.js # Безопасный API для renderer процесса
|
||
│ │ └── preload.ts # TypeScript версия
|
||
│ └── renderer/ # Процесс рендеринга (UI)
|
||
│ ├── index.html # HTML разметка
|
||
│ ├── styles.css # Стили
|
||
│ ├── renderer.js # Логика UI (ванильный JS)
|
||
│ └── renderer.ts # TypeScript версия
|
||
├── assets/ # Иконки для сборки
|
||
├── dist/ # Собранные приложения
|
||
├── package.json # Конфигурация и зависимости
|
||
└── README.md # Документация
|
||
```
|
||
|
||
### Как работает Electron
|
||
|
||
Electron состоит из двух основных процессов:
|
||
|
||
1. **Main Process (Основной процесс)** - `src/main/main.js`
|
||
- Управляет жизненным циклом приложения
|
||
- Создает и управляет окнами браузера
|
||
- Обеспечивает безопасный доступ к Node.js API
|
||
- Обрабатывает системные события (закрытие, фокус и т.д.)
|
||
|
||
2. **Renderer Process (Процесс рендеринга)** - `src/renderer/`
|
||
- Отображает пользовательский интерфейс
|
||
- Работает как обычная веб-страница (HTML/CSS/JS)
|
||
- Изолирован от Node.js API по соображениям безопасности
|
||
- Взаимодействует с main процессом через IPC (Inter-Process Communication)
|
||
|
||
3. **Preload Script (Preload скрипт)** - `src/preload/preload.js`
|
||
- Выполняется в renderer процессе, но имеет доступ к Node.js API
|
||
- Создает безопасный мост между main и renderer процессами
|
||
- Экспонирует только необходимые API через `contextBridge`
|
||
|
||
### Безопасность
|
||
|
||
Приложение использует современные принципы безопасности Electron:
|
||
|
||
- `contextIsolation: true` - изолирует контекст renderer от Node.js
|
||
- `nodeIntegration: false` - отключает прямой доступ к Node.js в renderer
|
||
- `sandbox: false` - позволяет preload скрипту работать (но только в preload)
|
||
|
||
## 🔧 Разработка
|
||
|
||
### Локальная разработка
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
Откроет приложение с включенными DevTools для отладки.
|
||
|
||
### Структура кода
|
||
|
||
#### Main Process (`src/main/main.js`)
|
||
|
||
```javascript
|
||
const { app, BrowserWindow, ipcMain, dialog } = require('electron');
|
||
|
||
// Создание главного окна
|
||
function createWindow() {
|
||
mainWindow = new BrowserWindow({
|
||
width: 1100,
|
||
height: 800,
|
||
webPreferences: {
|
||
preload: path.join(__dirname, '../preload/preload.js'),
|
||
contextIsolation: true, // Безопасность
|
||
nodeIntegration: false, // Безопасность
|
||
sandbox: false // Для preload
|
||
}
|
||
});
|
||
}
|
||
|
||
// IPC обработчики для файловых операций
|
||
ipcMain.handle('file:open', async () => {
|
||
const res = await dialog.showOpenDialog({...});
|
||
// Возвращает файл в renderer процесс
|
||
});
|
||
```
|
||
|
||
#### Preload Script (`src/preload/preload.js`)
|
||
|
||
```javascript
|
||
const { contextBridge, ipcRenderer } = require('electron');
|
||
|
||
// Безопасный API для renderer процесса
|
||
contextBridge.exposeInMainWorld('api', {
|
||
openFile: () => ipcRenderer.invoke('file:open'),
|
||
saveAs: (payload) => ipcRenderer.invoke('file:saveAs', payload),
|
||
// ... другие методы
|
||
});
|
||
```
|
||
|
||
#### Renderer Process (`src/renderer/renderer.js`)
|
||
|
||
```javascript
|
||
// Используем безопасный API из preload
|
||
window.addEventListener('DOMContentLoaded', () => {
|
||
document.getElementById('openFile').addEventListener('click', async () => {
|
||
const result = await window.api.openFile();
|
||
// Обрабатываем результат
|
||
});
|
||
});
|
||
```
|
||
|
||
### Функциональность
|
||
|
||
#### Режимы работы
|
||
|
||
1. **Inline режим** - простые поля для ввода targets, delay, verbose
|
||
2. **YAML режим** - редактирование YAML конфигурации с поддержкой файлов
|
||
3. **Form режим** - табличная форма для добавления/удаления целей
|
||
|
||
#### Файловые операции
|
||
|
||
- Открытие файлов через системный диалог
|
||
- Сохранение файлов с предложением имени
|
||
- Автоматическое извлечение `path` из YAML
|
||
- Синхронизация между YAML и serverFilePath полем
|
||
|
||
#### HTTP API
|
||
|
||
- Вызовы к `http://localhost:8080/api/v1/knock-actions/*`
|
||
- Basic Authentication с пользователем `knocker`
|
||
- Выполнение knock операций
|
||
- Шифрование/дешифрование конфигураций
|
||
|
||
### Отладка
|
||
|
||
#### DevTools
|
||
|
||
DevTools автоматически открываются при запуске в режиме разработки (`npm run dev`).
|
||
|
||
#### Консольные сообщения
|
||
|
||
```javascript
|
||
// В renderer процессе
|
||
console.log('Debug info:', data);
|
||
|
||
// В main процессе
|
||
console.log('Main process log:', data);
|
||
```
|
||
|
||
#### IPC отладка
|
||
|
||
```javascript
|
||
// В preload можно добавить логирование
|
||
ipcRenderer.invoke('file:open').then(result => {
|
||
console.log('IPC result:', result);
|
||
});
|
||
```
|
||
|
||
## 📦 Сборка и распространение
|
||
|
||
### Electron Builder конфигурация
|
||
|
||
В `package.json` настроена конфигурация `electron-builder`:
|
||
|
||
```json
|
||
{
|
||
"build": {
|
||
"appId": "com.knocker.desktop",
|
||
"productName": "Knocker Desktop",
|
||
"files": ["src/**/*", "node_modules/**/*"],
|
||
"win": {
|
||
"target": "nsis",
|
||
"icon": "assets/icon.ico"
|
||
},
|
||
"linux": {
|
||
"target": "AppImage",
|
||
"icon": "assets/icon.png"
|
||
},
|
||
"mac": {
|
||
"target": "dmg",
|
||
"icon": "assets/icon.icns"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Типы сборки
|
||
|
||
- **NSIS** (Windows) - установщик с мастером установки
|
||
- **AppImage** (Linux) - портативное приложение
|
||
- **DMG** (macOS) - образ диска для установки
|
||
|
||
### Команды сборки
|
||
|
||
```bash
|
||
npm run build # Сборка для текущей платформы
|
||
npm run build:win # Сборка для Windows
|
||
npm run build:linux # Сборка для Linux
|
||
npm run build:mac # Сборка для macOS
|
||
npm run pack # Упаковка без установщика
|
||
npm run dist # Сборка без публикации
|
||
```
|
||
|
||
### Иконки
|
||
|
||
Поместите иконки в папку `assets/`:
|
||
|
||
- `icon.ico` - для Windows (256x256)
|
||
- `icon.png` - для Linux (512x512)
|
||
- `icon.icns` - для macOS (512x512)
|
||
|
||
## 🔄 Интеграция с веб-версией
|
||
|
||
### Общие компоненты
|
||
|
||
- HTTP API остается тем же (`/api/v1/knock-actions/*`)
|
||
- YAML формат конфигурации идентичен
|
||
- Логика шифрования/дешифрования совместима
|
||
|
||
### Различия
|
||
|
||
- **Файловые операции**: Electron dialog вместо браузерных File API
|
||
- **UI библиотеки**: ванильный JS вместо Angular/PrimeNG
|
||
- **Автосохранение**: localStorage в веб-версии, файловая система в desktop
|
||
- **FSA API**: не нужен в desktop версии
|
||
|
||
### Миграция данных
|
||
|
||
Пользователи могут переносить конфигурации между версиями через:
|
||
|
||
- Экспорт/импорт YAML файлов
|
||
- Копирование содержимого между интерфейсами
|
||
- Использование одинаковых server paths
|
||
|
||
## 🐛 Устранение неполадок
|
||
|
||
### Частые проблемы
|
||
|
||
#### Приложение не запускается
|
||
|
||
```bash
|
||
# Проверьте зависимости
|
||
npm install
|
||
|
||
# Очистите node_modules
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
```
|
||
|
||
#### DevTools не открываются
|
||
|
||
Убедитесь, что в `src/main/main.js` есть строка:
|
||
|
||
```javascript
|
||
mainWindow.webContents.openDevTools();
|
||
```
|
||
|
||
#### Файлы не открываются
|
||
|
||
Проверьте, что backend сервер запущен на `http://localhost:8080`
|
||
|
||
#### Сборка не работает
|
||
|
||
```bash
|
||
# Очистите dist папку
|
||
rm -rf dist
|
||
|
||
# Пересоберите
|
||
npm run build
|
||
```
|
||
|
||
### Логи отладки
|
||
|
||
#### Main процесс
|
||
|
||
Логи main процесса видны в терминале, где запущено приложение.
|
||
|
||
#### Renderer процесс
|
||
|
||
Логи renderer процесса видны в DevTools Console.
|
||
|
||
#### IPC сообщения
|
||
|
||
Можно добавить логирование в preload для отладки IPC:
|
||
|
||
```javascript
|
||
const originalInvoke = ipcRenderer.invoke;
|
||
ipcRenderer.invoke = function(channel, ...args) {
|
||
console.log(`IPC: ${channel}`, args);
|
||
return originalInvoke.call(this, channel, ...args);
|
||
};
|
||
```
|
||
|
||
## 📚 Дополнительные ресурсы
|
||
|
||
- [Electron Documentation](https://www.electronjs.org/docs)
|
||
- [Electron Builder](https://www.electron.build/)
|
||
- [Context Isolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation)
|
||
- [IPC Communication](https://www.electronjs.org/docs/latest/tutorial/ipc)
|
||
|
||
## 🤝 Вклад в разработку
|
||
|
||
1. Форкните репозиторий
|
||
2. Создайте ветку для новой функции
|
||
3. Внесите изменения
|
||
4. Протестируйте на всех платформах
|
||
5. Создайте Pull Request
|
||
|
||
### Тестирование
|
||
|
||
```bash
|
||
# Тест на текущей платформе
|
||
npm run dev
|
||
|
||
# Сборка для тестирования
|
||
npm run pack
|
||
|
||
# Проверка на других платформах
|
||
npm run build:win
|
||
npm run build:linux
|
||
npm run build:mac
|
||
```
|