Files
API-WINDNAS/README.md

13 KiB

API de archivos por persona (FastAPI + Elasticsearch/FSCrawler)

Busca DENTRO de los archivos los que mencionan a una persona (cédula, nombres y apellidos) y entrega enlaces de descarga firmados. La indexación la hace FSCrawler.

Arquitectura

FSCrawler → recorre la carpeta de archivos, extrae texto (+ OCR de imágenes)
          → Elasticsearch (índice "archivos_docs")

Navegador → .10  Admin PHP + Apache  (reenvía /api/ a la API)
            API FastAPI
              ├─ búsqueda: consulta Elasticsearch
              └─ descarga: lee el archivo del disco (misma carpeta que FSCrawler)

La API no indexa nada: no hay indexador ni cron. Solo consulta, aplica permisos, registra búsquedas/descargas y firma los enlaces.

Endpoints

GET /archivos?cedula=&nombres=&apellidos=&limite=

Requiere Authorization: Bearer <JWT>. Se envía la cédula, o nombres y apellidos juntos, o los tres. limite va de 1 a 500 (por defecto 100).

Cómo busca:

  • Cédula: en el contenido como 1234567, 1.234.567 o 1,234,567, o dentro de la ruta del archivo.
  • Nombre, en cualquier orden: completo si aparecen todos los nombres y apellidos cerca (consulta intervals), parcial si aparecen primer nombre y primer apellido juntos.
  • Ignora tildes y mayúsculas: Pérez, Perez y PEREZ dan lo mismo (ver "Tildes").
  • Orden: cédula + nombre > cédula > nombre completo > nombre parcial; luego el más reciente.

Respuesta: criterios, total (devueltos), total_coincidencias (todos los que coinciden) y resultados, cada uno con id, nombre, carpeta, extension, tamano_bytes, modificado_en, coincide_cedula, coincide_nombre (completo / parcial / null), fragmento (coincidencia entre « ») y url_descarga.

Errores: 401 sin token, token inválido o vencido · 403 rol sin permiso · 422 parámetros inválidos · 503 Elasticsearch no disponible.

GET /descargas/{id}?u=&exp=&sig=

No lleva token: la firma HMAC del enlace lo autoriza. La ruta del archivo sale de Elasticsearch, nunca de la URL.

Errores: 403 firma inválida · 410 enlace vencido (DOWNLOAD_LINK_TTL_MINUTES) · 404 el archivo ya no está en disco o está en una carpeta excluida · 503 sin Elasticsearch o sin disco.

GET /salud

{"estado", "elasticsearch_accesible", "tipo_almacenamiento", "almacenamiento_accesible"}. estado es ok o degradado.

Contrato con el Admin PHP (JWT)

El Admin firma un JWT HS256 con el mismo JWT_SECRET que la API:

  • sub: id del usuario (obligatorio; queda en los logs y en los enlaces).
  • rol: tiene que estar en ALLOWED_ROLES (por defecto admin,rrhh).
  • exp: vencimiento (obligatorio). Conviene que dure pocos minutos.

El frontend de ejemplo está en integracion/archivos_persona.js.

Permisos y logs

  • Solo los roles de ALLOWED_ROLES pueden buscar.
  • EXCLUDE_FOLDERS: carpetas que la API nunca devuelve ni deja descargar, aunque estén indexadas. Excluirlas también en FSCrawler (fs.excludes) para que ni se indexen.
  • Cada búsqueda y cada descarga queda en la base (DATABASE_URL, tablas de log de búsquedas y descargas: usuario, criterio, resultados, IP, fecha) y en LOG_FILE.

Elasticsearch

  • Memoria: por defecto toma la mitad de la RAM. Limitarla en /etc/elasticsearch/jvm.options.d/heap.options:
    -Xms2g
    -Xmx2g
    
    1 GB alcanza para pruebas; 2 a 4 GB para ~700 mil archivos. Nunca más de la mitad de la RAM. Controlar con _cat/nodes?v&h=heap.percent,ram.percent: estable por debajo de 75 % está bien.
  • No arranca con "Failure running machine learning native code": agregar xpack.ml.enabled: false en /etc/elasticsearch/elasticsearch.yml.
  • Disco: con más de 90 % de uso Elasticsearch no crea índices (FSCrawler muestra HTTP 503 ... no_shard_available_action_exception). Liberar espacio y luego curl -X POST "$ES/_cluster/reroute?retry_failed=true".
  • En un servidor compartido, ponerle techo con systemd para que no afecte otros servicios: systemctl edit elasticsearch → [Service] / MemoryMax=3G.

FSCrawler

Nombre del índice

FSCrawler 3.0 crea <name>_docs (archivos) y <name>_folder (carpetas). Con name: "archivos", el índice que usa la API es archivos_docs (ES_INDEX).

_settings.yaml (~/.fscrawler/archivos/_settings.yaml, chmod 600)

