Files

317 lines
13 KiB
Markdown
Raw Permalink Normal View History

# 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`)
```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
```