Qué es NSFS
nsfs (NSFS) es un gestor de ficheros self-hosted en un único binario: explora el sistema de ficheros local y servidores remotos por SSH desde el navegador, con login JWT, RBAC por grupos→roles→permisos (afinable por conexión y prefijo de ruta), registro de auditoría y licencia nslib con trial de 30 días.
- Local + remoto: la barra lateral muestra la raíz
Localy cada conexión SSH como una raíz más; se navega igual en ambas. - Se ve sin descargar: texto y código con Monaco, imágenes, PDF, Word/Excel/PowerPoint, hexadecimal y cola de log en vivo, todo servido al visor del navegador.
- Búsqueda por dentro: un indexador extrae el contenido de los ficheros (txt, log, CSV, JSON, XML, código y Office) y la búsqueda encuentra dentro, no solo por nombre.
- Sin build de frontend: Alpine.js + Tailwind por CDN, 6 idiomas (EN fuente de verdad, ES traducida, FR/DE/IT/PT con fallback a EN).
- Credenciales SSH cifradas en reposo con AES-256-GCM (
security.aes_key). - Solo HTTPS: los usuarios no necesitan FTP, SSH ni instalar nada.
Los nombres de hosts, rutas y usuarios de los ejemplos son ficticios.
Casos de uso
1. Explorar y operar sobre el directorio local permitido
Ver el contenido de /data, crear carpetas, subir/descargar, renombrar y borrar.
nsfs init ./midata
nsfs start --config ./midata
nsfs statusFlujo web: login → conexión Local en la barra lateral → navegar con breadcrumbs → vista lista/cuadrícula → nueva carpeta, subir (arrastrar y soltar), descargar, renombrar, borrar, menú contextual.
2. Añadir un servidor remoto por SSH y navegarlo
Registrar el host prod-ejemplo y comprobar la conexión antes de usarla.
Flujo web: Administración → conexiones → crear (host, puerto 22, usuario, auth password o key con passphrase opcional, root_path) → botón probar conexión → aparece como raíz en la barra lateral (punto verde = conectado, gris = idle, rojo = error) → navegar igual que en local.
3. Dar acceso de solo lectura a un equipo sobre una ruta remota
El grupo operadores solo puede listar /var/log del host prod-ejemplo.
Flujo web: Administración → reglas de acceso → crear regla (connection_id + path_prefix + acciones list|read) para el grupo → comprobar con vista efectiva por usuario → el usuario ve la lista filtrada y recibe 403 al intentar crear carpetas fuera de su jail.
4. Subida masiva, búsqueda y descarga como zip con auditoría
Subir un lote, localizar un fichero por nombre y descargar la selección comprimida.
Flujo web: seleccionar múltiples ficheros → acciones en lote (borrado/movido en lote) → descargar como zip → buscar por nombre (insensible a mayúsculas, paginado con ?page=&limit=) → cada operación queda en audit/YYYY-MM-DD.jsonl y en la vista de auditoría reciente.
5. Publicar una carpeta como entorno propio de un grupo (shares)
El grupo contabilidad ve \\srv\contabilidad como una raíz propia con rol editor, sin ver el resto del servidor.
Flujo web: Administración → shares → crear share (nombre, conexión, root_path, orden) → asignar grupo × rol → el share aparece como raíz en la barra lateral del usuario. El rol del grupo solo aplica dentro del share (deny-wins); fuera de sus shares el usuario no ve nada. API: GET /api/shares/mine.
6. Ver los ficheros sin descargarlos
Un usuario abre un informe, un log o una imagen y lo ve en la página, sin que el fichero pase por su disco.
Flujo web: en el explorador, clic en el fichero → se abre en una pestaña con el visor que le corresponde: Monaco para texto y código, visor de imagen, PDF completo, lectura de Word/Excel/PowerPoint, hexadecimal para binarios y cola en vivo para logs (/api/fs/log/tail). El permiso read basta: la descarga es una opción aparte.
7. Buscar dentro de los ficheros, no solo por su nombre
El indexador extrae el contenido de los ficheros (txt, log, csv, json, xml, código y Office) y la búsqueda encuentra dentro.
# Estado del indexador y reindexado
curl -H "Authorization: Bearer $TOKEN" http://localhost:11000/api/admin/index/status
curl -H "Authorization: Bearer $TOKEN" -X POST http://localhost:11000/api/admin/index/resync
# Búsqueda por contenido (streaming)
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:11000/api/fs/search?connection=local&path=/data&q=cierre+contable"Flujo web: la barra de búsqueda admite nombre y contenido, con filtros por tipo y fecha; Administración → Índice muestra el estado y permite reindexar, reconstruir o pausar.
8. Unificar los ficheros de dos servidores
Copiar entre la carpeta local y una conexión SFTP, sin que nadie monte nada.
Flujo web: seleccionar los ficheros → copiar → la copia se ejecuta en segundo plano con progreso y opción de cancelar (/api/fs/copy-start, /api/fs/copy-progress, /api/fs/copy-cancel). Todo queda registrado en la auditoría.
Interfaz
Referencia
Comandos CLI
| Comando | Descripción |
|---|---|
nsfs init [dir] [--admin-password PASS] | Crea el entorno: config.yaml + base SQLite + carpetas. Sin --admin-password genera una clave aleatoria de 6 caracteres |
nsfs start [dir] / --config dir | Arranca el servidor en background (daemon) |
nsfs stop [--config dir] | Para el daemon |
nsfs status | PID, uptime, memoria |
nsfs run [--config dir] | Primer plano (interno, no documentado en --help) |
nsfs --version | Versión y build |
Configuración principal (config.yaml)
| Clave | Descripción |
|---|---|
server.host / server.port | Escucha (por defecto 0.0.0.0:11000) |
server.tls_cert_file / tls_key_file | TLS opcional |
database.path | Ruta SQLite (./db/security.db) |
security.jwt_secret | Secreto JWT (mín. 32 caracteres) |
security.token_expiry_hours | Validez del token (24) |
security.aes_key | Clave de cifrado de credenciales SSH |
security.password_reset_code_ttl_minutes | Validez del código de reset (10) |
fs.max_upload_mb | Tamaño máximo de subida (500) |
fs.hidden_patterns | Patrones ocultos |
fs.audit_dir | Directorio de auditoría (./audit) |
smtp.* | SMTP opcional para emails de reset |
pagination.page_size | Tamaño de página (100) |
indexer.* | Índice de contenido: intervalos de reindexado, tipos indexados, Office, rutas vigiladas |
Las carpetas publicadas ya no se siembran en el
config.yaml: se dan de alta en Administración → Carpetas y se guardan en la tablasharesde la base de datos. El jail de rutas lo define cada carpeta publicada.
Áreas de la web
Explorador (migas de pan, árbol lateral, vista lista/cuadrícula, búsqueda por nombre y por contenido, filtros por tipo y fecha, multiselección, menú contextual, arrastrar y soltar, pestañas de ficheros abiertos) · visores en el navegador (texto/código con Monaco, imagen, PDF, Word/Excel/PowerPoint, visor hexadecimal con edición por parches y cola de log en vivo) y editor inline con guardado · conexiones SSH/SFTP · shares (directorios gestionados por grupo) · espacios de trabajo, marcadores, búsquedas guardadas y recientes · administración (usuarios, grupos, roles, reglas de acceso, vista efectiva por usuario, mis permisos, estado del indexador, configuración) · feed de eventos en vivo · auditoría reciente · acerca de · temas y selector de idioma.
Límites de la vista previa
| Tipo | Límite | Notas |
|---|---|---|
| Multimedia (PDF, imagen, vídeo, audio) | En línea hasta 200 MB | Solo necesita el permiso read: el fichero no se descarga |
| Texto y código | 1 MB | Se sirve como text/plain para el editor |
| Binario | Por páginas de datos | Visor hexadecimal sin límite práctico de tamaño |
| Log | Últimos 64 KB, trozos de 128 KB | Cola en vivo, avisa de la rotación |
Ejemplos comentados
# 1. Entorno nuevo y arranque
nsfs init ./midata
nsfs start --config ./midata
nsfs status
# 2. Fijar la clave de admin en el init (para scripting)
nsfs init /opt/nsfs-prod --admin-password "clave-segura"
# 3. Ver versión
nsfs --version
# 4. Parar el daemon
nsfs stop --config ./midata# Listado paginado vía API (con token JWT)
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:11000/api/fs/list?connection=local&path=/data&page=1&limit=100"
# Búsqueda por nombre
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:11000/api/fs/search?connection=local&path=/data&q=informe"
# Shares visibles del usuario
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:11000/api/shares/mine"Preguntas frecuentes
¿Dónde creo la clave de admin? En el init: sin --admin-password se genera una aleatoria (se muestra una vez); fíjela con --admin-password para automatizar.
¿Por qué recibo 403 al crear una carpeta? La lista está filtrada por sus permisos (list|read) y la escritura exige regla sobre esa connection_id + path_prefix. Revise la vista efectiva del usuario.
¿Se guardan las contraseñas SSH en claro? No: se cifran con AES-256-GCM usando security.aes_key y nunca se registran en logs.
¿Cómo publico una carpeta como entorno propio de un grupo? Con un share: Administración → shares → crear (conexión + root_path) → asignar grupo × rol. El usuario lo ve como una raíz en su barra lateral.
¿Qué idiomas soporta? EN (fuente), ES (completa), FR/DE/IT/PT (con fallback a EN si falta alguna clave).
¿Necesita los usuarios FTP o SSH? No. Solo HTTPS: entran con su sesión de la web y el acceso a cada carpeta lo define el grupo al que pertenecen.
¿Ver un fichero es descargarlo? No. El contenido se sirve al visor del navegador; el fichero no pasa por el disco del usuario. La descarga (/api/fs/download) es una operación aparte y opcional.
¿Qué diferencia hay entre buscar y buscar por nombre? El buscador busca por nombre y por dentro del fichero. Para eso el indexador extrae el contenido de los ficheros de texto, log, CSV, JSON, XML, código y Office, y lo reindexa cada 5 minutos en local y cada 30 en las conexiones SFTP.
¿Puedo ver un Excel o un Word sin tener Office? Sí: se leen en el navegador, igual que un PDF. Lo mismo con los ficheros binarios, que se ven en hexadecimal y se pueden parchear.
¿Cómo se decide qué gana cuando hay varias reglas? Gana la denegación (deny), y a igualdad gana el prefijo de ruta más largo. La pestaña Efectivas muestra el resultado por usuario y por conexión.
¿Las carpetas publicadas se configuran en el config.yaml? No: se dan de alta en Administración → Carpetas y se guardan en la base de datos (shares). El config.yaml solo lleva los ajustes del servidor, la seguridad y el indexador.
¿Hay que montar el servidor remoto? No: la conexión SFTP se abre desde el propio NSFS, con pool y reconexión. El usuario ve la carpeta remota en el mismo explorador que las locales.