mirror of https://github.com/MacRimi/ProxMenux.git synced 2025-11-17 19:16:25 +00:00

Files

code78 2a0b298ae5 feat: add comprehensive project documentation and analysis

- Created detailed documentation covering ProxMenux project structure, installation flow, and core components
- Added in-depth analysis of script architecture, execution patterns, and key functionalities
- Documented system configuration, translation mechanism, and component interactions
- Included detailed breakdown of file organization, menu system, and installation processes
- Added technical specifications for ProxMenux Monitor web dashboar

2025-11-01 03:01:51 +00:00

Análisis Completo del proyecto ProxMenux

1. Estructura General del Proyecto

Archivos Principales

install_proxmenux.sh: Script de instalación principal (723 líneas)
menu: Script principal que se instala como comando del sistema (93 líneas)
version.txt: Control de versiones (actual: 1.1.7)

Directorios Principales

ProxMenuxDotDeb/
├── scripts/           # 122 archivos de scripts bash
│   ├── menus/        # 13 scripts de menús
│   ├── lxc/          # 6 scripts para contenedores LXC
│   ├── vm/           # 13 scripts para máquinas virtuales
│   ├── storage/      # 9 scripts de almacenamiento
│   ├── share/        # 12 scripts para compartir recursos
│   ├── utilities/    # 6 utilidades del sistema
│   ├── global/       # 10 funciones comunes
│   ├── backup_restore/ # 6 scripts de respaldo
│   ├── post_install/ # 3 scripts post-instalación
│   └── gpu_tpu/      # Scripts para hardware gráfico
├── web/              # 136 archivos - Dashboard Next.js
├── AppImage/         # 54 archivos - ProxMenux Monitor
├── json/             # Archivos de caché de traducciones
├── lang/             # Archivos de idioma
├── guides/           # 5 guías de usuario
└── images/           # 7 imágenes del proyecto

2. Flujo de Instalación

Script: install_proxmenux.sh

Fase 1: Inicialización

Verifica permisos root (línea 716-719)
Carga utils.sh desde GitHub (línea 54-57)
Limpia archivos corruptos de configuración (línea 59-68)

Fase 2: Detección de Instalación Existente

Función check_existing_installation() (línea 71-107)
Detecta 4 tipos: none, normal, translation, unknown
Verifica entorno virtual Python en /opt/googletrans-env
Verifica configuración de idioma en /usr/local/share/proxmenux/config.json

Fase 3: Selección de Versión

Versión Normal (opción 1):
- Dependencias: dialog, curl, jq
- Solo inglés
- Más ligera y rápida
Versión con Traducción (opción 2):
- Dependencias adicionales: python3, python3-venv, python3-pip
- Instala googletrans==4.0.0-rc1 en entorno virtual
- Soporte multiidioma: en, es, fr, de, it, pt
- Nota: No compatible con Proxmox VE 9+ (línea 639-658)

Fase 4: Instalación Normal (install_normal_version())

Instala dependencias básicas
Crea directorios:
- /usr/local/bin (ejecutables)
- /usr/local/share/proxmenux (archivos del sistema)
Descarga desde GitHub:
- utils.sh → /usr/local/share/proxmenux/utils.sh
- menu → /usr/local/bin/menu
- version.txt → /usr/local/share/proxmenux/version.txt
Instala ProxMenux Monitor (AppImage)

Fase 5: Instalación con Traducción (install_translation_version())

Pasos adicionales:
- Selector de idioma interactivo (línea 234-273)
- Crea entorno virtual Python en /opt/googletrans-env
- Instala googletrans con pip
- Descarga cache.json con traducciones precargadas
- Sistema de caché para reducir llamadas a la API de traducción

Fase 6: ProxMenux Monitor

Descarga AppImage desde GitHub (línea 317-360)
Verifica checksum SHA256 (línea 333-351)
Crea servicio systemd /etc/systemd/system/proxmenux-monitor.service
Puerto por defecto: 8008
Se ejecuta como usuario root
Auto-inicio en boot

Script Principal: `/usr/local/bin/menu`

Flujo de Ejecución:

Carga de Configuración (línea 33-44):