---
name: "archivos"
fs:
  url: "/srv/archivos"          # la misma carpeta que STORAGE_ROOT de la API
  update_rate: "15m"            # cada cuánto revisa altas, cambios y bajas
  excludes:
    - "/DATOS POLICIA/*"        # carpetas sensibles (además de EXCLUDE_FOLDERS)
  ocr:
    enabled: true
    language: "spa"
    pdf_strategy: "no_ocr"      # OCR solo a imágenes (JPG, PNG, TIFF); PDFs por su texto
elasticsearch:
  urls:
    - "https://127.0.0.1:9200"
  username: "elastic"
  password: "CLAVE"             # entre comillas si tiene #
  ssl_verification: false
  push_templates: false         # ver "Tildes": si no, FSCrawler pisa la plantilla

Validar la sintaxis:

python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1])); print('YAML válido')" ~/.fscrawler/archivos/_settings.yaml

Correr una pasada (--restart vuelve a leer todo, no solo lo cambiado):

export FS_JAVA_OPTS="-Xmx512m"   # memoria de FSCrawler
export OMP_THREAD_LIMIT=1        # Tesseract de a un hilo: evita picos de RAM
fscrawler archivos --loop 1 --restart

Tildes

La plantilla fscrawler_archivos_docs_mapping_content tiene que usar un analizador con asciifolding. Se aplica al crear el índice, así que va antes de indexar:

# 1) push_templates: false en _settings.yaml (arriba)
# 2) reemplazar la plantilla del campo content
curl -X PUT "$ES/_component_template/fscrawler_archivos_docs_mapping_content" \
  -H 'Content-Type: application/json' \
  -d '{"template":{"settings":{"analysis":{"analyzer":{"sin_tildes":{"type":"custom","tokenizer":"standard","filter":["lowercase","asciifolding"]}}}},"mappings":{"properties":{"content":{"type":"text","analyzer":"sin_tildes"}}}}}'
# 3) si el índice ya existía: borrarlo y reindexar
curl -X DELETE "$ES/archivos_docs,archivos_folder"
fscrawler archivos --loop 1 --restart

Sin esto la API igual encuentra lo escrito igual que en el documento (busca con y sin tilde lo que tipea el usuario), pero no "PEREZ" contra "Pérez".

OCR

  • El texto embebido (PDF con texto, Word, Excel, TXT) no necesita OCR.
  • Con pdf_strategy: "no_ocr" solo pasan por Tesseract las imágenes sueltas, por ejemplo los currículums en JPEG. Los PDF escaneados quedan sin contenido.
  • Requiere tesseract-ocr y tesseract-ocr-spa (openSUSE: tesseract-ocr-traineddata-spanish).
  • Probar la calidad con un archivo real: tesseract archivo.jpg - -l spa | head -30. Con resolución baja ("Estimating resolution as 99") lee bien lo grande y puede fallar en la letra chica.
  • Si más adelante se activa OCR para PDFs (pdf_strategy: "auto"), agregar a lib/ de FSCrawler jai-imageio-core y jai-imageio-jpeg2000 (Maven Central) para los PDF con imágenes JPEG2000. Alternativa más liviana: pasar esos PDF una vez por OCRmyPDF (--skip-text -j 1).

Contar los documentos que quedaron sin texto:

curl "$ES/archivos_docs/_count" -H 'Content-Type: application/json' \
  -d '{"query":{"bool":{"must_not":{"exists":{"field":"content"}}}}}'

Avisos que se pueden ignorar

Líneas WARN de Apache POI o PDFBox sobre archivos puntuales, por ejemplo LVL at offset ... has nfc o Paragraph [...] has no PAPX. Creating new one: son Word viejos (.doc) con formato raro; el texto se extrae igual. Preocuparse solo por ERROR que se repitan en todos los archivos.

Verificar contra Elasticsearch

Los tests usan un Elasticsearch simulado; esto confirma que el real se comporta como la API espera:

ES="https://localhost:9200"; AUTH="-u elastic:CLAVE -k"   # local sin seguridad: ES="http://localhost:9200"; AUTH=""

curl $AUTH "$ES/_cat/indices?v"                                  # archivos_docs con docs.count > 0
curl $AUTH -X POST "$ES/archivos_docs/_analyze" -H 'Content-Type: application/json' \
  -d '{"field":"content","text":"Pérez 1.234.567"}'             # tokens "perez" y "1.234.567"
curl $AUTH "$ES/archivos_docs/_mapping/field/path.virtual"      # "type": "keyword"

Instalar la API

Sin Docker

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cp .env.example .env && nano .env          # ES_*, STORAGE_ROOT, secretos
chmod 600 .env
.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips 192.168.0.10
curl http://127.0.0.1:8000/salud           # elasticsearch_accesible y almacenamiento_accesible en true

Con Docker (Dockerfile + docker-compose.yml)

