added desktop and rust version
This commit is contained in:
356
desktop/README.md
Normal file
356
desktop/README.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user