REPO_URL="https://raw.githubusercontent.com/MacRimi/ProxMenux/main"
BASE_DIR="/usr/local/share/proxmenux"
source "$UTILS_FILE"

Sistema de Traducción (línea 89-92):
- Carga idioma desde config.json
- Inicializa caché de traducciones
- Función translate() en utils.sh
Verificación de Actualizaciones (línea 48-80):
- Compara versión local vs remota
- Prompt interactivo para actualizar
- Descarga y ejecuta nuevo install_proxmenux.sh si hay actualización

Ejecución del Menú Principal (línea 84-86):

exec bash <(curl -fsSL "$REPO_URL/scripts/menus/main_menu.sh")

Importante: El comando menu NO ejecuta scripts locales, siempre descarga desde GitHub.

4. Sistema de Menús

Menú Principal: `scripts/menus/main_menu.sh`

Compatibilidad PVE 9 (línea 26-64):

Detecta versión de Proxmox
Si PVE 9+ y tiene traducciones instaladas → fuerza reinstalación en versión normal
Previene errores de compatibilidad

Opciones del Menú (línea 97-111):

1. Settings post-install Proxmox    → menu_post_install.sh
2. Hardware: GPUs and Coral-TPU     → hw_grafics_menu.sh
3. Create VM from template          → create_vm_menu.sh
4. Disk and Storage Manager         → storage_menu.sh
5. Mount and Share Manager          → share_menu.sh
6. Proxmox VE Helper Scripts        → menu_Helper_Scripts.sh
7. Network Management               → network_menu.sh
8. Utilities and Tools              → utilities_menu.sh
h. Help and Info Commands           → help_info_menu.sh
s. Settings                         → config_menu.sh
0. Exit

Patrón de Ejecución:

exec bash <(curl -s "$REPO_URL/scripts/menus/submenu.sh")

Todos los menús descargan y ejecutan scripts desde GitHub en tiempo real.

5. Scripts Locales vs Remotos

Estado Actual

Scripts locales: Están presentes en el repositorio (122 archivos)
Ejecución: Siempre desde GitHub mediante curl
Ventaja actual: Actualizaciones automáticas sin reinstalar
Desventaja: Requiere conexión a internet constante

Scripts Principales Disponibles Localmente

Gestión de VMs (scripts/vm/):

create_vm.sh - Crear VMs
synology.sh (39KB) - Instalación Synology DSM
zimaos.sh (40KB) - Instalación ZimaOS
uupdump_creator.sh - Creador de ISOs Windows
select_windows_iso.sh, select_linux_iso.sh, select_nas_iso.sh

Gestión de LXC (scripts/lxc/):

lxc-manual-guide.sh - Guía manual
lxc-privileged-to-unprivileged.sh
lxc-unprivileged-to-privileged.sh

Almacenamiento (scripts/storage/):

disk-passthrough.sh - Passthrough disco a VM
disk-passthrough_ct.sh - Passthrough disco a LXC (22KB)
import-disk-image.sh - Importar imágenes
format-disk.sh, mount-disk-on-host.sh

Compartir Recursos (scripts/share/):

lxc-mount-manager_minimal.sh (35KB) - Gestión mount points
nfs_host.sh (35KB) - Servidor NFS en host
samba_host.sh (52KB) - Servidor Samba en host
nfs_client.sh, samba_client.sh - Clientes en LXC
local-shared-manager.sh - Directorios compartidos locales

Post-Instalación (scripts/post_install/):

auto_post_install.sh (29KB) - Automatizado sin interacción
customizable_post_install.sh (148KB) - Personalizable
uninstall-tools.sh (34KB) - Desinstalador

Utilidades (scripts/utilities/):

upgrade_pve8_to_pve9.sh (35KB) - Upgrade PVE 8→9
system_utils.sh (20KB) - Instalador de utilidades
proxmox_update.sh - Actualización de Proxmox

Red (scripts/menus/network_menu.sh):

43KB de funcionalidades de red
Optimizaciones para LXC+NFS

Global (scripts/global/):

update-pve.sh, update-pve8.sh, update-pve9_2.sh
remove-banner-pve8.sh, remove-banner-pve9.sh
share-common.func (30KB) - Funciones compartidas