cp .env.example .env && nano .env
mkdir -p data certs && sudo chown $(id -u):$(id -g) data
sudo cp /etc/elasticsearch/certs/http_ca.crt certs/ && sudo chown $(id -u) certs/http_ca.crt
docker compose up -d --build
docker compose ps                          # "healthy" cuando /salud responde

El compose fija STORAGE_ROOT=/datos, DATABASE_URL y LOG_FILE (en ./data); el resto sale del .env. Variables propias del compose (en el .env o el entorno):

  • ARCHIVOS_DIR: carpeta del servidor que se monta en /datos (solo lectura). Tiene que ser la misma que fs.url de FSCrawler.
  • API_BIND / API_PORT: dónde escucha (por defecto 0.0.0.0:8000).
  • FORWARDED_ALLOW_IPS: IP del Apache (.10), para registrar la IP real del usuario.
  • APP_UID / APP_GID: usuario con el que corre (tiene que poder leer ARCHIVOS_DIR).

Dentro del contenedor, localhost es el propio contenedor, no el servidor:

  • ES_URL: usar la IP del servidor, por ejemplo https://192.168.0.22:9200. Esa IP está en el certificado de Elasticsearch, así que la verificación TLS funciona. Si el firewall limita el 9200, permitir también la red de Docker (172.16.0.0/12).
  • ES_CA_CERT=/certs/http_ca.crt (la copia en ./certs).

La API no indexa: FSCrawler corre fuera del compose.

Detalles

  • uvicorn --reload no relee el .env: después de cambiarlo, reiniciar la API (con Docker: docker compose up -d, que recrea el contenedor).
  • PUBLIC_BASE_URL tiene que coincidir con el host y puerto reales, o los enlaces de descarga apuntan mal.
  • El usuario de Elasticsearch de la API debería tener solo lectura sobre archivos_docs.
  • La carpeta de archivos se monta en solo lectura (en Docker: :ro).

Desarrollo local (sin servidor)

Elasticsearch de prueba (sin seguridad, solo accesible desde la propia máquina, tope de 1,5 GB de RAM) con el perfil dev del compose:

sudo systemctl start docker
docker compose --profile dev up -d elasticsearch
curl http://localhost:9200                 # responde con la versión

Apagar / prender: docker compose --profile dev stop / ... start. El índice queda en el volumen es-local-datos.

FSCrawler local con el mismo _settings.yaml, pero fs.url apuntando a una carpeta de prueba y urls: ["http://127.0.0.1:9200"] sin usuario ni clave.

API en Docker (docker compose --profile dev up -d --build), en el .env:

ARCHIVOS_DIR=/home/USUARIO/archivos_prueba
ES_URL=http://elasticsearch:9200
ES_INDEX=archivos_docs
ES_USERNAME=
ES_PASSWORD=
ES_CA_CERT=
ES_VERIFY_TLS=false
API_BIND=127.0.0.1
API_PORT=8080
PUBLIC_BASE_URL=http://127.0.0.1:8080

API con uvicorn directo (uvicorn app.main:app --port 8080 --reload), en el .env:

STORAGE_TYPE=local
STORAGE_ROOT=/home/USUARIO/archivos_prueba
ES_URL=http://localhost:9200
ES_INDEX=archivos_docs
ES_USERNAME=
ES_PASSWORD=
ES_CA_CERT=
ES_VERIFY_TLS=false
PUBLIC_BASE_URL=http://127.0.0.1:8080

Token de prueba (desde la carpeta de la API, con el entorno virtual activo):

python -c "import time,jwt; from app.config import get_settings as g; print(jwt.encode({'sub':'1','rol':'admin','exp':int(time.time())+3600}, g().jwt_secret, 'HS256'))"

En Postman: GET http://127.0.0.1:8080/archivos con los parámetros en Params y Authorization → Bearer Token. La url_descarga se prueba con "Send and Download" (sin token).

Pasar al NAS

  1. Montar el recurso del NAS por NFS, en solo lectura, en el servidor donde corren FSCrawler y la API.
  2. Cambiar fs.url (FSCrawler) y ARCHIVOS_DIR (compose) o STORAGE_ROOT (sin Docker) a esa ruta.
  3. Reindexar (--restart). El código no cambia.

Pendiente para producción

  • Usuario de Elasticsearch de solo lectura para la API.
  • FSCrawler como servicio (systemd) en lugar de a mano.
  • Firewall: el puerto 9200 solo accesible desde la API.
  • Secretos reales en JWT_SECRET y DOWNLOAD_SECRET.

Carpeta deploy

  • ../Dockerfile y ../docker-compose.yml: forma recomendada de correr la API.
  • linux/api-archivos.service: servicio systemd (si no usan Docker).
  • apache.conf: proxy de la .10 hacia la API.
  • nginx.conf: opcional, para que Nginx entregue las descargas (DOWNLOAD_MODE=nginx).

Pruebas

pip install pytest httpx
pytest -q