aljaz/flutter_server_box
1
1
Fork 0
mirror of https://github.com/lollipopkit/flutter_server_box.git synced 2026-01-31 05:14:56 +01:00
Code Issues Packages Projects Releases Wiki Activity

opt.: docs l10n (#1036)

Browse Source 
* opt.: docs l10n
Fixes #1035

* opt.

* rm: redundant docs

* rm: features chapter

* opt.: docs l10n
Fixes #1035

* fix
This commit is contained in:
lollipopkit🏳️‍⚧️
2026-01-29 20:27:21 +08:00
committed by GitHub
parent 9281a578e7
commit 6338c6ce6b
146 changed files with 14398 additions and 1287 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
docs/astro.config.mjs
View File

@@ -6,8 +6,35 @@ import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'Flutter Server Box',
title: 'Server Box',
description: 'A comprehensive cross-platform server management application built with Flutter',
defaultLocale: 'root',
locales: {
root: {
label: 'English',
lang: 'en',
},
zh: {
label: '简体中文',
lang: 'zh',
},
de: {
label: 'Deutsch',
lang: 'de',
},
fr: {
label: 'Français',
lang: 'fr',
},
es: {
label: 'Español',
lang: 'es',
},
ja: {
label: '日本語',
lang: 'ja',
},
},
logo: {
src: './src/assets/logo.svg',
},
@@ -17,73 +44,84 @@ export default defineConfig({
sidebar: [
{
label: 'Getting Started',
translations: {
zh: '开始使用',
de: 'Erste Schritte',
fr: 'Mise en route',
es: 'Primeros pasos',
ja: 'はじめに',
},
items: [
{ label: 'Introduction', slug: 'introduction' },
{ label: 'Installation', slug: 'installation' },
{ label: 'Quick Start', slug: 'quick-start' },
],
},
{
label: 'Features',
items: [
{ label: 'Server Monitoring', slug: 'features/monitoring' },
{ label: 'Docker Management', slug: 'features/docker' },
{ label: 'Process & Services', slug: 'features/process' },
{ label: 'Command Snippets', slug: 'features/snippets' },
{ label: 'Network Tools', slug: 'features/network' },
{ label: 'PVE (Proxmox)', slug: 'features/pve' },
],
},
{
label: 'Configuration',
items: [
{ label: 'Server Setup', slug: 'configuration/server' },
{ label: 'Terminal & SSH', slug: 'configuration/terminal' },
{ label: 'SFTP File Browser', slug: 'configuration/sftp' },
{ label: 'Jump Server', slug: 'configuration/jump-server' },
{ label: 'Backup & Restore', slug: 'configuration/backup' },
{ label: 'Appearance', slug: 'configuration/appearance' },
{ label: 'Localizations', slug: 'configuration/localizations' },
{ label: 'Introduction', translations: { zh: '介绍', de: 'Einführung', fr: 'Introduction', es: 'Introducción', ja: 'はじめに' }, slug: 'introduction' },
{ label: 'Installation', translations: { zh: '安装', de: 'Installation', fr: 'Installation', es: 'Instalación', ja: 'インストール' }, slug: 'installation' },
{ label: 'Quick Start', translations: { zh: '快速开始', de: 'Schnellstart', fr: 'Démarrage rapide', es: 'Inicio rápido', ja: 'クイックスタート' }, slug: 'quick-start' },
],
},
{
label: 'Platform Features',
translations: {
zh: '平台特性',
de: 'Plattformfunktionen',
fr: 'Fonctionnalités de la plateforme',
es: 'Características de la plataforma',
ja: 'プラットフォーム機能',
},
items: [
{ label: 'Mobile', slug: 'platforms/mobile' },
{ label: 'Desktop', slug: 'platforms/desktop' },
{ label: 'watchOS', slug: 'platforms/watchos' },
{ label: 'Mobile', translations: { zh: '移动端', de: 'Mobil', fr: 'Mobile', es: 'Móvil', ja: 'モバイル' }, slug: 'platforms/mobile' },
{ label: 'Desktop', translations: { zh: '桌面端', de: 'Desktop', fr: 'Bureau', es: 'Escritorio', ja: 'デスクトップ' }, slug: 'platforms/desktop' },
],
},
{
label: 'Advanced',
translations: {
zh: '进阶',
de: 'Fortgeschritten',
fr: 'Avancé',
es: 'Avanzado',
ja: '高度な設定',
},
items: [
{ label: 'Bulk Import Servers', slug: 'advanced/bulk-import' },
{ label: 'Widget Setup', slug: 'advanced/widgets' },
{ label: 'Custom Commands', slug: 'advanced/custom-commands' },
{ label: 'Custom Logo', slug: 'advanced/custom-logo' },
{ label: 'JSON Settings', slug: 'advanced/json-settings' },
{ label: 'Common Issues', slug: 'advanced/troubleshooting' },
{ label: 'Bulk Import Servers', translations: { zh: '批量导入服务器', de: 'Server-Massenimport', fr: 'Importation massive de serveurs', es: 'Importación masiva de servidores', ja: 'サーバーの一括インポート' }, slug: 'advanced/bulk-import' },
{ label: 'Widget Setup', translations: { zh: '小组件设置', de: 'Widget-Einrichtung', fr: 'Configuration du widget', es: 'Configuración de widgets', ja: 'ウィジェット設定' }, slug: 'advanced/widgets' },
{ label: 'Custom Commands', translations: { zh: '自定义命令', de: 'Benutzerdefinierte Befehle', fr: 'Commandes personnalisées', es: 'Comandos personalizados', ja: 'カスタムコマンド' }, slug: 'advanced/custom-commands' },
{ label: 'Custom Logo', translations: { zh: '自定义 Logo', de: 'Benutzerdefiniertes Logo', fr: 'Logo personnalisé', es: 'Logo personalizado', ja: 'カスタムロゴ' }, slug: 'advanced/custom-logo' },
{ label: 'JSON Settings', translations: { zh: 'JSON 设置', de: 'JSON-Einstellungen', fr: 'Paramètres JSON', es: 'Ajustes JSON', ja: 'JSON 設定' }, slug: 'advanced/json-settings' },
{ label: 'Common Issues', translations: { zh: '常见问题', de: 'Häufige Probleme', fr: 'Problèmes courants', es: 'Problemas comunes', ja: 'よくある質問' }, slug: 'advanced/troubleshooting' },
],
},
{
label: 'How It Works',
translations: {
zh: '工作原理',
de: 'Wie es funktioniert',
fr: 'Comment ça marche',
es: 'Cómo funciona',
ja: '仕組み',
},
items: [
{ label: 'Architecture', slug: 'principles/architecture' },
{ label: 'SSH Connection', slug: 'principles/ssh' },
{ label: 'Terminal', slug: 'principles/terminal' },
{ label: 'SFTP', slug: 'principles/sftp' },
{ label: 'State Management', slug: 'principles/state' },
{ label: 'Architecture', translations: { zh: '架构', de: 'Architektur', fr: 'Architecture', es: 'Arquitectura', ja: 'アーキテクチャ' }, slug: 'principles/architecture' },
{ label: 'SSH Connection', translations: { zh: 'SSH 连接', de: 'SSH-Verbindung', fr: 'Connexion SSH', es: 'Conexión SSH', ja: 'SSH 接続' }, slug: 'principles/ssh' },
{ label: 'Terminal', translations: { zh: '终端', de: 'Terminal', fr: 'Terminal', es: 'Terminal', ja: 'ターミナル' }, slug: 'principles/terminal' },
{ label: 'SFTP', translations: { zh: 'SFTP', de: 'SFTP', fr: 'SFTP', es: 'SFTP', ja: 'SFTP' }, slug: 'principles/sftp' },
{ label: 'State Management', translations: { zh: '状态管理', de: 'Zustandsverwaltung', fr: 'Gestion d\'état', es: 'Gestión de estado', ja: '状態管理' }, slug: 'principles/state' },
],
},
{
label: 'Development',
translations: {
zh: '开发',
de: 'Entwicklung',
fr: 'Développement',
es: 'Desarrollo',
ja: '開発',
},
items: [
{ label: 'Project Structure', slug: 'development/structure' },
{ label: 'Architecture', slug: 'development/architecture' },
{ label: 'State Management', slug: 'development/state' },
{ label: 'Code Generation', slug: 'development/codegen' },
{ label: 'Building', slug: 'development/building' },
{ label: 'Testing', slug: 'development/testing' },
{ label: 'Project Structure', translations: { zh: '项目结构', de: 'Projektstruktur', fr: 'Structure du projet', es: 'Estructura del proyecto', ja: 'プロジェクト構造' }, slug: 'development/structure' },
{ label: 'Architecture', translations: { zh: '架构', de: 'Architektur', fr: 'Architecture', es: 'Arquitectura', ja: 'アーキテクチャ' }, slug: 'development/architecture' },
{ label: 'State Management', translations: { zh: '状态管理', de: 'Zustandsverwaltung', fr: 'Gestion d\'état', es: 'Gestión de estado', ja: '状態管理' }, slug: 'development/state' },
{ label: 'Code Generation', translations: { zh: '代码生成', de: 'Code-Generierung', fr: 'Génération de code', es: 'Generación de código', ja: 'コード生成' }, slug: 'development/codegen' },
{ label: 'Building', translations: { zh: '构建', de: 'Bauen', fr: 'Construction', es: 'Construcción', ja: 'ビルド' }, slug: 'development/building' },
{ label: 'Testing', translations: { zh: '测试', de: 'Testen', fr: 'Tests', es: 'Pruebas', ja: 'テスト' }, slug: 'development/testing' },
],
},
],

14
docs/src/content/docs/advanced/json-settings.md
View File

@@ -11,22 +11,12 @@ Long-press **Settings** in drawer to open JSON editor.
## Common Hidden Settings
### serverTabUseOldUI
Use old server tab UI.
```json
{"serverTabUseOldUI": true}
```
**Type:** boolean | **Default:** false
### timeout
### timeOut
Connection timeout in seconds.
```json
{"timeout": 10}
{"timeOut": 10}
```
**Type:** integer | **Default:** 5 | **Range:** 1-60

124
docs/src/content/docs/configuration/appearance.md
View File

@@ -1,124 +0,0 @@
---
title: Appearance
description: Customize the look and feel
---
Flutter Server Box offers extensive appearance customization.
## Themes
### Light Theme
Clean, bright interface for daytime use.
### Dark Theme
Easy on the eyes for low-light environments.
### AMOLED Dark
Pure black background for OLED screens, saves battery.
### System Theme
Automatically switches between light and dark based on system settings.
Set in: **Settings > Appearance > Theme**
## Terminal Appearance
### Customization Options
- **Font Size**: Adjust text size in terminal
- **Font Family**: Choose from available fonts
- **Text Color**: Customize text color
- **Background Color**: Set terminal background
- **Background Opacity**: Adjust transparency
- **Blur Effect**: Enable background blur
### Terminal Themes
Create terminal color themes:
1. Go to Settings > Terminal > Themes
2. Create new theme or edit existing
3. Customize colors:
- Text color
- Background color
- Cursor color
- Selection color
## Server Cards
### Card Style
- **Compact**: Minimal information per card
- **Detailed**: Extended information per card
- **Custom**: Choose which metrics to show
### Card Order
1. Go to Settings > Server Card Order
2. Drag cards to reorder
3. Changes apply immediately
### Card Metrics
Enable/disable metrics:
- CPU
- Memory
- Disk
- Network
- GPU
- Temperature
## Charts and Graphs
### Chart Style
- **Line**: Continuous line chart
- **Area**: Filled area chart
- **Bar**: Bar chart visualization
### Chart Colors
Customize chart colors in:
**Settings > Charts > Colors**
### Refresh Rate
Adjust how often charts update:
**Settings > Charts > Refresh Rate**
- **Power Saving**: 5 seconds
- **Normal**: 2 seconds
- **High Performance**: 1 second
## Layout
### Navigation Style
- **Bottom Navigation**: Mobile-style bottom tabs
- **Side Navigation**: Desktop-style sidebar
- **Tabs**: Classic tab interface
### View Mode
- **List**: Vertical list view
- **Grid**: Grid layout for servers
- **Cards**: Card-based layout
## Icons and Symbols
Choose icon style:
- **Filled**: Solid icons
- **Outlined**: Line icons
- **Rounded**: Soft, rounded icons
## Animations
Control animation speed:
- **Off**: No animations
- **Reduced**: Minimal animations
- **Normal**: Standard animations
- **Enhanced**: Extra animations

80
docs/src/content/docs/configuration/backup.md
View File

@@ -1,80 +0,0 @@
---
title: Backup & Restore
description: Backup and restore your app data
---
Protect your server configurations and settings with built-in backup functionality.
## What Gets Backed Up
- **Server Configurations**: All saved servers
- **SSH Keys**: Imported private keys (encrypted)
- **Snippets**: Saved command snippets
- **Settings**: App preferences
**Not included:** Passwords (for security)
## Creating Backups
### Manual Backup
1. Settings → Backup
2. Tap **Create Backup**
3. Choose location
4. Backup saved with timestamp
### Auto Backup
Settings → Backup → Auto Backup:
- Daily / Weekly / Monthly / Off
### Cloud Sync
- **iOS/macOS**: iCloud automatic backup
- **Android**: Google Drive integration
## Restoring
### From Local Backup
1. Settings → Backup → Restore Backup
2. Select backup file
3. Authenticate (biometric/password)
4. Confirm restore
### From Cloud
1. Sign in to same cloud account
2. Settings → Backup → Restore from Cloud
3. Select backup from list
4. Authenticate and confirm
## Important Notes
### Passwords Not Backed Up
After restore, you'll need to re-enter passwords for each server.
**Tip:** Use SSH keys instead - they ARE backed up.
### Cross-Platform
Backups work across all platforms (iOS ↔ Android ↔ Desktop).
## Best Practices
1. **Enable auto backup** for peace of mind
2. **Test restore** periodically to verify backups work
3. **Backup before** updating app or switching devices
4. **Use SSH keys** to avoid re-entering passwords
## Troubleshooting
**Restore failed:**
- Check backup file integrity
- Ensure sufficient storage
- Verify app version compatibility
**Missing data after restore:**
- Passwords are not backed up (re-enter them)
- Check selective restore settings

88
docs/src/content/docs/configuration/jump-server.md
View File

@@ -1,88 +0,0 @@
---
title: Jump Server
description: Route connections through intermediate servers
---
Connect to servers behind firewalls or in private networks by routing through an intermediate jump server.
## What is Jump Server?
A jump server acts as a gateway to access other servers that:
- Are behind firewalls
- Don't have direct SSH access
- Are in private networks
- Require multi-hop connections
## Setup
### Step 1: Configure Jump Server
Add the jump server as a normal server first:
1. Add server with SSH credentials
2. Test connection to ensure it works
3. This server will be your jump host
### Step 2: Configure Target Servers
For each server you want to access via jump:
1. Add target server (credentials for target, not jump)
2. Server settings → Jump Server
3. Select your jump server from list
4. Save
### Step 3: Connect
Connect to target server normally. The app automatically:
1. Connects to jump server
2. Tunnels through to target server
3. Maintains connection
## Use Cases
### Private Network Access
```
Your Device → Jump Server (public IP) → Private Server (10.0.0.x)
```
### Behind Firewall
```
Your Device → Bastion Host → Internal Server
```
### Multi-Hop
You can chain multiple jump servers for complex networks.
## Requirements
- Jump server must be accessible from your device
- Jump server must be able to reach target servers
- SSH keys recommended for jump server (faster authentication)
## Tips
- **Use SSH keys** on jump server for faster connections
- **Test direct access** to jump server first
- **Check firewall rules** on both ends
- **Monitor connection** - issues could be on jump or target
## Troubleshooting
### Connection Times Out
- Verify jump server is accessible
- Check jump server can reach target
- Test manually: `ssh -J jump@jump-server user@target-server`
### Authentication Fails
- Verify credentials for target server (not jump)
- Check SSH keys if using key authentication
### Slow Connection
- Normal for jump connections (extra hop)
- Consider using SSH keys for faster auth
- Check network latency to jump server

93
docs/src/content/docs/configuration/localizations.md
View File

@@ -1,93 +0,0 @@
---
title: Localizations
description: Language and region settings
---
Flutter Server Box supports 12+ languages with full localization.
## Supported Languages
| Language | Status |
|----------|--------|
| English (en) | ✅ Native |
| 简体中文 (zh) | ✅ Native |
| 繁體中文 (zh-Hant) | ✅ Native |
| Deutsch (de) | ✅ Native |
| Français (fr) | ✅ Native |
| Español (es) | ✅ Native |
| Português (pt) | ✅ Native |
| Русский (ru) | ✅ Native |
| Türkçe (tr) | ✅ Native |
| Українська (uk) | ✅ Native |
| Bahasa Indonesia (id) | ✅ Native |
| Nederlands (nl) | ✅ Native |
| 日本語 (ja) | ✅ AI-translated |
## Changing Language
1. Go to **Settings > Language**
2. Select preferred language
3. App restarts to apply changes
## Number Formatting
Numbers are formatted according to locale:
- **Thousands separator**: Comma vs period
- **Decimal separator**: Period vs comma
- **Date format**: Locale-specific
## Time Format
Choose between:
- **24-hour**: 13:00, 14:30
- **12-hour**: 1:00 PM, 2:30 PM
Set in: **Settings > Time Format**
## Contributing Translations
We welcome community translations!
### Translation Files
Located in `lib/l10n/`:
- `app_en.arb` - English (reference)
- `app_zh.arb` - Simplified Chinese
- etc.
### How to Contribute
1. Fork the repository
2. Copy `app_en.arb` to `app_YOUR_LOCALE.arb`
3. Translate values (keep keys the same)
4. Test your translations
5. Submit pull request
### Translation Guidelines
- Keep technical terms consistent
- Use formal address for professional tone
- Maintain placeholder format: `{variable}`
- Test UI with translated strings
## Adding New Language
1. Create new ARB file: `app_xx.arb`
2. Copy all keys from `app_en.arb`
3. Translate all values
4. Add to `l10n.yaml` configuration
5. Run `flutter gen-l10n`
6. Test with new locale
## RTL Languages
Right-to-left languages (Arabic, Hebrew) are partially supported. Full RTL layout support is planned for future releases.
## Quality Notes
- Some languages are AI-translated and may contain errors
- Native speaker reviews are appreciated
- Report translation issues via GitHub

90
docs/src/content/docs/configuration/server.md
View File

@@ -1,90 +0,0 @@
---
title: Server Setup
description: Configure and manage server connections
---
## Adding a Server
1. Tap the **+** button on the main screen
2. Fill in connection details:
- **Name**: Friendly name for identification
- **Host**: IP address or domain name
- **Port**: SSH port (default: 22)
- **Username**: SSH login user
- **Authentication**: Password or SSH key
3. Configure optional settings:
- **Initial Directory**: Starting directory for terminal/SFTP
- **Environment**: Custom environment variables
- **Keep-alive Interval**: Connection keep-alive setting
4. Tap **Save**
## Connection Types
### Password Authentication
Simple username/password authentication:
- Enter password in the password field
- Password is stored securely (encrypted)
- Requires re-entry on app restart (unless saved)
### SSH Key Authentication
More secure, passwordless authentication:
1. Generate or import SSH key
2. Add key to server's `~/.ssh/authorized_keys`
3. Select key in app when adding server
See [SSH Keys](/configuration/ssh-keys/) for detailed setup.
## Server Groups
Organize servers into groups for easier management:
1. Go to Settings > Server Groups
2. Create a new group
3. Assign servers to groups
4. Groups appear as sections in main view
## Server Cards
Customize what information appears on server cards:
1. Go to Settings > Server Card Settings
2. Enable/disable metrics:
- CPU
- Memory
- Disk
- Network
3. Reorder cards by dragging
## Connection Profiles
Save connection profiles for different use cases:
- **Default Profile**: Standard settings
- **Low Bandwidth**: Reduced refresh rate
- **High Performance**: Maximum refresh rate
## Troubleshooting
### Connection Refused
- Check server is running
- Verify SSH port
- Check firewall rules
### Authentication Failed
- Verify username/password
- Check SSH key permissions
- Ensure SSH service is running
### Timeout
- Check network connectivity
- Increase timeout in settings
- Try different network

118
docs/src/content/docs/configuration/sftp.md
View File

@@ -1,118 +0,0 @@
---
title: SFTP File Browser
description: File transfer and management via SFTP
---
Browse, edit, and transfer files on your servers with a built-in SFTP client.
## Basic Usage
### Opening SFTP
1. Connect to server
2. Tap **Files** button on server page
3. Or from terminal: Tap **SFTP** button
### Navigation
- **Tap folder**: Enter directory
- **Tap file**: View/Edit/Download options
- **Back button**: Previous directory
- **Home button**: User's home directory
- **Goto button**: Jump to path with autocomplete
## File Operations
### Common Actions
| Action | How |
|--------|-----|
| **Download** | Long-press file → Download |
| **Upload** | Folder icon → Select file |
| **Rename** | Long-press → Rename |
| **Delete** | Long-press → Delete |
| **Copy/Move** | Long-press → Select → Choose destination |
| **Permissions** | Tap file info → Edit permissions |
### Permission Editor
Unix permissions editor:
- **3x3 Grid**: User/Group/Other × Read/Write/Execute
- **Numeric**: Direct input (755, 644, etc.)
- **Symbolic**: rwxr-xr-x format
### Edit Files
1. Tap file → Edit
2. Edit in built-in editor
3. Save → Upload back to server
**Size limit:** Files up to 1 MB. For larger files, use the terminal with vim/nano instead.
**Editor settings:** Settings → SFTP Editor
- Preferred editor (vim, nano, etc.)
- Close after save
- Soft wrap
- Syntax highlighting
## Display Settings
### Sort Order
Settings → Sort By:
- Name (alphabetical)
- Size (largest first)
- Time (newest first)
### Folders First
Show directories before files:
Settings → Folders First
### Hidden Files
Show dotfiles (`.git`, `.bashrc`, etc.):
Settings → Show Hidden Files
## Archive Support
Extract common archive formats directly on your server.
| Format | Variants | Command Required |
|--------|----------|------------------|
| .tar.gz | .tgz, .tar.Z | tar |
| .tar.bz2 | .tbz2, .tar.bz2 | tar |
| .tar.xz | .txz | tar |
| .zip | .zipx | unzip |
| .7z | - | 7z |
| .rar | - | unrar |
**Note:** The corresponding command (`tar`, `unzip`, `7z`, `unrar`) must be installed on your server. These tools handle many sub-formats not listed above.
## Quick Access
### From Terminal
Tap **SFTP** button to open current terminal directory in file browser.
### Remember Last Path
Automatically return to last visited directory:
Settings → SFTP Open Last Path
## Troubleshooting
### Permission Denied
- Check user has read access to directory
- Verify directory permissions: `ls -la`
- Ensure SFTP is enabled in sshd_config
### Slow Listing
Large directories (1000+ items) use pagination for performance.
### Can't Edit File
File larger than 1 MB? Use terminal with vim/nano instead.

127
docs/src/content/docs/configuration/terminal.md
View File

@@ -1,127 +0,0 @@
---
title: Terminal & SSH
description: SSH terminal setup and configuration
---
Complete SSH terminal access with full keyboard support and customizable interface.
## Basic Setup
### First Connection
1. Add server with SSH credentials
2. Tap server card to connect
3. Accept host key fingerprint (first time only)
4. Terminal opens automatically
### Virtual Keyboard (Mobile)
Customizable virtual keyboard for terminal access:
| Button | Function |
|--------|----------|
| **Ctrl, Alt, Shift** | Modifier keys (tap before other key) |
| **Esc, Tab** | Special characters |
| **Arrows** | Navigation |
| **F1-F12** | Function keys |
| **SFTP** | Open current directory in file browser |
| **Clipboard** | Copy selection / Paste clipboard |
| **Snippets** | Quick command execution |
**Customize keyboard:** Settings → SSH Virtual Keys
- Enable/disable keys
- Reorder layout
- Add/remove buttons
## Terminal Settings
### Appearance
**Font Size:** Settings → Terminal Font Size
- Affects all new sessions
- Typical range: 8-24 pixels
**Colors:** Settings → Terminal Color
- Text color
- Background color & opacity
- Blur effect (iOS/macOS)
- Cursor color
### Keyboard Type
If you can't input certain characters:
1. Settings → Keyboard Type
2. Switch to `visiblePassword`
3. Note: CJK input may not work after this change
## Connection Management
### Multi-Tab
- **Desktop**: Ctrl+T (new), Ctrl+W (close)
- **Mobile**: Tap + button
- Sessions persist between app launches
### Auto-Connect
Set server to auto-connect on app open:
1. Server settings → Auto-Connect
2. Enable toggle
### Jump Server
Route through intermediate server:
1. Add and configure jump server first
2. Target server settings → Select jump server
3. Connection routes through jump server automatically
## SSH Keys (Recommended)
More secure than passwords:
1. Generate key: Settings → Private Keys → Add
2. Upload public key to server: `ssh-copy-id -i pubkey user@server`
3. Server settings → Use key instead of password
## Common Issues
### Can't Connect
**Timeout/Refused:**
- Verify server is Unix-like (Linux, macOS, Android/Termux)
- Check firewall allows SSH port (default 22)
- Test manually: `ssh user@server -p port`
**Auth Failed:**
- Verify username and password
- Check SSH key is uploaded correctly
- Ensure account is not locked
### Terminal Disconnects
**Frequent disconnections:**
1. Check server keep-alive settings:
```bash
# /etc/ssh/sshd_config
ClientAliveInterval 60
ClientAliveCountMax 3
```
2. Disable battery optimization:
- **MIUI**: Battery → "No limits"
- **Android**: Settings → Apps → Disable optimization
- **iOS**: Enable background refresh
### Can't Input Characters
Change keyboard type to `visiblePassword` in settings.
## Tips
- **Test connection** first with regular SSH client
- **Use SSH keys** instead of passwords for security
- **Save snippets** for frequently used commands
- **Pinch to zoom** for temporary font size change (mobile)

83
docs/src/content/docs/de/advanced/bulk-import.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: Massenimport von Servern
description: Importieren Sie mehrere Server aus einer JSON-Datei
---
Importieren Sie mehrere Serverkonfigurationen gleichzeitig mithilfe einer JSON-Datei.
## JSON-Format
:::danger[Sicherheitswarnung]
**Speichern Sie niemals Klartext-Passwörter in Dateien!** Dieses JSON-Beispiel zeigt ein Passwort-Feld nur zur Demonstration, aber Sie sollten:
- **SSH-Schlüssel bevorzugen** (`keyId`) anstelle von `pwd` - diese sind sicherer
- **Passwort-Manager** oder Umgebungsvariablen verwenden, wenn Sie Passwörter verwenden müssen
- **Löschen Sie die Datei sofort** nach dem Import - lassen Sie keine Anmeldedaten herumliegen
- **Fügen Sie sie zur .gitignore hinzu** - checken Sie niemals Anmeldedatendateien in die Versionsverwaltung ein
:::
```json
[
{
"name": "Mein Server",
"ip": "example.com",
"port": 22,
"user": "root",
"pwd": "password",
"keyId": "",
"tags": ["production"],
"autoConnect": false
}
]
```
## Felder
| Feld | Erforderlich | Beschreibung |
|-------|----------|-------------|
| `name` | Ja | Anzeigename |
| `ip` | Ja | Domain oder IP-Adresse |
| `port` | Ja | SSH-Port (normalerweise 22) |
| `user` | Ja | SSH-Benutzername |
| `pwd` | Nein | Passwort (vermeiden - stattdessen SSH-Schlüssel verwenden) |
| `keyId` | Nein | SSH-Schlüsselname (aus Private Keys - empfohlen) |
| `tags` | Nein | Organisations-Tags |
| `autoConnect` | Nein | Automatische Verbindung beim Start |
## Import-Schritte
1. Erstellen Sie eine JSON-Datei mit Serverkonfigurationen
2. Einstellungen → Backup → Server massenhaft importieren
3. Wählen Sie Ihre JSON-Datei aus
4. Bestätigen Sie den Import
## Beispiel
```json
[
{
"name": "Produktion",
"ip": "prod.example.com",
"port": 22,
"user": "admin",
"keyId": "my-key",
"tags": ["production", "web"]
},
{
"name": "Entwicklung",
"ip": "dev.example.com",
"port": 2222,
"user": "dev",
"keyId": "dev-key",
"tags": ["development"]
}
]
```
## Tipps
- **Verwenden Sie SSH-Schlüssel** anstelle von Passwörtern, wann immer möglich
- **Testen Sie die Verbindung** nach dem Import
- **Organisieren Sie mit Tags** für eine einfachere Verwaltung
- **Löschen Sie die JSON-Datei** nach dem Import
- **Checken Sie niemals** JSON-Dateien mit Anmeldedaten in die Versionsverwaltung ein

72
docs/src/content/docs/de/advanced/custom-commands.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Benutzerdefinierte Befehle
description: Anzeige der Ausgabe benutzerdefinierter Befehle auf der Serverseite
---
Fügen Sie benutzerdefinierte Shell-Befehle hinzu, um deren Ausgabe auf der Server-Detailseite anzuzeigen.
## Einrichtung
1. Servereinstellungen → Benutzerdefinierte Befehle
2. Befehle im JSON-Format eingeben
## Basisformat
```json
{
"Anzeigename": "Shell-Befehl"
}
```
**Beispiel:**
```json
{
"Speicher": "free -h",
"Festplatte": "df -h",
"Laufzeit": "uptime"
}
```
## Ergebnisse anzeigen
Nach der Einrichtung erscheinen benutzerdefinierte Befehle auf der Server-Detailseite und werden automatisch aktualisiert.
## Spezielle Befehlsnamen
### server_card_top_right
Anzeige auf der Serverkarte der Startseite (oben rechts):
```json
{
"server_card_top_right": "Ihr-Befehl-hier"
}
```
## Tipps
**Absolute Pfade verwenden:**
```json
{"Mein Skript": "/usr/local/bin/mein-skript.sh"}
```
**Pipe-Befehle:**
```json
{"Top-Prozess": "ps aux | sort -rk 3 | head -5"}
```
**Ausgabe formatieren:**
```json
{"CPU-Last": "uptime | awk -F'load average:' '{print $2}'"}
```
**Befehle schnell halten:** Unter 5 Sekunden für das beste Erlebnis.
**Ausgabe begrenzen:**
```json
{"Logs": "tail -20 /var/log/syslog"}
```
## Sicherheit
Befehle werden mit den Berechtigungen des SSH-Benutzers ausgeführt. Vermeiden Sie Befehle, die den Systemzustand ändern.

54
docs/src/content/docs/de/advanced/custom-logo.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: Benutzerdefiniertes Server-Logo
description: Verwenden Sie benutzerdefinierte Bilder für Serverkarten
---
Zeigen Sie benutzerdefinierte Logos auf Serverkarten mithilfe von Bild-URLs an.
## Einrichtung
1. Servereinstellungen → Benutzerdefiniertes Logo
2. Bild-URL eingeben
## URL-Platzhalter
### {DIST} - Linux-Distribution
Wird automatisch durch die erkannte Distribution ersetzt:
```
https://example.com/{DIST}.png
```
Wird zu: `debian.png`, `ubuntu.png`, `arch.png`, usw.
### {BRIGHT} - Theme
Wird automatisch durch das aktuelle Theme ersetzt:
```
https://example.com/{BRIGHT}.png
```
Wird zu: `light.png` oder `dark.png`
### Beide kombinieren
```
https://example.com/{DIST}-{BRIGHT}.png
```
Wird zu: `debian-light.png`, `ubuntu-dark.png`, usw.
## Tipps
- Verwenden Sie PNG- oder SVG-Formate
- Empfohlene Größe: 64x64 bis 128x128 Pixel
- Verwenden Sie HTTPS-URLs
- Halten Sie die Dateigrößen gering
## Unterstützte Distributionen
debian, ubuntu, centos, fedora, opensuse, kali, alpine, arch, rocky, deepin, armbian, wrt
Vollständige Liste: [`dist.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/model/server/dist.dart)

64
docs/src/content/docs/de/advanced/json-settings.md Normal file
View File

@@ -0,0 +1,64 @@
---
title: Versteckte Einstellungen (JSON)
description: Zugriff auf erweiterte Einstellungen über den JSON-Editor
---
Einige Einstellungen sind in der Benutzeroberfläche ausgeblendet, aber über den JSON-Editor zugänglich.
## Zugriff
Halten Sie **Einstellungen** in der Seitenleiste lange gedrückt, um den JSON-Editor zu öffnen.
## Gängige versteckte Einstellungen
### timeOut
Verbindungs-Timeout in Sekunden.
```json
{"timeOut": 10}
```
**Typ:** Integer | **Standard:** 5 | **Bereich:** 1-60
### recordHistory
Verlauf speichern (SFTP-Pfade, usw.).
```json
{"recordHistory": true}
```
**Typ:** Boolean | **Standard:** true
### textFactor
Textskalierungsfaktor.
```json
{"textFactor": 1.2}
```
**Typ:** Double | **Standard:** 1.0 | **Bereich:** 0.8-1.5
## Weitere Einstellungen finden
Alle Einstellungen sind in [`setting.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/store/setting.dart) definiert.
Suchen Sie nach:
```dart
late final settingName = StoreProperty(box, 'settingKey', defaultValue);
```
## ⚠️ Wichtig
**Vor dem Bearbeiten:**
- **Backup erstellen** - Falsche Einstellungen können dazu führen, dass die App nicht mehr öffnet
- **Sorgfältig bearbeiten** - JSON muss gültig sein
## Wiederherstellung
Wenn die App nach dem Bearbeiten nicht mehr öffnet:
1. App-Daten löschen (letzter Ausweg)
2. App neu installieren
3. Aus Backup wiederherstellen

118
docs/src/content/docs/de/advanced/troubleshooting.md Normal file
View File

@@ -0,0 +1,118 @@
---
title: Häufige Probleme
description: Lösungen für gängige Probleme
---
## Verbindungsprobleme
### SSH verbindet nicht
**Symptome:** Timeout, Verbindung abgelehnt, Authentifizierung fehlgeschlagen
**Lösungen:**
1. **Servertyp überprüfen:** Nur Unix-ähnliche Systeme werden unterstützt (Linux, macOS, Android/Termux)
2. **Manuell testen:** `ssh benutzer@server -p port`
3. **Firewall prüfen:** Port 22 muss offen sein
4. **Anmeldedaten prüfen:** Benutzername und Passwort/Schlüssel korrekt
### Häufige Verbindungsabbrüche
**Symptome:** Das Terminal trennt die Verbindung nach Inaktivität
**Lösungen:**
1. **Server Keep-Alive:**
```bash
# /etc/ssh/sshd_config
ClientAliveInterval 60
ClientAliveCountMax 3
```
2. **Akku-Optimierung deaktivieren:**
- MIUI: Akku → "Keine Beschränkungen"
- Android: Einstellungen → Apps → Optimierung deaktivieren
- iOS: Hintergrundaktualisierung aktivieren
## Eingabeprobleme
### Bestimmte Zeichen können nicht getippt werden
**Lösung:** Einstellungen → Tastaturtyp → Wechseln zu `visiblePassword`
Hinweis: CJK-Eingaben funktionieren nach dieser Änderung möglicherweise nicht mehr.
## App-Probleme
### App stürzt beim Start ab
**Symptome:** App öffnet sich nicht, schwarzer Bildschirm
**Ursachen:** Korrupte Einstellungen, insbesondere durch den JSON-Editor
**Lösungen:**
1. **App-Daten löschen:**
- Android: Einstellungen → Apps → ServerBox → Daten löschen
- iOS: Löschen und neu installieren
2. **Backup wiederherstellen:** Importieren Sie ein Backup, das vor der Änderung der Einstellungen erstellt wurde
### Probleme beim Sichern/Wiederherstellen
**Backup funktioniert nicht:**
- Speicherplatz prüfen
- Sicherstellen, dass die App Speicherberechtigungen hat
- Anderen Speicherort versuchen
**Wiederherstellung schlägt fehl:**
- Integrität der Backup-Datei prüfen
- Kompatibilität der App-Version prüfen
## Widget-Probleme
### Widget aktualisiert nicht
**iOS:**
- Bis zu 30 Minuten auf automatische Aktualisierung warten
- Widget entfernen und neu hinzufügen
- Prüfen, ob die URL auf `/status` endet
**Android:**
- Auf das Widget tippen, um die Aktualisierung zu erzwingen
- Sicherstellen, dass die Widget-ID mit der Konfiguration in den App-Einstellungen übereinstimmt
**watchOS:**
- Watch-App neu starten
- Nach Konfigurationsänderung einige Minuten warten
- URL-Format prüfen
### Widget zeigt Fehler
- Sicherstellen, dass der ServerBox Monitor auf dem Server läuft
- URL im Browser testen
- Authentifizierungsdaten prüfen
## Leistungsprobleme
### App ist langsam
**Lösungen:**
- Aktualisierungsrate in den Einstellungen reduzieren
- Netzwerkgeschwindigkeit prüfen
- Nicht verwendete Server deaktivieren
### Hoher Akkuverbrauch
**Lösungen:**
- Aktualisierungsintervalle vergrößern
- Hintergrundaktualisierung deaktivieren
- Nicht verwendete SSH-Sitzungen schließen
## Hilfe erhalten
Wenn die Probleme weiterhin bestehen:
1. **GitHub Issues durchsuchen:** https://github.com/lollipopkit/flutter_server_box/issues
2. **Neues Issue erstellen:** App-Version, Plattform und Schritte zur Reproduktion angeben
3. **Wiki prüfen:** Diese Dokumentation und das GitHub Wiki

90
docs/src/content/docs/de/advanced/widgets.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: Startbildschirm-Widgets
description: Fügen Sie Serverstatus-Widgets zu Ihrem Startbildschirm hinzu
---
Erfordert [ServerBox Monitor](https://github.com/lollipopkit/server_box_monitor) auf Ihren Servern installiert.
## Voraussetzungen
Installieren Sie zuerst ServerBox Monitor auf Ihrem Server. Anweisungen zur Einrichtung finden Sie im [ServerBox Monitor Wiki](https://github.com/lollipopkit/server_box_monitor/wiki/Home).
Nach der Installation sollte Ihr Server verfügen über:
- Einen HTTP/HTTPS-Endpunkt
- Einen `/status` API-Endpunkt
- Optionale Authentifizierung
## URL-Format
```
https://ihr-server.com/status
```
Muss auf `/status` enden.
## iOS-Widget
### Einrichtung
1. Startbildschirm lange drücken → Auf **+** tippen
2. Nach "ServerBox" suchen
3. Widget-Größe wählen
4. Widget lange drücken → **Widget bearbeiten**
5. URL eingeben, die auf `/status` endet
### Hinweise
- Muss HTTPS verwenden (außer bei lokalen IPs)
- Maximale Aktualisierungsrate: 30 Minuten (iOS-Limit)
- Fügen Sie mehrere Widgets für mehrere Server hinzu
## Android-Widget
### Einrichtung
1. Startbildschirm lange drücken → **Widgets**
2. "ServerBox" finden → Zum Startbildschirm hinzufügen
3. Notieren Sie sich die angezeigte Widget-ID-Nummer
4. ServerBox-App öffnen → Einstellungen
5. Tippen Sie auf **Config home widget link**
6. Eintrag hinzufügen: `Widget ID` = `Status-URL`
Beispiel:
- Key: `17`
- Value: `https://mein-server.com/status`
7. Tippen Sie auf das Widget auf dem Startbildschirm, um es zu aktualisieren
## watchOS-Widget
### Einrichtung
1. iPhone-App öffnen → Einstellungen
2. **iOS-Einstellungen** → **Watch-App**
3. Auf **URL hinzufügen** tippen
4. URL eingeben, die auf `/status` endet
5. Warten, bis die Watch-App synchronisiert ist
### Hinweise
- Versuchen Sie, die Watch-App neu zu starten, wenn sie nicht aktualisiert wird
- Sicherstellen, dass Telefon und Watch verbunden sind
## Fehlerbehebung
### Widget aktualisiert nicht
**iOS:** Warten Sie bis zu 30 Minuten, dann entfernen Sie es und fügen es erneut hinzu.
**Android:** Tippen Sie auf das Widget, um die Aktualisierung zu erzwingen, überprüfen Sie die ID in den Einstellungen.
**watchOS:** Starten Sie die Watch-App neu, warten Sie einige Minuten.
### Widget zeigt Fehler an
- Sicherstellen, dass ServerBox Monitor läuft
- URL im Browser testen
- Prüfen, ob die URL auf `/status` endet
## Sicherheit
- **Verwenden Sie immer HTTPS**, wann immer möglich
- **Lokale IPs nur** in vertrauenswürdigen Netzwerken

86
docs/src/content/docs/de/development/architecture.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: Architektur
description: Architekturmuster und Designentscheidungen
---
Server Box folgt den Prinzipien der Clean Architecture mit einer klaren Trennung zwischen Daten-, Domänen- und Präsentationsschicht.
## Schichtarchitektur
```
┌─────────────────────────────────────┐
│ Präsentationsschicht │
│ (lib/view/page/) │
│ - Seiten, Widgets, Controller │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Business-Logik-Schicht │
│ (lib/data/provider/) │
│ - Riverpod Provider │
│ - Zustandsverwaltung │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Datenschicht │
│ (lib/data/model/, store/) │
│ - Modelle, Speicher, Dienste │
└─────────────────────────────────────┘
```
## Schlüsselmuster
### Zustandsverwaltung: Riverpod
- **Codegenerierung**: Verwendet `riverpod_generator` für typsichere Provider
- **State Notifier**: Für veränderlichen Zustand mit Business-Logik
- **Async Notifier**: Für Lade- und Fehlerzustände
- **Stream Provider**: Für Echtzeitdaten
### Unveränderliche Modelle: Freezed
- Alle Datenmodelle verwenden Freezed für Unveränderlichkeit
- Union-Typen zur Darstellung von Zuständen
- Integrierte JSON-Serialisierung
- CopyWith-Erweiterungen für Aktualisierungen
### Lokale Speicherung: Hive
- **hive_ce**: Community-Edition von Hive
- Keine manuellen `@HiveField` oder `@HiveType` erforderlich
- Typ-Adapter werden automatisch generiert
- Persistenter Key-Value-Speicher
## Dependency Injection
Dienste und Stores werden injiziert über:
1. **Provider**: Stellen Abhängigkeiten der UI zur Verfügung
2. **GetIt**: Service-Locator (wo anwendbar)
3. **Konstruktor-Injektion**: Explizite Abhängigkeiten
## Datenfluss
```
Benutzeraktion → Widget → Provider → Dienst/Store → Modell-Update → UI-Neuaufbau
```
1. Benutzer interagiert mit Widget
2. Widget ruft Provider-Methode auf
3. Provider aktualisiert Zustand über Dienst/Store
4. Zustandsänderung löst Neuaufbau der UI aus
5. Neuer Zustand spiegelt sich im Widget wider
## Eigene Abhängigkeiten
Das Projekt verwendet mehrere eigene Forks zur Funktionserweiterung:
- **dartssh2**: Erweiterte SSH-Funktionen
- **xterm**: Terminal-Emulator mit mobiler Unterstützung
- **fl_lib**: Gemeinsame UI-Komponenten und Dienstprogramme
## Threading
- **Isolates**: Rechenintensive Aufgaben außerhalb des Main-Threads
- **computer-Paket**: Dienstprogramme für Multi-Threading
- **Async/Await**: Nicht-blockierende I/O-Operationen

116
docs/src/content/docs/de/development/building.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: Bauen
description: Bauanleitungen für verschiedene Plattformen
---
Server Box verwendet ein benutzerdefiniertes Build-System (`fl_build`) für plattformübergreifende Builds.
## Voraussetzungen
- Flutter SDK (stabiler Kanal)
- Plattformspezifische Tools (Xcode für iOS, Android Studio für Android)
- Rust-Toolchain (für einige native Abhängigkeiten)
## Entwicklungs-Build
```bash
# Im Entwicklungsmodus ausführen
flutter run
# Auf einem bestimmten Gerät ausführen
flutter run -d <device-id>
```
## Produktions-Build
Das Projekt verwendet `fl_build` zum Bauen:
```bash
# Für eine bestimmte Plattform bauen
dart run fl_build -p <platform>
# Verfügbare Plattformen:
# - ios
# - android
# - macos
# - linux
# - windows
```
## Plattformspezifische Builds
### iOS
```bash
dart run fl_build -p ios
```
Erfordert:
- macOS mit Xcode
- CocoaPods
- Apple Developer Account für die Signierung
### Android
```bash
dart run fl_build -p android
```
Erfordert:
- Android SDK
- Java Development Kit
- Keystore für die Signierung
### macOS
```bash
dart run fl_build -p macos
```
### Linux
```bash
dart run fl_build -p linux
```
### Windows
```bash
dart run fl_build -p windows
```
Erfordert Windows mit Visual Studio.
## Vor/Nach dem Build
Das Skript `make.dart` übernimmt:
- Metadaten-Generierung
- Aktualisierung der Versions-Strings
- Plattformspezifische Konfigurationen
## Fehlerbehebung
### Clean Build
```bash
flutter clean
dart run build_runner build --delete-conflicting-outputs
flutter pub get
```
### Versions-Konflikt
Stellen Sie sicher, dass alle Abhängigkeiten kompatibel sind:
```bash
flutter pub upgrade
```
## Release-Checkliste
1. Version in `pubspec.yaml` aktualisieren
2. Codegenerierung ausführen
3. Tests ausführen
4. Für alle Zielplattformen bauen
5. Auf physischen Geräten testen
6. GitHub-Release erstellen

98
docs/src/content/docs/de/development/codegen.md Normal file
View File

@@ -0,0 +1,98 @@
---
title: Codegenerierung
description: Verwendung von build_runner für die Codegenerierung
---
Server Box verwendet intensiv Codegenerierung für Modelle, Zustandsverwaltung und Serialisierung.
## Wann sollte die Codegenerierung ausgeführt werden?
Führen Sie sie aus nach der Änderung von:
- Modellen mit `@freezed` Annotation
- Klassen mit `@JsonSerializable`
- Hive-Modellen
- Providern mit `@riverpod`
- Lokalisierungen (ARB-Dateien)
## Codegenerierung ausführen
```bash
# Gesamten Code generieren
dart run build_runner build --delete-conflicting-outputs
# Bereinigen und neu generieren
dart run build_runner build --delete-conflicting-outputs --clean
```
## Generierte Dateien
### Freezed (`*.freezed.dart`)
Unveränderliche Datenmodelle mit Union Types:
```dart
@freezed
class ServerState with _$ServerState {
const factory ServerState.connected() = Connected;
const factory ServerState.disconnected() = Disconnected;
const factory ServerState.error(String message) = Error;
}
```
### JSON-Serialisierung (`*.g.dart`)
Generiert durch `json_serializable`:
```dart
@JsonSerializable()
class Server {
final String id;
final String name;
final String host;
Server({required this.id, required this.name, required this.host});
factory Server.fromJson(Map<String, dynamic> json) =>
_$ServerFromJson(json);
Map<String, dynamic> toJson() => _$ServerToJson(this);
}
```
### Riverpod Provider (`*.g.dart`)
Generiert aus der `@riverpod` Annotation:
```dart
@riverpod
class MyNotifier extends _$MyNotifier {
@override
int build() => 0;
}
```
### Hive-Adapter (`*.g.dart`)
Automatisch generiert für Hive-Modelle (hive_ce):
```dart
@HiveType(typeId: 0)
class ServerModel {
@HiveField(0)
final String id;
}
```
## Generierung der Lokalisierung
```bash
flutter gen-l10n
```
Generiert `lib/generated/l10n/` aus `lib/l10n/*.arb` Dateien.
## Tipps
- Verwenden Sie `--delete-conflicting-outputs`, um Konflikte zu vermeiden.
- Fügen Sie generierte Dateien zur `.gitignore` hinzu.
- Bearbeiten Sie generierte Dateien niemals manuell.

115
docs/src/content/docs/de/development/state.md Normal file
View File

@@ -0,0 +1,115 @@
---
title: Zustandsverwaltung
description: Riverpod-basierte Zustandsverwaltungsmuster
---
Server Box verwendet Riverpod mit Codegenerierung für die Zustandsverwaltung.
## Provider-Typen
### StateProvider
Einfacher Zustand, der gelesen und geschrieben werden kann:
```dart
@riverpod
class Settings extends _$Settings {
@override
SettingsModel build() {
return SettingsModel.defaults();
}
void update(SettingsModel newSettings) {
state = newSettings;
}
}
```
### AsyncNotifierProvider
Zustand, der asynchron mit Lade-/Fehlerzuständen geladen wird:
```dart
@riverpod
class ServerStatus extends _$ServerStatus {
@override
Future<StatusModel> build(Server server) async {
return fetchStatus(server);
}
Future<void> refresh() async {
state = const AsyncValue.loading();
state = await AsyncValue.guard(() => fetchStatus(server));
}
}
```
### StreamProvider
Echtzeitdaten aus Streams:
```dart
@riverpod
Stream<CpuUsage> cpuUsage(CpuUsageRef ref, Server server) {
return cpuService.monitor(server);
}
```
## Zustandsmuster
### Ladezustände
```dart
state.when(
data: (data) => DataWidget(data),
loading: () => LoadingWidget(),
error: (error, stack) => ErrorWidget(error),
)
```
### Family Provider
Parametrisierte Provider:
```dart
@riverpod
List<Container> containers(ContainersRef ref, Server server) {
return containerService.list(server);
}
```
### Auto-Dispose
Provider, die verworfen werden, wenn sie nicht mehr referenziert werden:
```dart
@Riverpod(keepAlive: false)
class TempState extends _$TempState {
// ...
}
```
## Best Practices
1. **Codegenerierung nutzen**: Immer die `@riverpod` Annotation verwenden.
2. **Provider lokal platzieren**: In der Nähe der Widgets platzieren, die sie nutzen.
3. **Singletons vermeiden**: Stattdessen Provider verwenden.
4. **Korrekt schichten**: UI-Logik von Business-Logik getrennt halten.
## Zustand in Widgets lesen
```dart
class ServerWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final status = ref.watch(serverStatusProvider(server));
return status.when(...);
}
}
```
## Zustand ändern
```dart
ref.read(settingsProvider.notifier).update(newSettings);
```

96
docs/src/content/docs/de/development/structure.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Projektstruktur
description: Verständnis der Server Box Codebasis
---
Das Server Box-Projekt folgt einer modularen Architektur mit einer klaren Trennung der Belange.
## Verzeichnisstruktur
```
lib/
├── core/ # Kern-Dienstprogramme und Erweiterungen
├── data/ # Datenschicht
│ ├── model/ # Datenmodelle nach Funktionen
│ ├── provider/ # Riverpod Provider
│ └── store/ # Lokale Speicherung (Hive)
├── view/ # UI-Schicht
│ ├── page/ # Hauptseiten
│ └── widget/ # Wiederverwendbare Widgets
├── generated/ # Generierte Lokalisierung
├── l10n/ # Lokalisierungs-ARB-Dateien
└── hive/ # Hive-Adapter
```
## Kernschicht (`lib/core/`)
Enthält Dienstprogramme, Erweiterungen und Routing-Konfiguration:
- **Erweiterungen**: Dart-Erweiterungen für gängige Typen
- **Routen**: App-Routing-Konfiguration
- **Dienstprogramme**: Gemeinsame Hilfsfunktionen
## Datenschicht (`lib/data/`)
### Modelle (`lib/data/model/`)
Organisiert nach Funktionen:
- `server/` - Server-Verbindung und Status-Modelle
- `container/` - Docker-Container-Modelle
- `ssh/` - SSH-Sitzungs-Modelle
- `sftp/` - SFTP-Datei-Modelle
- `app/` - App-spezifische Modelle
### Provider (`lib/data/provider/`)
Riverpod Provider für Dependency Injection und Zustandsverwaltung:
- Server Provider
- UI-Zustands-Provider
- Service Provider
### Stores (`lib/data/store/`)
Hive-basierte lokale Speicherung:
- Server-Speicher
- Einstellungs-Speicher
- Cache-Speicher
## UI-Schicht (`lib/view/`)
### Seiten (`lib/view/page/`)
Hauptbildschirme der Anwendung:
- `server/` - Server-Verwaltungsseiten
- `ssh/` - SSH-Terminal-Seiten
- `container/` - Container-Seiten
- `setting/` - Einstellungsseiten
- `storage/` - SFTP-Seiten
- `snippet/` - Snippet-Seiten
### Widgets (`lib/view/widget/`)
Wiederverwendbare UI-Komponenten:
- Server-Karten
- Status-Diagramme
- Eingabe-Komponenten
- Dialoge
## Generierte Dateien
- `lib/generated/l10n/` - Automatisch generierte Lokalisierung
- `*.g.dart` - Generierter Code (json_serializable, freezed, hive, riverpod)
- `*.freezed.dart` - Unveränderliche Freezed-Klassen
## Verzeichnis "packages" (`/packages/`)
Enthält eigene Forks von Abhängigkeiten:
- `dartssh2/` - SSH-Bibliothek
- `xterm/` - Terminal-Emulator
- `fl_lib/` - Gemeinsame Dienstprogramme
- `fl_build/` - Build-System

113
docs/src/content/docs/de/development/testing.md Normal file
View File

@@ -0,0 +1,113 @@
---
title: Testen
description: Teststrategien und Ausführung von Tests
---
## Tests ausführen
```bash
# Alle Tests ausführen
flutter test
# Bestimmte Testdatei ausführen
flutter test test/battery_test.dart
# Mit Coverage ausführen
flutter test --coverage
```
## Teststruktur
Tests befinden sich im Verzeichnis `test/` und spiegeln die Struktur von `lib/` wider:
```
test/
├── data/
│ ├── model/
│ └── provider/
├── view/
│ └── widget/
└── test_helpers.dart
```
## Unit-Tests
Geschäftslogik und Datenmodelle testen:
```dart
test('sollte CPU-Prozentsatz berechnen', () {
final cpu = CpuModel(usage: 75.0);
expect(cpu.usagePercentage, '75%');
});
```
## Widget-Tests
UI-Komponenten testen:
```dart
testWidgets('ServerCard zeigt Servernamen an', (tester) async {
await tester.pumpWidget(
ProviderScope(
child: MaterialApp(
home: ServerCard(server: testServer),
),
),
);
expect(find.text('Test Server'), findsOneWidget);
});
```
## Provider-Tests
Riverpod Provider testen:
```dart
test('serverStatusProvider gibt Status zurück', () async {
final container = ProviderContainer();
final status = await container.read(serverStatusProvider(testServer).future);
expect(status, isA<StatusModel>());
});
```
## Mocking
Mocks für externe Abhängigkeiten verwenden:
```dart
class MockSshService extends Mock implements SshService {}
test('verbindet zum Server', () async {
final mockSsh = MockSshService();
when(mockSsh.connect(any)).thenAnswer((_) async => true);
// Test mit Mock
});
```
## Integrationstests
Komplette Benutzerabläufe testen (in `integration_test/`):
```dart
testWidgets('Server hinzufügen Ablauf', (tester) async {
await tester.pumpWidget(MyApp());
// Hinzufügen-Button tippen
await tester.tap(find.byIcon(Icons.add));
await tester.pumpAndSettle();
// Formular ausfüllen
await tester.enterText(find.byKey(Key('name')), 'Test Server');
// ...
});
```
## Best Practices
1. **Arrange-Act-Assert**: Tests klar strukturieren
2. **Beschreibende Namen**: Testnamen sollten das Verhalten beschreiben
3. **Eine Assertion pro Test**: Tests fokussiert halten
4. **Externe Abhängigkeiten mocken**: Nicht von echten Servern abhängig sein
5. **Grenzfälle testen**: Leere Listen, Null-Werte, usw.

46
docs/src/content/docs/de/index.mdx Normal file
View File

@@ -0,0 +1,46 @@
---
title: Server Box
description: Eine umfassende plattformübergreifende Server-Management-Anwendung
hero:
tagline: Verwalten Sie Ihre Linux-Server von überall aus
actions:
- text: Loslegen
link: /de/introduction/
icon: right-arrow
variant: primary
- text: Auf GitHub ansehen
link: https://github.com/lollipopkit/flutter_server_box
icon: github
variant: minimal
---
import { Card, CardGrid } from '@astrojs/starlight/components';
## Funktionen
<CardGrid stagger>
<Card title="Echtzeit-Überwachung" icon="chart">
Überwachen Sie CPU, Arbeitsspeicher, Festplatte, Netzwerk, GPU und Temperatur mit ansprechenden Echtzeit-Diagrammen.
</Card>
<Card title="SSH-Terminal" icon="terminal">
Voll ausgestattetes SSH-Terminal mit Multi-Tab-Unterstützung und virtueller Tastatur für mobile Geräte.
</Card>
<Card title="SFTP-Dateibrowser" icon="folder">
Verwalten Sie Dateien auf Ihren Servern mit dem integrierten SFTP-Client und dem lokalen Dateibrowser.
</Card>
<Card title="Docker-Verwaltung" icon="box">
Starten, stoppen und überwachen Sie Docker-Container mit einer intuitiven Benutzeroberfläche.
</Card>
<Card title="Plattformübergreifend" icon="device-mobile">
Verfügbar für iOS, Android, macOS, Linux, Windows und watchOS.
</Card>
<Card title="12+ Sprachen" icon="globe">
Vollständige Lokalisierungsunterstützung inklusive Englisch, Chinesisch, Deutsch, Französisch und mehr.
</Card>
</CardGrid>
## Quick-Links
- **Download**: Verfügbar im [App Store](https://apps.apple.com/app/id1586449703), auf [GitHub](https://github.com/lollipopkit/flutter_server_box/releases) und bei [F-Droid](https://f-droid.org/)
- **Dokumentation**: Entdecken Sie die Anleitungen für den Einstieg in die Server Box
- **Support**: Treten Sie unserer Community auf GitHub für Diskussionen und Probleme bei

51
docs/src/content/docs/de/installation.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
title: Installation
description: Laden Sie Server Box herunter und installieren Sie es auf Ihrem Gerät
---
Server Box ist für mehrere Plattformen verfügbar. Wählen Sie Ihre bevorzugte Installationsmethode.
## Mobile Apps
### iOS
Laden Sie es aus dem **[App Store](https://apps.apple.com/app/id1586449703)** herunter.
### Android
Wählen Sie Ihre bevorzugte Quelle:
- **[F-Droid](https://f-droid.org/)** – Für Benutzer, die reine FOSS-Quellen bevorzugen
- **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)** – Für die neueste Version direkt von der Quelle
## Desktop Apps
### macOS
Herunterladen von den **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
Funktionen:
- Native Menüleisten-Integration
- Unterstützung für sowohl Intel als auch Apple Silicon
### Linux
Herunterladen von den **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
Verfügbar als AppImage, deb oder tar.gz Pakete.
### Windows
Herunterladen von den **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
## watchOS
Verfügbar im **[App Store](https://apps.apple.com/app/id1586449703)** als Teil der iOS-App.
## Aus dem Quellcode bauen
Um Server Box aus dem Quellcode zu bauen, lesen Sie den Abschnitt [Bauen](/de/development/building/) in der Entwicklungsdokumentation.
## Versionsinformationen
Besuchen Sie die Seite [GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases) für die neueste Version und das Änderungsprotokoll.

32
docs/src/content/docs/de/introduction.mdx Normal file
View File

@@ -0,0 +1,32 @@
---
title: Einführung
description: Erfahren Sie, was Server Box ist und was es kann
---
Server Box ist eine umfassende plattformübergreifende Server-Management-Anwendung, die mit Flutter entwickelt wurde. Sie ermöglicht es Ihnen, Ihre Linux-, Unix- und Windows-Server von überall aus zu überwachen, zu verwalten und zu steuern.
## Was ist Server Box?
Server Box bietet eine einheitliche Oberfläche für Server-Administrationsaufgaben über SSH-Verbindungen. Egal, ob Sie Systemadministrator, Entwickler oder Hobbyist mit eigenen Heimservern sind – diese App bietet Ihnen leistungsstarke Server-Management-Tools direkt in Ihrer Tasche.
## Kernfunktionen
- **Echtzeit-Überwachung**: Verfolgen Sie CPU, Arbeitsspeicher, Festplattenbelegung, Netzwerkgeschwindigkeit, GPU-Status und Systemtemperaturen.
- **SSH-Terminal**: Voller Terminalzugriff mit Multi-Tab-Unterstützung und anpassbarem Erscheinungsbild.
- **SFTP-Client**: Durchsuchen und verwalten Sie Dateien auf Ihren Servern.
- **Docker-Verwaltung**: Steuern Sie Container mit Leichtigkeit.
- **Prozess-Management**: Systemprozesse anzeigen und verwalten.
- **Systemd-Dienste**: Systemd-Dienste starten, stoppen und überwachen.
- **Netzwerk-Tools**: iPerf-Tests, Ping und Wake-on-LAN.
- **Snippets**: Benutzerdefinierte Shell-Befehle speichern und ausführen.
## Unterstützte Plattformen
Server Box ist wahrhaft plattformübergreifend:
- **Mobil**: iOS und Android
- **Desktop**: macOS, Linux und Windows
## Lizenz
Dieses Projekt ist unter der AGPL v3 lizenziert. Der Quellcode ist auf [GitHub](https://github.com/lollipopkit/flutter_server_box) verfügbar.

80
docs/src/content/docs/de/platforms/desktop.md Normal file
View File

@@ -0,0 +1,80 @@
---
title: Desktop-Funktionen
description: Spezifische Funktionen für macOS, Linux und Windows
---
Server Box bietet auf Desktop-Plattformen zusätzliche Produktivitätsfunktionen.
## macOS
### Menüleisten-Integration
- Schneller Serverstatus in der Menüleiste
- Serverzugriff mit einem Klick
- Kompaktmodus für minimale Ablenkung
- Natives macOS-Menüleistenstyling
### Beständigkeit des Fensterzustands
- Merkt sich Fensterposition und -größe
- Wiederherstellung der vorherigen Sitzung beim Start
- Unterstützung für mehrere Monitore
### Native Funktionen
- **Titelleiste**: Option für benutzerdefinierte oder System-Titelleiste
- **Vollbildmodus**: Dedizierte Serverüberwachung
- **Tastenkombinationen**: macOS-native Tastenkürzel
- **Touch Bar** (unterstützte Geräte): Schnellaktionen
## Linux
### Native Integration
- Unterstützung für System-Tray
- Integration von Desktop-Benachrichtigungen
- Integration der Dateiauswahl
### Fensterverwaltung
- Unterstützung für X11 und Wayland
- Freundlich gegenüber Tiling-Window-Managern
- Option für benutzerdefinierte Fensterdekorationen
## Windows
### Funktionen
- System-Tray-Integration
- Jump List Schnellaktionen
- Native Fenstersteuerung
- Option für Autostart beim Booten
## Plattformübergreifende Desktop-Funktionen
### Tastenkombinationen
- **Cmd/Ctrl + N**: Neuer Server
- **Cmd/Ctrl + W**: Tab schließen
- **Cmd/Ctrl + T**: Neuer Terminal-Tab
- **Cmd/Ctrl + ,**: Einstellungen
### Themes
- Helles Theme
- Dunkles Theme
- AMOLED Theme (reines Schwarz)
- System-Theme (folgt dem Betriebssystem)
### Mehrere Fenster
- Öffnen mehrerer Server in separaten Fenstern
- Tabs in ein neues Fenster ziehen
- Serverstatistiken Seite an Seite vergleichen
### Vorteile gegenüber Mobile
- Größerer Bildschirm für die Überwachung
- Volle Tastatur für das Terminal
- Schnellere Dateioperationen
- Besseres Multitasking

77
docs/src/content/docs/de/platforms/mobile.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: Mobile Funktionen
description: Spezifische Funktionen für iOS und Android
---
Server Box bietet mehrere mobile-spezifische Funktionen für iOS- und Android-Geräte.
## Biometrische Authentifizierung
Sichern Sie Ihre Server mit biometrischer Authentifizierung:
- **iOS**: Face ID oder Touch ID
- **Android**: Fingerabdruck-Authentifizierung
Aktivieren Sie dies unter Einstellungen > Sicherheit > Biometrische Authentifizierung.
## Startbildschirm-Widgets
Fügen Sie Serverstatus-Widgets zu Ihrem Startbildschirm für eine schnelle Überwachung hinzu.
### iOS
- Auf den Startbildschirm lange drücken
- Auf **+** tippen, um ein Widget hinzuzufügen
- Nach "Server Box" suchen
- Widget-Größe wählen:
- Klein: Status eines einzelnen Servers
- Mittel: Mehrere Server
- Groß: Detaillierte Informationen
### Android
- Auf den Startbildschirm lange drücken
- Auf **Widgets** tippen
- "Server Box" finden
- Widget-Typ auswählen
## Hintergrundbetrieb
### Android
Verbindungen im Hintergrund aufrechterhalten:
- Aktivieren unter Einstellungen > Erweitert > Hintergrundbetrieb
- Erfordert Ausschluss von der Akku-Optimierung
- Permanente Benachrichtigungen für aktive Verbindungen
### iOS
Es gelten Hintergrundbeschränkungen:
- Verbindungen können im Hintergrund pausieren
- Schnelle Wiederverbindung bei Rückkehr zur App
- Unterstützung für Hintergrundaktualisierung
## Push-Benachrichtigungen
Erhalten Sie Benachrichtigungen für:
- Server-Offline-Alarme
- Warnungen bei hoher Ressourcenauslastung
- Alarme bei Abschluss von Aufgaben
Konfigurieren unter Einstellungen > Benachrichtigungen.
## Mobile UI-Funktionen
- **Pull to Refresh**: Serverstatus aktualisieren
- **Wischgesten**: Schnelle Serveroperationen
- **Querformat**: Besseres Terminal-Erlebnis
- **Virtuelle Tastatur**: Terminal-Shortcuts
## Datei-Integration
- **Dateien-App (iOS)**: Direkter SFTP-Zugriff aus Dateien
- **Storage Access Framework (Android)**: Dateien mit anderen Apps teilen
- **Dokumentenauswahl**: Einfache Dateiauswahl

214
docs/src/content/docs/de/principles/architecture.md Normal file
View File

@@ -0,0 +1,214 @@
---
title: Architektur-Übersicht
description: High-Level-Anwendungsarchitektur
---
Server Box folgt einer Schichtarchitektur mit klarer Trennung der Belange (Separation of Concerns).
## Architektur-Schichten
```
┌─────────────────────────────────────────────────┐
│ Präsentationsschicht (UI) │
│ lib/view/page/, lib/view/widget/ │
│ - Seiten, Widgets, Controller │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Business-Logik-Schicht │
│ lib/data/provider/ │
│ - Riverpod Provider, State Notifier │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Datenzugriffsschicht │
│ lib/data/store/, lib/data/model/ │
│ - Hive Stores, Datenmodelle │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Externe Integrationsschicht │
│ - SSH (dartssh2), Terminal (xterm), SFTP │
│ - Plattformspezifischer Code (iOS, Android etc.)│
└─────────────────────────────────────────────────┘
```
## Anwendungsgrundlagen
### Haupteinstiegspunkt
`lib/main.dart` initialisiert die App:
```dart
void main() {
runApp(
ProviderScope(
child: MyApp(),
),
);
}
```
### Root-Widget
`MyApp` bietet:
- **Theme-Management**: Umschalten zwischen hellem/dunklem Theme
- **Routing-Konfiguration**: Navigationsstruktur
- **Provider Scope**: Wurzel für Dependency Injection
### Startseite
`HomePage` dient als Navigationszentrum:
- **Tab-Interface**: Server, Snippet, Container, SSH
- **Zustandsverwaltung**: Zustand pro Tab
- **Navigation**: Funktionszugriff
## Kernsysteme
### Zustandsverwaltung: Riverpod
**Warum Riverpod?**
- Sicherheit zur Kompilierzeit
- Einfache Testbarkeit
- Keine Abhängigkeit vom Build-Kontext
- Funktioniert plattformübergreifend
**Verwendete Provider-Typen:**
- `StateProvider`: Einfacher veränderlicher Zustand
- `AsyncNotifierProvider`: Lade-/Fehler-/Datenzustände
- `StreamProvider`: Echtzeit-Datenströme
- Future Provider: Einmalige asynchrone Operationen
### Datenpersistenz: Hive CE
**Warum Hive CE?**
- Keine Abhängigkeiten von nativem Code
- Schneller Key-Value-Speicher
- Typsicher durch Codegenerierung
- Keine manuellen Feld-Annotationen erforderlich
**Stores:**
- `SettingStore`: App-Einstellungen
- `ServerStore`: Server-Konfigurationen
- `SnippetStore`: Befehls-Snippets
- `KeyStore`: SSH-Schlüssel
### Immutable Modelle: Freezed
**Vorteile:**
- Unveränderlichkeit zur Kompilierzeit
- Union Types für Zustände
- Integrierte JSON-Serialisierung
- CopyWith-Erweiterungen
## Cross-Plattform-Strategie
### Plugin-System
Flutter-Plugins ermöglichen die Plattformintegration:
| Plattform | Integrationsmethode |
|-----------|--------------------|
| iOS | CocoaPods, Swift/Obj-C |
| Android | Gradle, Kotlin/Java |
| macOS | CocoaPods, Swift |
| Linux | CMake, C++ |
| Windows | CMake, C# |
### Plattformspezifische Funktionen
**Nur iOS:**
- Startbildschirm-Widgets
- Live-Aktivitäten
- Apple Watch Begleit-App
**Nur Android:**
- Hintergrunddienst
- Push-Benachrichtigungen
- Dateisystemzugriff
**Nur Desktop:**
- Menüleisten-Integration
- Mehrere Fenster
- Benutzerdefinierte Titelleiste
## Eigene Abhängigkeiten
### dartssh2 Fork
Erweiterter SSH-Client mit:
- Besserer mobiler Unterstützung
- Verbesserter Fehlerbehandlung
- Leistungsoptimierungen
### xterm.dart Fork
Terminal-Emulator mit:
- Für Mobilgeräte optimiertem Rendering
- Unterstützung für Touch-Gesten
- Integration der virtuellen Tastatur
### fl_lib
Paket mit gemeinsamen Dienstprogrammen:
- Gemeinsame Widgets
- Erweiterungen
- Hilfsfunktionen
## Build-System
### fl_build Paket
Eigenes Build-System für:
- Multi-Plattform-Builds
- Code-Signierung
- Asset-Bündelung
- Versionsverwaltung
### Build-Prozess
```
make.dart (Version) → fl_build (Build) → Plattform-Output
```
1. **Pre-build**: Berechnung der Version aus Git
2. **Build**: Kompilierung für die Zielplattform
3. **Post-build**: Paketierung und Signierung
## Beispiel für den Datenfluss
### Aktualisierung des Serverstatus
```
1. Timer löst aus →
2. Provider ruft Service auf →
3. Service führt SSH-Befehl aus →
4. Antwort wird in Modell geparst →
5. Zustand wird aktualisiert →
6. UI wird mit neuen Daten neu aufgebaut
```
### Ablauf einer Benutzeraktion
```
1. Benutzer tippt auf Schaltfläche →
2. Widget ruft Provider-Methode auf →
3. Provider aktualisiert Zustand →
4. Zustandsänderung löst Neuaufbau aus →
5. Neuer Zustand spiegelt sich in der UI wider
```
## Sicherheitsarchitektur
### Datenschutz
- **Passwörter**: Verschlüsselt mit flutter_secure_storage
- **SSH-Schlüssel**: Verschlüsselt gespeichert
- **Host-Fingerabdrücke**: Sicher gespeichert
- **Sitzungsdaten**: Werden nicht persistiert
### Verbindungssicherheit
- **Host-Key-Verifizierung**: MITM-Erkennung
- **Verschlüsselung**: Standard-SSH-Verschlüsselung
- **Kein Klartext**: Sensible Daten werden niemals im Klartext gespeichert

490
docs/src/content/docs/de/principles/sftp.md Normal file
View File

@@ -0,0 +1,490 @@
---
title: SFTP-System
description: Wie der SFTP-Dateibrowser funktioniert
---
Das SFTP-System bietet Dateimanagement-Funktionen über SSH.
## Architektur
```
┌─────────────────────────────────────────────┐
│ SFTP UI Schicht │
│ - Dateibrowser (remote) │
│ - Dateibrowser (lokal) │
│ - Transfer-Warteschlange │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ SFTP-Zustandsverwaltung │
│ - sftpProvider │
│ - Pfadverwaltung │
│ - Operations-Warteschlange │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ SFTP-Protokollschicht │
│ - SSH-Subsystem │
│ - Dateioperationen │
│ - Verzeichnisauflistung │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ SSH-Transport │
│ - Sicherer Kanal │
│ - Daten-Streaming │
└─────────────────────────────────────────────┘
```
## Verbindungsaufbau
### Erstellung des SFTP-Clients
```dart
Future<SftpClient> createSftpClient(Spi spi) async {
// 1. SSH-Client abrufen (wiederverwenden, falls verfügbar)
final sshClient = await genClient(spi);
// 2. SFTP-Subsystem öffnen
final sftp = await sshClient.openSftp();
return sftp;
}
```
### Wiederverwendung von Verbindungen
SFTP verwendet bestehende SSH-Verbindungen wieder:
```dart
class ServerProvider {
SSHClient? _sshClient;
SftpClient? _sftpClient;
Future<SftpClient> getSftpClient(String spiId) async {
_sftpClient ??= await _sshClient!.openSftp();
return _sftpClient!;
}
}
```
## Dateisystem-Operationen
### Verzeichnisauflistung
```dart
Future<List<SftpFile>> listDirectory(String path) async {
final sftp = await getSftpClient(spiId);
// Verzeichnis auflisten
final files = await sftp.listDir(path);
// Basierend auf Einstellungen sortieren
files.sort((a, b) {
switch (sortOption) {
case SortOption.name:
return a.name.toLowerCase().compareTo(b.name.toLowerCase());
case SortOption.size:
return a.size.compareTo(b.size);
case SortOption.time:
return a.modified.compareTo(b.modified);
}
});
// Ordner zuerst, falls aktiviert
if (showFoldersFirst) {
final dirs = files.where((f) => f.isDirectory);
final regular = files.where((f) => !f.isDirectory);
return [...dirs, ...regular];
}
return files;
}
```
### Dateimetadaten
```dart
class SftpFile {
final String name;
final String path;
final int size; // Bytes
final int modified; // Unix-Zeitstempel
final String permissions; // z.B. "rwxr-xr-x"
final String owner;
final String group;
final bool isDirectory;
final bool isSymlink;
String get sizeFormatted => formatBytes(size);
String get modifiedFormatted => formatDate(modified);
}
```
## Dateioperationen
### Hochladen
```dart
Future<void> uploadFile(
String localPath,
String remotePath,
) async {
final sftp = await getSftpClient(spiId);
// Anfrage erstellen
final req = SftpReq(
spi: spi,
remotePath: remotePath,
localPath: localPath,
type: SftpReqType.upload,
);
// Zur Warteschlange hinzufügen
_transferQueue.add(req);
// Transfer mit Fortschritt ausführen
final file = File(localPath);
final size = await file.length();
final stream = file.openRead();
await sftp.upload(
stream: stream,
toPath: remotePath,
onProgress: (transferred) {
_updateProgress(req, transferred, size);
},
);
// Fertigstellen
_transferQueue.remove(req);
}
```
### Herunterladen
```dart
Future<void> downloadFile(
String remotePath,
String localPath,
) async {
final sftp = await getSftpClient(spiId);
// Lokale Datei erstellen
final file = File(localPath);
final sink = file.openWrite();
// Herunterladen mit Fortschritt
final stat = await sftp.stat(remotePath);
await sftp.download(
fromPath: remotePath,
toSink: sink,
onProgress: (transferred) {
_updateProgress(
SftpReq(...),
transferred,
stat.size,
);
},
);
await sink.close();
}
```
### Berechtigungen bearbeiten
```dart
Future<void> setPermissions(
String path,
String permissions,
) async {
final sftp = await getSftpClient(spiId);
// Berechtigungen parsen (z.B. "rwxr-xr-x" oder "755")
final mode = parsePermissions(permissions);
// Über SSH-Befehl setzen (zuverlässiger als SFTP)
final ssh = await getSshClient(spiId);
await ssh.exec('chmod $mode "$path"');
}
```
## Pfadverwaltung
### Pfadstruktur
```dart
class PathWithPrefix {
final String prefix; // z.B. "/home/user"
final String path; // Relativ oder absolut
String get fullPath {
if (path.startsWith('/')) {
return path; // Absoluter Pfad
}
return '$prefix/$path'; // Relativer Pfad
}
PathWithPrefix cd(String subPath) {
return PathWithPrefix(
prefix: fullPath,
path: subPath,
);
}
}
```
### Navigationsverlauf
```dart
class PathHistory {
final List<String> _history = [];
int _index = -1;
void push(String path) {
// Vorwärtsverlauf entfernen
_history.removeRange(_index + 1, _history.length);
_history.add(path);
_index = _history.length - 1;
}
String? back() {
if (_index > 0) {
_index--;
return _history[_index];
}
return null;
}
String? forward() {
if (_index < _history.length - 1) {
_index++;
return _history[_index];
}
return null;
}
}
```
## Transfersystem
### Transfer-Anfrage
```dart
class SftpReq {
final Spi spi;
final String remotePath;
final String localPath;
final SftpReqType type;
final DateTime createdAt;
int? totalBytes;
int? transferredBytes;
String? error;
}
```
### Fortschrittsverfolgung
```dart
class TransferProgress {
final SftpReq request;
final int total;
final int transferred;
final DateTime startTime;
double get percentage => (transferred / total) * 100;
Duration get elapsed => DateTime.now().difference(startTime);
String get speedFormatted {
final bytesPerSecond = transferred / elapsed.inSeconds;
return formatSpeed(bytesPerSecond);
}
}
```
### Warteschlangen-Management
```dart
class TransferQueue {
final List<SftpReq> _queue = [];
final Map<String, TransferProgress> _progress = {};
int _concurrent = 3; // Max. gleichzeitige Transfers
Future<void> process() async {
final active = _progress.values.where((p) => p.isInProgress);
if (active.length >= _concurrent) return;
final pending = _queue.where((r) => !_progress.containsKey(r.id));
for (final req in pending.take(_concurrent - active.length)) {
_executeTransfer(req);
}
}
Future<void> _executeTransfer(SftpReq req) async {
try {
_progress[req.id] = TransferProgress.inProgress(req);
if (req.type == SftpReqType.upload) {
await uploadFile(req.localPath, req.remotePath);
} else {
await downloadFile(req.remotePath, req.localPath);
}
_progress[req.id] = TransferProgress.completed(req);
} catch (e) {
_progress[req.id] = TransferProgress.failed(req, e);
}
}
}
```
## Lokales Speichermuster
### Download-Cache
Heruntergeladene Dateien werden gespeichert unter:
```dart
String getLocalDownloadPath(String spiId, String remotePath) {
final normalized = remotePath.replaceAll('/', '_');
return 'Paths.file/$spiId/$normalized';
}
```
Beispiel:
- Remote: `/var/log/nginx/access.log`
- spiId: `server-123`
- Lokal: `Paths.file/server-123/_var_log_nginx_access.log`
## Dateibearbeitung
### Bearbeitungs-Workflow
```dart
Future<void> editFile(String path) async {
final sftp = await getSftpClient(spiId);
// 1. Größe prüfen
final stat = await sftp.stat(path);
if (stat.size > editorMaxSize) {
showWarning('Datei zu groß für den integrierten Editor');
return;
}
// 2. Temporär herunterladen
final temp = await downloadToTemp(path);
// 3. Im Editor öffnen
final content = await openEditor(temp.path);
// 4. Zurück hochladen
await uploadFile(temp.path, path);
// 5. Aufräumen
await temp.delete();
}
```
### Integration externer Editoren
```dart
Future<void> editInExternalEditor(String path) async {
final ssh = await getSshClient(spiId);
// Terminal mit Editor öffnen
final editor = getSetting('sftpEditor', 'vim');
await ssh.exec('$editor "$path"');
// Benutzer bearbeitet im Terminal
// Nach dem Speichern die SFTP-Ansicht aktualisieren
}
```
## Fehlerbehandlung
### Berechtigungsfehler
```dart
try {
await sftp.upload(...);
} on SftpPermissionException {
showError('Berechtigung verweigert: ${stat.path}');
showHint('Prüfen Sie Dateiberechtigungen und Eigentümerschaft');
}
```
### Verbindungsfehler
```dart
try {
await sftp.listDir(path);
} on SftpConnectionException {
showError('Verbindung verloren');
await reconnect();
}
```
### Speicherplatzfehler
```dart
try {
await sftp.upload(...);
} on SftpNoSpaceException {
showError('Festplatte auf dem Remote-Server voll');
}
```
## Leistungsoptimierungen
### Verzeichnis-Caching
```dart
class DirectoryCache {
final Map<String, CachedDirectory> _cache = {};
final Duration ttl = Duration(minutes: 5);
Future<List<SftpFile>> list(String path) async {
final cached = _cache[path];
if (cached != null && !cached.isExpired) {
return cached.files;
}
final files = await sftp.listDir(path);
_cache[path] = CachedDirectory(files);
return files;
}
}
```
### Lazy Loading
Für große Verzeichnisse (>1000 Einträge):
```dart
List<SftpFile> loadPage(String path, int page, int pageSize) {
final all = cache[path] ?? [];
final start = page * pageSize;
final end = start + pageSize;
return all.sublist(start, end.clamp(0, all.length));
}
```
### Paginierung
```dart
class PaginatedDirectory {
static const pageSize = 100;
Future<List<SftpFile>> getPage(int page) async {
final offset = page * pageSize;
return await sftp.listDir(
path,
offset: offset,
limit: pageSize,
);
}
}
```

305
docs/src/content/docs/de/principles/ssh.md Normal file
View File

@@ -0,0 +1,305 @@
---
title: SSH-Verbindung
description: Wie SSH-Verbindungen aufgebaut und verwaltet werden
---
Verständnis der SSH-Verbindungen in Server Box.
## Verbindungsablauf
```text
Benutzereingabe → Spi-Konfiguration → genClient() → SSH-Client → Sitzung
```
### Schritt 1: Konfiguration
Das `Spi` (Server Parameter Info) Modell enthält:
```dart
class Spi {
String id; // eindeutige ID / unique identifier
String name; // Servername
String ip; // IP-Adresse
int port; // SSH-Port (Standard 22)
String user; // Benutzername
String? pwd; // Passwort (verschlüsselt)
String? keyId; // SSH-Schlüssel-ID
String? jumpId; // Jump-Server-ID
String? alterUrl; // Alternative URL
}
```
### Schritt 2: Client-Generierung
`genClient(spi)` erstellt den SSH-Client:
```dart
Future<SSHClient> genClient(Spi spi) async {
// 1. Socket aufbauen
var socket = await connect(spi.ip, spi.port);
// 2. Alternative URL versuchen, falls fehlgeschlagen
if (socket == null && spi.alterUrl != null) {
socket = await connect(spi.alterUrl, spi.port);
}
if (socket == null) {
throw ConnectionException('Unable to connect');
}
// 3. Authentifizieren
final client = SSHClient(
socket: socket,
username: spi.user,
onPasswordRequest: () => spi.pwd,
onIdentityRequest: () => loadKey(spi.keyId),
);
// 4. Host-Key verifizieren
await verifyHostKey(client, spi);
return client;
}
```
### Schritt 3: Jump-Server (falls konfiguriert)
Für Jump-Server, rekursive Verbindung:
```dart
if (spi.jumpId != null) {
final jumpClient = await genClient(getJumpSpi(spi.jumpId));
final forwarded = await jumpClient.forwardLocal(
spi.ip,
spi.port,
);
// Über weitergeleiteten Socket verbinden
}
```
## Authentifizierungsmethoden
### Passwort-Authentifizierung
```dart
onPasswordRequest: () => spi.pwd
```
- Passwort verschlüsselt in Hive gespeichert
- Bei Verbindung entschlüsselt
- Zur Verifizierung an den Server gesendet
### Private-Key-Authentifizierung
```dart
onIdentityRequest: () async {
final key = await KeyStore.get(spi.keyId);
return decyptPem(key.pem, key.password);
}
```
**Schlüssel-Ladeprozess:**
1. Verschlüsselten Schlüssel aus `KeyStore` abrufen
2. Passwort entschlüsseln (Biometrie/Eingabeaufforderung)
3. PEM-Format parsen
4. Zeilenenden standardisieren (LF)
5. Zur Authentifizierung zurückgeben
### Tastatur-Interaktiv (Keyboard-Interactive)
```dart
onUserInfoRequest: (instructions) async {
// Challenge-Response handhaben
return responses;
}
```
Unterstützt:
- Passwort-Authentifizierung
- OTP-Token
- Zwei-Faktor-Authentifizierung (2FA)
## Host-Key-Verifizierung
### Warum Host-Keys verifizieren?
Verhindert **Man-in-the-Middle (MITM)** Angriffe, indem sichergestellt wird, dass Sie sich mit demselben Server verbinden.
### Speicherformat
```text
{spi.id}::{keyType}
```
Beispiel:
```text
mein-server::ssh-ed25519
mein-server::ecdsa-sha2-nistp256
```
### Fingerabdruck-Formate
**MD5 Hex:**
```text
aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
```
**Base64:**
```text
SHA256:AbCdEf1234567890...=
```
### Verifizierungsablauf
```dart
Future<void> verifyHostKey(SSHClient client, Spi spi) async {
final key = await client.hostKey;
final keyType = key.type;
final fingerprint = md5Hex(key); // oder base64
final stored = SettingStore.sshKnownHostsFingerprints
['${spi.id}::$keyType'];
if (stored == null) {
// Neuer Host - Benutzer fragen
final trust = await promptUser(
'Unbekannter Host',
'Fingerabdruck: $fingerprint',
);
if (trust) {
SettingStore.sshKnownHostsFingerprints
['${spi.id}::$keyType'] = fingerprint;
}
} else if (stored != fingerprint) {
// Geändert - Benutzer warnen
await warnUser(
'Host-Key geändert!',
'Möglicher MITM-Angriff',
);
}
}
```
## Sitzungsverwaltung
### Verbindungs-Pooling
Aktive Clients werden im `ServerProvider` verwaltet:
```dart
class ServerProvider {
final Map<String, SSHClient> _clients = {};
SSHClient getClient(String spiId) {
return _clients[spiId] ??= connect(spiId);
}
}
```
### Keep-Alive
Verbindung bei Inaktivität aufrechterhalten:
```dart
Timer.periodic(
Duration(seconds: 30),
(_) => client.sendKeepAlive(),
);
```
### Automatische Wiederverbindung
Bei Verbindungsverlust:
```dart
client.onError.listen((error) async {
await Future.delayed(Duration(seconds: 5));
reconnect();
});
```
## Lebenszyklus einer Verbindung
```text
┌─────────────┐
│ Initial │
└──────┬──────┘
│ connect()
↓
┌─────────────┐
│ Verbinden │ ←──┐
└──────┬──────┘ │
│ Erfolg │
↓ │ Fehler (Retry)
┌─────────────┐ │
│ Verbunden │───┘
└──────┬──────┘
│
↓
┌─────────────┐
│ Aktiv │ ──→ Befehle senden
└──────┬──────┘
│
↓ (Fehler/Trennung)
┌─────────────┐
│ Getrennt │
└─────────────┘
```
## Fehlerbehandlung
### Verbindungs-Timeout
```dart
try {
await client.connect().timeout(
Duration(seconds: 30),
);
} on TimeoutException {
throw ConnectionException('Verbindungs-Timeout');
}
```
### Authentifizierungsfehler
```dart
onAuthFail: (error) {
if (error.contains('password')) {
return 'Ungültiges Passwort';
} else if (error.contains('key')) {
return 'Ungültiger SSH-Schlüssel';
}
return 'Authentifizierung fehlgeschlagen';
}
```
### Host-Key-Abweichung
```dart
onHostKeyMismatch: (stored, current) {
showSecurityWarning(
'Host-Key hat sich geändert!',
'Möglicher MITM-Angriff',
);
}
```
## Leistungsaspekte
### Wiederverwendung von Verbindungen
- Wiederverwendung von Clients über Funktionen hinweg
- Nicht unnötig trennen/wiederverbinden
- Verbindungs-Pooling für gleichzeitige Operationen
### Optimale Einstellungen
- **Timeout**: 30 Sekunden (anpassbar)
- **Keep-Alive**: Alle 30 Sekunden
- **Wiederholungsverzögerung**: 5 Sekunden
### Netzwerkeffizienz
- Einzelne Verbindung für mehrere Operationen
- Befehle pipelinen, wenn möglich
- Das Öffnen mehrerer Verbindungen vermeiden

221
docs/src/content/docs/de/principles/state.md Normal file
View File

@@ -0,0 +1,221 @@
---
title: Zustandsverwaltung
description: Wie der Zustand mit Riverpod verwaltet wird
---
Verständnis der Architektur zur Zustandsverwaltung in Server Box.
## Warum Riverpod?
**Hauptvorteile:**
- **Sicherheit zur Kompilierzeit**: Fehler werden bereits beim Kompilieren abgefangen
- **Kein BuildContext erforderlich**: Zugriff auf den Zustand von überall aus
- **Einfache Testbarkeit**: Provider können leicht isoliert getestet werden
- **Codegenerierung**: Weniger Boilerplate, typsicher
## Provider-Architektur
```
┌─────────────────────────────────────────────┐
│ UI-Schicht (Widgets) │
│ - ConsumerWidget / ConsumerStatefulWidget │
│ - ref.watch() / ref.read() │
└─────────────────────────────────────────────┘
↓ beobachtet (watches)
┌─────────────────────────────────────────────┐
│ Provider-Schicht │
│ - @riverpod Annotationen │
│ - Generierte *.g.dart Dateien │
└─────────────────────────────────────────────┘
↓ nutzt (uses)
┌─────────────────────────────────────────────┐
│ Service- / Store-Schicht │
│ - Business-Logik │
│ - Datenzugriff │
└─────────────────────────────────────────────┘
```
## Verwendete Provider-Typen
### 1. StateProvider (Einfacher Zustand)
Für einfachen, beobachtbaren Zustand:
```dart
@riverpod
class ThemeNotifier extends _$ThemeNotifier {
@override
ThemeMode build() {
// Aus Einstellungen laden
return SettingStore.themeMode;
}
void setTheme(ThemeMode mode) {
state = mode;
SettingStore.themeMode = mode; // Persistieren
}
}
```
**Verwendung:**
```dart
class MyWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final theme = ref.watch(themeNotifierProvider);
return Text('Theme: $theme');
}
}
```
### 2. AsyncNotifierProvider (Asynchroner Zustand)
Für Daten, die asynchron geladen werden:
```dart
@riverpod
class ServerStatus extends _$ServerStatus {
@override
Future<StatusModel> build(Server server) async {
// Initiales Laden
return await fetchStatus(server);
}
Future<void> refresh() async {
state = const AsyncValue.loading();
state = await AsyncValue.guard(() async {
return await fetchStatus(server);
});
}
}
```
**Verwendung:**
```dart
final status = ref.watch(serverStatusProvider(server));
status.when(
data: (data) => StatusWidget(data),
loading: () => LoadingWidget(),
error: (error, stack) => ErrorWidget(error),
)
```
### 3. StreamProvider (Echtzeit-Daten)
Für kontinuierliche Datenströme:
```dart
@riverpod
Stream<CpuUsage> cpuUsage(CpuUsageRef ref, Server server) {
final client = ref.watch(sshClientProvider(server));
final stream = client.monitorCpu();
// Ressourcen freigeben, wenn nicht mehr beobachtet
ref.onDispose(() {
client.stopMonitoring();
});
return stream;
}
```
**Verwendung:**
```dart
final cpu = ref.watch(cpuUsageProvider(server));
cpu.when(
data: (usage) => CpuChart(usage),
loading: () => CircularProgressIndicator(),
error: (error, stack) => ErrorWidget(error),
)
```
### 4. Family Provider (Parametrisiert)
Provider, die Parameter akzeptieren:
```dart
@riverpod
Future<List<Container>> containers(ContainersRef ref, Server server) async {
final client = await ref.watch(sshClientProvider(server).future);
return await client.listContainers();
}
```
**Verwendung:**
```dart
final containers = ref.watch(containersProvider(server));
// Verschiedene Server = verschiedene gecachte Zustände
final containers2 = ref.watch(containersProvider(server2));
```
## Muster für Zustandsaktualisierungen
### Direkte Zustandsaktualisierung
```dart
ref.read(settingsProvider.notifier).updateTheme(darkMode);
```
### Berechneter Zustand (Computed State)
```dart
@riverpod
int totalServers(TotalServersRef ref) {
final servers = ref.watch(serversProvider);
return servers.length;
}
```
### Abgeleiteter Zustand (Derived State)
```dart
@riverpod
List<Server> onlineServers(OnlineServersRef ref) {
final all = ref.watch(serversProvider);
return all.where((s) => s.isOnline).toList();
}
```
## Server-spezifischer Zustand
### Pro-Server Provider
Jeder Server hat einen isolierten Zustand:
```dart
@riverpod
class ServerProvider extends _$ServerProvider {
@override
ServerState build(Server server) {
return ServerState.disconnected();
}
Future<void> connect() async {
state = ServerState.connecting();
try {
final client = await genClient(server.spi);
state = ServerState.connected(client);
} catch (e) {
state = ServerState.error(e.toString());
}
}
}
```
## Leistungsoptimierungen
- **Provider Keep-Alive**: `@Riverpod(keepAlive: true)` verwenden, um automatische Entsorgung ohne Listener zu verhindern.
- **Selektives Beobachten**: `select` verwenden, um nur bestimmte Teile des Zustands zu beobachten.
- **Provider Caching**: Family Provider cachen Ergebnisse pro Parameter.
## Best Practices
1. **Provider lokal platzieren**: In der Nähe der Widgets, die sie nutzen.
2. **Codegenerierung nutzen**: Immer `@riverpod` verwenden.
3. **Provider fokussiert halten**: Jedes Provider sollte nur eine Aufgabe haben.
4. **Ladezustände behandeln**: AsyncValue-Zustände immer vollständig behandeln.
5. **Ressourcen entsorgen**: `ref.onDispose()` für Aufräumarbeiten nutzen.
6. **Tiefe Provider-Bäume vermeiden**: Den Provider-Graphen flach halten.

198
docs/src/content/docs/de/principles/terminal.md Normal file
View File

@@ -0,0 +1,198 @@
---
title: Terminal-Implementierung
description: Wie das SSH-Terminal intern funktioniert
---
Das SSH-Terminal ist eine der komplexesten Funktionen, aufgebaut auf einem benutzerdefinierten xterm.dart-Fork.
## Architektur-Übersicht
```
┌─────────────────────────────────────────────┐
│ Terminal UI Schicht │
│ - Tab-Management │
│ - Virtuelle Tastatur │
│ - Textauswahl │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ xterm.dart Emulator │
│ - PTY (Pseudo Terminal) │
│ - VT100/ANSI Emulation │
│ - Rendering-Engine │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ SSH-Client-Schicht │
│ - SSH-Sitzung │
│ - Kanalverwaltung │
│ - Daten-Streaming │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Remote-Server │
│ - Shell-Prozess │
│ - Befehlsausführung │
└─────────────────────────────────────────────┘
```
## Lebenszyklus einer Terminal-Sitzung
### 1. Sitzungserstellung
```dart
Future<TerminalSession> createSession(Spi spi) async {
// 1. SSH-Client abrufen
final client = await genClient(spi);
// 2. PTY erstellen
final pty = await client.openPty(
term: 'xterm-256color',
cols: 80,
rows: 24,
);
// 3. Terminal-Emulator initialisieren
final terminal = Terminal(
backend: PtyBackend(pty),
);
// 4. Resize-Handler einrichten
terminal.onResize.listen((size) {
pty.resize(size.cols, size.rows);
});
return TerminalSession(
terminal: terminal,
pty: pty,
client: client,
);
}
```
### 2. Terminal-Emulation
Der xterm.dart-Fork bietet:
**VT100/ANSI Emulation:**
- Cursor-Bewegung
- Farben (256-Farben-Unterstützung)
- Textattribute (fett, unterstrichen, usw.)
- Scroll-Bereiche
- Alternativer Bildschirmpuffer
**Rendering:**
- Zeilenbasiertes Rendering
- Unterstützung für bidirektionalen Text
- Unicode/Emoji Unterstützung
- Optimierte Redraws
### 3. Datenfluss
```
Benutzereingabe
↓
Virtuelle Tastatur / Physische Tastatur
↓
Terminal-Emulator (Taste → Escape-Sequenz)
↓
SSH-Kanal (senden)
↓
Remote PTY
↓
Remote Shell
↓
Befehlsausgabe
↓
SSH-Kanal (empfangen)
↓
Terminal-Emulator (Analyse von ANSI-Codes)
↓
Rendering auf dem Bildschirm
```
## Multi-Tab System
### Tab-Management
Tabs behalten ihren Zustand bei Navigationswechseln bei:
- SSH-Verbindung bleibt aktiv
- Terminalzustand bleibt erhalten
- Scroll-Puffer bleibt bestehen
- Eingabeverlauf bleibt erhalten
## Virtuelle Tastatur
### Plattformspezifische Implementierung
**iOS:**
- UIView-basierte benutzerdefinierte Tastatur
- Umschaltbar mit Tastatur-Button
- Automatisches Ein-/Ausblenden basierend auf dem Fokus
**Android:**
- Benutzerdefinierte Eingabemethode
- Integriert in die Systemtastatur
- Schnellaktionstasten
### Tastatur-Buttons
| Button | Aktion |
|--------|--------|
| **Umschalten** | Systemtastatur ein-/ausblenden |
| **Ctrl** | Ctrl-Modifikator senden |
| **Alt** | Alt-Modifikator senden |
| **SFTP** | Aktuelles Verzeichnis öffnen |
| **Zwischenablage** | Kontextsensitive Kopieren/Einfügen |
| **Snippets** | Snippet ausführen |
## Textauswahl
1. **Langes Drücken**: Auswahlmodus aktivieren
2. **Ziehen**: Auswahl erweitern
3. **Loslassen**: In die Zwischenablage kopieren
## Schriftart und Dimensionen
### Größenberechnung
```dart
class TerminalDimensions {
static Size calculate(double fontSize, Size screenSize) {
final charWidth = fontSize * 0.6; // Monospace-Seitenverhältnis
final charHeight = fontSize * 1.2;
final cols = (screenSize.width / charWidth).floor();
final rows = (screenSize.height / charHeight).floor();
return Size(cols.toDouble(), rows.toDouble());
}
}
```
### Pinch-to-Zoom
```dart
GestureDetector(
onScaleStart: () => _baseFontSize = currentFontSize,
onScaleUpdate: (details) {
final newFontSize = _baseFontSize * details.scale;
resize(newFontSize);
},
)
```
## Farbschema
- **Hell (Light)**: Heller Hintergrund, dunkler Text
- **Dunkel (Dark)**: Dunkler Hintergrund, heller Text
- **AMOLED**: Rein schwarzer Hintergrund
## Leistungsoptimierungen
- **Dirty Rectangle**: Nur geänderte Regionen neu zeichnen
- **Zeilen-Caching**: Gerenderte Zeilen cachen
- **Lazy Scrolling**: Virtuelles Scrollen für lange Puffer
- **Batch-Updates**: Mehrere Schreibvorgänge zusammenfassen
- **Kompression**: Kompression des Scroll-Puffers
- **Debouncing**: Debouncing für schnelle Eingaben

45
docs/src/content/docs/de/quick-start.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: Schnellstart
description: In wenigen Minuten mit Server Box loslegen
---
Folgen Sie dieser Schnellstartanleitung, um sich mit Ihrem ersten Server zu verbinden und mit der Überwachung zu beginnen.
## Schritt 1: Einen Server hinzufügen
1. Öffnen Sie Server Box
2. Tippen Sie auf die Schaltfläche **+**, um einen neuen Server hinzuzufügen
3. Geben Sie die Serverinformationen ein:
- **Name**: Ein Anzeigename für Ihren Server
- **Host**: IP-Adresse oder Domainname
- **Port**: SSH-Port (Standard: 22)
- **Benutzer**: SSH-Benutzername
- **Passwort oder Schlüssel**: Authentifizierungsmethode
4. Tippen Sie auf **Speichern**, um den Server hinzuzufügen
## Schritt 2: Verbinden und Überwachen
1. Tippen Sie auf Ihre Serverkarte, um die Verbindung herzustellen
2. Die App baut eine SSH-Verbindung auf
3. Sie sehen den Echtzeit-Status für:
- CPU-Auslastung
- Arbeitsspeicher (RAM) und Swap
- Festplattenbelegung
- Netzwerkgeschwindigkeit
## Schritt 3: Funktionen erkunden
Sobald die Verbindung hergestellt ist, können Sie:
- **Terminal öffnen**: Tippen Sie auf die Terminal-Schaltfläche für vollen SSH-Zugriff
- **Dateien durchsuchen**: Verwenden Sie SFTP, um Dateien zu verwalten
- **Container verwalten**: Docker-Container anzeigen und steuern
- **Prozesse anzeigen**: Laufende Prozesse überprüfen
- **Snippets ausführen**: Gespeicherte Befehle ausführen
## Tipps
- **Biometrische Authentifizierung**: Aktivieren Sie Face ID / Touch ID / Fingerabdruck für schnellen Zugriff (Mobilgerät)
- **Startbildschirm-Widgets**: Fügen Sie Serverstatus-Widgets zu Ihrem Startbildschirm hinzu (iOS/Android)
- **Hintergrundbetrieb**: Halten Sie Verbindungen im Hintergrund aktiv (Android)

2
docs/src/content/docs/development/architecture.md
View File

@@ -3,7 +3,7 @@ title: Architecture
description: Architecture patterns and design decisions
---
Flutter Server Box follows clean architecture principles with clear separation between data, domain, and presentation layers.
Server Box follows clean architecture principles with clear separation between data, domain, and presentation layers.
## Layered Architecture

2
docs/src/content/docs/development/building.md
View File

@@ -3,7 +3,7 @@ title: Building
description: Build instructions for different platforms
---
Flutter Server Box uses a custom build system (`fl_build`) for cross-platform builds.
Server Box uses a custom build system (`fl_build`) for cross-platform builds.
## Prerequisites

2
docs/src/content/docs/development/codegen.md
View File

@@ -3,7 +3,7 @@ title: Code Generation
description: Using build_runner for code generation
---
Flutter Server Box heavily uses code generation for models, state management, and serialization.
Server Box heavily uses code generation for models, state management, and serialization.
## When to Run Code Generation

2
docs/src/content/docs/development/state.md
View File

@@ -3,7 +3,7 @@ title: State Management
description: Riverpod-based state management patterns
---
Flutter Server Box uses Riverpod with code generation for state management.
Server Box uses Riverpod with code generation for state management.
## Provider Types

4
docs/src/content/docs/development/structure.md
View File

@@ -1,9 +1,9 @@
---
title: Project Structure
description: Understanding the Flutter Server Box codebase
description: Understanding the Server Box codebase
---
The Flutter Server Box project follows a modular architecture with clear separation of concerns.
The Server Box project follows a modular architecture with clear separation of concerns.
## Directory Structure

83
docs/src/content/docs/es/advanced/bulk-import.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: Importación Masiva de Servidores
description: Importar múltiples servidores desde un archivo JSON
---
Importa múltiples configuraciones de servidor a la vez utilizando un archivo JSON.
## Formato JSON
:::danger[Advertencia de Seguridad]
**¡Nunca guardes contraseñas en texto plano en archivos!** Este ejemplo JSON muestra un campo de contraseña solo con fines demostrativos, pero deberías:
- **Preferir claves SSH** (`keyId`) en lugar de `pwd`; son más seguras
- **Usar gestores de secretos** o variables de entorno si debes usar contraseñas
- **Eliminar el archivo inmediatamente** después de la importación; no dejes credenciales tiradas
- **Añadir a .gitignore**: nunca subas archivos de credenciales al control de versiones
:::
```json
[
{
"name": "Mi Servidor",
"ip": "example.com",
"port": 22,
"user": "root",
"pwd": "password",
"keyId": "",
"tags": ["production"],
"autoConnect": false
}
]
```
## Campos
| Campo | Requerido | Descripción |
|-------|-----------|-------------|
| `name` | Sí | Nombre para mostrar |
| `ip` | Sí | Dominio o dirección IP |
| `port` | Sí | Puerto SSH (usualmente 22) |
| `user` | Sí | Usuario SSH |
| `pwd` | No | Contraseña (evitar - usar claves SSH en su lugar) |
| `keyId` | No | Nombre de la clave SSH (de Claves Privadas - recomendado) |
| `tags` | No | Etiquetas de organización |
| `autoConnect` | No | Autoconexión al iniciar |
## Pasos para Importar
1. Crea un archivo JSON con las configuraciones del servidor
2. Ajustes → Copia de seguridad → Importación masiva de servidores
3. Selecciona tu archivo JSON
4. Confirma la importación
## Ejemplo
```json
[
{
"name": "Producción",
"ip": "prod.example.com",
"port": 22,
"user": "admin",
"keyId": "mi-clave",
"tags": ["production", "web"]
},
{
"name": "Desarrollo",
"ip": "dev.example.com",
"port": 2222,
"user": "dev",
"keyId": "dev-clave",
"tags": ["development"]
}
]
```
## Consejos
- **Usa claves SSH** en lugar de contraseñas cuando sea posible
- **Prueba la conexión** después de la importación
- **Organiza con etiquetas** para una gestión más sencilla
- **Elimina el archivo JSON** después de la importación
- **Nunca subas** archivos JSON con credenciales al control de versiones

72
docs/src/content/docs/es/advanced/custom-commands.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Comandos Personalizados
description: Mostrar la salida de comandos personalizados en la página del servidor
---
Añade comandos shell personalizados para mostrar su salida en la página de detalles del servidor.
## Configuración
1. Ajustes del servidor → Comandos personalizados
2. Introduce los comandos en formato JSON
## Formato Básico
```json
{
"Nombre a mostrar": "comando shell"
}
```
**Ejemplo:**
```json
{
"Memoria": "free -h",
"Disco": "df -h",
"Tiempo de actividad": "uptime"
}
```
## Ver Resultados
Tras la configuración, los comandos personalizados aparecerán en la página de detalles del servidor y se actualizarán automáticamente.
## Nombres de Comando Especiales
### server_card_top_right
Se muestra en la tarjeta del servidor de la página de inicio (esquina superior derecha):
```json
{
"server_card_top_right": "tu-comando-aquí"
}
```
## Consejos
**Usa rutas absolutas:**
```json
{"Mi Script": "/usr/local/bin/mi-script.sh"}
```
**Comandos con tuberías (pipes):**
```json
{"Proceso principal": "ps aux | sort -rk 3 | head -5"}
```
**Formatear salida:**
```json
{"Carga de CPU": "uptime | awk -F'load average:' '{print $2}'"}
```
**Mantén los comandos rápidos:** Menos de 5 segundos para una mejor experiencia.
**Limitar salida:**
```json
{"Logs": "tail -20 /var/log/syslog"}
```
## Seguridad
Los comandos se ejecutan con los permisos del usuario SSH. Evita comandos que modifiquen el estado del sistema.

54
docs/src/content/docs/es/advanced/custom-logo.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: Logo de Servidor Personalizado
description: Usa imágenes personalizadas para las tarjetas de servidor
---
Muestra logos personalizados en las tarjetas de servidor mediante URLs de imagen.
## Configuración
1. Ajustes del servidor → Logo personalizado
2. Introduce la URL de la imagen
## Marcadores de posición de URL
### {DIST} - Distribución Linux
Se reemplaza automáticamente por la distribución detectada:
```
https://ejemplo.com/{DIST}.png
```
Se convierte en: `debian.png`, `ubuntu.png`, `arch.png`, etc.
### {BRIGHT} - Tema
Se reemplaza automáticamente por el tema actual:
```
https://ejemplo.com/{BRIGHT}.png
```
Se convierte en: `light.png` o `dark.png`
### Combinar ambos
```
https://ejemplo.com/{DIST}-{BRIGHT}.png
```
Se convierte en: `debian-light.png`, `ubuntu-dark.png`, etc.
## Consejos
- Usa formatos PNG o SVG
- Tamaño recomendado: de 64x64 a 128x128 píxeles
- Usa URLs HTTPS
- Mantén tamaños de archivo pequeños
## Distribuciones Soportadas
debian, ubuntu, centos, fedora, opensuse, kali, alpine, arch, rocky, deepin, armbian, wrt
Lista completa: [`dist.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/model/server/dist.dart)

64
docs/src/content/docs/es/advanced/json-settings.md Normal file
View File

@@ -0,0 +1,64 @@
---
title: Ajustes Ocultos (JSON)
description: Accede a ajustes avanzados mediante el editor JSON
---
Algunos ajustes están ocultos en la interfaz de usuario pero son accesibles a través del editor JSON.
## Acceso
Mantén pulsado **Ajustes** en el menú lateral para abrir el editor JSON.
## Ajustes Ocultos Comunes
### timeOut
Tiempo de espera de conexión en segundos.
```json
{"timeOut": 10}
```
**Tipo:** entero | **Predeterminado:** 5 | **Rango:** 1-60
### recordHistory
Guardar historial (rutas SFTP, etc.).
```json
{"recordHistory": true}
```
**Tipo:** booleano | **Predeterminado:** true
### textFactor
Factor de escala de texto.
```json
{"textFactor": 1.2}
```
**Tipo:** doble | **Predeterminado:** 1.0 | **Rango:** 0.8-1.5
## Encontrar Más Ajustes
Todos los ajustes están definidos en [`setting.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/store/setting.dart).
Busca:
```dart
late final settingName = StoreProperty(box, 'settingKey', defaultValue);
```
## ⚠️ Importante
**Antes de editar:**
- **Crea una copia de seguridad**: unos ajustes incorrectos pueden hacer que la app no se abra
- **Edita con cuidado**: el JSON debe ser válido
## Recuperación
Si la aplicación no se abre tras editar:
1. Borra los datos de la aplicación (último recurso)
2. Reinstala la aplicación
3. Restaura desde una copia de seguridad

118
docs/src/content/docs/es/advanced/troubleshooting.md Normal file
View File

@@ -0,0 +1,118 @@
---
title: Problemas Comunes
description: Soluciones a problemas frecuentes
---
## Problemas de Conexión
### SSH no conecta
**Síntomas:** Tiempo de espera agotado (timeout), conexión rechazada, fallo de autenticación
**Soluciones:**
1. **Verificar el tipo de servidor:** Solo se admiten sistemas tipo Unix (Linux, macOS, Android/Termux)
2. **Probar manualmente:** `ssh usuario@servidor -p puerto`
3. **Comprobar el cortafuegos:** El puerto 22 debe estar abierto
4. **Verificar credenciales:** Usuario y contraseña/clave correctos
### Desconexiones frecuentes
**Síntomas:** El terminal se desconecta tras un periodo de inactividad
**Soluciones:**
1. **Keep-alive del servidor:**
```bash
# /etc/ssh/sshd_config
ClientAliveInterval 60
ClientAliveCountMax 3
```
2. **Desactivar optimización de batería:**
- MIUI: Batería → "Sin restricciones"
- Android: Ajustes → Aplicaciones → Desactivar optimización
- iOS: Activar actualización en segundo plano
## Problemas de Entrada
### No se pueden escribir ciertos caracteres
**Solución:** Ajustes → Tipo de teclado → Cambiar a `visiblePassword`
Nota: Es posible que la entrada CJK (chino, japonés, coreano) no funcione tras este cambio.
## Problemas de la Aplicación
### La aplicación se cierra al iniciar
**Síntomas:** La aplicación no se abre, pantalla en negro
**Causas:** Ajustes corruptos, especialmente tras usar el editor JSON
**Soluciones:**
1. **Borrar datos de la aplicación:**
- Android: Ajustes → Aplicaciones → ServerBox → Borrar datos
- iOS: Eliminar y reinstalar
2. **Restaurar copia de seguridad:** Importar una copia de seguridad creada antes de cambiar los ajustes
### Problemas con Copia de Seguridad/Restauración
**La copia de seguridad no funciona:**
- Comprobar espacio de almacenamiento
- Verificar que la aplicación tiene permisos de almacenamiento
- Probar una ubicación diferente
**La restauración falla:**
- Verificar la integridad del archivo de copia de seguridad
- Comprobar la compatibilidad de la versión de la aplicación
## Problemas con Widgets
### El Widget no se actualiza
**iOS:**
- Esperar hasta 30 minutos para la actualización automática
- Eliminar y volver a añadir el widget
- Comprobar que la URL termina en `/status`
**Android:**
- Pulsar el widget para forzar la actualización
- Verificar que el ID del widget coincide con la configuración en los ajustes de la aplicación
**watchOS:**
- Reiniciar la aplicación del reloj
- Esperar unos minutos tras cambiar la configuración
- Verificar el formato de la URL
### El Widget muestra un error
- Verificar que ServerBox Monitor se está ejecutando en el servidor
- Probar la URL en un navegador
- Comprobar las credenciales de autenticación
## Problemas de Rendimiento
### La aplicación va lenta
**Soluciones:**
- Reducir la tasa de refresco en los ajustes
- Comprobar la velocidad de la red
- Desactivar servidores no utilizados
### Alto consumo de batería
**Soluciones:**
- Aumentar los intervalos de refresco
- Desactivar la actualización en segundo plano
- Cerrar sesiones SSH no utilizadas
## Obtener Ayuda
Si los problemas persisten:
1. **Buscar en GitHub Issues:** https://github.com/lollipopkit/flutter_server_box/issues
2. **Crear nueva Issue:** Incluir versión de la aplicación, plataforma y pasos para reproducir
3. **Consultar la Wiki:** Esta documentación y la Wiki de GitHub

90
docs/src/content/docs/es/advanced/widgets.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: Widgets de Pantalla de Inicio
description: Añade widgets de estado del servidor a tu pantalla de inicio
---
Requiere tener instalado [ServerBox Monitor](https://github.com/lollipopkit/server_box_monitor) en tus servidores.
## Requisitos Previos
Instala primero ServerBox Monitor en tu servidor. Consulta la [Wiki de ServerBox Monitor](https://github.com/lollipopkit/server_box_monitor/wiki/Home) para ver las instrucciones de configuración.
Tras la instalación, tu servidor debería tener:
- Un punto de acceso (endpoint) HTTP/HTTPS
- El punto de acceso API `/status`
- Autenticación opcional
## Formato de URL
```
https://tu-servidor.com/status
```
Debe terminar en `/status`.
## Widget de iOS
### Configuración
1. Mantén pulsada la pantalla de inicio → Toca el símbolo **+**
2. Busca "ServerBox"
3. Elige el tamaño del widget
4. Mantén pulsado el widget → **Editar widget**
5. Introduce la URL terminada en `/status`
### Notas
- Debe usar HTTPS (excepto IPs locales)
- Tasa máxima de refresco: 30 minutos (límite de iOS)
- Añade varios widgets para varios servidores
## Widget de Android
### Configuración
1. Mantén pulsada la pantalla de inicio → **Widgets**
2. Busca "ServerBox" → Añadir a la pantalla de inicio
3. Anota el número de ID del widget que aparece
4. Abre la app ServerBox → Ajustes
5. Toca en **Configurar enlace de widget de inicio**
6. Añade la entrada: `Widget ID` = `URL de estado`
Ejemplo:
- Clave (Key): `17`
- Valor (Value): `https://mi-servidor.com/status`
7. Toca el widget en la pantalla de inicio para refrescarlo
## Widget de watchOS
### Configuración
1. Abre la app en el iPhone → Ajustes
2. **Ajustes de iOS** → **App del Watch**
3. Toca en **Añadir URL**
4. Introduce la URL terminada en `/status`
5. Espera a que la app del reloj se sincronice
### Notas
- Prueba a reiniciar la app del reloj si no se actualiza
- Verifica que el teléfono y el reloj están conectados
## Solución de Problemas
### El Widget no se actualiza
**iOS:** Espera hasta 30 minutos, luego elimínalo y vuelve a añadirlo.
**Android:** Toca el widget para forzar el refresco, verifica el ID en los ajustes.
**watchOS:** Reinicia la app del reloj, espera unos minutos.
### El Widget muestra un error
- Verifica que ServerBox Monitor se está ejecutando
- Prueba la URL en un navegador
- Comprueba que la URL termina en `/status`
## Seguridad
- **Usa siempre HTTPS** cuando sea posible
- **IPs locales solo** en redes de confianza

86
docs/src/content/docs/es/development/architecture.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: Arquitectura
description: Patrones de arquitectura y decisiones de diseño
---
Server Box sigue los principios de Clean Architecture con una clara separación entre las capas de datos, dominio y presentación.
## Arquitectura por Capas
```
┌─────────────────────────────────────┐
│ Capa de Presentación │
│ (lib/view/page/) │
│ - Páginas, Widgets, Controladores │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Capa de Lógica de Negocio │
│ (lib/data/provider/) │
│ - Riverpod Providers │
│ - Gestión de Estado │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Capa de Datos │
│ (lib/data/model/, store/) │
│ - Modelos, Almacén, Servicios │
└─────────────────────────────────────┘
```
## Patrones Clave
### Gestión de Estado: Riverpod
- **Generación de Código**: Usa `riverpod_generator` para providers con tipado seguro
- **State Notifiers**: Para estados mutables con lógica de negocio
- **Async Notifiers**: Para estados de carga y error
- **Stream Providers**: Para datos en tiempo real
### Modelos Inmutables: Freezed
- Todos los modelos de datos usan Freezed para inmutabilidad
- Tipos Union para representación de estados
- Serialización JSON integrada
- Extensiones CopyWith para actualizaciones
### Almacenamiento Local: Hive
- **hive_ce**: Edición comunitaria de Hive
- No se requiere `@HiveField` o `@HiveType` manual
- Adaptadores de tipo generados automáticamente
- Almacenamiento persistente clave-valor
## Inyección de Dependencias
Los servicios y almacenes se inyectan a través de:
1. **Providers**: Exponen dependencias a la UI
2. **GetIt**: Localizador de servicios (donde sea aplicable)
3. **Inyección en Constructor**: Dependencias explícitas
## Flujo de Datos
```
Acción de Usuario → Widget → Provider → Servicio/Almacén → Actualización de Modelo → Reconstrucción de UI
```
1. El usuario interactúa con el widget
2. El widget llama al método del provider
3. El provider actualiza el estado a través del servicio/almacén
4. El cambio de estado activa la reconstrucción de la UI
5. El nuevo estado se refleja en el widget
## Dependencias Personalizadas
El proyecto utiliza varias ramas (forks) personalizadas para extender la funcionalidad:
- **dartssh2**: Funciones SSH mejoradas
- **xterm**: Emulador de terminal con soporte móvil
- **fl_lib**: Componentes de UI y utilidades compartidas
## Multihilo
- **Isolates**: Computación pesada fuera del hilo principal
- **paquete computer**: Utilidades para multihilo
- **Async/Await**: Operaciones de E/S no bloqueantes

116
docs/src/content/docs/es/development/building.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: Compilación
description: Instrucciones de compilación para diferentes plataformas
---
Server Box utiliza un sistema de compilación personalizado (`fl_build`) para compilaciones multiplataforma.
## Requisitos Previos
- Flutter SDK (canal stable)
- Herramientas específicas de cada plataforma (Xcode para iOS, Android Studio para Android)
- Cadena de herramientas de Rust (para algunas dependencias nativas)
## Compilación de Desarrollo
```bash
# Ejecutar en modo desarrollo
flutter run
# Ejecutar en un dispositivo específico
flutter run -d <id-del-dispositivo>
```
## Compilación de Producción
El proyecto utiliza `fl_build` para compilar:
```bash
# Compilar para una plataforma específica
dart run fl_build -p <plataforma>
# Plataformas disponibles:
# - ios
# - android
# - macos
# - linux
# - windows
```
## Compilaciones Específicas por Plataforma
### iOS
```bash
dart run fl_build -p ios
```
Requiere:
- macOS con Xcode
- CocoaPods
- Cuenta de Apple Developer para la firma
### Android
```bash
dart run fl_build -p android
```
Requiere:
- Android SDK
- Java Development Kit
- Keystore para la firma
### macOS
```bash
dart run fl_build -p macos
```
### Linux
```bash
dart run fl_build -p linux
```
### Windows
```bash
dart run fl_build -p windows
```
Requiere Windows con Visual Studio.
## Pre/Post Compilación
El script `make.dart` se encarga de:
- Generación de metadatos
- Actualización de cadenas de versión
- Configuraciones específicas de plataforma
## Solución de Problemas
### Compilación Limpia
```bash
flutter clean
dart run build_runner build --delete-conflicting-outputs
flutter pub get
```
### Discrepancia de Versión
Asegúrate de que todas las dependencias son compatibles:
```bash
flutter pub upgrade
```
## Lista de Verificación de Lanzamiento
1. Actualizar la versión en `pubspec.yaml`
2. Ejecutar la generación de código
3. Ejecutar las pruebas
4. Compilar para todas las plataformas de destino
5. Probar en dispositivos físicos
6. Crear lanzamiento (release) en GitHub

98
docs/src/content/docs/es/development/codegen.md Normal file
View File

@@ -0,0 +1,98 @@
---
title: Generación de Código
description: Uso de build_runner para la generación de código
---
Server Box utiliza intensivamente la generación de código para modelos, gestión de estado y serialización.
## Cuándo Ejecutar la Generación de Código
Ejecutar tras modificar:
- Modelos con la anotación `@freezed`
- Clases con `@JsonSerializable`
- Modelos de Hive
- Providers con `@riverpod`
- Localizaciones (archivos ARB)
## Ejecutar la Generación de Código
```bash
# Generar todo el código
dart run build_runner build --delete-conflicting-outputs
# Limpiar y regenerar
dart run build_runner build --delete-conflicting-outputs --clean
```
## Archivos Generados
### Freezed (`*.freezed.dart`)
Modelos de datos inmutables con tipos Union:
```dart
@freezed
class ServerState with _$ServerState {
const factory ServerState.connected() = Connected;
const factory ServerState.disconnected() = Disconnected;
const factory ServerState.error(String message) = Error;
}
```
### Serialización JSON (`*.g.dart`)
Generado por `json_serializable`:
```dart
@JsonSerializable()
class Server {
final String id;
final String name;
final String host;
Server({required this.id, required this.name, required this.host});
factory Server.fromJson(Map<String, dynamic> json) =>
_$ServerFromJson(json);
Map<String, dynamic> toJson() => _$ServerToJson(this);
}
```
### Providers de Riverpod (`*.g.dart`)
Generados a partir de la anotación `@riverpod`:
```dart
@riverpod
class MyNotifier extends _$MyNotifier {
@override
int build() => 0;
}
```
### Adaptadores de Hive (`*.g.dart`)
Auto-generados para modelos de Hive (hive_ce):
```dart
@HiveType(typeId: 0)
class ServerModel {
@HiveField(0)
final String id;
}
```
## Generación de Localización
```bash
flutter gen-l10n
```
Genera `lib/generated/l10n/` a partir de los archivos `lib/l10n/*.arb`.
## Consejos
- Usa `--delete-conflicting-outputs` para evitar conflictos
- Añade los archivos generados al `.gitignore`
- Nunca edites manualmente los archivos generados

115
docs/src/content/docs/es/development/state.md Normal file
View File

@@ -0,0 +1,115 @@
---
title: Gestión de Estado
description: Patrones de gestión de estado basados en Riverpod
---
Server Box utiliza Riverpod con generación de código para la gestión de estado.
## Tipos de Provider
### StateProvider
Estado simple que se puede leer y escribir:
```dart
@riverpod
class Settings extends _$Settings {
@override
SettingsModel build() {
return SettingsModel.defaults();
}
void update(SettingsModel newSettings) {
state = newSettings;
}
}
```
### AsyncNotifierProvider
Estado que se carga de forma asíncrona con estados de carga/error:
```dart
@riverpod
class ServerStatus extends _$ServerStatus {
@override
Future<StatusModel> build(Server server) async {
return fetchStatus(server);
}
Future<void> refresh() async {
state = const AsyncValue.loading();
state = await AsyncValue.guard(() => fetchStatus(server));
}
}
```
### StreamProvider
Datos en tiempo real desde flujos (streams):
```dart
@riverpod
Stream<CpuUsage> cpuUsage(CpuUsageRef ref, Server server) {
return cpuService.monitor(server);
}
```
## Patrones de Estado
### Estados de Carga
```dart
state.when(
data: (data) => DataWidget(data),
loading: () => LoadingWidget(),
error: (error, stack) => ErrorWidget(error),
)
```
### Family Providers
Providers parametrizados:
```dart
@riverpod
List<Container> containers(ContainersRef ref, Server server) {
return containerService.list(server);
}
```
### Auto-Dispose
Providers que se eliminan cuando ya no están referenciados:
```dart
@Riverpod(keepAlive: false)
class TempState extends _$TempState {
// ...
}
```
## Mejores Prácticas
1. **Usar generación de código**: Usa siempre la anotación `@riverpod`
2. **Co-localizar providers**: Ponlos cerca de los widgets que los consumen
3. **Evitar singletons**: Usa providers en su lugar
4. **Capas correctas**: Mantén la lógica de UI separada de la lógica de negocio
## Leer el Estado en Widgets
```dart
class ServerWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final status = ref.watch(serverStatusProvider(server));
return status.when(...);
}
}
```
## Modificar el Estado
```dart
ref.read(settingsProvider.notifier).update(newSettings);
```

96
docs/src/content/docs/es/development/structure.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Estructura del Proyecto
description: Comprendiendo la base de código de Server Box
---
El proyecto Server Box sigue una arquitectura modular con una clara separación de responsabilidades.
## Estructura de Directorios
```
lib/
├── core/ # Utilidades centrales y extensiones
├── data/ # Capa de datos
│ ├── model/ # Modelos de datos por función
│ ├── provider/ # Riverpod providers
│ └── store/ # Almacenamiento local (Hive)
├── view/ # Capa de UI
│ ├── page/ # Páginas principales
│ └── widget/ # Widgets reutilizables
├── generated/ # Localización generada
├── l10n/ # Archivos ARB de localización
└── hive/ # Adaptadores de Hive
```
## Capa Central (`lib/core/`)
Contiene utilidades, extensiones y configuración de rutas:
- **Extensions**: Extensiones de Dart para tipos comunes
- **Routes**: Configuración de rutas de la app
- **Utils**: Funciones de utilidad compartidas
## Capa de Datos (`lib/data/`)
### Modelos (`lib/data/model/`)
Organizados por función:
- `server/` - Modelos de conexión y estado del servidor
- `container/` - Modelos de contenedores Docker
- `ssh/` - Modelos de sesión SSH
- `sftp/` - Modelos de archivos SFTP
- `app/` - Modelos específicos de la app
### Providers (`lib/data/provider/`)
Providers de Riverpod para inyección de dependencias y gestión de estado:
- Providers de servidor
- Providers de estado de UI
- Providers de servicios
### Almacenes (`lib/data/store/`)
Almacenamiento local basado en Hive:
- Almacén de servidores
- Almacén de ajustes
- Almacén de caché
## Capa de Vista (`lib/view/`)
### Páginas (`lib/view/page/`)
Pantallas principales de la aplicación:
- `server/` - Páginas de gestión de servidores
- `ssh/` - Páginas de terminal SSH
- `container/` - Páginas de contenedores
- `setting/` - Páginas de ajustes
- `storage/` - Páginas de SFTP
- `snippet/` - Páginas de fragmentos (snippets)
### Widgets (`lib/view/widget/`)
Componentes de UI reutilizables:
- Tarjetas de servidor
- Gráficos de estado
- Componentes de entrada
- Diálogos
## Archivos Generados
- `lib/generated/l10n/` - Localización auto-generada
- `*.g.dart` - Código generado (json_serializable, freezed, hive, riverpod)
- `*.freezed.dart` - Clases inmutables de Freezed
## Directorio de Paquetes (`/packages/`)
Contiene ramas (forks) personalizadas de las dependencias:
- `dartssh2/` - Librería SSH
- `xterm/` - Emulador de terminal
- `fl_lib/` - Utilidades compartidas
- `fl_build/` - Sistema de compilación

113
docs/src/content/docs/es/development/testing.md Normal file
View File

@@ -0,0 +1,113 @@
---
title: Pruebas
description: Estrategias de prueba y ejecución de pruebas
---
## Ejecución de Pruebas
```bash
# Ejecutar todas las pruebas
flutter test
# Ejecutar un archivo de prueba específico
flutter test test/battery_test.dart
# Ejecutar con cobertura
flutter test --coverage
```
## Estructura de las Pruebas
Las pruebas se encuentran en el directorio `test/` reflejando la estructura de lib:
```
test/
├── data/
│ ├── model/
│ └── provider/
├── view/
│ └── widget/
└── test_helpers.dart
```
## Pruebas Unitarias
Probar la lógica de negocio y los modelos de datos:
```dart
test('debería calcular el porcentaje de CPU', () {
final cpu = CpuModel(usage: 75.0);
expect(cpu.usagePercentage, '75%');
});
```
## Pruebas de Widgets
Probar componentes de la interfaz de usuario (UI):
```dart
testWidgets('ServerCard muestra el nombre del servidor', (tester) async {
await tester.pumpWidget(
ProviderScope(
child: MaterialApp(
home: ServerCard(server: testServer),
),
),
);
expect(find.text('Test Server'), findsOneWidget);
});
```
## Pruebas de Providers
Probar providers de Riverpod:
```dart
test('serverStatusProvider devuelve el estado', () async {
final container = ProviderContainer();
final status = await container.read(serverStatusProvider(testServer).future);
expect(status, isA<StatusModel>());
});
```
## Mocking (Simulaciones)
Utilizar mocks para dependencias externas:
```dart
class MockSshService extends Mock implements SshService {}
test('se conecta al servidor', () async {
final mockSsh = MockSshService();
when(mockSsh.connect(any)).thenAnswer((_) async => true);
// Probar con el mock
});
```
## Pruebas de Integración
Probar flujos de usuario completos (en `integration_test/`):
```dart
testWidgets('flujo de agregar servidor', (tester) async {
await tester.pumpWidget(MyApp());
// Tocar el botón de agregar
await tester.tap(find.byIcon(Icons.add));
await tester.pumpAndSettle();
// Completar el formulario
await tester.enterText(find.byKey(Key('name')), 'Test Server');
// ...
});
```
## Buenas Prácticas
1. **Arrange-Act-Assert**: Estructurar las pruebas claramente.
2. **Nombres descriptivos**: Los nombres de las pruebas deben describir el comportamiento.
3. **Una aserción por prueba**: Mantener las pruebas enfocadas.
4. **Simular dependencias externas**: No depender de servidores reales.
5. **Probar casos límite**: Listas vacías, valores nulos, etc.

46
docs/src/content/docs/es/index.mdx Normal file
View File

@@ -0,0 +1,46 @@
---
title: Server Box
description: Una aplicación integral de gestión de servidores multiplataforma
hero:
tagline: Administra tus servidores Linux desde cualquier lugar
actions:
- text: Empezar
link: /es/introduction/
icon: right-arrow
variant: primary
- text: Ver en GitHub
link: https://github.com/lollipopkit/flutter_server_box
icon: github
variant: minimal
---
import { Card, CardGrid } from '@astrojs/starlight/components';
## Características
<CardGrid stagger>
<Card title="Monitoreo en Tiempo Real" icon="chart">
Monitorea CPU, memoria, disco, red, GPU y temperatura con hermosos gráficos en tiempo real.
</Card>
<Card title="Terminal SSH" icon="terminal">
Terminal SSH con todas las funciones, soporte para múltiples pestañas y teclado virtual para dispositivos móviles.
</Card>
<Card title="Navegador de Archivos SFTP" icon="folder">
Administra archivos en tus servidores con el cliente SFTP integrado y el navegador de archivos local.
</Card>
<Card title="Gestión de Docker" icon="box">
Inicia, detén y monitorea contenedores Docker con una interfaz intuitiva.
</Card>
<Card title="Multiplataforma" icon="device-mobile">
Disponible en iOS, Android, macOS, Linux, Windows y watchOS.
</Card>
<Card title="Más de 12 Idiomas" icon="globe">
Soporte completo de localización que incluye inglés, chino, alemán, francés y más.
</Card>
</CardGrid>
## Enlaces Rápidos
- **Descarga**: Disponible en [App Store](https://apps.apple.com/app/id1586449703), [GitHub](https://github.com/lollipopkit/flutter_server_box/releases) y [F-Droid](https://f-droid.org/)
- **Documentación**: Explora las guías para comenzar con Server Box
- **Soporte**: Únete a nuestra comunidad en GitHub para discusiones y problemas

51
docs/src/content/docs/es/installation.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
title: Instalación
description: Descarga e instala Server Box en tu dispositivo
---
Server Box está disponible en múltiples plataformas. Elige tu método de instalación preferido.
## Aplicaciones Móviles
### iOS
Descárgalo desde la **[App Store](https://apps.apple.com/app/id1586449703)**.
### Android
Elige tu fuente preferida:
- **[F-Droid](https://f-droid.org/)** - Para usuarios que prefieren fuentes exclusivamente FOSS (Software Libre y de Código Abierto)
- **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)** - Para la última versión directamente desde la fuente
## Aplicaciones de Escritorio
### macOS
Descárgalo desde **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
Características:
- Integración nativa con la barra de menú
- Soporte para Intel y Apple Silicon
### Linux
Descárgalo desde **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
Disponible en paquetes AppImage, deb o tar.gz.
### Windows
Descárgalo desde **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
## watchOS
Disponible en la **[App Store](https://apps.apple.com/app/id1586449703)** como parte de la aplicación para iOS.
## Compilación desde el Código Fuente
Para compilar Server Box desde el código fuente, consulta la sección de [Compilación](/es/development/building/) en la documentación de desarrollo.
## Información de Versión
Consulta la página de [GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases) para ver la última versión y el registro de cambios.

32
docs/src/content/docs/es/introduction.mdx Normal file
View File

@@ -0,0 +1,32 @@
---
title: Introducción
description: Aprende qué es Server Box y qué puede hacer
---
Server Box es una aplicación integral de gestión de servidores multiplataforma creada con Flutter. Te permite monitorear, gestionar y controlar tus servidores Linux, Unix y Windows desde cualquier lugar.
## ¿Qué es Server Box?
Server Box proporciona una interfaz unificada para tareas de administración de servidores a través de conexiones SSH. Ya seas un administrador de sistemas, desarrollador o entusiasta con servidores domésticos, esta aplicación pone potentes herramientas de gestión de servidores en tu bolsillo.
## Capacidades Clave
- **Monitoreo en Tiempo Real**: Sigue el uso de CPU, memoria, disco, velocidad de red, estado de GPU y temperaturas del sistema.
- **Terminal SSH**: Acceso total a la terminal con soporte multi-pestaña y apariencia personalizable.
- **Cliente SFTP**: Explora y gestiona archivos en tus servidores.
- **Gestión de Docker**: Controla contenedores con facilidad.
- **Gestión de Procesos**: Visualiza y gestiona procesos del sistema.
- **Servicios Systemd**: Inicia, detén y monitorea servicios systemd.
- **Herramientas de Red**: Pruebas iPerf, ping y Wake-on-LAN.
- **Snippets**: Guarda y ejecuta comandos de shell personalizados.
## Plataformas Soportadas
Server Box es verdaderamente multiplataforma:
- **Móvil**: iOS y Android
- **Escritorio**: macOS, Linux y Windows
## Licencia
Este proyecto está bajo la licencia AGPL v3. El código fuente está disponible en [GitHub](https://github.com/lollipopkit/flutter_server_box).

80
docs/src/content/docs/es/platforms/desktop.md Normal file
View File

@@ -0,0 +1,80 @@
---
title: Funciones de Escritorio
description: Funciones específicas para macOS, Linux y Windows
---
Server Box en plataformas de escritorio ofrece funciones de productividad adicionales.
## macOS
### Integración en la Barra de Menús
- Estado rápido del servidor en la barra de menús
- Acceso al servidor con un solo clic
- Modo compacto para una mínima distracción
- Estilo nativo de la barra de menús de macOS
### Persistencia del Estado de la Ventana
- Recuerda la posición y el tamaño de la ventana
- Restaura la sesión anterior al iniciar
- Soporte para múltiples monitores
### Funciones Nativas
- **Barra de título**: Opción de barra de título personalizada o del sistema
- **Modo pantalla completa**: Monitorización dedicada del servidor
- **Atajos de teclado**: Atajos nativos de macOS
- **Touch Bar** (dispositivos compatibles): Acciones rápidas
## Linux
### Integración Nativa
- Soporte para bandeja del sistema (systray)
- Integración con notificaciones de escritorio
- Integración con el selector de archivos
### Gestión de Ventanas
- Soporte para X11 y Wayland
- Compatible con gestores de ventanas en mosaico (tiling)
- Opción de decoraciones de ventana personalizadas
## Windows
### Funciones
- Integración en la bandeja del sistema
- Acciones rápidas en la Jump List
- Controles de ventana nativos
- Opción de inicio automático al arrancar
## Funciones de Escritorio Multiplataforma
### Atajos de Teclado
- **Cmd/Ctrl + N**: Nuevo servidor
- **Cmd/Ctrl + W**: Cerrar pestaña
- **Cmd/Ctrl + T**: Nueva pestaña de terminal
- **Cmd/Ctrl + ,**: Ajustes
### Temas
- Tema claro
- Tema oscuro
- Tema AMOLED (negro puro)
- Tema del sistema (sigue al SO)
### Múltiples Ventanas
- Abrir varios servidores en ventanas separadas
- Arrastrar pestañas a una nueva ventana
- Comparar estadísticas de servidores en paralelo
### Ventajas sobre el Móvil
- Pantalla más grande para monitorización
- Teclado completo para la terminal
- Operaciones de archivos más rápidas
- Mejor multitarea

77
docs/src/content/docs/es/platforms/mobile.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: Funciones Móviles
description: Funciones específicas para iOS y Android
---
Server Box proporciona varias funciones específicas para dispositivos móviles iOS y Android.
## Autenticación Biométrica
Asegura tus servidores con autenticación biométrica:
- **iOS**: Face ID o Touch ID
- **Android**: Autenticación por huella dactilar
Actívalo en Ajustes > Seguridad > Autenticación biométrica.
## Widgets de Pantalla de Inicio
Añade widgets de estado del servidor a tu pantalla de inicio para una monitorización rápida.
### iOS
- Mantén pulsada la pantalla de inicio
- Toca en **+** para añadir un widget
- Busca "Server Box"
- Elige el tamaño del widget:
- Pequeño: Estado de un solo servidor
- Mediano: Múltiples servidores
- Grande: Información detallada
### Android
- Mantén pulsada la pantalla de inicio
- Toca en **Widgets**
- Busca "Server Box"
- Selecciona el tipo de widget
## Ejecución en Segundo Plano
### Android
Mantén las conexiones activas en segundo plano:
- Actívalo en Ajustes > Avanzado > Ejecución en segundo plano
- Requiere exclusión de la optimización de batería
- Notificaciones persistentes para conexiones activas
### iOS
Se aplican limitaciones de segundo plano:
- Las conexiones pueden pausarse en segundo plano
- Reconexión rápida al volver a la app
- Soporte para actualización en segundo plano
## Notificaciones Push
Recibe notificaciones para:
- Alertas de servidor fuera de línea
- Avisos de alto uso de recursos
- Alertas de finalización de tareas
Configúralo en Ajustes > Notificaciones.
## Funciones de UI Móvil
- **Deslizar para refrescar**: Actualiza el estado del servidor
- **Acciones de deslizamiento**: Operaciones rápidas de servidor
- **Modo horizontal**: Mejor experiencia de terminal
- **Teclado virtual**: Atajos de terminal
## Integración de Archivos
- **App Archivos (iOS)**: Acceso directo SFTP desde Archivos
- **Storage Access Framework (Android)**: Comparte archivos con otras apps
- **Selector de documentos**: Selección de archivos sencilla

214
docs/src/content/docs/es/principles/architecture.md Normal file
View File

@@ -0,0 +1,214 @@
---
title: Descripción General de la Arquitectura
description: Arquitectura de alto nivel de la aplicación
---
Server Box sigue una arquitectura por capas con una clara separación de responsabilidades.
## Capas de la Arquitectura
```
┌─────────────────────────────────────────────────┐
│ Capa de Presentación (UI) │
│ lib/view/page/, lib/view/widget/ │
│ - Páginas, Widgets, Controladores │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Capa de Lógica de Negocio │
│ lib/data/provider/ │
│ - Riverpod Providers, State Notifiers │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Capa de Acceso a Datos │
│ lib/data/store/, lib/data/model/ │
│ - Hive Stores, Modelos de Datos │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Capa de Integración Externa │
│ - SSH (dartssh2), Terminal (xterm), SFTP │
│ - Código específico de plataforma (iOS, etc.) │
└─────────────────────────────────────────────────┘
```
## Fundamentos de la Aplicación
### Punto de Entrada Principal
`lib/main.dart` inicializa la aplicación:
```dart
void main() {
runApp(
ProviderScope(
child: MyApp(),
),
);
}
```
### Widget Raíz
`MyApp` proporciona:
- **Gestión de Temas**: Cambio entre tema claro/oscuro
- **Configuración de Rutas**: Estructura de navegación
- **Provider Scope**: Raíz para la inyección de dependencias
### Página de Inicio
`HomePage` sirve como núcleo de navegación:
- **Interfaz de Pestañas**: Servidor, Snippet, Contenedor, SSH
- **Gestión de Estado**: Estado por pestaña
- **Navegación**: Acceso a funciones
## Sistemas Principales
### Gestión de Estado: Riverpod
**¿Por qué Riverpod?**
- Seguridad en tiempo de compilación
- Facilidad para realizar pruebas
- Sin dependencia del Build context
- Funciona en todas las plataformas
**Tipos de Provider Utilizados:**
- `StateProvider`: Estado mutable simple
- `AsyncNotifierProvider`: Estados de carga/error/datos
- `StreamProvider`: Flujos de datos en tiempo real
- Future providers: Operaciones asíncronas únicas
### Persistencia de Datos: Hive CE
**¿Por qué Hive CE?**
- Sin dependencias de código nativo
- Almacenamiento clave-valor rápido
- Tipado seguro con generación de código
- Sin necesidad de anotaciones manuales de campos
**Almacenes (Stores):**
- `SettingStore`: Preferencias de la app
- `ServerStore`: Configuraciones de servidores
- `SnippetStore`: Fragmentos de comandos
- `KeyStore`: Claves SSH
### Modelos Inmutables: Freezed
**Beneficios:**
- Inmutabilidad en tiempo de compilación
- Tipos Union para el estado
- Serialización JSON integrada
- Extensiones CopyWith
## Estrategia Multiplataforma
### Sistema de Plugins
Los plugins de Flutter proporcionan la integración con la plataforma:
| Plataforma | Método de Integración |
|------------|-----------------------|
| iOS | CocoaPods, Swift/Obj-C |
| Android | Gradle, Kotlin/Java |
| macOS | CocoaPods, Swift |
| Linux | CMake, C++ |
| Windows | CMake, C# |
### Funciones Específicas por Plataforma
**Solo iOS:**
- Widgets de pantalla de inicio
- Actividades en Directo (Live Activities)
- Compañero de Apple Watch
**Solo Android:**
- Servicio en segundo plano
- Notificaciones push
- Acceso al sistema de archivos
**Solo Escritorio:**
- Integración en la barra de menús
- Múltiples ventanas
- Barra de título personalizada
## Dependencias Personalizadas
### Rama (Fork) de dartssh2
Cliente SSH mejorado con:
- Mejor soporte para móviles
- Gestión de errores mejorada
- Optimizaciones de rendimiento
### Rama (Fork) de xterm.dart
Emulador de terminal con:
- Renderizado optimizado para móviles
- Soporte para gestos táctiles
- Integración con teclado virtual
### fl_lib
Paquete de utilidades compartidas con:
- Widgets comunes
- Extensiones
- Funciones de ayuda
## Sistema de Compilación
### Paquete fl_build
Sistema de compilación personalizado para:
- Compilaciones multiplataforma
- Firma de código
- Empaquetado de recursos (assets)
- Gestión de versiones
### Proceso de Compilación
```
make.dart (versión) → fl_build (compilación) → Salida de plataforma
```
1. **Pre-compilación**: Cálculo de la versión desde Git
2. **Compilación**: Compilar para la plataforma de destino
3. **Post-compilación**: Empaquetado y firma
## Ejemplo de Flujo de Datos
### Actualización del Estado del Servidor
```
1. El temporizador se activa →
2. El Provider llama al servicio →
3. El servicio ejecuta el comando SSH →
4. La respuesta se analiza en el modelo →
5. Se actualiza el estado →
6. La UI se reconstruye con los nuevos datos
```
### Flujo de Acción del Usuario
```
1. El usuario toca un botón →
2. El Widget llama al método del provider →
3. El Provider actualiza el estado →
4. El cambio de estado activa la reconstrucción →
5. El nuevo estado se refleja en la UI
```
## Arquitectura de Seguridad
### Protección de Datos
- **Contraseñas**: Cifradas con flutter_secure_storage
- **Claves SSH**: Cifradas en reposo
- **Huellas de Host**: Almacenadas de forma segura
- **Datos de Sesión**: No se persisten
### Seguridad de Conexión
- **Verificación de Clave de Host**: Detección de MITM
- **Cifrado**: Cifrado SSH estándar
- **Sin Texto Plano**: Los datos sensibles nunca se almacenan en plano

490
docs/src/content/docs/es/principles/sftp.md Normal file
View File

@@ -0,0 +1,490 @@
---
title: Sistema SFTP
description: Cómo funciona el explorador de archivos SFTP
---
El sistema SFTP proporciona capacidades de gestión de archivos sobre SSH.
## Arquitectura
```
┌─────────────────────────────────────────────┐
│ Capa UI de SFTP │
│ - Explorador de archivos (remoto) │
│ - Explorador de archivos (local) │
│ - Cola de transferencia │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Gestión de Estado SFTP │
│ - sftpProvider │
│ - Gestión de rutas │
│ - Cola de operaciones │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Capa de Protocolo SFTP │
│ - Subsistema SSH │
│ - Operaciones de archivos │
│ - Listado de directorios │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Transporte SSH │
│ - Canal seguro │
│ - Streaming de datos │
└─────────────────────────────────────────────┘
```
## Establecimiento de la Conexión
### Creación del Cliente SFTP
```dart
Future<SftpClient> createSftpClient(Spi spi) async {
// 1. Obtener cliente SSH (reutilizar si está disponible)
final sshClient = await genClient(spi);
// 2. Abrir subsistema SFTP
final sftp = await sshClient.openSftp();
return sftp;
}
```
### Reutilización de Conexiones
SFTP reutiliza las conexiones SSH existentes:
```dart
class ServerProvider {
SSHClient? _sshClient;
SftpClient? _sftpClient;
Future<SftpClient> getSftpClient(String spiId) async {
_sftpClient ??= await _sshClient!.openSftp();
return _sftpClient!;
}
}
```
## Operaciones del Sistema de Archivos
### Listado de Directorios
```dart
Future<List<SftpFile>> listDirectory(String path) async {
final sftp = await getSftpClient(spiId);
// Listar directorio
final files = await sftp.listDir(path);
// Ordenar según ajustes
files.sort((a, b) {
switch (sortOption) {
case SortOption.name:
return a.name.toLowerCase().compareTo(b.name.toLowerCase());
case SortOption.size:
return a.size.compareTo(b.size);
case SortOption.time:
return a.modified.compareTo(b.modified);
}
});
// Carpetas primero si está activado
if (showFoldersFirst) {
final dirs = files.where((f) => f.isDirectory);
final regular = files.where((f) => !f.isDirectory);
return [...dirs, ...regular];
}
return files;
}
```
### Metadatos de Archivo
```dart
class SftpFile {
final String name;
final String path;
final int size; // Bytes
final int modified; // Timestamp Unix
final String permissions; // ej., "rwxr-xr-x"
final String owner;
final String group;
final bool isDirectory;
final bool isSymlink;
String get sizeFormatted => formatBytes(size);
String get modifiedFormatted => formatDate(modified);
}
```
## Operaciones de Archivo
### Subida (Upload)
```dart
Future<void> uploadFile(
String localPath,
String remotePath,
) async {
final sftp = await getSftpClient(spiId);
// Crear petición
final req = SftpReq(
spi: spi,
remotePath: remotePath,
localPath: localPath,
type: SftpReqType.upload,
);
// Añadir a la cola
_transferQueue.add(req);
// Ejecutar transferencia con progreso
final file = File(localPath);
final size = await file.length();
final stream = file.openRead();
await sftp.upload(
stream: stream,
toPath: remotePath,
onProgress: (transferred) {
_updateProgress(req, transferred, size);
},
);
// Completar
_transferQueue.remove(req);
}
```
### Descarga (Download)
```dart
Future<void> downloadFile(
String remotePath,
String localPath,
) async {
final sftp = await getSftpClient(spiId);
// Crear archivo local
final file = File(localPath);
final sink = file.openWrite();
// Descargar con progreso
final stat = await sftp.stat(remotePath);
await sftp.download(
fromPath: remotePath,
toSink: sink,
onProgress: (transferred) {
_updateProgress(
SftpReq(...),
transferred,
stat.size,
);
},
);
await sink.close();
}
```
### Edición de Permisos
```dart
Future<void> setPermissions(
String path,
String permissions,
) async {
final sftp = await getSftpClient(spiId);
// Analizar permisos (ej., "rwxr-xr-x" o "755")
final mode = parsePermissions(permissions);
// Establecer vía comando SSH (más fiable que SFTP)
final ssh = await getSshClient(spiId);
await ssh.exec('chmod $mode "$path"');
}
```
## Gestión de Rutas
### Estructura de Rutas
```dart
class PathWithPrefix {
final String prefix; // ej., "/home/user"
final String path; // Relativa o absoluta
String get fullPath {
if (path.startsWith('/')) {
return path; // Ruta absoluta
}
return '$prefix/$path'; // Ruta relativa
}
PathWithPrefix cd(String subPath) {
return PathWithPrefix(
prefix: fullPath,
path: subPath,
);
}
}
```
### Historial de Navegación
```dart
class PathHistory {
final List<String> _history = [];
int _index = -1;
void push(String path) {
// Eliminar historial hacia adelante
_history.removeRange(_index + 1, _history.length);
_history.add(path);
_index = _history.length - 1;
}
String? back() {
if (_index > 0) {
_index--;
return _history[_index];
}
return null;
}
String? forward() {
if (_index < _history.length - 1) {
_index++;
return _history[_index];
}
return null;
}
}
```
## Sistema de Transferencia
### Petición de Transferencia
```dart
class SftpReq {
final Spi spi;
final String remotePath;
final String localPath;
final SftpReqType type;
final DateTime createdAt;
int? totalBytes;
int? transferredBytes;
String? error;
}
```
### Seguimiento de Progreso
```dart
class TransferProgress {
final SftpReq request;
final int total;
final int transferred;
final DateTime startTime;
double get percentage => (transferred / total) * 100;
Duration get elapsed => DateTime.now().difference(startTime);
String get speedFormatted {
final bytesPerSecond = transferred / elapsed.inSeconds;
return formatSpeed(bytesPerSecond);
}
}
```
### Gestión de Colas
```dart
class TransferQueue {
final List<SftpReq> _queue = [];
final Map<String, TransferProgress> _progress = {};
int _concurrent = 3; // Transferencias concurrentes máx.
Future<void> process() async {
final active = _progress.values.where((p) => p.isInProgress);
if (active.length >= _concurrent) return;
final pending = _queue.where((r) => !_progress.containsKey(r.id));
for (final req in pending.take(_concurrent - active.length)) {
_executeTransfer(req);
}
}
Future<void> _executeTransfer(SftpReq req) async {
try {
_progress[req.id] = TransferProgress.inProgress(req);
if (req.type == SftpReqType.upload) {
await uploadFile(req.localPath, req.remotePath);
} else {
await downloadFile(req.remotePath, req.localPath);
}
_progress[req.id] = TransferProgress.completed(req);
} catch (e) {
_progress[req.id] = TransferProgress.failed(req, e);
}
}
}
```
## Patrón de Almacenamiento Local
### Caché de Descargas
Los archivos descargados se guardan en:
```dart
String getLocalDownloadPath(String spiId, String remotePath) {
final normalized = remotePath.replaceAll('/', '_');
return 'Paths.file/$spiId/$normalized';
}
```
Ejemplo:
- Remoto: `/var/log/nginx/access.log`
- spiId: `server-123`
- Local: `Paths.file/server-123/_var_log_nginx_access.log`
## Edición de Archivos
### Flujo de Trabajo de Edición
```dart
Future<void> editFile(String path) async {
final sftp = await getSftpClient(spiId);
// 1. Comprobar tamaño
final stat = await sftp.stat(path);
if (stat.size > editorMaxSize) {
showWarning('Archivo demasiado grande para el editor integrado');
return;
}
// 2. Descargar a temporal
final temp = await downloadToTemp(path);
// 3. Abrir en editor
final content = await openEditor(temp.path);
// 4. Subir de nuevo
await uploadFile(temp.path, path);
// 5. Limpieza
await temp.delete();
}
```
### Integración con Editor Externo
```dart
Future<void> editInExternalEditor(String path) async {
final ssh = await getSshClient(spiId);
// Abrir terminal con editor
final editor = getSetting('sftpEditor', 'vim');
await ssh.exec('$editor "$path"');
// El usuario edita en la terminal
// Tras guardar, refrescar la vista SFTP
}
```
## Gestión de Errores
### Errores de Permiso
```dart
try {
await sftp.upload(...);
} on SftpPermissionException {
showError('Permiso denegado: ${stat.path}');
showHint('Comprueba los permisos y la propiedad del archivo');
}
```
### Erreores de Conexión
```dart
try {
await sftp.listDir(path);
} on SftpConnectionException {
showError('Conexión perdida');
await reconnect();
}
```
### Errores de Espacio
```dart
try {
await sftp.upload(...);
} on SftpNoSpaceException {
showError('Disco lleno en el servidor remoto');
}
```
## Optimizaciones de Rendimiento
### Caché de Directorios
```dart
class DirectoryCache {
final Map<String, CachedDirectory> _cache = {};
final Duration ttl = Duration(minutes: 5);
Future<List<SftpFile>> list(String path) async {
final cached = _cache[path];
if (cached != null && !cached.isExpired) {
return cached.files;
}
final files = await sftp.listDir(path);
_cache[path] = CachedDirectory(files);
return files;
}
}
```
### Carga Perezosa (Lazy Loading)
Para directorios grandes (>1000 elementos):
```dart
List<SftpFile> loadPage(String path, int page, int pageSize) {
final all = cache[path] ?? [];
final start = page * pageSize;
final end = start + pageSize;
return all.sublist(start, end.clamp(0, all.length));
}
```
### Paginación
```dart
class PaginatedDirectory {
static const pageSize = 100;
Future<List<SftpFile>> getPage(int page) async {
final offset = page * pageSize;
return await sftp.listDir(
path,
offset: offset,
limit: pageSize,
);
}
}
```

305
docs/src/content/docs/es/principles/ssh.md Normal file
View File

@@ -0,0 +1,305 @@
---
title: Conexión SSH
description: Cómo se establecen y gestionan las conexiones SSH
---
Entendiendo las conexiones SSH en Server Box.
## Flujo de Conexión
```text
Entrada de Usuario → Configuración Spi → genClient() → Cliente SSH → Sesión
```
### Paso 1: Configuración
El modelo `Spi` (Server Parameter Info) contiene:
```dart
class Spi {
String id; // ID del servidor
String name; // Nombre del servidor
String ip; // Dirección IP
int port; // Puerto SSH (por defecto 22)
String user; // Usuario
String? pwd; // Contraseña (cifrada)
String? keyId; // ID de la clave SSH
String? jumpId; // ID del servidor de salto (Jump server)
String? alterUrl; // URL alternativa
}
```
### Paso 2: Generación del Cliente
`genClient(spi)` crea el cliente SSH:
```dart
Future<SSHClient> genClient(Spi spi) async {
// 1. Establecer socket
var socket = await connect(spi.ip, spi.port);
// 2. Probar URL alternativa si falla
if (socket == null && spi.alterUrl != null) {
socket = await connect(spi.alterUrl, spi.port);
}
if (socket == null) {
throw ConnectionException('Unable to connect');
}
// 3. Autenticar
final client = SSHClient(
socket: socket,
username: spi.user,
onPasswordRequest: () => spi.pwd,
onIdentityRequest: () => loadKey(spi.keyId),
);
// 4. Verificar clave de host
await verifyHostKey(client, spi);
return client;
}
```
### Paso 3: Servidor de Salto (si está configurado)
Para servidores de salto, conexión recursiva:
```dart
if (spi.jumpId != null) {
final jumpClient = await genClient(getJumpSpi(spi.jumpId));
final forwarded = await jumpClient.forwardLocal(
spi.ip,
spi.port,
);
// Conectar a través del socket reenviado
}
```
## Métodos de Autenticación
### Autenticación por Contraseña
```dart
onPasswordRequest: () => spi.pwd
```
- Contraseña almacenada cifrada en Hive
- Descifrada al conectar
- Enviada al servidor para verificación
### Autenticación por Clave Privada
```dart
onIdentityRequest: () async {
final key = await KeyStore.get(spi.keyId);
return decyptPem(key.pem, key.password);
}
```
**Proceso de Carga de Clave:**
1. Recuperar clave cifrada de `KeyStore`
2. Descifrar contraseña (biometría/aviso)
3. Analizar formato PEM
4. Estandarizar finales de línea (LF)
5. Retornar para autenticación
### Interacción por Teclado (Keyboard-Interactive)
```dart
onUserInfoRequest: (instructions) async {
// Gestionar desafío-respuesta
return responses;
}
```
Soporta:
- Autenticación por contraseña
- Tokens OTP
- Autenticación de doble factor (2FA)
## Verificación de Clave de Host
### ¿Por qué verificar las claves de host?
Evita ataques de **Hombre en el Medio (MITM)** asegurando que te conectas al mismo servidor.
### Formato de Almacenamiento
```text
{spi.id}::{keyType}
```
Ejemplo:
```text
mi-servidor::ssh-ed25519
mi-servidor::ecdsa-sha2-nistp256
```
### Formatos de Huella Digital (Fingerprint)
**MD5 Hex:**
```text
aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
```
**Base64:**
```text
SHA256:AbCdEf1234567890...=
```
### Flujo de Verificación
```dart
Future<void> verifyHostKey(SSHClient client, Spi spi) async {
final key = await client.hostKey;
final keyType = key.type;
final fingerprint = md5Hex(key); // o base64
final stored = SettingStore.sshKnownHostsFingerprints
['${spi.id}::$keyType'];
if (stored == null) {
// Nuevo host - preguntar al usuario
final trust = await promptUser(
'Host desconocido',
'Huella: $fingerprint',
);
if (trust) {
SettingStore.sshKnownHostsFingerprints
['${spi.id}::$keyType'] = fingerprint;
}
} else if (stored != fingerprint) {
// Ha cambiado - advertir al usuario
await warnUser(
'¡La clave de host ha cambiado!',
'Posible ataque MITM',
);
}
}
```
## Gestión de Sesiones
### Pool de Conexiones
Clientes activos mantenidos en `ServerProvider`:
```dart
class ServerProvider {
final Map<String, SSHClient> _clients = {};
SSHClient getClient(String spiId) {
return _clients[spiId] ??= connect(spiId);
}
}
```
### Keep-Alive
Mantener la conexión durante la inactividad:
```dart
Timer.periodic(
Duration(seconds: 30),
(_) => client.sendKeepAlive(),
);
```
### Reconexión Automática
Al perder la conexión:
```dart
client.onError.listen((error) async {
await Future.delayed(Duration(seconds: 5));
reconnect();
});
```
## Ciclo de Vida de la Conexión
```text
┌─────────────┐
│ Inicial │
└──────┬──────┘
│ connect()
↓
┌─────────────┐
│ Conectando │ ←──┐
└──────┬──────┘ │
│ éxito │
↓ │ fallo (reintento)
┌─────────────┐ │
│ Conectado │───┘
└──────┬──────┘
│
↓
┌─────────────┐
│ Activo │ ──→ Enviar comandos
└──────┬──────┘
│
↓ (error/desconexión)
┌─────────────┐
│ Desconectado│
└─────────────┘
```
## Gestión de Errores
### Tiempo de Espera Agotado (Timeout)
```dart
try {
await client.connect().timeout(
Duration(seconds: 30),
);
} on TimeoutException {
throw ConnectionException('Tiempo de espera de conexión agotado');
}
```
### Fallo de Autenticación
```dart
onAuthFail: (error) {
if (error.contains('password')) {
return 'Contraseña no válida';
} else if (error.contains('key')) {
return 'Clave SSH no válida';
}
return 'Fallo de autenticación';
}
```
### Discrepancia en Clave de Host
```dart
onHostKeyMismatch: (stored, current) {
showSecurityWarning(
'¡La clave de host ha cambiado!',
'Posible ataque MITM',
);
}
```
## Consideraciones de Rendimiento
### Reutilización de Conexiones
- Reutilizar clientes entre funciones
- No desconectar/reconectar innecesariamente
- Pool de conexiones para operaciones concurrentes
### Ajustes Óptimos
- **Timeout**: 30 segundos (ajustable)
- **Keep-alive**: Cada 30 segundos
- **Retraso de reintento**: 5 segundos
### Eficiencia de Red
- Conexión única para múltiples operaciones
- Comandos en tubería (pipeline) cuando sea posible
- Evitar abrir múltiples conexiones

167
docs/src/content/docs/es/principles/state.md Normal file
View File

@@ -0,0 +1,167 @@
---
title: Gestión de Estado
description: Cómo se gestiona el estado con Riverpod
---
Entendiendo la arquitectura de gestión de estado en Server Box.
## ¿Por qué Riverpod?
**Beneficios Clave:**
- **Seguridad en tiempo de compilación**: Detecta errores al compilar
- **Sin necesidad de BuildContext**: Accede al estado desde cualquier lugar
- **Facilidad de pruebas**: Sencillo de probar providers de forma aislada
- **Generación de código**: Menos código repetitivo, tipado seguro
## Arquitectura de Providers
```
┌─────────────────────────────────────────────┐
│ Capa UI (Widgets) │
│ - ConsumerWidget / ConsumerStatefulWidget │
│ - ref.watch() / ref.read() │
└─────────────────────────────────────────────┘
↓ observa (watches)
┌─────────────────────────────────────────────┐
│ Capa de Provider │
│ - Anotaciones @riverpod │
│ - Archivos *.g.dart generados │
└─────────────────────────────────────────────┘
↓ usa (uses)
┌─────────────────────────────────────────────┐
│ Capa de Servicio / Store │
│ - Lógica de negocio │
│ - Acceso a datos │
└─────────────────────────────────────────────┘
```
## Tipos de Provider Utilizados
### 1. StateProvider (Estado Simple)
Para estados simples y observables:
```dart
@riverpod
class ThemeNotifier extends _$ThemeNotifier {
@override
ThemeMode build() {
// Cargar desde ajustes
return SettingStore.themeMode;
}
void setTheme(ThemeMode mode) {
state = mode;
SettingStore.themeMode = mode; // Persistir
}
}
```
**Uso:**
```dart
class MyWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final theme = ref.watch(themeNotifierProvider);
return Text('Tema: $theme');
}
}
```
### 2. AsyncNotifierProvider (Estado Asíncrono)
Para datos que se cargan de forma asíncrona:
```dart
@riverpod
class ServerStatus extends _$ServerStatus {
@override
Future<StatusModel> build(Server server) async {
// Carga inicial
return await fetchStatus(server);
}
Future<void> refresh() async {
state = const AsyncValue.loading();
state = await AsyncValue.guard(() async {
return await fetchStatus(server);
});
}
}
```
**Uso:**
```dart
final status = ref.watch(serverStatusProvider(server));
status.when(
data: (data) => StatusWidget(data),
loading: () => LoadingWidget(),
error: (error, stack) => ErrorWidget(error),
)
```
### 3. StreamProvider (Datos en Tiempo Real)
Para flujos de datos continuos:
```dart
@riverpod
Stream<CpuUsage> cpuUsage(CpuUsageRef ref, Server server) {
final client = ref.watch(sshClientProvider(server));
final stream = client.monitorCpu();
// Liberación automática cuando no se observa
ref.onDispose(() {
client.stopMonitoring();
});
return stream;
}
```
**Uso:**
```dart
final cpu = ref.watch(cpuUsageProvider(server));
cpu.when(
data: (usage) => CpuChart(usage),
loading: () => CircularProgressIndicator(),
error: (error, stack) => ErrorWidget(error),
)
```
### 4. Family Providers (Parametrizados)
Providers que aceptan parámetros:
```dart
@riverpod
Future<List<Container>> containers(ContainersRef ref, Server server) async {
final client = await ref.watch(sshClientProvider(server).future);
return await client.listContainers();
}
```
**Uso:**
```dart
final containers = ref.watch(containersProvider(server));
// Diferentes servidores = diferentes estados en caché
final containers2 = ref.watch(containersProvider(server2));
```
## Optimizaciones de Rendimiento
- **Provider Keep-Alive**: Usa `@Riverpod(keepAlive: true)` para evitar que se destruya automáticamente cuando no haya escuchadores.
- **Observación selectiva**: Usa `select` para observar solo una parte específica del estado.
- **Caché de Providers**: Los Family providers cachean resultados por parámetro.
## Mejores Prácticas
1. **Co-localizar providers**: Colócalos cerca de los widgets que los consumen.
2. **Usar generación de código**: Usa siempre `@riverpod`.
3. **Mantener providers enfocados**: Responsabilidad única.
4. **Gestionar estados de carga**: Maneja siempre los estados de AsyncValue.
5. **Liberar recursos**: Usa `ref.onDispose()` para la limpieza.
6. **Evitar árboles de providers profundos**: Mantén el grafo de providers plano.

198
docs/src/content/docs/es/principles/terminal.md Normal file
View File

@@ -0,0 +1,198 @@
---
title: Implementación de la Terminal
description: Cómo funciona internamente la terminal SSH
---
La terminal SSH es una de las funciones más complejas, construida sobre un fork personalizado de xterm.dart.
## Resumen de la Arquitectura
```
┌─────────────────────────────────────────────┐
│ Capa de UI de la Terminal │
│ - Gestión de pestañas │
│ - Teclado virtual │
│ - Selección de texto │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Emulador xterm.dart │
│ - PTY (Pseudo Terminal) │
│ - Emulación VT100/ANSI │
│ - Motor de renderizado │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Capa de Cliente SSH │
│ - Sesión SSH │
│ - Gestión de canales │
│ - Streaming de datos │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Servidor Remoto │
│ - Proceso de Shell │
│ - Ejecución de comandos │
└─────────────────────────────────────────────┘
```
## Ciclo de Vida de la Sesión de Terminal
### 1. Creación de la Sesión
```dart
Future<TerminalSession> createSession(Spi spi) async {
// 1. Obtener cliente SSH
final client = await genClient(spi);
// 2. Crear PTY
final pty = await client.openPty(
term: 'xterm-256color',
cols: 80,
rows: 24,
);
// 3. Inicializar emulador de terminal
final terminal = Terminal(
backend: PtyBackend(pty),
);
// 4. Configurar manejador de cambio de tamaño
terminal.onResize.listen((size) {
pty.resize(size.cols, size.rows);
});
return TerminalSession(
terminal: terminal,
pty: pty,
client: client,
);
}
```
### 2. Emulación de Terminal
El fork de xterm.dart proporciona:
**Emulación VT100/ANSI:**
- Movimiento del cursor
- Colores (soporte para 256 colores)
- Atributos de texto (negrita, subrayado, etc.)
- Regiones de desplazamiento
- Búfer de pantalla alternativo
**Renderizado:**
- Renderizado basado en líneas
- Soporte para texto bidireccional
- Soporte para Unicode/emoji
- Redibujado optimizado
### 3. Flujo de Datos
```
Entrada del Usuario
↓
Teclado Virtual / Teclado Físico
↓
Emulador de Terminal (tecla → secuencia de escape)
↓
Canal SSH (envío)
↓
PTY Remoto
↓
Shell Remoto
↓
Salida del Comando
↓
Canal SSH (recepción)
↓
Emulador de Terminal (analizar códigos ANSI)
↓
Renderizado en Pantalla
```
## Sistema de Múltiples Pestañas
### Gestión de Pestañas
Las pestañas mantienen su estado durante la navegación:
- La conexión SSH se mantiene activa
- Se preserva el estado de la terminal
- Se mantiene el búfer de desplazamiento
- Se retiene el historial de entrada
## Teclado Virtual
### Implementación Específica por Plataforma
**iOS:**
- Teclado personalizado basado en UIView
- Conmutable con un botón de teclado
- Mostrar/ocultar automáticamente basado en el enfoque
**Android:**
- Método de entrada personalizado
- Integrado con el teclado del sistema
- Botones de acción rápida
### Botones del Teclado
| Botón | Acción |
|--------|--------|
| **Conmutar** | Mostrar/ocultar teclado del sistema |
| **Ctrl** | Enviar modificador Ctrl |
| **Alt** | Enviar modificador Alt |
| **SFTP** | Abrir directorio actual |
| **Portapapeles** | Copiar/Pegar sensible al contexto |
| **Snippets** | Ejecutar fragmento de código |
## Selección de Texto
1. **Pulsación larga**: Entrar en modo selección
2. **Arrastrar**: Extender la selección
3. **Soltar**: Copiar al portapapeles
## Fuente y Dimensiones
### Cálculo de Tamaño
```dart
class TerminalDimensions {
static Size calculate(double fontSize, Size screenSize) {
final charWidth = fontSize * 0.6; // Relación de aspecto monoespaciada
final charHeight = fontSize * 1.2;
final cols = (screenSize.width / charWidth).floor();
final rows = (screenSize.height / charHeight).floor();
return Size(cols.toDouble(), rows.toDouble());
}
}
```
### Pellizcar para Ampliar (Pinch-to-Zoom)
```dart
GestureDetector(
onScaleStart: () => _baseFontSize = currentFontSize,
onScaleUpdate: (details) {
final newFontSize = _baseFontSize * details.scale;
resize(newFontSize);
},
)
```
## Esquema de Colores
- **Claro (Light)**: Fondo claro, texto oscuro
- **Oscuro (Dark)**: Fondo oscuro, texto claro
- **AMOLED**: Fondo negro puro
## Optimizaciones de Rendimiento
- **Dirty rectangle**: Solo redibujar las regiones cambiadas
- **Caché de líneas**: Cachear las líneas renderizadas
- **Desplazamiento perezoso (Lazy scrolling)**: Desplazamiento virtual para búferes largos
- **Actualizaciones por lotes**: Unificar múltiples escrituras
- **Compresión**: Comprimir el búfer de desplazamiento
- **Debouncing**: Antirrebote para entradas rápidas

45
docs/src/content/docs/es/quick-start.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: Inicio Rápido
description: Comienza a usar Server Box en cuestión de minutos
---
Sigue esta guía de inicio rápido para conectarte a tu primer servidor y comenzar la monitorización.
## Paso 1: Agregar un Servidor
1. Abre Server Box
2. Toca el botón **+** para agregar un nuevo servidor
3. Completa la información del servidor:
- **Nombre**: Un nombre descriptivo para tu servidor
- **Host**: Dirección IP o nombre de dominio
- **Puerto**: Puerto SSH (por defecto: 22)
- **Usuario**: Nombre de usuario SSH
- **Contraseña o Llave**: Método de autenticación
4. Toca **Guardar** para agregar el servidor
## Paso 2: Conectar y Monitorear
1. Toca en la tarjeta de tu servidor para conectarte
2. La aplicación establecerá una conexión SSH
3. Verás el estado en tiempo real de:
- Uso de CPU
- Memoria (RAM) y Swap
- Uso de disco
- Velocidad de red
## Paso 3: Explorar Funcionalidades
Una vez conectado, puedes:
- **Abrir la Terminal**: Toca el botón de la terminal para obtener acceso SSH completo
- **Explorar Archivos**: Usa SFTP para gestionar archivos
- **Gestionar Contenedores**: Visualiza y controla contenedores Docker
- **Ver Procesos**: Revisa los procesos en ejecución
- **Ejecutar Snippets**: Ejecuta comandos guardados
## Consejos
- **Autenticación Biométrica**: Activa Face ID / Touch ID / Huella dactilar para un acceso rápido (móvil)
- **Widgets en la Pantalla de Inicio**: Agrega widgets de estado del servidor a tu pantalla de inicio (iOS/Android)
- **Ejecución en Segundo Plano**: Mantén las conexiones activas en segundo plano (Android)

55
docs/src/content/docs/features/docker.md
View File

@@ -1,55 +0,0 @@
---
title: Docker Management
description: Monitor and manage Docker containers
---
Flutter Server Box provides an intuitive interface for managing Docker containers on your servers.
## Features
### Container List
- View all containers (running and stopped)
- Container ID and name display
- Image information
- Status indicators
- Creation time
### Container Actions
- **Start**: Launch stopped containers
- **Stop**: Gracefully stop running containers
- **Restart**: Restart containers
- **Remove**: Delete containers
- **View Logs**: Check container logs
- **Inspect**: View container details
### Container Details
- Environment variables
- Port mappings
- Volume mounts
- Network configuration
- Resource usage
## Requirements
- Docker must be installed on your server
- SSH user must have Docker permissions
- For non-root users, add to docker group:
```bash
sudo usermod -aG docker your_username
```
## Quick Actions
- Single tap: View container details
- Long press: Quick action menu
- Swipe: Quick start/stop
- Bulk select: Multiple container operations
## Tips
- Use **auto-refresh** to monitor container status changes
- Filter by running/stopped containers
- Search containers by name or ID

73
docs/src/content/docs/features/monitoring.md
View File

@@ -1,73 +0,0 @@
---
title: Server Monitoring
description: Real-time server status monitoring with beautiful charts
---
Flutter Server Box provides comprehensive real-time monitoring of your server's health and performance.
## Status Cards
The server detail page displays configurable status cards for different system metrics. You can enable/disable cards in settings.
### CPU Monitoring
- Real-time CPU usage percentage
- Per-core CPU usage breakdown
- Historical usage charts
- CPU frequency information
### Memory Monitoring
- **RAM Usage**: Used vs total memory with percentage
- **Swap Usage**: Swap memory utilization
- Memory pressure indicators
- Historical memory trends
### Disk Monitoring
- Mount point usage with percentage
- Total, used, and free space
- I/O statistics
- Multiple disk support
### Network Monitoring
- Real-time upload/download speeds
- Bandwidth usage charts
- Network interface statistics
- Total data transferred
### Advanced Metrics
- **GPU Status**: NVIDIA and AMD GPU monitoring
- **Temperature**: CPU, GPU, and system temperatures
- **Sensors**: Fan speeds, voltages, and other sensor data
- **S.M.A.R.T**: Disk health monitoring
- **Battery**: UPS or battery status (if available)
## Customizing Display
### Reordering Cards
1. Go to Settings
2. Select Server Settings
3. Drag cards to reorder them on the server detail page
### Enabling/Disabling Cards
1. Open a server's detail page
2. Tap the edit/menu button
3. Toggle individual cards on or off
## Auto-Refresh
- Status cards automatically refresh
- Refresh interval is configurable in settings
- Manual refresh available with pull-to-refresh gesture
## Charts and Visualizations
- **Line Charts**: Historical data trends
- **Gauge Charts**: Current usage percentage
- **Color Coding**: Visual indicators for status levels
- **Zoom**: Pinch to zoom on charts for detailed views

67
docs/src/content/docs/features/network.md
View File

@@ -1,67 +0,0 @@
---
title: Network Tools
description: Network testing and diagnostic tools
---
Flutter Server Box includes several network tools for testing and diagnostics.
## iPerf
Perform network speed tests between your device and server.
### Features
- **Upload/Download Speed**: Test bandwidth
- **Server Mode**: Use server as iPerf server
- **Client Mode**: Connect to iPerf servers
- **Custom Parameters**: Duration, parallel streams, etc.
### Usage
1. Open a server
2. Tap **iPerf**
3. Choose server or client mode
4. Configure parameters
5. Start test
## Ping
Test network connectivity and latency.
### Features
- **ICMP Ping**: Standard ping tool
- **Packet Count**: Specify number of packets
- **Packet Size**: Custom packet size
- **Interval**: Time between pings
### Usage
1. Open a server
2. Tap **Ping**
3. Enter target host
4. Configure parameters
5. Start pinging
## Wake on LAN
Wake up remote servers via magic packet.
### Features
- **MAC Address**: Target device MAC
- **Broadcast**: Send broadcast magic packet
- **Saved Profiles**: Store WoL configurations
### Requirements
- Target device must support Wake-on-LAN
- WoL must be enabled in BIOS/UEFI
- Device must be in sleep/soft-off state
- Device must be on the same network or reachable via broadcast
## Tips
- Use iPerf to diagnose network bottlenecks
- Ping multiple hosts to compare latency
- Save WoL profiles for frequently woken devices

56
docs/src/content/docs/features/process.md
View File

@@ -1,56 +0,0 @@
---
title: Process & Services
description: Monitor processes and manage systemd services
---
## Process Management
View and manage running processes on your servers.
### Process List
- All running processes with details
- PID (Process ID)
- CPU and memory usage
- User ownership
- Process command
### Process Actions
- **Kill**: Terminate processes
- **Filter**: By name or user
- **Sort**: By CPU, memory, or PID
- **Search**: Find specific processes
## Systemd Services
Manage systemd services for service control.
### Service List
- All systemd services
- Active/inactive status
- Enabled/disabled state
- Service description
### Service Actions
- **Start**: Launch a stopped service
- **Stop**: Stop a running service
- **Restart**: Restart a service
- **Enable**: Enable auto-start on boot
- **Disable**: Disable auto-start
- **View Status**: Check service status and logs
- **Reload**: Reload service configuration
## Requirements
- SSH user must have appropriate permissions
- For service management: `sudo` access may be required
- Process viewing: Standard user permissions usually sufficient
## Tips
- Use process list to identify resource hogs
- Check service logs for troubleshooting
- Monitor critical services with auto-refresh

105
docs/src/content/docs/features/pve.md
View File

@@ -1,105 +0,0 @@
---
title: Proxmox (PVE)
description: Proxmox Virtual Environment management
---
Flutter Server Box includes support for managing Proxmox VE virtualization platform.
## Features
### VM Management
- **List VMs**: View all virtual machines
- **VM Status**: Check running/stopped states
- **VM Actions**: Start, stop, restart VMs
- **VM Details**: View configuration and resources
### Container (LXC) Management
- **List Containers**: View all LXC containers
- **Container Status**: Monitor container states
- **Container Actions**: Start, stop, restart containers
- **Console Access**: Terminal access to containers
### Node Monitoring
- **Resource Usage**: CPU, memory, disk, network
- **Node Status**: Check node health
- **Cluster View**: Multi-node cluster overview
## Setup
### Adding PVE Server
1. Add server as normal SSH connection
2. Ensure user has PVE permissions
3. Access PVE features from server detail page
### Permissions Required
PVE user needs:
- **VM.Audit**: View VM status
- **VM.PowerMgmt**: Start/stop VMs
- **VM.Console**: Console access
Example permissions setup:
```bash
pveum useradd myuser -password mypass
pveum aclmod /vms -user myuser@pve -role VMAdmin
```
## Usage
### VM Management
1. Open server with PVE
2. Tap **PVE** button
3. View VM list
4. Tap VM for details
5. Use action buttons for management
### Container Management
1. Open server with PVE
2. Tap **PVE** button
3. Switch to Containers tab
4. View and manage LXC containers
### Monitoring
- Real-time resource usage
- Historical data charts
- Multiple node support
## Features by Status
### Implemented
- VM listing and status
- Container listing and status
- Basic VM operations (start/stop/restart)
- Resource monitoring
### Planned
- VM creation from templates
- Snapshot management
- Console access
- Storage management
- Network configuration
## Requirements
- **PVE Version**: 6.x or 7.x
- **Access**: SSH access to PVE host
- **Permissions**: Appropriate PVE user roles
- **Network**: Connectivity to PVE API (via SSH)
## Tips
- Use **dedicated PVE user** with limited permissions
- Monitor **resource usage** for optimal performance
- Check **VM status** before maintenance
- Use **snapshots** before major changes

60
docs/src/content/docs/features/snippets.md
View File

@@ -1,60 +0,0 @@
---
title: Snippets
description: Save and execute custom shell commands
---
Snippets allow you to save frequently used shell commands for quick execution.
## Creating Snippets
1. Go to the **Snippets** tab
2. Tap the **+** button
3. Fill in snippet details:
- **Name**: Friendly name for the snippet
- **Command**: The shell command to execute
- **Description**: Optional notes
4. Save the snippet
## Using Snippets
1. Open a server
2. Tap the **Snippet** button
3. Select a snippet to execute
4. View output in the terminal
## Snippet Features
- **Quick Execute**: One-tap command execution
- **Variables**: Use server-specific variables
- **Organization**: Group related snippets
- **Import/Export**: Share snippets between devices
- **Sync**: Optional cloud sync
## Example Snippets
### System Update
```bash
sudo apt update && sudo apt upgrade -y
```
### Disk Cleanup
```bash
sudo apt autoremove -y && sudo apt clean
```
### Docker Cleanup
```bash
docker system prune -a
```
### View System Logs
```bash
journalctl -n 50 -f
```
## Tips
- Use **descriptive names** for easy identification
- Add **comments** for complex commands
- Test commands before saving as snippets
- Organize snippets by category or server type

83
docs/src/content/docs/fr/advanced/bulk-import.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: Importation massive de serveurs
description: Importer plusieurs serveurs à partir d'un fichier JSON
---
Importez plusieurs configurations de serveur en une seule fois à l'aide d'un fichier JSON.
## Format JSON
:::danger[Avertissement de sécurité]
**Ne stockez jamais de mots de passe en clair dans des fichiers !** Cet exemple JSON montre un champ de mot de passe à des fins de démonstration uniquement, mais vous devriez :
- **Préférer les clés SSH** (`keyId`) au lieu de `pwd` - elles sont plus sûres
- **Utiliser des gestionnaires de mots de passe** ou des variables d'environnement si vous devez utiliser des mots de passe
- **Supprimer le fichier immédiatement** après l'importation - ne laissez pas traîner des identifiants
- **Ajouter au .gitignore** - ne validez jamais de fichiers d'identifiants dans le contrôle de version
:::
```json
[
{
"name": "Mon serveur",
"ip": "example.com",
"port": 22,
"user": "root",
"pwd": "password",
"keyId": "",
"tags": ["production"],
"autoConnect": false
}
]
```
## Champs
| Champ | Requis | Description |
|-------|----------|-------------|
| `name` | Oui | Nom d'affichage |
| `ip` | Oui | Domaine ou adresse IP |
| `port` | Oui | Port SSH (généralement 22) |
| `user` | Oui | Nom d'utilisateur SSH |
| `pwd` | Non | Mot de passe (à éviter - utilisez plutôt des clés SSH) |
| `keyId` | Non | Nom de la clé SSH (à partir des clés privées - recommandé) |
| `tags` | Non | Tags d'organisation |
| `autoConnect` | Non | Connexion automatique au démarrage |
## Étapes d'importation
1. Créer un fichier JSON avec les configurations de serveur
2. Paramètres → Sauvegarde → Importation massive de serveurs
3. Sélectionnez votre fichier JSON
4. Confirmez l'importation
## Exemple
```json
[
{
"name": "Production",
"ip": "prod.example.com",
"port": 22,
"user": "admin",
"keyId": "my-key",
"tags": ["production", "web"]
},
{
"name": "Développement",
"ip": "dev.example.com",
"port": 2222,
"user": "dev",
"keyId": "dev-key",
"tags": ["development"]
}
]
```
## Conseils
- **Utilisez des clés SSH** au lieu de mots de passe lorsque cela est possible
- **Testez la connexion** après l'importation
- **Organisez avec des tags** pour une gestion plus facile
- **Supprimez le fichier JSON** après l'importation
- **Ne validez jamais** de fichiers JSON contenant des identifiants dans le contrôle de version

72
docs/src/content/docs/fr/advanced/custom-commands.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Commandes personnalisées
description: Afficher la sortie des commandes personnalisées sur la page du serveur
---
Ajoutez des commandes shell personnalisées pour afficher leur sortie sur la page de détails du serveur.
## Configuration
1. Paramètres du serveur → Commandes personnalisées
2. Entrez les commandes au format JSON
## Format de base
```json
{
"Nom d'affichage": "commande shell"
}
```
**Exemple :**
```json
{
"Mémoire": "free -h",
"Disque": "df -h",
"Uptime": "uptime"
}
```
## Visualisation des résultats
Après la configuration, les commandes personnalisées apparaissent sur la page de détails du serveur et s'actualisent automatiquement.
## Noms de commandes spéciaux
### server_card_top_right
Affichage sur la carte du serveur de la page d'accueil (coin supérieur droit) :
```json
{
"server_card_top_right": "votre-commande-ici"
}
```
## Conseils
**Utilisez des chemins absolus :**
```json
{"Mon script": "/usr/local/bin/mon-script.sh"}
```
**Commandes avec pipe :**
```json
{"Processus principal": "ps aux | sort -rk 3 | head -5"}
```
**Formater la sortie :**
```json
{"Charge CPU": "uptime | awk -F'load average:' '{print $2}'"}
```
**Gardez les commandes rapides :** Moins de 5 secondes pour une meilleure expérience.
**Limiter la sortie :**
```json
{"Logs": "tail -20 /var/log/syslog"}
```
## Sécurité
Les commandes s'exécutent avec les permissions de l'utilisateur SSH. Évitez les commandes qui modifient l'état du système.

54
docs/src/content/docs/fr/advanced/custom-logo.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: Logo de serveur personnalisé
description: Utiliser des images personnalisées pour les cartes de serveur
---
Affichez des logos personnalisés sur les cartes de serveur à l'aide d'URL d'images.
## Configuration
1. Paramètres du serveur → Logo personnalisé
2. Entrez l'URL de l'image
## Espaces réservés d'URL
### {DIST} - Distribution Linux
Remplacé automatiquement par la distribution détectée :
```
https://example.com/{DIST}.png
```
Devient : `debian.png`, `ubuntu.png`, `arch.png`, etc.
### {BRIGHT} - Thème
Remplacé automatiquement par le thème actuel :
```
https://example.com/{BRIGHT}.png
```
Devient : `light.png` ou `dark.png`
### Combiner les deux
```
https://example.com/{DIST}-{BRIGHT}.png
```
Devient : `debian-light.png`, `ubuntu-dark.png`, etc.
## Conseils
- Utilisez les formats PNG ou SVG
- Taille recommandée : 64x64 à 128x128 pixels
- Utilisez des URL HTTPS
- Gardez des tailles de fichiers réduites
## Distributions supportées
debian, ubuntu, centos, fedora, opensuse, kali, alpine, arch, rocky, deepin, armbian, wrt
Liste complète : [`dist.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/model/server/dist.dart)

64
docs/src/content/docs/fr/advanced/json-settings.md Normal file
View File

@@ -0,0 +1,64 @@
---
title: Paramètres cachés (JSON)
description: Accéder aux paramètres avancés via l'éditeur JSON
---
Certains paramètres sont masqués de l'interface utilisateur mais accessibles via l'éditeur JSON.
## Accès
Appuyez longuement sur **Paramètres** dans le menu latéral pour ouvrir l'éditeur JSON.
## Paramètres cachés courants
### timeOut
Délai d'attente de connexion en secondes.
```json
{"timeOut": 10}
```
**Type :** entier | **Par défaut :** 5 | **Plage :** 1-60
### recordHistory
Enregistrer l'historique (chemins SFTP, etc.).
```json
{"recordHistory": true}
```
**Type :** booléen | **Par défaut :** true
### textFactor
Facteur de mise à l'échelle du texte.
```json
{"textFactor": 1.2}
```
**Type :** double | **Par défaut :** 1.0 | **Plage :** 0.8-1.5
## Trouver plus de paramètres
Tous les paramètres sont définis dans [`setting.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/store/setting.dart).
Recherchez :
```dart
late final settingName = StoreProperty(box, 'settingKey', defaultValue);
```
## ⚠️ Important
**Avant d'éditer :**
- **Créer une sauvegarde** - De mauvais paramètres peuvent empêcher l'ouverture de l'application
- **Éditer avec soin** - Le JSON doit être valide
## Récupération
Si l'application ne s'ouvre plus après l'édition :
1. Effacer les données de l'application (dernier recours)
2. Réinstaller l'application
3. Restaurer à partir d'une sauvegarde

118
docs/src/content/docs/fr/advanced/troubleshooting.md Normal file
View File

@@ -0,0 +1,118 @@
---
title: Problèmes courants
description: Solutions aux problèmes fréquents
---
## Problèmes de connexion
### SSH ne se connecte pas
**Symptômes :** Délai d'attente (timeout), connexion refusée, échec d'authentification
**Solutions :**
1. **Vérifier le type de serveur :** Seuls les systèmes de type Unix sont supportés (Linux, macOS, Android/Termux)
2. **Tester manuellement :** `ssh utilisateur@serveur -p port`
3. **Vérifier le pare-feu :** Le port 22 doit être ouvert
4. **Vérifier les identifiants :** Nom d'utilisateur et mot de passe/clé corrects
### Déconnexions fréquentes
**Symptômes :** Le terminal se déconnecte après une période d'inactivité
**Solutions :**
1. **Keep-alive du serveur :**
```bash
# /etc/ssh/sshd_config
ClientAliveInterval 60
ClientAliveCountMax 3
```
2. **Désactiver l'optimisation de la batterie :**
- MIUI : Batterie → "Pas de restrictions"
- Android : Paramètres → Applications → Désactiver l'optimisation
- iOS : Activer l'actualisation en arrière-plan
## Problèmes de saisie
### Impossible de taper certains caractères
**Solution :** Paramètres → Type de clavier → Passer à `visiblePassword`
Note : La saisie CJK (Chinois, Japonais, Coréen) peut ne pas fonctionner après ce changement.
## Problèmes de l'application
### L'application plante au démarrage
**Symptômes :** L'application ne s'ouvre pas, écran noir
**Causes :** Paramètres corrompus, particulièrement via l'éditeur JSON
**Solutions :**
1. **Effacer les données de l'application :**
- Android : Paramètres → Applications → ServerBox → Effacer les données
- iOS : Supprimer et réinstaller
2. **Restaurer une sauvegarde :** Importer une sauvegarde créée avant de modifier les paramètres
### Problèmes de sauvegarde/restauration
**La sauvegarde ne fonctionne pas :**
- Vérifier l'espace de stockage
- Vérifier que l'application a les permissions de stockage
- Essayer un autre emplacement
**La restauration échoue :**
- Vérifier l'intégrité du fichier de sauvegarde
- Vérifier la compatibilité de la version de l'application
## Problèmes de Widget
### Le widget ne se met pas à jour
**iOS :**
- Attendre jusqu'à 30 minutes pour le rafraîchissement automatique
- Supprimer et rajouter le widget
- Vérifier que l'URL se termine par `/status`
**Android :**
- Appuyer sur le widget pour forcer le rafraîchissement
- Vérifier que l'ID du widget correspond à la configuration dans les paramètres de l'application
**watchOS :**
- Redémarrer l'application sur la montre
- Attendre quelques minutes après un changement de configuration
- Vérifier le format de l'URL
### Le widget affiche une erreur
- Vérifier que ServerBox Monitor fonctionne sur le serveur
- Tester l'URL dans un navigateur
- Vérifier les identifiants d'authentification
## Problèmes de performance
### L'application est lente
**Solutions :**
- Réduire la fréquence de rafraîchissement dans les paramètres
- Vérifier la vitesse du réseau
- Désactiver les serveurs inutilisés
### Utilisation élevée de la batterie
**Solutions :**
- Augmenter les intervalles de rafraîchissement
- Désactiver le rafraîchissement en arrière-plan
- Fermer les sessions SSH inutilisées
## Obtenir de l'aide
Si les problèmes persistent :
1. **Rechercher dans les Issues GitHub :** https://github.com/lollipopkit/flutter_server_box/issues
2. **Créer une nouvelle Issue :** Inclure la version de l'application, la plateforme et les étapes pour reproduire le problème
3. **Consulter le Wiki :** Cette documentation et le Wiki GitHub

90
docs/src/content/docs/fr/advanced/widgets.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: Widgets de l'écran d'accueil
description: Ajoutez des widgets d'état du serveur à votre écran d'accueil
---
Nécessite l'installation de [ServerBox Monitor](https://github.com/lollipopkit/server_box_monitor) sur vos serveurs.
## Prérequis
Installez d'abord ServerBox Monitor sur votre serveur. Consultez le [Wiki de ServerBox Monitor](https://github.com/lollipopkit/server_box_monitor/wiki/Home) pour les instructions de configuration.
Après l'installation, votre serveur doit avoir :
- Un point de terminaison HTTP/HTTPS
- Un point de terminaison API `/status`
- Une authentification facultative
## Format de l'URL
```
https://votre-serveur.com/status
```
Doit se terminer par `/status`.
## Widget iOS
### Configuration
1. Appuyez longuement sur l'écran d'accueil → Appuyez sur **+**
2. Recherchez "ServerBox"
3. Choisissez la taille du widget
4. Appuyez longuement sur le widget → **Modifier le widget**
5. Entrez l'URL se terminant par `/status`
### Notes
- Doit utiliser HTTPS (sauf pour les adresses IP locales)
- Taux de rafraîchissement maximal : 30 minutes (limite iOS)
- Ajoutez plusieurs widgets pour plusieurs serveurs
## Widget Android
### Configuration
1. Appuyez longuement sur l'écran d'accueil → **Widgets**
2. Trouvez "ServerBox" → Ajoutez à l'écran d'accueil
3. Notez le numéro d'ID du widget affiché
4. Ouvrez l'application ServerBox → Paramètres
5. Appuyez sur **Configurer le lien du widget d'accueil**
6. Ajoutez l'entrée : `Widget ID` = `URL d'état`
Exemple :
- Clé : `17`
- Valeur : `https://mon-serveur.com/status`
7. Appuyez sur le widget sur l'écran d'accueil pour le rafraîchir
## Widget watchOS
### Configuration
1. Ouvrez l'application iPhone → Paramètres
2. **Paramètres iOS** → **Application Watch**
3. Appuyez sur **Ajouter une URL**
4. Entrez l'URL se terminant par `/status`
5. Attendez que l'application de la montre se synchronise
### Notes
- Essayez de redémarrer l'application de la montre si elle ne se met pas à jour
- Vérifiez que le téléphone et la montre sont connectés
## Dépannage
### Le widget ne se met pas à jour
**iOS :** Attendez jusqu'à 30 minutes, puis supprimez et rajoutez-le.
**Android :** Appuyez sur le widget pour forcer le rafraîchissement, vérifiez l'ID dans les paramètres.
**watchOS :** Redémarrez l'application de la montre, attendez quelques minutes.
### Le widget affiche une erreur
- Vérifiez que ServerBox Monitor fonctionne
- Testez l'URL dans un navigateur
- Vérifiez que l'URL se termine par `/status`
## Sécurité
- **Utilisez toujours HTTPS** si possible
- **Adresses IP locales uniquement** sur les réseaux de confiance

86
docs/src/content/docs/fr/development/architecture.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: Architecture
description: Modèles d'architecture et décisions de conception
---
Server Box suit les principes de la Clean Architecture avec une séparation claire entre les couches de données, de domaine et de présentation.
## Architecture en couches
```
┌─────────────────────────────────────┐
│ Couche Présentation │
│ (lib/view/page/) │
│ - Pages, Widgets, Contrôleurs │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Couche Logique Métier │
│ (lib/data/provider/) │
│ - Providers Riverpod │
│ - Gestion de l'état │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Couche Données │
│ (lib/data/model/, store/) │
│ - Modèles, Stockage, Services │
└─────────────────────────────────────┘
```
## Modèles clés
### Gestion de l'état : Riverpod
- **Génération de code** : Utilise `riverpod_generator` pour des providers type-safe
- **State Notifiers** : Pour un état mutable avec une logique métier
- **Async Notifiers** : Pour les états de chargement et d'erreur
- **Stream Providers** : Pour les données en temps réel
### Modèles immuables : Freezed
- Tous les modèles de données utilisent Freezed pour l'immuabilité
- Types Union pour la représentation de l'état
- Sérialisation JSON intégrée
- Extensions CopyWith pour les mises à jour
### Stockage local : Hive
- **hive_ce** : Édition communautaire de Hive
- Pas de `@HiveField` ou `@HiveType` manuel requis
- Adaptateurs de type auto-générés
- Stockage clé-valeur persistant
## Injection de dépendances
Les services et les stores sont injectés via :
1. **Providers** : Exposer les dépendances à l'UI
2. **GetIt** : Localisation de services (le cas échéant)
3. **Injection par constructeur** : Dépendances explicites
## Flux de données
```
Action Utilisateur → Widget → Provider → Service/Store → Mise à jour Modèle → Reconstruction UI
```
1. L'utilisateur interagit avec le widget
2. Le widget appelle une méthode du provider
3. Le provider met à jour l'état via le service/store
4. Le changement d'état déclenche la reconstruction de l'UI
5. Le nouvel état est reflété dans le widget
## Dépendances personnalisées
Le projet utilise plusieurs forks personnalisés pour étendre les fonctionnalités :
- **dartssh2** : Fonctionnalités SSH améliorées
- **xterm** : Émulateur de terminal avec support mobile
- **fl_lib** : Composants UI et utilitaires partagés
## Threading (Multi-processus)
- **Isolates** : Calculs lourds hors du thread principal
- **paquet computer** : Utilitaires multi-threading
- **Async/Await** : Opérations d'E/S non bloquantes

116
docs/src/content/docs/fr/development/building.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: Construction (Building)
description: Instructions de construction pour différentes plateformes
---
Server Box utilise un système de construction personnalisé (`fl_build`) pour les constructions multiplateformes.
## Prérequis
- Flutter SDK (canal stable)
- Outils spécifiques à la plateforme (Xcode pour iOS, Android Studio pour Android)
- Chaîne d'outils Rust (pour certaines dépendances natives)
## Construction pour le développement
```bash
# Exécuter en mode développement
flutter run
# Exécuter sur un appareil spécifique
flutter run -d <id-appareil>
```
## Construction pour la production
Le projet utilise `fl_build` pour la construction :
```bash
# Construire pour une plateforme spécifique
dart run fl_build -p <plateforme>
# Plateformes disponibles :
# - ios
# - android
# - macos
# - linux
# - windows
```
## Constructions spécifiques aux plateformes
### iOS
```bash
dart run fl_build -p ios
```
Nécessite :
- macOS avec Xcode
- CocoaPods
- Compte Apple Developer pour la signature
### Android
```bash
dart run fl_build -p android
```
Nécessite :
- Android SDK
- Java Development Kit
- Keystore pour la signature
### macOS
```bash
dart run fl_build -p macos
```
### Linux
```bash
dart run fl_build -p linux
```
### Windows
```bash
dart run fl_build -p windows
```
Nécessite Windows avec Visual Studio.
## Pré/Post Construction
Le script `make.dart` gère :
- La génération des métadonnées
- Les mises à jour de la chaîne de version
- Les configurations spécifiques aux plateformes
## Dépannage
### Nettoyage de la construction (Clean Build)
```bash
flutter clean
dart run build_runner build --delete-conflicting-outputs
flutter pub get
```
### Incompatibilité de version
Assurez-vous que toutes les dépendances sont compatibles :
```bash
flutter pub upgrade
```
## Liste de contrôle de publication (Release Checklist)
1. Mettre à jour la version dans `pubspec.yaml`
2. Exécuter la génération de code
3. Exécuter les tests
4. Construire pour toutes les plateformes cibles
5. Tester sur des appareils physiques
6. Créer une version (release) GitHub

98
docs/src/content/docs/fr/development/codegen.md Normal file
View File

@@ -0,0 +1,98 @@
---
title: Génération de code
description: Utiliser build_runner pour la génération de code
---
Server Box utilise intensivement la génération de code pour les modèles, la gestion de l'état et la sérialisation.
## Quand exécuter la génération de code
À exécuter après avoir modifié :
- Des modèles avec l'annotation `@freezed`
- Des classes avec `@JsonSerializable`
- Des modèles Hive
- Des providers avec `@riverpod`
- Des localisations (fichiers ARB)
## Exécuter la génération de code
```bash
# Générer tout le code
dart run build_runner build --delete-conflicting-outputs
# Nettoyer et régénérer
dart run build_runner build --delete-conflicting-outputs --clean
```
## Fichiers générés
### Freezed (`*.freezed.dart`)
Modèles de données immuables avec types Union :
```dart
@freezed
class ServerState with _$ServerState {
const factory ServerState.connected() = Connected;
const factory ServerState.disconnected() = Disconnected;
const factory ServerState.error(String message) = Error;
}
```
### Sérialisation JSON (`*.g.dart`)
Généré à partir de `json_serializable` :
```dart
@JsonSerializable()
class Server {
final String id;
final String name;
final String host;
Server({required this.id, required this.name, required this.host});
factory Server.fromJson(Map<String, dynamic> json) =>
_$ServerFromJson(json);
Map<String, dynamic> toJson() => _$ServerToJson(this);
}
```
### Providers Riverpod (`*.g.dart`)
Généré à partir de l'annotation `@riverpod` :
```dart
@riverpod
class MyNotifier extends _$MyNotifier {
@override
int build() => 0;
}
```
### Adaptateurs Hive (`*.g.dart`)
Auto-générés pour les modèles Hive (hive_ce) :
```dart
@HiveType(typeId: 0)
class ServerModel {
@HiveField(0)
final String id;
}
```
## Génération de localisation
```bash
flutter gen-l10n
```
Génère `lib/generated/l10n/` à partir des fichiers `lib/l10n/*.arb`.
## Conseils
- Utilisez `--delete-conflicting-outputs` pour éviter les conflits
- Ajoutez les fichiers générés au `.gitignore`
- Ne modifiez jamais manuellement les fichiers générés

115
docs/src/content/docs/fr/development/state.md Normal file
View File

@@ -0,0 +1,115 @@
---
title: Gestion de l'état
description: Modèles de gestion de l'état basés sur Riverpod
---
Server Box utilise Riverpod avec la génération de code pour la gestion de l'état.
## Types de Provider
### StateProvider
État simple qui peut être lu et écrit :
```dart
@riverpod
class Settings extends _$Settings {
@override
SettingsModel build() {
return SettingsModel.defaults();
}
void update(SettingsModel newSettings) {
state = newSettings;
}
}
```
### AsyncNotifierProvider
État qui se charge de manière asynchrone avec des états de chargement/erreur :
```dart
@riverpod
class ServerStatus extends _$ServerStatus {
@override
Future<StatusModel> build(Server server) async {
return fetchStatus(server);
}
Future<void> refresh() async {
state = const AsyncValue.loading();
state = await AsyncValue.guard(() => fetchStatus(server));
}
}
```
### StreamProvider
Données en temps réel provenant de flux (streams) :
```dart
@riverpod
Stream<CpuUsage> cpuUsage(CpuUsageRef ref, Server server) {
return cpuService.monitor(server);
}
```
## Modèles d'état
### États de chargement
```dart
state.when(
data: (data) => DataWidget(data),
loading: () => LoadingWidget(),
error: (error, stack) => ErrorWidget(error),
)
```
### Family Providers
Providers paramétrés :
```dart
@riverpod
List<Container> containers(ContainersRef ref, Server server) {
return containerService.list(server);
}
```
### Auto-Dispose
Providers qui se détruisent lorsqu'ils ne sont plus référencés :
```dart
@Riverpod(keepAlive: false)
class TempState extends _$TempState {
// ...
}
```
## Bonnes pratiques
1. **Utiliser la génération de code** : Utilisez toujours l'annotation `@riverpod`
2. **Co-localiser les providers** : Placez-les près des widgets qui les consomment
3. **Éviter les singletons** : Utilisez des providers à la place
4. **Couches correctes** : Gardez la logique UI séparée de la logique métier
## Lire l'état dans les Widgets
```dart
class ServerWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final status = ref.watch(serverStatusProvider(server));
return status.when(...);
}
}
```
## Modifier l'état
```dart
ref.read(settingsProvider.notifier).update(newSettings);
```

96
docs/src/content/docs/fr/development/structure.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Structure du projet
description: Comprendre la base de code de Server Box
---
Le projet Server Box suit une architecture modulaire avec une séparation claire des préoccupations.
## Structure des répertoires
```
lib/
├── core/ # Utilitaires de base et extensions
├── data/ # Couche de données
│ ├── model/ # Modèles de données par fonctionnalité
│ ├── provider/ # Providers Riverpod
│ └── store/ # Stockage local (Hive)
├── view/ # Couche UI
│ ├── page/ # Pages principales
│ └── widget/ # Widgets réutilisables
├── generated/ # Localisation générée
├── l10n/ # Fichiers ARB de localisation
└── hive/ # Adaptateurs Hive
```
## Couche Core (`lib/core/`)
Contient les utilitaires, les extensions et la configuration du routage :
- **Extensions** : Extensions Dart pour les types courants
- **Routes** : Configuration du routage de l'application
- **Utils** : Fonctions utilitaires partagées
## Couche Données (`lib/data/`)
### Modèles (`lib/data/model/`)
Organisés par fonctionnalité :
- `server/` - Modèles de connexion et d'état du serveur
- `container/` - Modèles de conteneurs Docker
- `ssh/` - Modèles de session SSH
- `sftp/` - Modèles de fichiers SFTP
- `app/` - Modèles spécifiques à l'application
### Providers (`lib/data/provider/`)
Providers Riverpod pour l'injection de dépendances et la gestion de l'état :
- Providers de serveur
- Providers d'état de l'UI
- Providers de service
### Stores (`lib/data/store/`)
Stockage local basé sur Hive :
- Stockage des serveurs
- Stockage des paramètres
- Stockage du cache
## Couche Vue (`lib/view/`)
### Pages (`lib/view/page/`)
Écrans principaux de l'application :
- `server/` - Pages de gestion des serveurs
- `ssh/` - Pages de terminal SSH
- `container/` - Pages de conteneurs
- `setting/` - Pages de paramètres
- `storage/` - Pages SFTP
- `snippet/` - Pages d'extraits de code (snippets)
### Widgets (`lib/view/widget/`)
Composants UI réutilisables :
- Cartes de serveur
- Graphiques d'état
- Composants de saisie (input)
- Dialogues
## Fichiers générés
- `lib/generated/l10n/` - Localisation auto-générée
- `*.g.dart` - Code généré (json_serializable, freezed, hive, riverpod)
- `*.freezed.dart` - Classes immuables Freezed
## Répertoire Packages (`/packages/`)
Contient les forks personnalisés des dépendances :
- `dartssh2/` - Bibliothèque SSH
- `xterm/` - Émulateur de terminal
- `fl_lib/` - Utilitaires partagés
- `fl_build/` - Système de construction

113
docs/src/content/docs/fr/development/testing.md Normal file
View File

@@ -0,0 +1,113 @@
---
title: Tests
description: Stratégies de test et exécution des tests
---
## Exécuter les tests
```bash
# Exécuter tous les tests
flutter test
# Exécuter un fichier de test spécifique
flutter test test/battery_test.dart
# Exécuter avec couverture de code
flutter test --coverage
```
## Structure des tests
Les tests sont situés dans le répertoire `test/`, reflétant la structure de `lib/` :
```
test/
├── data/
│ ├── model/
│ └── provider/
├── view/
│ └── widget/
└── test_helpers.dart
```
## Tests unitaires
Tester la logique métier et les modèles de données :
```dart
test('devrait calculer le pourcentage du CPU', () {
final cpu = CpuModel(usage: 75.0);
expect(cpu.usagePercentage, '75%');
});
```
## Tests de widgets
Tester les composants UI :
```dart
testWidgets('ServerCard affiche le nom du serveur', (tester) async {
await tester.pumpWidget(
ProviderScope(
child: MaterialApp(
home: ServerCard(server: testServer),
),
),
);
expect(find.text('Test Server'), findsOneWidget);
});
```
## Tests de providers
Tester les providers Riverpod :
```dart
test('serverStatusProvider retourne le statut', () async {
final container = ProviderContainer();
final status = await container.read(serverStatusProvider(testServer).future);
expect(status, isA<StatusModel>());
});
```
## Mocking (Simulations)
Utiliser des mocks pour les dépendances externes :
```dart
class MockSshService extends Mock implements SshService {}
test('se connecte au serveur', () async {
final mockSsh = MockSshService();
when(mockSsh.connect(any)).thenAnswer((_) async => true);
// Tester avec le mock
});
```
## Tests d'intégration
Tester des flux utilisateurs complets (dans `integration_test/`) :
```dart
testWidgets('flux d\'ajout de serveur', (tester) async {
await tester.pumpWidget(MyApp());
// Appuyer sur le bouton d'ajout
await tester.tap(find.byIcon(Icons.add));
await tester.pumpAndSettle();
// Remplir le formulaire
await tester.enterText(find.byKey(Key('name')), 'Test Server');
// ...
});
```
## Bonnes pratiques
1. **Arrange-Act-Assert** : Structurer les tests clairement
2. **Noms descriptifs** : Les noms de tests doivent décrire le comportement
3. **Une assertion par test** : Garder les tests focalisés
4. **Mocker les dépendances externes** : Ne pas dépendre de serveurs réels
5. **Tester les cas limites** : Listes vides, valeurs nulles, etc.

46
docs/src/content/docs/fr/index.mdx Normal file
View File

@@ -0,0 +1,46 @@
---
title: Server Box
description: Une application complète de gestion de serveurs multiplateforme
hero:
tagline: Gérez vos serveurs Linux de n'importe où
actions:
- text: Commencer
link: /fr/introduction/
icon: right-arrow
variant: primary
- text: Voir sur GitHub
link: https://github.com/lollipopkit/flutter_server_box
icon: github
variant: minimal
---
import { Card, CardGrid } from '@astrojs/starlight/components';
## Fonctionnalités
<CardGrid stagger>
<Card title="Surveillance en temps réel" icon="chart">
Surveillez le CPU, la mémoire, le disque, le réseau, le GPU et la température avec de magnifiques graphiques en temps réel.
</Card>
<Card title="Terminal SSH" icon="terminal">
Terminal SSH complet avec support multi-onglets et clavier virtuel pour les appareils mobiles.
</Card>
<Card title="Navigateur de fichiers SFTP" icon="folder">
Gérez les fichiers sur vos serveurs avec le client SFTP intégré et le navigateur de fichiers local.
</Card>
<Card title="Gestion Docker" icon="box">
Démarrez, arrêtez et surveillez les conteneurs Docker avec une interface intuitive.
</Card>
<Card title="Multiplateforme" icon="device-mobile">
Disponible sur iOS, Android, macOS, Linux, Windows et watchOS.
</Card>
<Card title="Plus de 12 langues" icon="globe">
Support complet de localisation incluant l'anglais, le chinois, l'allemand, le français et plus encore.
</Card>
</CardGrid>
## Liens rapides
- **Téléchargement**: Disponible sur l'[App Store](https://apps.apple.com/app/id1586449703), [GitHub](https://github.com/lollipopkit/flutter_server_box/releases) et [F-Droid](https://f-droid.org/)
- **Documentation**: Explorez les guides pour commencer avec Server Box
- **Support**: Rejoignez notre communauté sur GitHub pour des discussions et des problèmes

51
docs/src/content/docs/fr/installation.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
title: Installation
description: Téléchargez et installez Server Box sur votre appareil
---
Server Box est disponible sur plusieurs plateformes. Choisissez votre méthode d'installation préférée.
## Applications Mobiles
### iOS
Téléchargez depuis l'**[App Store](https://apps.apple.com/app/id1586449703)**.
### Android
Choisissez votre source préférée :
- **[F-Droid](https://f-droid.org/)** - Pour les utilisateurs qui préfèrent les sources exclusivement FOSS
- **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)** - Pour la dernière version directement depuis la source
## Applications de Bureau
### macOS
Téléchargez depuis les **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
Caractéristiques :
- Intégration native de la barre de menus
- Prise en charge d'Intel et d'Apple Silicon
### Linux
Téléchargez depuis les **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
Disponible en packages AppImage, deb ou tar.gz.
### Windows
Téléchargez depuis les **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)**.
## watchOS
Disponible sur l'**[App Store](https://apps.apple.com/app/id1586449703)** en tant que partie de l'application iOS.
## Construction à partir des sources
Pour construire Server Box à partir des sources, consultez la section [Construction](/fr/development/building/) dans la documentation de développement.
## Informations sur la version
Consultez la page [GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases) pour la dernière version et le journal des modifications (changelog).

32
docs/src/content/docs/fr/introduction.mdx Normal file
View File

@@ -0,0 +1,32 @@
---
title: Introduction
description: Découvrez ce qu'est Server Box et ce qu'il peut faire
---
Server Box est une application complète de gestion de serveur multiplateforme construite avec Flutter. Elle vous permet de surveiller, gérer et contrôler vos serveurs Linux, Unix et Windows de n'importe où.
## Qu'est-ce que Server Box ?
Server Box fournit une interface unifiée pour les tâches d'administration de serveur via des connexions SSH. Que vous soyez un administrateur système, un développeur ou un passionné gérant des serveurs domestiques, cette application met de puissants outils de gestion de serveur dans votre poche.
## Capacités clés
- **Surveillance en temps réel** : Suivez le processeur (CPU), la mémoire, l'utilisation du disque, la vitesse du réseau, l'état du GPU et les températures du système.
- **Terminal SSH** : Accès complet au terminal avec prise en charge multi-onglets et apparence personnalisable.
- **Client SFTP** : Parcourez et gérez les fichiers sur vos serveurs.
- **Gestion Docker** : Contrôlez les conteneurs en toute simplicité.
- **Gestion des processus** : Visualisez et gérez les processus système.
- **Services Systemd** : Démarrez, arrêtez et surveillez les services systemd.
- **Outils réseau** : Tests iPerf, ping et Wake-on-LAN.
- **Snippets** : Enregistrez et exécutez des commandes shell personnalisées.
## Plateformes supportées
Server Box est véritablement multiplateforme :
- **Mobile** : iOS et Android
- **Bureau** : macOS, Linux et Windows
## Licence
Ce projet est sous licence AGPL v3. Le code source est disponible sur [GitHub](https://github.com/lollipopkit/flutter_server_box).

80
docs/src/content/docs/fr/platforms/desktop.md Normal file
View File

@@ -0,0 +1,80 @@
---
title: Fonctionnalités de bureau
description: Fonctionnalités spécifiques à macOS, Linux et Windows
---
Server Box sur les plateformes de bureau offre des fonctionnalités de productivité supplémentaires.
## macOS
### Intégration de la barre de menus
- État rapide du serveur dans la barre de menus
- Accès au serveur en un clic
- Mode compact pour une distraction minimale
- Style de barre de menus natif macOS
### Persistance de l'état des fenêtres
- Mémorise la position et la taille de la fenêtre
- Restaurer la session précédente au lancement
- Prise en charge de plusieurs écrans
### Fonctionnalités natives
- **Barre de titre** : Option de barre de titre personnalisée ou système
- **Mode plein écran** : Surveillance dédiée du serveur
- **Raccourcis clavier** : Raccourcis natifs macOS
- **Touch Bar** (appareils compatibles) : Actions rapides
## Linux
### Intégration native
- Prise en charge de la zone de notification (systray)
- Intégration des notifications de bureau
- Intégration du sélecteur de fichiers
### Gestion des fenêtres
- Prise en charge de X11 et Wayland
- Compatible avec les gestionnaires de fenêtres à tuiles (tiling)
- Option de décorations de fenêtre personnalisées
## Windows
### Fonctionnalités
- Intégration de la zone de notification (systray)
- Actions rapides via la Jump List
- Contrôles de fenêtre natifs
- Option de démarrage automatique au boot
## Fonctionnalités de bureau multiplateformes
### Raccourcis clavier
- **Cmd/Ctrl + N** : Nouveau serveur
- **Cmd/Ctrl + W** : Fermer l'onglet
- **Cmd/Ctrl + T** : Nouvel onglet de terminal
- **Cmd/Ctrl + ,** : Paramètres
### Thèmes
- Thème clair
- Thème sombre
- Thème AMOLED (noir pur)
- Thème système (suit l'OS)
### Fenêtres multiples
- Ouvrir plusieurs serveurs dans des fenêtres séparées
- Faire glisser des onglets vers une nouvelle fenêtre
- Comparer les statistiques des serveurs côte à côte
### Avantages par rapport au mobile
- Écran plus grand pour la surveillance
- Clavier complet pour le terminal
- Opérations de fichiers plus rapides
- Meilleur multitâche

77
docs/src/content/docs/fr/platforms/mobile.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: Fonctionnalités mobiles
description: Fonctionnalités spécifiques à iOS et Android
---
Server Box offre plusieurs fonctionnalités spécifiques aux mobiles pour les appareils iOS et Android.
## Authentification biométrique
Sécurisez vos serveurs avec l'authentification biométrique :
- **iOS** : Face ID ou Touch ID
- **Android** : Authentification par empreinte digitale
Activez-la dans Paramètres > Sécurité > Authentification biométrique.
## Widgets de l'écran d'accueil
Ajoutez des widgets d'état du serveur à votre écran d'accueil pour une surveillance rapide.
### iOS
- Appui long sur l'écran d'accueil
- Appuyez sur **+** pour ajouter un widget
- Recherchez "Server Box"
- Choisissez la taille du widget :
- Petit : État d'un seul serveur
- Moyen : Plusieurs serveurs
- Grand : Informations détaillées
### Android
- Appui long sur l'écran d'accueil
- Appuyez sur **Widgets**
- Trouvez "Server Box"
- Sélectionnez le type de widget
## Fonctionnement en arrière-plan
### Android
Maintenir les connexions actives en arrière-plan :
- Activer dans Paramètres > Avancé > Fonctionnement en arrière-plan
- Nécessite l'exclusion de l'optimisation de la batterie
- Notifications persistantes pour les connexions actives
### iOS
Des limitations en arrière-plan s'appliquent :
- Les connexions peuvent se mettre en pause en arrière-plan
- Reconnexion rapide au retour dans l'application
- Prise en charge de l'actualisation en arrière-plan
## Notifications Push
Recevez des notifications pour :
- Alertes de serveur hors ligne
- Avertissements d'utilisation élevée des ressources
- Alertes de fin de tâche
Configurez dans Paramètres > Notifications.
## Fonctionnalités de l'interface mobile
- **Tirer pour rafraîchir** : Mettre à jour l'état du serveur
- **Actions de glissement** : Opérations rapides sur le serveur
- **Mode paysage** : Meilleure expérience du terminal
- **Clavier virtuel** : Raccourcis pour le terminal
## Intégration de fichiers
- **Application Fichiers (iOS)** : Accès direct SFTP depuis Fichiers
- **Storage Access Framework (Android)** : Partager des fichiers avec d'autres applications
- **Sélecteur de documents** : Sélection de fichiers facile

214
docs/src/content/docs/fr/principles/architecture.md Normal file
View File

@@ -0,0 +1,214 @@
---
title: Présentation de l'architecture
description: Architecture de haut niveau de l'application
---
Server Box suit une architecture en couches avec une séparation claire des préoccupations.
## Couches architecturales
```
┌─────────────────────────────────────────────────┐
│ Couche de présentation (UI) │
│ lib/view/page/, lib/view/widget/ │
│ - Pages, Widgets, Contrôleurs │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Couche logique métier │
│ lib/data/provider/ │
│ - Riverpod Providers, State Notifiers │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Couche d'accès aux données │
│ lib/data/store/, lib/data/model/ │
│ - Hive Stores, Modèles de données │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Couche d'intégration externe │
│ - SSH (dartssh2), Terminal (xterm), SFTP │
│ - Code spécifique à la plateforme (iOS, etc.) │
└─────────────────────────────────────────────────┘
```
## Fondations de l'application
### Point d'entrée principal
`lib/main.dart` initialise l'application :
```dart
void main() {
runApp(
ProviderScope(
child: MyApp(),
),
);
}
```
### Widget racine
`MyApp` fournit :
- **Gestion des thèmes** : Commutation entre thèmes clair/sombre
- **Configuration du routage** : Structure de navigation
- **Provider Scope** : Racine de l'injection de dépendances
### Page d'accueil
`HomePage` sert de plaque tournante pour la navigation :
- **Interface par onglets** : Serveur, Snippet, Conteneur, SSH
- **Gestion de l'état** : État par onglet
- **Navigation** : Accès aux fonctionnalités
## Systèmes de base
### Gestion de l'état : Riverpod
**Pourquoi Riverpod ?**
- Sécurité au moment de la compilation
- Tests faciles
- Pas de dépendance au Build context
- Fonctionne sur toutes les plateformes
**Types de Provider utilisés :**
- `StateProvider` : État mutable simple
- `AsyncNotifierProvider` : États de chargement/erreur/données
- `StreamProvider` : Flux de données en temps réel
- Future providers : Opérations asynchrones uniques
### Persistance des données : Hive CE
**Pourquoi Hive CE ?**
- Pas de dépendances de code natif
- Stockage clé-valeur rapide
- Type-safe avec génération de code
- Pas d'annotations de champs manuelles requises
**Stores :**
- `SettingStore` : Préférences de l'application
- `ServerStore` : Configurations de serveur
- `SnippetStore` : Extraits de commande
- `KeyStore` : Clés SSH
### Modèles immuables : Freezed
**Avantages :**
- Immuabilité au moment de la compilation
- Types Union pour l'état
- Sérialisation JSON intégrée
- Extensions CopyWith
## Stratégie multiplateforme
### Système de plugins
Les plugins Flutter permettent l'intégration avec les plateformes :
| Plateforme | Méthode d'intégration |
|------------|----------------------|
| iOS | CocoaPods, Swift/Obj-C |
| Android | Gradle, Kotlin/Java |
| macOS | CocoaPods, Swift |
| Linux | CMake, C++ |
| Windows | CMake, C# |
### Fonctionnalités spécifiques aux plateformes
**iOS uniquement :**
- Widgets de l'écran d'accueil
- Activités en direct (Live Activities)
- Compagnon Apple Watch
**Android uniquement :**
- Service en arrière-plan
- Notifications push
- Accès au système de fichiers
**Bureau uniquement :**
- Intégration de la barre de menus
- Fenêtres multiples
- Barre de titre personnalisée
## Dépendances personnalisées
### Fork de dartssh2
Client SSH amélioré avec :
- Meilleur support mobile
- Gestion des erreurs améliorée
- Optimisations de performance
### Fork de xterm.dart
Émulateur de terminal avec :
- Rendu optimisé pour le mobile
- Support des gestes tactiles
- Intégration du clavier virtuel
### fl_lib
Paquet d'utilitaires partagés avec :
- Widgets communs
- Extensions
- Fonctions d'aide
## Système de construction
### Paquet fl_build
Système de construction personnalisé pour :
- Constructions multiplateformes
- Signature de code
- Regroupement des ressources (assets)
- Gestion des versions
### Processus de construction
```
make.dart (version) → fl_build (build) → Sortie plateforme
```
1. **Pré-construction** : Calculer la version à partir de Git
2. **Construction** : Compiler pour la plateforme cible
3. **Post-construction** : Paqueter et signer
## Exemple de flux de données
### Mise à jour de l'état du serveur
```
1. Le minuteur se déclenche →
2. Le Provider appelle le service →
3. Le service exécute la commande SSH →
4. La réponse est analysée en modèle →
5. L'état est mis à jour →
6. L'UI se reconstruit avec les nouvelles données
```
### Flux d'action utilisateur
```
1. L'utilisateur appuie sur un bouton →
2. Le Widget appelle une méthode du provider →
3. Le Provider met à jour l'état →
4. Le changement d'état déclenche la reconstruction →
5. Le nouvel état est reflété dans l'UI
```
## Architecture de sécurité
### Protection des données
- **Mots de passe** : Chiffrés avec flutter_secure_storage
- **Clés SSH** : Chiffrées au repos
- **Empreintes d'hôte** : Stockées de manière sécurisée
- **Données de session** : Non persistées
### Sécurité de la connexion
- **Vérification de la clé d'hôte** : Détection MITM (homme du milieu)
- **Chiffrement** : Chiffrement SSH standard
- **Pas de texte clair** : Les données sensibles ne sont jamais stockées en clair

490
docs/src/content/docs/fr/principles/sftp.md Normal file
View File

@@ -0,0 +1,490 @@
---
title: Système SFTP
description: Comment fonctionne le navigateur de fichiers SFTP
---
Le système SFTP fournit des capacités de gestion de fichiers via SSH.
## Architecture
```
┌─────────────────────────────────────────────┐
│ Couche UI SFTP │
│ - Navigateur de fichiers (distant) │
│ - Navigateur de fichiers (local) │
│ - File d'attente de transfert │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Gestion de l'état SFTP │
│ - sftpProvider │
│ - Gestion des chemins │
│ - File d'attente d'opérations │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Couche protocole SFTP │
│ - Sous-système SSH │
│ - Opérations sur les fichiers │
│ - Liste des répertoires │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Transport SSH │
│ - Canal sécurisé │
│ - Streaming de données │
└─────────────────────────────────────────────┘
```
## Établissement de la connexion
### Création du client SFTP
```dart
Future<SftpClient> createSftpClient(Spi spi) async {
// 1. Obtenir le client SSH (réutiliser si disponible)
final sshClient = await genClient(spi);
// 2. Ouvrir le sous-système SFTP
final sftp = await sshClient.openSftp();
return sftp;
}
```
### Réutilisation de la connexion
SFTP réutilise les connexions SSH existantes :
```dart
class ServerProvider {
SSHClient? _sshClient;
SftpClient? _sftpClient;
Future<SftpClient> getSftpClient(String spiId) async {
_sftpClient ??= await _sshClient!.openSftp();
return _sftpClient!;
}
}
```
## Opérations du système de fichiers
### Liste des répertoires
```dart
Future<List<SftpFile>> listDirectory(String path) async {
final sftp = await getSftpClient(spiId);
// Lister le répertoire
final files = await sftp.listDir(path);
// Trier selon les paramètres
files.sort((a, b) {
switch (sortOption) {
case SortOption.name:
return a.name.toLowerCase().compareTo(b.name.toLowerCase());
case SortOption.size:
return a.size.compareTo(b.size);
case SortOption.time:
return a.modified.compareTo(b.modified);
}
});
// Dossiers en premier si activé
if (showFoldersFirst) {
final dirs = files.where((f) => f.isDirectory);
final regular = files.where((f) => !f.isDirectory);
return [...dirs, ...regular];
}
return files;
}
```
### Métadonnées de fichiers
```dart
class SftpFile {
final String name;
final String path;
final int size; // Octets
final int modified; // Horodatage Unix
final String permissions; // ex: "rwxr-xr-x"
final String owner;
final String group;
final bool isDirectory;
final bool isSymlink;
String get sizeFormatted => formatBytes(size);
String get modifiedFormatted => formatDate(modified);
}
```
## Opérations sur les fichiers
### Téléversement (Upload)
```dart
Future<void> uploadFile(
String localPath,
String remotePath,
) async {
final sftp = await getSftpClient(spiId);
// Créer la requête
final req = SftpReq(
spi: spi,
remotePath: remotePath,
localPath: localPath,
type: SftpReqType.upload,
);
// Ajouter à la file d'attente
_transferQueue.add(req);
// Exécuter le transfert avec progression
final file = File(localPath);
final size = await file.length();
final stream = file.openRead();
await sftp.upload(
stream: stream,
toPath: remotePath,
onProgress: (transferred) {
_updateProgress(req, transferred, size);
},
);
// Terminé
_transferQueue.remove(req);
}
```
### Téléchargement (Download)
```dart
Future<void> downloadFile(
String remotePath,
String localPath,
) async {
final sftp = await getSftpClient(spiId);
// Créer le fichier local
final file = File(localPath);
final sink = file.openWrite();
// Télécharger avec progression
final stat = await sftp.stat(remotePath);
await sftp.download(
fromPath: remotePath,
toSink: sink,
onProgress: (transferred) {
_updateProgress(
SftpReq(...),
transferred,
stat.size,
);
},
);
await sink.close();
}
```
### Édition des permissions
```dart
Future<void> setPermissions(
String path,
String permissions,
) async {
final sftp = await getSftpClient(spiId);
// Analyser les permissions (ex: "rwxr-xr-x" ou "755")
final mode = parsePermissions(permissions);
// Définir via commande SSH (plus fiable que SFTP)
final ssh = await getSshClient(spiId);
await ssh.exec('chmod $mode "$path"');
}
```
## Gestion des chemins
### Structure de chemin
```dart
class PathWithPrefix {
final String prefix; // ex: "/home/user"
final String path; // Relatif ou absolu
String get fullPath {
if (path.startsWith('/')) {
return path; // Chemin absolu
}
return '$prefix/$path'; // Chemin relatif
}
PathWithPrefix cd(String subPath) {
return PathWithPrefix(
prefix: fullPath,
path: subPath,
);
}
}
```
### Historique de navigation
```dart
class PathHistory {
final List<String> _history = [];
int _index = -1;
void push(String path) {
// Supprimer l'historique suivant
_history.removeRange(_index + 1, _history.length);
_history.add(path);
_index = _history.length - 1;
}
String? back() {
if (_index > 0) {
_index--;
return _history[_index];
}
return null;
}
String? forward() {
if (_index < _history.length - 1) {
_index++;
return _history[_index];
}
return null;
}
}
```
## Système de transfert
### Requête de transfert
```dart
class SftpReq {
final Spi spi;
final String remotePath;
final String localPath;
final SftpReqType type;
final DateTime createdAt;
int? totalBytes;
int? transferredBytes;
String? error;
}
```
### Suivi de progression
```dart
class TransferProgress {
final SftpReq request;
final int total;
final int transferred;
final DateTime startTime;
double get percentage => (transferred / total) * 100;
Duration get elapsed => DateTime.now().difference(startTime);
String get speedFormatted {
final bytesPerSecond = transferred / elapsed.inSeconds;
return formatSpeed(bytesPerSecond);
}
}
```
### Gestion de la file d'attente
```dart
class TransferQueue {
final List<SftpReq> _queue = [];
final Map<String, TransferProgress> _progress = {};
int _concurrent = 3; // Nombre max de transferts simultanés
Future<void> process() async {
final active = _progress.values.where((p) => p.isInProgress);
if (active.length >= _concurrent) return;
final pending = _queue.where((r) => !_progress.containsKey(r.id));
for (final req in pending.take(_concurrent - active.length)) {
_executeTransfer(req);
}
}
Future<void> _executeTransfer(SftpReq req) async {
try {
_progress[req.id] = TransferProgress.inProgress(req);
if (req.type == SftpReqType.upload) {
await uploadFile(req.localPath, req.remotePath);
} else {
await downloadFile(req.remotePath, req.localPath);
}
_progress[req.id] = TransferProgress.completed(req);
} catch (e) {
_progress[req.id] = TransferProgress.failed(req, e);
}
}
}
```
## Modèle de stockage local
### Cache de téléchargement
Fichiers téléchargés stockés sur :
```dart
String getLocalDownloadPath(String spiId, String remotePath) {
final normalized = remotePath.replaceAll('/', '_');
return 'Paths.file/$spiId/$normalized';
}
```
Exemple :
- Distant : `/var/log/nginx/access.log`
- spiId : `server-123`
- Local : `Paths.file/server-123/_var_log_nginx_access.log`
## Édition de fichiers
### Flux d'édition
```dart
Future<void> editFile(String path) async {
final sftp = await getSftpClient(spiId);
// 1. Vérifier la taille
final stat = await sftp.stat(path);
if (stat.size > editorMaxSize) {
showWarning('Fichier trop volumineux pour l\'éditeur intégré');
return;
}
// 2. Télécharger vers dossier temp
final temp = await downloadToTemp(path);
// 3. Ouvrir dans l'éditeur
final content = await openEditor(temp.path);
// 4. Téléverser en retour
await uploadFile(temp.path, path);
// 5. Nettoyage
await temp.delete();
}
```
### Intégration d'un éditeur externe
```dart
Future<void> editInExternalEditor(String path) async {
final ssh = await getSshClient(spiId);
// Ouvrir le terminal avec l'éditeur
final editor = getSetting('sftpEditor', 'vim');
await ssh.exec('$editor "$path"');
// L'utilisateur édite dans le terminal
// Après sauvegarde, rafraîchir la vue SFTP
}
```
## Gestion des erreurs
### Erreurs de permission
```dart
try {
await sftp.upload(...);
} on SftpPermissionException {
showError('Permission refusée : ${stat.path}');
showHint('Vérifiez les permissions et la propriété du fichier');
}
```
### Erreurs de connexion
```dart
try {
await sftp.listDir(path);
} on SftpConnectionException {
showError('Connexion perdue');
await reconnect();
}
```
### Erreurs d'espace disque
```dart
try {
await sftp.upload(...);
} on SftpNoSpaceException {
showError('Disque plein sur le serveur distant');
}
```
## Optimisations de performance
### Cache de répertoire
```dart
class DirectoryCache {
final Map<String, CachedDirectory> _cache = {};
final Duration ttl = Duration(minutes: 5);
Future<List<SftpFile>> list(String path) async {
final cached = _cache[path];
if (cached != null && !cached.isExpired) {
return cached.files;
}
final files = await sftp.listDir(path);
_cache[path] = CachedDirectory(files);
return files;
}
}
```
### Chargement différé (Lazy Loading)
Pour les répertoires volumineux (>1000 éléments) :
```dart
List<SftpFile> loadPage(String path, int page, int pageSize) {
final all = cache[path] ?? [];
final start = page * pageSize;
final end = start + pageSize;
return all.sublist(start, end.clamp(0, all.length));
}
```
### Pagination
```dart
class PaginatedDirectory {
static const pageSize = 100;
Future<List<SftpFile>> getPage(int page) async {
final offset = page * pageSize;
return await sftp.listDir(
path,
offset: offset,
limit: pageSize,
);
}
}
```

305
docs/src/content/docs/fr/principles/ssh.md Normal file
View File

@@ -0,0 +1,305 @@
---
title: Connexion SSH
description: Comment les connexions SSH sont établies et gérées
---
Comprendre les connexions SSH dans Server Box.
## Flux de connexion
```text
Entrée utilisateur → Configuration Spi → genClient() → Client SSH → Session
```
### Étape 1 : Configuration
Le modèle `Spi` (Server Parameter Info) contient :
```dart
class Spi {
String id; // Identifiant unique
String name; // Nom du serveur
String ip; // Adresse IP
int port; // Port SSH (par défaut 22)
String user; // Nom d'utilisateur
String? pwd; // Mot de passe (chiffré)
String? keyId; // ID de la clé SSH
String? jumpId; // ID du serveur de rebond (Jump server)
String? alterUrl; // URL alternative
}
```
### Étape 2 : Génération du client
`genClient(spi)` crée le client SSH :
```dart
Future<SSHClient> genClient(Spi spi) async {
// 1. Établir le socket
var socket = await connect(spi.ip, spi.port);
// 2. Essayer l'URL alternative en cas d'échec
if (socket == null && spi.alterUrl != null) {
socket = await connect(spi.alterUrl, spi.port);
}
if (socket == null) {
throw ConnectionException('Unable to connect');
}
// 3. Authentifier
final client = SSHClient(
socket: socket,
username: spi.user,
onPasswordRequest: () => spi.pwd,
onIdentityRequest: () => loadKey(spi.keyId),
);
// 4. Vérifier la clé d'hôte
await verifyHostKey(client, spi);
return client;
}
```
### Étape 3 : Serveur de rebond (si configuré)
Pour les serveurs de rebond, connexion récursive :
```dart
if (spi.jumpId != null) {
final jumpClient = await genClient(getJumpSpi(spi.jumpId));
final forwarded = await jumpClient.forwardLocal(
spi.ip,
spi.port,
);
// Se connecter via le socket transféré
}
```
## Méthodes d'authentification
### Authentification par mot de passe
```dart
onPasswordRequest: () => spi.pwd
```
- Mot de passe stocké chiffré dans Hive
- Déchiffré lors de la connexion
- Envoyé au serveur pour vérification
### Authentification par clé privée
```dart
onIdentityRequest: () async {
final key = await KeyStore.get(spi.keyId);
return decyptPem(key.pem, key.password);
}
```
**Processus de chargement de la clé :**
1. Récupérer la clé chiffrée depuis `KeyStore`
2. Déchiffrer le mot de passe (biométrie/invite)
3. Analyser le format PEM
4. Standardiser les fins de ligne (LF)
5. Retourner pour l'authentification
### Keyboard-Interactive
```dart
onUserInfoRequest: (instructions) async {
// Gérer le challenge-response
return responses;
}
```
Supporte :
- L'authentification par mot de passe
- Les jetons OTP
- L'authentification à deux facteurs (2FA)
## Vérification de la clé d'hôte
### Pourquoi vérifier les clés d'hôte ?
Empêche les attaques de type **Man-in-the-Middle (MITM)** en s'assurant que vous vous connectez au même serveur.
### Format de stockage
```text
{spi.id}::{keyType}
```
Exemple :
```text
mon-serveur::ssh-ed25519
mon-serveur::ecdsa-sha2-nistp256
```
### Formats d'empreinte
**MD5 Hex :**
```text
aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
```
**Base64 :**
```text
SHA256:AbCdEf1234567890...=
```
### Flux de vérification
```dart
Future<void> verifyHostKey(SSHClient client, Spi spi) async {
final key = await client.hostKey;
final keyType = key.type;
final fingerprint = md5Hex(key); // ou base64
final stored = SettingStore.sshKnownHostsFingerprints
['${spi.id}::$keyType'];
if (stored == null) {
// Nouvel hôte - inviter l'utilisateur
final trust = await promptUser(
'Hôte inconnu',
'Empreinte : $fingerprint',
);
if (trust) {
SettingStore.sshKnownHostsFingerprints
['${spi.id}::$keyType'] = fingerprint;
}
} else if (stored != fingerprint) {
// Modifié - avertir l'utilisateur
await warnUser(
'La clé d\'hôte a changé !',
'Attaque MITM possible',
);
}
}
```
## Gestion des sessions
### Mise en commun des connexions (Pooling)
Clients actifs maintenus dans `ServerProvider` :
```dart
class ServerProvider {
final Map<String, SSHClient> _clients = {};
SSHClient getClient(String spiId) {
return _clients[spiId] ??= connect(spiId);
}
}
```
### Keep-Alive
Maintenir la connexion pendant l'inactivité :
```dart
Timer.periodic(
Duration(seconds: 30),
(_) => client.sendKeepAlive(),
);
```
### Reconnexion automatique
En cas de perte de connexion :
```dart
client.onError.listen((error) async {
await Future.delayed(Duration(seconds: 5));
reconnect();
});
```
## Cycle de vie de la connexion
```text
┌─────────────┐
│ Initial │
└──────┬──────┘
│ connect()
↓
┌─────────────┐
│ Connexion │ ←──┐
└──────┬──────┘ │
│ succès │
↓ │ échec (retry)
┌─────────────┐ │
│ Connecté │───┘
└──────┬──────┘
│
↓
┌─────────────┐
│ Actif │ ──→ Envoyer des commandes
└──────┬──────┘
│
↓ (erreur/déconnexion)
┌─────────────┐
│ Déconnecté │
└─────────────┘
```
## Gestion des erreurs
### Délai d'attente de connexion (Timeout)
```dart
try {
await client.connect().timeout(
Duration(seconds: 30),
);
} on TimeoutException {
throw ConnectionException('Délai d\'attente de connexion dépassé');
}
```
### Échec d'authentification
```dart
onAuthFail: (error) {
if (error.contains('password')) {
return 'Mot de passe invalide';
} else if (error.contains('key')) {
return 'Clé SSH invalide';
}
return 'Authentification échouée';
}
```
### Discordance de clé d'hôte
```dart
onHostKeyMismatch: (stored, current) {
showSecurityWarning(
'La clé d\'hôte a changé !',
'Attaque MITM possible',
);
}
```
## Considérations de performance
### Réutilisation de la connexion
- Réutiliser les clients entre les fonctionnalités
- Ne pas déconnecter/reconnecter inutilement
- Mutualiser les connexions pour les opérations simultanées
### Paramètres optimaux
- **Timeout** : 30 secondes (ajustable)
- **Keep-alive** : Toutes les 30 secondes
- **Délai de relecture** : 5 secondes
### Efficacité du réseau
- Connexion unique pour plusieurs opérations
- Commandes en pipeline si possible
- Éviter d'ouvrir plusieurs connexions

167
docs/src/content/docs/fr/principles/state.md Normal file
View File

@@ -0,0 +1,167 @@
---
title: Gestion de l'état
description: Comment l'état est géré avec Riverpod
---
Comprendre l'architecture de gestion de l'état dans Server Box.
## Pourquoi Riverpod ?
**Avantages clés :**
- **Sécurité à la compilation** : Capture les erreurs lors de la compilation
- **Pas de BuildContext requis** : Accès à l'état n'importe où
- **Tests faciles** : Simple de tester les providers de manière isolée
- **Génération de code** : Moins de code répétitif, type-safe
## Architecture des Providers
```
┌─────────────────────────────────────────────┐
│ Couche UI (Widgets) │
│ - ConsumerWidget / ConsumerStatefulWidget │
│ - ref.watch() / ref.read() │
└─────────────────────────────────────────────┘
↓ observe (watches)
┌─────────────────────────────────────────────┐
│ Couche Provider │
│ - Annotations @riverpod │
│ - Fichiers *.g.dart générés │
└─────────────────────────────────────────────┘
↓ utilise (uses)
┌─────────────────────────────────────────────┐
│ Couche Service / Store │
│ - Logique métier │
│ - Accès aux données │
└─────────────────────────────────────────────┘
```
## Types de Providers utilisés
### 1. StateProvider (État simple)
Pour un état simple et observable :
```dart
@riverpod
class ThemeNotifier extends _$ThemeNotifier {
@override
ThemeMode build() {
// Charger depuis les paramètres
return SettingStore.themeMode;
}
void setTheme(ThemeMode mode) {
state = mode;
SettingStore.themeMode = mode; // Persister
}
}
```
**Utilisation :**
```dart
class MyWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final theme = ref.watch(themeNotifierProvider);
return Text('Thème : $theme');
}
}
```
### 2. AsyncNotifierProvider (État asynchrone)
Pour les données qui se chargent de manière asynchrone :
```dart
@riverpod
class ServerStatus extends _$ServerStatus {
@override
Future<StatusModel> build(Server server) async {
// Chargement initial
return await fetchStatus(server);
}
Future<void> refresh() async {
state = const AsyncValue.loading();
state = await AsyncValue.guard(() async {
return await fetchStatus(server);
});
}
}
```
**Utilisation :**
```dart
final status = ref.watch(serverStatusProvider(server));
status.when(
data: (data) => StatusWidget(data),
loading: () => LoadingWidget(),
error: (error, stack) => ErrorWidget(error),
)
```
### 3. StreamProvider (Données en temps réel)
Pour les flux de données continus :
```dart
@riverpod
Stream<CpuUsage> cpuUsage(CpuUsageRef ref, Server server) {
final client = ref.watch(sshClientProvider(server));
final stream = client.monitorCpu();
// Libération automatique des ressources quand non observé
ref.onDispose(() {
client.stopMonitoring();
});
return stream;
}
```
**Utilisation :**
```dart
final cpu = ref.watch(cpuUsageProvider(server));
cpu.when(
data: (usage) => CpuChart(usage),
loading: () => CircularProgressIndicator(),
error: (error, stack) => ErrorWidget(error),
)
```
### 4. Family Providers (Paramétrés)
Providers qui acceptent des paramètres :
```dart
@riverpod
Future<List<Container>> containers(ContainersRef ref, Server server) async {
final client = await ref.watch(sshClientProvider(server).future);
return await client.listContainers();
}
```
**Utilisation :**
```dart
final containers = ref.watch(containersProvider(server));
// Différents serveurs = différents états mis en cache
final containers2 = ref.watch(containersProvider(server2));
```
## Optimisations de performance
- **Provider Keep-Alive** : Utilisez `@Riverpod(keepAlive: true)` pour empêcher la destruction automatique quand il n'y a plus d'écouteurs.
- **Observation sélective** : Utilisez `select` pour n'observer qu'une partie spécifique de l'état.
- **Mise en cache des Providers** : Les Family providers mettent en cache les résultats par paramètre.
## Bonnes pratiques
1. **Co-localiser les providers** : Placez-les près des widgets qui les consomment.
2. **Utiliser la génération de code** : Utilisez toujours `@riverpod`.
3. **Garder les providers focalisés** : Responsabilité unique.
4. **Gérer les états de chargement** : Gérez toujours les états AsyncValue.
5. **Libérer les ressources** : Utilisez `ref.onDispose()` pour le nettoyage.
6. **Éviter les arbres de providers profonds** : Gardez le graphe des providers plat.

198
docs/src/content/docs/fr/principles/terminal.md Normal file
View File

@@ -0,0 +1,198 @@
---
title: Implémentation du terminal
description: Comment le terminal SSH fonctionne en interne
---
Le terminal SSH est l'une des fonctionnalités les plus complexes, basée sur un fork personnalisé de xterm.dart.
## Présentation de l'architecture
```
┌─────────────────────────────────────────────┐
│ Couche UI du terminal │
│ - Gestion des onglets │
│ - Clavier virtuel │
│ - Sélection de texte │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Émulateur xterm.dart │
│ - PTY (Pseudo Terminal) │
│ - Émulation VT100/ANSI │
│ - Moteur de rendu │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Couche client SSH │
│ - Session SSH │
│ - Gestion des canaux │
│ - Streaming de données │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Serveur distant │
│ - Processus Shell │
│ - Exécution de commandes │
└─────────────────────────────────────────────┘
```
## Cycle de vie d'une session de terminal
### 1. Création de la session
```dart
Future<TerminalSession> createSession(Spi spi) async {
// 1. Obtenir le client SSH
final client = await genClient(spi);
// 2. Créer le PTY
final pty = await client.openPty(
term: 'xterm-256color',
cols: 80,
rows: 24,
);
// 3. Initialiser l'émulateur de terminal
final terminal = Terminal(
backend: PtyBackend(pty),
);
// 4. Configurer le gestionnaire de redimensionnement
terminal.onResize.listen((size) {
pty.resize(size.cols, size.rows);
});
return TerminalSession(
terminal: terminal,
pty: pty,
client: client,
);
}
```
### 2. Émulation de terminal
Le fork xterm.dart fournit :
**Émulation VT100/ANSI :**
- Mouvement du curseur
- Couleurs (support 256 couleurs)
- Attributs de texte (gras, souligné, etc.)
- Régions de défilement
- Tampon d'écran alterné
**Rendu :**
- Rendu basé sur les lignes
- Support du texte bidirectionnel
- Support Unicode/emoji
- Redessins optimisés
### 3. Flux de données
```
Entrée utilisateur
↓
Clavier virtuel / Clavier physique
↓
Émulateur de terminal (touche → séquence d'échappement)
↓
Canal SSH (envoi)
↓
PTY distant
↓
Shell distant
↓
Sortie de commande
↓
Canal SSH (réception)
↓
Émulateur de terminal (analyse des codes ANSI)
↓
Rendu à l'écran
```
## Système multi-onglets
### Gestion des onglets
Les onglets maintiennent leur état lors de la navigation :
- Connexion SSH maintenue active
- État du terminal préservé
- Tampon de défilement conservé
- Historique de saisie retenu
## Clavier virtuel
### Implémentation spécifique à la plateforme
**iOS :**
- Clavier personnalisé basé sur UIView
- Basculable avec un bouton clavier
- Affichage/masquage automatique basé sur le focus
**Android :**
- Méthode de saisie personnalisée
- Intégré au clavier système
- Boutons d'action rapide
### Boutons du clavier
| Bouton | Action |
|--------|--------|
| **Basculer** | Afficher/masquer le clavier système |
| **Ctrl** | Envoyer le modificateur Ctrl |
| **Alt** | Envoyer le modificateur Alt |
| **SFTP** | Ouvrir le répertoire courant |
| **Presse-papiers** | Copier/Coller contextuel |
| **Snippets** | Exécuter un extrait de code |
## Sélection de texte
1. **Appui long** : Entrer en mode sélection
2. **Glisser** : Étendre la sélection
3. **Relâcher** : Copier dans le presse-papiers
## Police et dimensions
### Calcul de la taille
```dart
class TerminalDimensions {
static Size calculate(double fontSize, Size screenSize) {
final charWidth = fontSize * 0.6; // Ratio d'aspect monospace
final charHeight = fontSize * 1.2;
final cols = (screenSize.width / charWidth).floor();
final rows = (screenSize.height / charHeight).floor();
return Size(cols.toDouble(), rows.toDouble());
}
}
```
### Pincer pour zoomer (Pinch-to-Zoom)
```dart
GestureDetector(
onScaleStart: () => _baseFontSize = currentFontSize,
onScaleUpdate: (details) {
final newFontSize = _baseFontSize * details.scale;
resize(newFontSize);
},
)
```
## Schéma de couleurs
- **Clair (Light)** : Fond clair, texte sombre
- **Sombre (Dark)** : Fond sombre, texte clair
- **AMOLED** : Fond noir pur
## Optimisations de performance
- **Dirty rectangle** : Ne redessiner que les régions modifiées
- **Mise en cache des lignes** : Mettre en cache les lignes rendues
- **Défilement paresseux (Lazy scrolling)** : Défilement virtuel pour les longs tampons
- **Mises à jour par lots** : Fusionner plusieurs écritures
- **Compression** : Compresser le tampon de défilement
- **Anti-rebond (Debouncing)** : Anti-rebond pour les saisies rapides

45
docs/src/content/docs/fr/quick-start.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: Démarrage Rapide
description: Soyez opérationnel avec Server Box en quelques minutes
---
Suivez ce guide de démarrage rapide pour vous connecter à votre premier serveur et commencer la surveillance.
## Étape 1 : Ajouter un serveur
1. Ouvrez Server Box
2. Appuyez sur le bouton **+** pour ajouter un nouveau serveur
3. Remplissez les informations du serveur :
- **Nom** : Un nom convivial pour votre serveur
- **Hôte** : Adresse IP ou nom de domaine
- **Port** : Port SSH (par défaut : 22)
- **Utilisateur** : Nom d'utilisateur SSH
- **Mot de passe ou Clé** : Méthode d'authentification
4. Appuyez sur **Enregistrer** pour ajouter le serveur
## Étape 2 : Connecter et surveiller
1. Appuyez sur la carte de votre serveur pour vous connecter
2. L'application établira une connexion SSH
3. Vous verrez le statut en temps réel pour :
- L'utilisation du processeur (CPU)
- La mémoire (RAM) et le Swap
- L'utilisation du disque
- La vitesse du réseau
## Étape 3 : Explorer les fonctionnalités
Une fois connecté, vous pouvez :
- **Ouvrir le terminal** : Appuyez sur le bouton du terminal pour un accès SSH complet
- **Parcourir les fichiers** : Utilisez SFTP pour gérer les fichiers
- **Gérer les conteneurs** : Visualisez et contrôlez les conteneurs Docker
- **Afficher les processus** : Vérifiez les processus en cours d'exécution
- **Exécuter des snippets** : Exécutez des commandes enregistrées
## Conseils
- **Authentification biométrique** : Activez Face ID / Touch ID / Empreinte digitale pour un accès rapide (mobile)
- **Widgets de l'écran d'accueil** : Ajoutez des widgets d'état du serveur à votre écran d'accueil (iOS/Android)
- **Fonctionnement en arrière-plan** : Maintenez les connexions actives en arrière-plan (Android)

6
docs/src/content/docs/index.mdx
View File

@@ -1,5 +1,5 @@
---
title: Flutter Server Box
title: Server Box
description: A comprehensive cross-platform server management application
hero:
tagline: Manage your Linux servers from anywhere
@@ -41,6 +41,6 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
## Quick Links
- **Download**: Available on [App Store](https://apps.apple.com/app/flutter-server-box), [Google Play](https://play.google.com/store/apps/details), [GitHub](https://github.com/lollipopkit/flutter_server_box/releases), and [F-Droid](https://f-droid.org/)
- **Documentation**: Explore the guides to get started with Flutter Server Box
- **Download**: Available on [App Store](https://apps.apple.com/app/id1586449703), [GitHub](https://github.com/lollipopkit/flutter_server_box/releases), and [F-Droid](https://f-droid.org/)
- **Documentation**: Explore the guides to get started with Server Box
- **Support**: Join our community on GitHub for discussions and issues

11
docs/src/content/docs/installation.mdx
View File

@@ -1,21 +1,20 @@
---
title: Installation
description: Download and install Flutter Server Box on your device
description: Download and install Server Box on your device
---
Flutter Server Box is available on multiple platforms. Choose your preferred method of installation.
Server Box is available on multiple platforms. Choose your preferred method of installation.
## Mobile Apps
### iOS
Download from the **[App Store](https://apps.apple.com/app/flutter-server-box)**.
Download from the **[App Store](https://apps.apple.com/app/id1586449703)**.
### Android
Choose your preferred source:
- **[Google Play](https://play.google.com/store/apps/details)** - Recommended for most users
- **[F-Droid](https://f-droid.org/)** - For users who prefer FOSS-only sources
- **[GitHub Releases](https://github.com/lollipopkit/flutter_server_box/releases)** - For the latest version directly from the source
@@ -41,11 +40,11 @@ Download from **[GitHub Releases](https://github.com/lollipopkit/flutter_server_
## watchOS
Available on the **[App Store](https://apps.apple.com/app/flutter-server-box)** as part of the iOS app.
Available on the **[App Store](https://apps.apple.com/app/id1586449703)** as part of the iOS app.
## Building from Source
To build Flutter Server Box from source, see the [Building](/development/building) section in the Development documentation.
To build Server Box from source, see the [Building](/development/building) section in the Development documentation.
## Version Information

11
docs/src/content/docs/introduction.mdx
View File

@@ -1,13 +1,13 @@
---
title: Introduction
description: Learn what Flutter Server Box is and what it can do
description: Learn what Server Box is and what it can do
---
Flutter Server Box is a comprehensive cross-platform server management application built with Flutter. It allows you to monitor, manage, and control your Linux, Unix, and Windows servers from anywhere.
Server Box is a comprehensive cross-platform server management application built with Flutter. It allows you to monitor, manage, and control your Linux, Unix, and Windows servers from anywhere.
## What is Flutter Server Box?
## What is Server Box?
Flutter Server Box provides a unified interface for server administration tasks through SSH connections. Whether you're a system administrator, developer, or hobbyist running home servers, this app puts powerful server management tools in your pocket.
Server Box provides a unified interface for server administration tasks through SSH connections. Whether you're a system administrator, developer, or hobbyist running home servers, this app puts powerful server management tools in your pocket.
## Key Capabilities
@@ -22,11 +22,10 @@ Flutter Server Box provides a unified interface for server administration tasks
## Supported Platforms
Flutter Server Box is truly cross-platform:
Server Box is truly cross-platform:
- **Mobile**: iOS and Android
- **Desktop**: macOS, Linux, and Windows
- **Wearable**: watchOS (Apple Watch)
## License

83
docs/src/content/docs/ja/advanced/bulk-import.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: サーバーの一括インポート
description: JSON ファイルから複数のサーバーをインポートする
---
JSON ファイルを使用して、複数のサーバー設定を一度にインポートします。
## JSON 形式
:::danger[セキュリティ警告]
**プレーンテキストのパスワードをファイルに保存しないでください！** この JSON の例ではデモンストレーションのためにパスワードフィールドを表示していますが、以下の点に注意してください。
- **SSH キーを優先** (`keyId`) し、`pwd` の使用は避けてください。その方が安全です。
- パスワードを使用する必要がある場合は、**シークレットマネージャー**や環境変数を使用してください。
- インポート後は**直ちにファイルを削除**してください。資格情報を放置しないでください。
- **.gitignore に追加**してください。資格情報ファイルをバージョン管理にコミットしないでください。
:::
```json
[
{
"name": "My Server",
"ip": "example.com",
"port": 22,
"user": "root",
"pwd": "password",
"keyId": "",
"tags": ["production"],
"autoConnect": false
}
]
```
## フィールド
| フィールド | 必須 | 説明 |
|-------|----------|-------------|
| `name` | はい | 表示名 |
| `ip` | はい | ドメインまたは IP アドレス |
| `port` | はい | SSH ポート (通常は 22) |
| `user` | はい | SSH ユーザー名 |
| `pwd` | いいえ | パスワード (非推奨 - 代わりに SSH キーを使用してください) |
| `keyId` | いいえ | SSH キー名 (「非公開鍵」から取得 - 推奨) |
| `tags` | いいえ | 整理用タグ |
| `autoConnect` | いいえ | 起動時に自動接続 |
## インポートの手順
1. サーバー設定を含む JSON ファイルを作成する
2. 設定 → バックアップ → サーバーの一括インポート
3. JSON ファイルを選択する
4. インポートを確認する
## 例
```json
[
{
"name": "Production",
"ip": "prod.example.com",
"port": 22,
"user": "admin",
"keyId": "my-key",
"tags": ["production", "web"]
},
{
"name": "Development",
"ip": "dev.example.com",
"port": 2222,
"user": "dev",
"keyId": "dev-key",
"tags": ["development"]
}
]
```
## ヒント
- 可能な限りパスワードの代わりに **SSH キーを使用**してください。
- インポート後に**接続をテスト**してください。
- 管理を容易にするために**タグで整理**してください。
- インポート後に **JSON ファイルを削除**してください。
- 資格情報を含む JSON ファイルを**決してコミットしないでください**。

72
docs/src/content/docs/ja/advanced/custom-commands.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: カスタムコマンド
description: サーバーページにカスタムコマンドの出力を表示する
---
カスタムシェルコマンドを追加して、サーバー詳細ページに出力を表示します。
## 設定
1. サーバー設定 → カスタムコマンド
2. JSON 形式でコマンドを入力
## 基本形式
```json
{
"表示名": "シェルコマンド"
}
```
**例:**
```json
{
"メモリ": "free -h",
"ディスク": "df -h",
"稼働時間": "uptime"
}
```
## 結果の確認
設定後、カスタムコマンドがサーバー詳細ページに表示され、自動的に更新されます。
## 特殊なコマンド名
### server_card_top_right
ホーム画面のサーバーカード（右上の隅）に表示されます。
```json
{
"server_card_top_right": "実行したいコマンド"
}
```
## ヒント
**絶対パスを使用する:**
```json
{"マイ・スクリプト": "/usr/local/bin/my-script.sh"}
```
**パイプを使用する:**
```json
{"トッププロセス": "ps aux | sort -rk 3 | head -5"}
```
**出力を整形する:**
```json
{"CPU負荷": "uptime | awk -F'load average:' '{print $2}'"}
```
**コマンドを高速に保つ:** 最高の体験のために 5 秒以内に完了するようにしてください。
**出力を制限する:**
```json
{"ログ": "tail -20 /var/log/syslog"}
```
## セキュリティ
コマンドは SSH ユーザーの権限で実行されます。システムの整合性を変更するようなコマンドは避けてください。

54
docs/src/content/docs/ja/advanced/custom-logo.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: カスタムサーバーロゴ
description: サーバーカードにカスタム画像を使用する
---
画像の URL を使用して、サーバーカードにカスタムロゴを表示します。
## 設定
1. サーバー設定 → カスタムロゴ
2. 画像の URL を入力
## URL プレースホルダー
### {DIST} - Linux ディストリビューション
検出されたディストリビューションに自動的に置換されます。
```
https://example.com/{DIST}.png
```
例: `debian.png`、`ubuntu.png`、`arch.png` など。
### {BRIGHT} - テーマ
現在のテーマに自動的に置換されます。
```
https://example.com/{BRIGHT}.png
```
例: `light.png` または `dark.png`。
### 両方を組み合わせる
```
https://example.com/{DIST}-{BRIGHT}.png
```
例: `debian-light.png`、`ubuntu-dark.png` など。
## ヒント
- PNG または SVG 形式を使用してください。
- 推奨サイズ: 64x64 〜 128x128 ピクセル。
- HTTPS の URL を使用してください。
- ファイルサイズは小さく保ってください。
## サポートされているディストリビューション
debian, ubuntu, centos, fedora, opensuse, kali, alpine, arch, rocky, deepin, armbian, wrt
全リスト: [`dist.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/model/server/dist.dart)

64
docs/src/content/docs/ja/advanced/json-settings.md Normal file
View File

@@ -0,0 +1,64 @@
---
title: 隠し設定 (JSON)
description: JSON エディタ経由で詳細設定にアクセスする
---
一部の設定は UI 上では非表示になっていますが、JSON エディタからアクセス可能です。
## アクセス方法
サイドメニューの**「設定」**を長押しすると、JSON エディタが開きます。
## よく使われる隠し設定
### timeOut
接続のタイムアウト時間（秒）。
```json
{"timeOut": 10}
```
**型:** integer | **デフォルト:** 5 | **範囲:** 1-60
### recordHistory
履歴（SFTP パスなど）を保存します。
```json
{"recordHistory": true}
```
**型:** boolean | **デフォルト:** true
### textFactor
テキストの倍率。
```json
{"textFactor": 1.2}
```
**型:** double | **デフォルト:** 1.0 | **範囲:** 0.8-1.5
## その他の設定を探す
すべての設定は [`setting.dart`](https://github.com/lollipopkit/flutter_server_box/blob/main/lib/data/store/setting.dart) で定義されています。
以下の形式を探してください。
```dart
late final settingName = StoreProperty(box, 'settingKey', defaultValue);
```
## ⚠️ 重要
**編集する前に:**
- **バックアップを作成する** - 設定を間違えるとアプリが起動しなくなる可能性があります。
- **慎重に編集する** - JSON は有効な形式である必要があります。
## 復旧方法
編集後にアプリが起動しなくなった場合:
1. アプリのデータを消去する（最終手段）
2. アプリを再インストールする
3. バックアップから復元する

118
docs/src/content/docs/ja/advanced/troubleshooting.md Normal file
View File

@@ -0,0 +1,118 @@
---
title: 一般的な問題
description: よくある問題の解決策
---
## 接続の問題
### SSH が接続できない
**症状:** タイムアウト、接続拒否、認証失敗
**解決策:**
1. **サーバーの種類を確認する:** Unix 系のシステムのみがサポートされています (Linux, macOS, Android/Termux)。
2. **手動でテストする:** `ssh user@server -p port`
3. **ファイアウォールを確認する:** ポート 22 が開放されている必要があります。
4. **資格情報を確認する:** ユーザー名とパスワード/キーが正しいことを確認してください。
### 頻繁に切断される
**症状:** 放置しているとターミナルが切断される
**解決策:**
1. **サーバーの Keep-alive 設定:**
```bash
# /etc/ssh/sshd_config
ClientAliveInterval 60
ClientAliveCountMax 3
```
2. **バッテリーの最適化を無効にする:**
- MIUI: バッテリー → 「制限なし」
- Android: 設定 → アプリ → 最適化を無効化
- iOS: バックグラウンド更新を有効にする
## 入力の問題
### 特定の文字が入力できない
**解決策:** 設定 → キーボードの種類 → `visiblePassword` に切り替える
注意: この変更後、CJK（中日韓）入力が動作しなくなる可能性があります。
## アプリの問題
### 起動時にアプリがクラッシュする
**症状:** アプリが開かない、画面が真っ暗になる
**原因:** 設定の破損（特に JSON エディタによる編集後）
**解決策:**
1. **アプリのデータを消去する:**
- Android: 設定 → アプリ → ServerBox → データを消去
- iOS: アプリを削除して再インストール
2. **バックアップから復元する:** 設定を変更する前に作成したバックアップをインポートしてください。
### バックアップ/復元の問題
**バックアップが動作しない:**
- ストレージの空き容量を確認してください。
- アプリにストレージ権限があるか確認してください。
- 別の保存場所を試してください。
**復元に失敗する:**
- バックアップファイルの整合性を確認してください。
- アプリのバージョンの互換性を確認してください。
## ウィジェットの問題
### ウィジェットが更新されない
**iOS:**
- 自動更新まで最大 30 分待機してください。
- ウィジェットを一度削除してから再度追加してください。
- URL が `/status` で終わっているか確認してください。
**Android:**
- ウィジェットをタップして強制的に更新してください。
- ウィジェット ID がアプリ設定の構成と一致しているか確認してください。
**watchOS:**
- ウォッチアプリを再起動してください。
- 設定変更後、数分待機してください。
- URL の形式を確認してください。
### ウィジェットにエラーが表示される
- サーバーで ServerBox Monitor が実行されているか確認してください。
- ブラウザで URL をテストしてください。
- 認証資格情報を確認してください。
## パフォーマンスの問題
### アプリが重い
**解決策:**
- 設定で更新頻度を下げてください。
- ネットワーク速度を確認してください。
- 使用していないサーバーを無効にしてください。
### バッテリー消費が激しい
**解決策:**
- 更新間隔を長くしてください。
- バックグラウンド更新を無効にしてください。
- 使用していない SSH セッションを閉じてください。
## サポートを受ける
問題が解決しない場合:
1. **GitHub Issues を検索する:** https://github.com/lollipopkit/flutter_server_box/issues
2. **新しい Issue を作成する:** アプリのバージョン、プラットフォーム、再現手順を含めてください。
3. **Wiki を確認する:** 本ドキュメントおよび GitHub Wiki を参照してください。

90
docs/src/content/docs/ja/advanced/widgets.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: ホーム画面ウィジェット
description: サーバーの状態を表示するウィジェットをホーム画面に追加する
---
サーバーに [ServerBox Monitor](https://github.com/lollipopkit/server_box_monitor) がインストールされている必要があります。
## 前提条件
まずサーバーに ServerBox Monitor をインストールしてください。設定手順については [ServerBox Monitor Wiki](https://github.com/lollipopkit/server_box_monitor/wiki/Home) を参照してください。
インストール後、サーバーで以下が利用可能である必要があります。
- HTTP/HTTPS エンドポイント
- `/status` API エンドポイント
- オプションの認証
## URL 形式
```
https://your-server.com/status
```
末尾は必ず `/status` である必要があります。
## iOS ウィジェット
### 設定
1. ホーム画面を長押し → **+** をタップ
2. 「ServerBox」を検索
3. ウィジェットのサイズを選択
4. ウィジェットを長押し → **ウィジェットを編集**
5. `/status` で終わる URL を入力
### 注意事項
- HTTPS を使用する必要があります（ローカル IP を除く）。
- 最大更新頻度: 30 分（iOS の制限）。
- 複数のサーバーに対して複数のウィジェットを追加できます。
## Android ウィジェット
### 設定
1. ホーム画面を長押し → **ウィジェット**
2. 「ServerBox」を見つける → ホーム画面に追加
3. 表示されたウィジェット ID 番号をメモする
4. ServerBox アプリを開く → 設定
5. **「ホームウィジェットのリンクを構成」**をタップ
6. エントリを追加: `ウィジェット ID` = `ステータス URL`
例:
- キー: `17`
- 値: `https://my-server.com/status`
7. ホーム画面のウィジェットをタップして更新
## watchOS ウィジェット
### 設定
1. iPhone アプリを開く → 設定
2. **iOS 設定** → **Watch アプリ**
3. **「URL を追加」**をタップ
4. `/status` で終わる URL を入力
5. ウォッチアプリが同期されるのを待つ
### 注意事項
- 更新されない場合は、ウォッチアプリの再起動を試してください。
- iPhone と Apple Watch が接続されていることを確認してください。
## トラブルシューティング
### ウィジェットが更新されない
**iOS:** 最大 30 分待機し、その後ウィジェットを削除して再追加してください。
**Android:** ウィジェットをタップして強制的に更新し、設定で ID を確認してください。
**watchOS:** ウォッチアプリを再起動し、数分待機してください。
### ウィジェットにエラーが表示される
- ServerBox Monitor が実行されているか確認してください。
- ブラウザで URL をテストしてください。
- URL が `/status` で終わっているか確認してください。
## セキュリティ
- 可能な限り**常に HTTPS を使用**してください。
- **ローカル IP** は信頼できるネットワーク内でのみ使用してください。

86
docs/src/content/docs/ja/development/architecture.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: アーキテクチャ
description: アーキテクチャパターンと設計上の決定事項
---
Server Box は、データ層、ドメイン層、プレゼンテーション層を明確に分離したクリーンアーキテクチャの原則に従っています。
## 階層型アーキテクチャ
```
┌─────────────────────────────────────┐
│ プレゼンテーション層 │
│ (lib/view/page/) │
│ - ページ、ウィジェット、コントローラー │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ ビジネスロジック層 │
│ (lib/data/provider/) │
│ - Riverpod Provider │
│ - 状態管理 │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ データ層 │
│ (lib/data/model/, store/) │
│ - モデル、ストレージ、サービス │
└─────────────────────────────────────┘
```
## 主要なパターン
### 状態管理: Riverpod
- **コード生成**: 型安全な Provider のために `riverpod_generator` を使用
- **State Notifier**: ビジネスロジックを伴う可変状態に使用
- **Async Notifier**: ロード中やエラー状態の管理に使用
- **Stream Provider**: リアルタイムデータに使用
### 不変モデル: Freezed
- すべてのデータモデルで Freezed による不変性を確保
- 状態表現のための Union 型の活用
- 組み込みの JSON シリアライズ
- 更新のための CopyWith エクステンション
### ローカルストレージ: Hive
- **hive_ce**: Hive のコミュニティ版を使用
- 手動での `@HiveField` や `@HiveType` の指定が不要
- 型アダプターの自動生成
- 永続的なキーバリューストレージ
## 依存関係の注入 (DI)
サービスやストアは以下を通じて注入されます。
1. **Provider**: UI に対して依存関係を公開
2. **GetIt**: サービスロケーター（必要に応じて使用）
3. **コンストラクタ注入**: 明示的な依存関係の定義
## データフロー
```
ユーザーアクション → Widget → Provider → サービス/ストア → モデル更新 → UI 再構築
```
1. ユーザーがウィジェットを操作
2. ウィジェットが Provider のメソッドを呼び出す
3. Provider がサービス/ストアを通じて状態を更新
4. 状態の変化により UI の再構築がトリガーされる
5. 新しい状態がウィジェットに反映される
## カスタム依存関係
プロジェクトでは、機能を拡張するためにいくつかのカスタムフォークを使用しています。
- **dartssh2**: 強化された SSH 機能
- **xterm**: モバイル対応のターミナルエミュレータ
- **fl_lib**: 共有 UI コンポーネントとユーティリティ
## スレッディング
- **Isolate**: 重い計算処理をメインスレッドから分離
- **computer パッケージ**: マルチスレッド用のユーティリティ
- **Async/Await**: 非ブロッキングな I/O 操作

116
docs/src/content/docs/ja/development/building.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: ビルド
description: 各プラットフォーム向けのビルド手順
---
Server Box は、クロスプラットフォームビルドのためにカスタムビルドシステム (`fl_build`) を使用しています。
## 前提条件
- Flutter SDK (stable チャネル)
- プラットフォーム固有のツール (iOS 用の Xcode、Android 用の Android Studio)
- Rust ツールチェーン (一部のネイティブ依存関係のため)
## 開発用ビルド
```bash
# 開発モードで実行
flutter run
# 特定のデバイスで実行
flutter run -d <device-id>
```
## 製品用ビルド
プロジェクトではビルドに `fl_build` を使用します。
```bash
# 特定のプラットフォーム向けにビルド
dart run fl_build -p <platform>
# 利用可能なプラットフォーム:
# - ios
# - android
# - macos
# - linux
# - windows
```
## プラットフォーム固有のビルド
### iOS
```bash
dart run fl_build -p ios
```
以下が必要です。
- Xcode がインストールされた macOS
- CocoaPods
- 署名用の Apple Developer アカウント
### Android
```bash
dart run fl_build -p android
```
以下が必要です。
- Android SDK
- Java Development Kit (JDK)
- 署名用のキーストア
### macOS
```bash
dart run fl_build -p macos
```
### Linux
```bash
dart run fl_build -p linux
```
### Windows
```bash
dart run fl_build -p windows
```
Visual Studio がインストールされた Windows が必要です。
## ビルド前/後処理
`make.dart` スクリプトが以下を処理します。
- メタデータの生成
- バージョン文字列の更新
- プラットフォーム固有の構成
## トラブルシューティング
### クリーンビルド
```bash
flutter clean
dart run build_runner build --delete-conflicting-outputs
flutter pub get
```
### バージョンの不一致
すべての依存関係に互換性があることを確認してください。
```bash
flutter pub upgrade
```
## リリースチェックリスト
1. `pubspec.yaml` のバージョンを更新する
2. コード生成を実行する
3. テストを実行する
4. すべてのターゲットプラットフォーム向けにビルドする
5. 実機でテストする
6. GitHub リリースを作成する

Some files were not shown because too many files have changed in this diff Show More