6. Sistema de Utilidades: `utils.sh`

Funciones Principales

Interfaz Visual (línea 50-71):

Definición de colores ANSI
Códigos de estilo para terminal
Spinner animado (línea 75-88)

Mensajes Estandarizados:

msg_info() - Info con spinner
msg_ok() - Éxito (checkmark verde)
msg_error() - Error (rojo)
msg_warn() - Advertencia (amarillo)
msg_title() - Títulos
type_text() - Efecto máquina de escribir

Sistema de Traducción (línea 232-305):

translate() {
    # Si idioma es "en" → retorna texto original
    # Busca en caché local (cache.json)
    # Si no existe → llama a googletrans vía Python
    # Guarda en caché para futuras traducciones
    # Limpia prefijos de contexto
}

Contexto de Traducción (línea 48):

TRANSLATION_CONTEXT="Context: Technical message for Proxmox and IT. Translate:"

Logo ASCII (línea 314-400):

Dos versiones: terminal noVNC y SSH
Detección automática del entorno
Diseño en ASCII art con colores

7. ProxMenux Monitor

Componente Web (AppImage)

Tecnología:

Frontend: Next.js 14, React 18, TypeScript
UI: Radix UI + shadcn/ui + Tailwind CSS
Gráficos: Recharts
Backend: Flask (Python) para recolección de datos del sistema
Empaquetado: AppImage (10.3 MB)

Características:

Dashboard en tiempo real
Monitoreo de CPU, RAM, temperatura
Estado de VMs y LXC containers
Gestión de almacenamiento visual
Estadísticas de red
Logs del sistema
Tema oscuro/claro
Responsive design
Puerto: 8008

Servicio Systemd:

[Unit]
Description=ProxMenux Monitor - Web Dashboard
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/usr/local/share/proxmenux
ExecStart=/usr/local/share/proxmenux/ProxMenux-Monitor.AppImage
Restart=on-failure
RestartSec=10
Environment="PORT=8008"

Estado: Se instala automáticamente en ambas versiones (normal y traducción)

8. Sistema de Configuración

Archivos de Configuración

/usr/local/share/proxmenux/config.json:

Estado de instalación de componentes
Idioma seleccionado
Timestamps de instalación
Estados: installed, already_installed, failed

Componentes Rastreados (línea 201):

{
  "dialog": {"status": "installed", "timestamp": "..."},
  "curl": {"status": "already_installed", "timestamp": "..."},
  "jq": {"status": "installed", "timestamp": "..."},
  "python3": {"status": "installed", "timestamp": "..."},
  "virtual_environment": {"status": "created", "timestamp": "..."},
  "googletrans": {"status": "installed", "timestamp": "..."},
  "proxmenux_monitor": {"status": "installed", "timestamp": "..."},
  "language": "es"
}

/usr/local/share/proxmenux/cache.json:

Traducciones cacheadas (100 KB)
Formato: {"texto_original": {"es": "traducción", "fr": "traduction"}}
Reduce llamadas a Google Translate API

/usr/local/share/proxmenux/installed_tools.json:

Registro de herramientas post-instalación
Usado por el desinstalador

9. Funcionalidades Destacadas

Post-Instalación Automatizada

Optimizaciones de repositorios: Limpia duplicados, configura repos gratuitos
Eliminación de banner de suscripción: Con respaldo y reversión
Optimización de memoria y kernel: Ajustes según RAM disponible
Log2RAM: Instalación automática en SSD/NVMe
Network tuning: Optimización de stack de red
Límites del sistema: Aumenta límites de archivos y procesos
Configuración de journald: Ajustada para Log2RAM
Entropía: Mejora generación de números aleatorios
Aliases bash: Personalización del entorno

Gestión de Compartición de Recursos

Enfoque: Mount Points LXC (Host ↔ Container)

Detección automática de tipo de filesystem
Mapeo UID/GID para contenedores unprivileged
Visualización de mount points existentes
Eliminación segura con verificación

Configuraciones disponibles:

NFS: Host, Client LXC, Server LXC
Samba: Host, Client LXC, Server LXC
Directorios locales compartidos

