# 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 `. 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 **`_docs`** (archivos) y `_folder` (carpetas). Con `name: "archivos"`, el índice que usa la API es **`archivos_docs`** (`ES_INDEX`). ### `_settings.yaml` (`~/.fscrawler/archivos/_settings.yaml`, `chmod 600`) ```yaml --- 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: ```bash 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): ```bash 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: ```bash # 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: ```bash 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: ```bash 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 ```bash 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`) ```bash 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: ```bash 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`: ```ini 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`: ```ini 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): ```bash 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 ```bash pip install pytest httpx pytest -q ```