147 lines
3.1 KiB
Markdown
147 lines
3.1 KiB
Markdown
# Epirent Read‑Only Cache Proxy (Node/TS)
|
||
|
||
Reverse‑Proxy mit zentralem Cache (TTL + _stale‑while‑revalidate_) für die Epirent‑API.
|
||
Alle **GET/HEAD**‑Requests werden 1:1 an Epirent weitergereicht, Antworten werden zwischengespeichert.
|
||
Authentifizierung erfolgt serverseitig via `X-EPI-NO-SESSION: True` und `X-EPI-ACC-TOK: <token>`.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- 100 % dynamischer Read‑Only‑Proxy
|
||
- Zentraler Cache mit **TTL** und **stale‑while‑revalidate**
|
||
- **ETag/Last‑Modified**‑Revalidation (falls vom Upstream geliefert)
|
||
- Schutz vor Thundering‑Herd durch pro‑Key In‑Flight‑Lock
|
||
- Optional: **Redis** als Shared Cache
|
||
- Ausführliches Debug‑Logging (`DEBUG=1/2`)
|
||
- **Metriken** (Prometheus + kleines Web‑Dashboard) auf **zweitem Port** (optional)
|
||
|
||
---
|
||
|
||
## Voraussetzungen
|
||
|
||
- Node.js **20+** (oder Docker)
|
||
- Optional: Redis **7+** (für Shared Cache)
|
||
|
||
---
|
||
|
||
## Konfiguration
|
||
|
||
`.env` anlegen (Beispiel in der .env.sample).
|
||
> **Hinweis:** `.env` wird über `dotenv` geladen. Alternativ können Variablen vor dem Start im Shell‑Environment gesetzt werden.
|
||
|
||
---
|
||
|
||
## Installation (ohne Docker)
|
||
|
||
```bash
|
||
npm ci
|
||
npm run build
|
||
npm start
|
||
```
|
||
|
||
### Entwicklung
|
||
Zwei Debug Level (1 und 2) sind implementiert
|
||
|
||
- Linux/macOS:
|
||
```bash
|
||
DEBUG=1 npm run dev
|
||
```
|
||
|
||
- Windows PowerShell:
|
||
```powershell
|
||
$env:DEBUG="1"; npm run dev
|
||
```
|
||
|
||
---
|
||
|
||
## Docker
|
||
|
||
### Build & Run
|
||
|
||
```bash
|
||
docker build -t epirent-cache .
|
||
docker run --rm -p 8080:8080 --env-file .env epirent-cache
|
||
```
|
||
|
||
### docker-compose (mit Redis & Metriken)
|
||
|
||
```yaml
|
||
services:
|
||
cache-api:
|
||
build: .
|
||
env_file: .env
|
||
ports:
|
||
- "8080:8080"
|
||
- "9090:9090"
|
||
depends_on: [ redis ]
|
||
|
||
redis:
|
||
image: redis:7-alpine
|
||
command: ["redis-server","--appendonly","yes"]
|
||
volumes:
|
||
- ./data/redis:/data
|
||
```
|
||
|
||
Start:
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## Endpunkte
|
||
|
||
- **Proxy:** `GET /…` → `X-Cache-Status: HIT|MISS|MISS-EXPIRED|STALE|STALE-ERROR`
|
||
- **Health:** `GET /_healthz`
|
||
- **Purge:** `POST /_purge?secret=<PURGE_SECRET>&url=<VOLLE_UPSTREAM_URL>`
|
||
- **Metriken (zweiter Port):** `GET /metrics` (Prometheus), `GET /` (Dashboard)
|
||
|
||
|
||
---
|
||
|
||
## Systemd (optional)
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=Epirent Read-Only Cache Proxy
|
||
After=network.target
|
||
|
||
[Service]
|
||
WorkingDirectory=/opt/epirent-cache
|
||
ExecStart=/usr/bin/node dist/server.js
|
||
EnvironmentFile=/opt/epirent-cache/.env
|
||
Restart=always
|
||
RestartSec=3
|
||
User=www-data
|
||
Group=www-data
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
Aktivieren:
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now epirent-cache
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### 502 Bad Gateway
|
||
- `UPSTREAM_BASE` prüfen (Schema/Host/Port)
|
||
- Direkt via `curl` testen:
|
||
```bash
|
||
curl -v "http://epirent.host.local:8080/api/..." -H "X-EPI-NO-SESSION: True" -H "X-EPI-ACC-TOK: DEIN_TOKEN"
|
||
```
|
||
- `DEBUG=2` aktivieren und Logs prüfen
|
||
- Interne Zertifikate? Testweise `TLS_REJECT_UNAUTHORIZED=0` (nicht dauerhaft!)
|
||
|
||
### Keine Cache‑Treffer
|
||
- `Accept` unterscheidet sich zwischen Clients → gleiche Werte nutzen oder Vary‑Liste erweitern
|
||
|
||
### Redis wird nicht genutzt
|
||
- `REDIS_URL` leer → In‑Memory LRU aktiv. `REDIS_URL` setzen und Service neu starten
|