Hardware Especializado

Coral TPU: Instalación de drivers compatible con PVE 8 y 9
GPUs: Passthrough y configuración para VMs y LXC
iGPU: Configuración para contenedores LXC

Upgrade PVE 8 → 9

Script de 35 KB con verificaciones exhaustivas
Guía manual interactiva
Checker de compatibilidad

10. Arquitectura de Ejecución

Patrón de Descarga Dinámica

Todos los scripts siguen este patrón:

exec bash <(curl -s "$REPO_URL/scripts/path/to/script.sh")

Ventajas:

✅ Usuarios siempre tienen la última versión
✅ No requiere reinstalación para actualizaciones
✅ Hotfixes inmediatos
✅ Control centralizado de versiones

Consideraciones:

⚠️ Requiere internet en cada ejecución
⚠️ Dependencia de disponibilidad de GitHub
⚠️ No funciona offline
⚠️ Los scripts locales del repo no se usan directamente

Sistema de Versionado

version.txt en repo: versión remota
/usr/local/share/proxmenux/version.txt: versión local instalada
Check en cada ejecución del comando menu
Prompt para actualizar si hay nueva versión

11. Flujo de Navegación

Comando: menu
    ↓
Verifica actualizaciones
    ↓
Carga utils.sh y traducciones
    ↓
Descarga main_menu.sh desde GitHub
    ↓
Usuario selecciona opción
    ↓
Descarga submenu correspondiente desde GitHub
    ↓
Usuario selecciona acción
    ↓
Descarga y ejecuta script específico desde GitHub
    ↓
Retorna al menú anterior

Ejemplo de navegación:

menu → main_menu.sh
  → opción 5: share_menu.sh
    → opción 4: lxc-mount-manager_minimal.sh (35KB)
      → Ejecuta acciones
      → Retorna a share_menu.sh
    → opción 0: Retorna a main_menu.sh
  → opción 0: Exit

12. Integración con Comunidad

Scripts de la Comunidad Integrados

Proxmox VE Helper-Scripts:

Post-install script oficial
Ejecutado desde: https://github.com/community-scripts/ProxmoxVE

Xshok-proxmox (fork):

Post-install alternativo
Descarga desde fork de MacRimi

Elementos compartidos:

Funciones de utils.sh basadas en Helper-Scripts
Misma filosofía de mensajes estandarizados
Licencia MIT compatible

13. Sistema de Desinstalación

Función: `uninstall_proxmenux()` (línea 109-161)

Proceso:

Confirmación interactiva (whiptail)
Desinstala googletrans y entorno virtual Python
Selector de dependencias a eliminar (python3, python3-venv, pip)
Elimina /usr/local/bin/menu
Elimina /usr/local/share/proxmenux/
Restaura .bashrc desde backup
Restaura /etc/motd desde backup

Tool-specific uninstaller: scripts/post_install/uninstall-tools.sh

Lee installed_tools.json
Permite desinstalar herramientas individualmente
Restaura configuraciones originales

14. Estructura de Archivos JSON

`json/cache.json` (100 KB)

Traducciones precargadas para acelerar el sistema

`json/helpers_cache.json` (273 KB)

Caché extendido, probablemente para Helper Scripts

`lang/cache.json` (5.5 KB)

Caché de idiomas específico

`lang/en.lang` y `lang/es.lang`

Archivos de idioma estáticos (4-5 KB cada uno)

15. Resumen de Componentes

Componente	Ubicación	Función
Instalador	`install_proxmenux.sh`	Instalación inicial y actualizaciones
Comando principal	`/usr/local/bin/menu`	Punto de entrada del usuario
Utilidades	`/usr/local/share/proxmenux/utils.sh`	Funciones compartidas
Configuración	`/usr/local/share/proxmenux/config.json`	Estado del sistema
Caché traducciones	`/usr/local/share/proxmenux/cache.json`	Traducciones cacheadas
Entorno Python	`/opt/googletrans-env/`	Traducción (solo versión translation)
Monitor	`/usr/local/share/proxmenux/ProxMenux-Monitor.AppImage`	Dashboard web
Servicio Monitor	`/etc/systemd/system/proxmenux-monitor.service`	Servicio systemd
Scripts	GitHub (descarga dinámica)	Todos los scripts funcionales

