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.567o1,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,PerezyPEREZdan 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 enALLOWED_ROLES(por defectoadmin,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_ROLESpueden 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 enLOG_FILE.
Elasticsearch
- Memoria: por defecto toma la mitad de la RAM. Limitarla en
/etc/elasticsearch/jvm.options.d/heap.options:1 GB alcanza para pruebas; 2 a 4 GB para ~700 mil archivos. Nunca más de la mitad de la RAM. Controlar con-Xms2g -Xmx2g_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: falseen/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 luegocurl -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-ocrytesseract-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 alib/de FSCrawlerjai-imageio-coreyjai-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 quefs.urlde FSCrawler.API_BIND/API_PORT: dónde escucha (por defecto0.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 leerARCHIVOS_DIR).
Dentro del contenedor, localhost es el propio contenedor, no el servidor:
ES_URL: usar la IP del servidor, por ejemplohttps://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 --reloadno relee el.env: después de cambiarlo, reiniciar la API (con Docker:docker compose up -d, que recrea el contenedor).PUBLIC_BASE_URLtiene 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
- Montar el recurso del NAS por NFS, en solo lectura, en el servidor donde corren FSCrawler y la API.
- Cambiar
fs.url(FSCrawler) yARCHIVOS_DIR(compose) oSTORAGE_ROOT(sin Docker) a esa ruta. - 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_SECRETyDOWNLOAD_SECRET.
Carpeta deploy
../Dockerfiley../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