Conclusión

ProxMenuxDotDeb es un sistema modular de gestión de Proxmox VE que utiliza una arquitectura híbrida:

Núcleo local: Comando menu, utilidades, sistema de configuración
Scripts remotos: Toda la funcionalidad se descarga dinámicamente desde GitHub
Dashboard web: AppImage independiente con Next.js + Flask
Sistema de traducción: Opcional, basado en Python + googletrans + caché

El proyecto tiene 122 scripts bash en el repositorio local que podrían ejecutarse localmente, pero actualmente todos se descargan desde GitHub en tiempo de ejecución. Esta arquitectura prioriza mantener a los usuarios actualizados sobre la ejecución offline.

17 KiB

Raw Blame History

Análisis Completo del proyecto ProxMenux

1. Estructura General del Proyecto

Archivos Principales

Directorios Principales

2. Flujo de Instalación

Script: install_proxmenux.sh

3. Funcionamiento del Comando `menu`

Script Principal: `/usr/local/bin/menu`

4. Sistema de Menús

Menú Principal: `scripts/menus/main_menu.sh`

5. Scripts Locales vs Remotos

Estado Actual

Scripts Principales Disponibles Localmente

6. Sistema de Utilidades: `utils.sh`

Funciones Principales

7. ProxMenux Monitor

Componente Web (AppImage)

8. Sistema de Configuración

Archivos de Configuración

9. Funcionalidades Destacadas

Post-Instalación Automatizada

Gestión de Compartición de Recursos

Hardware Especializado

Upgrade PVE 8 → 9

10. Arquitectura de Ejecución

Patrón de Descarga Dinámica

Sistema de Versionado

11. Flujo de Navegación

12. Integración con Comunidad

Scripts de la Comunidad Integrados

13. Sistema de Desinstalación

Función: `uninstall_proxmenux()` (línea 109-161)

14. Estructura de Archivos JSON

`json/cache.json` (100 KB)

`json/helpers_cache.json` (273 KB)

`lang/cache.json` (5.5 KB)

`lang/en.lang` y `lang/es.lang`

15. Resumen de Componentes

Conclusión

17 KiB Raw Blame History

Análisis Completo del proyecto ProxMenux

1. Estructura General del Proyecto

Archivos Principales

Directorios Principales

2. Flujo de Instalación

Script: install_proxmenux.sh

3. Funcionamiento del Comando menu

Script Principal: /usr/local/bin/menu

4. Sistema de Menús

Menú Principal: scripts/menus/main_menu.sh

5. Scripts Locales vs Remotos

Estado Actual

Scripts Principales Disponibles Localmente

6. Sistema de Utilidades: utils.sh

Funciones Principales

7. ProxMenux Monitor

Componente Web (AppImage)

8. Sistema de Configuración

Archivos de Configuración

9. Funcionalidades Destacadas

Post-Instalación Automatizada

Gestión de Compartición de Recursos

Hardware Especializado

Upgrade PVE 8 → 9

10. Arquitectura de Ejecución

Patrón de Descarga Dinámica

Sistema de Versionado

11. Flujo de Navegación

12. Integración con Comunidad

Scripts de la Comunidad Integrados

13. Sistema de Desinstalación

Función: uninstall_proxmenux() (línea 109-161)

14. Estructura de Archivos JSON

json/cache.json (100 KB)

json/helpers_cache.json (273 KB)

lang/cache.json (5.5 KB)

lang/en.lang y lang/es.lang

15. Resumen de Componentes

Conclusión

17 KiB

Raw Blame History

3. Funcionamiento del Comando `menu`

Script Principal: `/usr/local/bin/menu`

Menú Principal: `scripts/menus/main_menu.sh`

6. Sistema de Utilidades: `utils.sh`

Función: `uninstall_proxmenux()` (línea 109-161)

`json/cache.json` (100 KB)

`json/helpers_cache.json` (273 KB)

`lang/cache.json` (5.5 KB)

`lang/en.lang` y `lang/es.lang`