282 lines
15 KiB
Markdown
282 lines
15 KiB
Markdown
<p align="center">
|
|
<img src="public/favicon.png" alt="TokenWatch Logo" width="128" />
|
|
</p>
|
|
|
|
<h1 align="center">TokenWatch</h1>
|
|
<p align="center"><strong>Selbstgehosteter API-Quota- & Limit-Tracker mit Live-Dashboard, 7-Tage-Verlaufsdiagramm und ntfy-Benachrichtigungen.</strong></p>
|
|
|
|
<p align="center">
|
|
<a href="README.md">🇬🇧 English</a> · <a href="LIESMICH.md">🇩🇪 Deutsch</a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## Überblick
|
|
|
|
**TokenWatch** ist eine selbstgehostete Webanwendung zur zentralen Überwachung von KI-API-Kontingenten und Rate-Limit-Fenstern über mehrere Anbieter hinweg. Die Anwendung fragt externe Provider-APIs ab, empfängt Webhook-Updates eines lokalen Antigravity-Language-Server-Sync-Skripts, speichert Verlaufsdaten in PostgreSQL, stellt interaktive 7-Tage-Verläufe grafisch dar und verschickt automatische Push-Warnungen über **ntfy**, sobald konfigurierte Schwellenwerte überschritten werden.
|
|
|
|
### Architektur
|
|
|
|
```text
|
|
+-----------------------------------+ POST /api/webhook/antigravity
|
|
| Windows-Host (Antigravity IDE) | -------------------------------------+
|
|
| Push-AntigravityQuota.ps1 | |
|
|
| -> tokenwatch-sync.js | v
|
|
+-----------------------------------+ +------------------------------+
|
|
| TokenWatch-Server (Express) |
|
|
+-----------------------------------+ REST-API (30-Min- | Port 3000 |
|
|
| Externe APIs | Cron + Live-Abruf) | - Statische UI (public/) |
|
|
| - POE (current_balance) | <-------------------> | - /api/quotas |
|
|
| - MiniMax (coding_plan/remains) | | - /api/history |
|
|
+-----------------------------------+ +--------------+---------------+
|
|
|
|
|
+----------------------------+----------------------------+
|
|
v v
|
|
+------------------------------+ +------------------------------+
|
|
| PostgreSQL-Datenbank | | ntfy-Server |
|
|
| - quotas (Verlauf) | | Schwellenwert-Warnungen |
|
|
| - antigravity_latest (JSONB) | +------------------------------+
|
|
+------------------------------+
|
|
```
|
|
|
|
---
|
|
|
|
## Funktionen
|
|
|
|
- **Multi-Provider-Quota-Tracking**:
|
|
- **POE**: Überwacht den aktuellen Punktestand im Verhältnis zum Limit von `2.500.000`, täglichem Refresh (`75.000`), verfallenden Punkten, Tagen bis zum Cap, dem heutigen Tagesverbrauch (berechnet gegen den ersten UTC-Snapshot des Tages) sowie einem Live-Countdown bis 00:00 Uhr UTC.
|
|
- **MiniMax**: Überwacht `MiniMax (5h)` und `MiniMax (Weekly)` in Prozent (`model_name === 'general'`) inklusive Live-Reset-Countdowns.
|
|
- **Antigravity (AG)**: Überwacht 5 separate Kontingente per Webhook-Push (`AG Gemini (5h)`, `AG Gemini (Weekly)`, `AG Claude (5h)`, `AG Claude (Weekly)`, `AG Gemini 4 Argon (Weekly)`) inklusive individueller Reset-Zeitstempel (`Heute`, `Morgen` oder Wochentag + Countdown).
|
|
- **Persistenter Antigravity-Status**: Eingehende Webhook-Daten werden in der PostgreSQL-Tabelle `antigravity_latest` (`JSONB`) gespeichert und beim Serverstart automatisch wiederhergestellt.
|
|
- **Automatisierte Cron-Snapshots & ntfy-Alerts**: Alle 30 Minuten (`*/30 * * * *`) ruft `node-cron` alle Quotas ab, speichert sie in PostgreSQL und sendet bei Überschreitung von `ALERT_THRESHOLD_PERCENT` (Standard: `80`) eine `ntfy`-Meldung (`Title: TokenWatch Alert`, `Tags: warning,robot`).
|
|
- **7-Tage-Verlaufsdiagramm**: Interaktives Chart.js-Liniendiagramm, das Datenpunkte in 5-Minuten-Intervallen für `AG Gemini (5h)`, `AG Claude (5h)`, `POE` und `MiniMax (5h)` gruppiert.
|
|
- **6 wählbare Fortschrittsbalken-Themes**: Live-Wechsel zwischen `Standard`, `Pac-Man`, `Battery`, `Nyan Cat`, `Matrix` und `Lava` (passt auch die Chart.js-Farben dynamisch an).
|
|
- **Konfetti-Effekt bei 100 %**: Löst bei Erreichen von `100 %` eine `canvas-confetti`-Animation aus und zeigt bei Nicht-POE-Providern `LIMIT REACHED!` an.
|
|
- **Lokale Antigravity-Sync- & Debug-Werkzeuge**: Enthält `tokenwatch-sync.js`, `Push-AntigravityQuota.ps1` (für die Windows-Aufgabenplanung) sowie das plattformübergreifende Debug-Skript `fetch-quota.js` zum Auslesen der Rohantwort des lokalen Language Servers.
|
|
|
|
---
|
|
|
|
## Funktionsweise & Tech-Stack
|
|
|
|
### Interner Ablauf
|
|
|
|
1. **Serverstart (`src/server.ts`)**: Startet Express auf `0.0.0.0:3000`, liefert statische Dateien aus `public/` aus, initialisiert die PostgreSQL-Tabellen (`quotas` und `antigravity_latest`) über `initDb()` und lädt gespeicherte Antigravity-Werte über `initAntigravityFromDb()`.
|
|
2. **Quota-Abruf (`src/services/providers.ts`)**:
|
|
- `fetchPoeQuota()` fragt `https://api.poe.com/usage/current_balance` ab.
|
|
- `fetchMinimaxQuota()` fragt `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` ab.
|
|
- `fetchAntigravityQuota()` liest den In-Memory-`antigravityCache`, der über `POST /api/webhook/antigravity` aktualisiert oder beim Start aus PostgreSQL geladen wird.
|
|
3. **Alert-Logik (`src/cron.ts` & `src/services/ntfy.ts`)**:
|
|
- Bei **POE** (hier steht `percentage` für das *verbleibende* Kontingent) wird gewarnt, wenn `percentage <= (100 - ALERT_THRESHOLD_PERCENT)` (Standard: `<= 20 %` verbleibend).
|
|
- Bei **MiniMax** und **Antigravity** (hier steht `percentage` für das *verbrauchte* Kontingent) wird gewarnt, wenn `percentage >= ALERT_THRESHOLD_PERCENT` (Standard: `>= 80 %` verbraucht).
|
|
4. **Lokaler Antigravity-Sync (`tokenwatch-sync.js`)**: Sucht laufende `language_server*`-Prozesse über PowerShell (`Get-CimInstance Win32_Process`), liest `--csrf_token` und `--extension_server_port` aus, ermittelt offene Loopback-Ports (`Get-NetTCPConnection` mit `netstat -ano` als Fallback), ruft `POST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary` auf und sendet die extrahierten Werte an `/api/webhook/antigravity`.
|
|
|
|
### Tech-Stack & Ports
|
|
|
|
| Komponente | Technologie / Version | Details |
|
|
| :--- | :--- | :--- |
|
|
| Laufzeitumgebung | Node.js 24 (`node:24-alpine`) | CommonJS-TypeScript-Build (`tsc` -> `dist/`) |
|
|
| Backend | Express `^5.2.1`, TypeScript `^7.0.2` | REST-API + Auslieferung statischer Dateien |
|
|
| Scheduler | `node-cron` `^4.6.0` | Läuft alle 30 Minuten (`*/30 * * * *`) |
|
|
| HTTP-Client | `axios` `^1.20.0` | Provider-API-Abfragen & ntfy-Alerts |
|
|
| Datenbank | PostgreSQL (`postgres:15-alpine`, `pg` `^8.23.0`) | Tabellen: `quotas`, `antigravity_latest` |
|
|
| Frontend | Natives HTML/CSS/JS, Chart.js, `canvas-confetti` | Ausgeliefert aus `public/` |
|
|
| Standard-Port | `3000` (Container) / `3500` (Jannik-Cloud-Host-Bind) | Konfigurierbar über `PORT` |
|
|
|
|
---
|
|
|
|
## Voraussetzungen & Installation
|
|
|
|
### Voraussetzungen
|
|
|
|
- **Lokale Entwicklung**: Node.js (v20+ / v24 empfohlen), npm und eine laufende PostgreSQL-Instanz.
|
|
- **Docker-Deployment**: Docker und Docker Compose.
|
|
- **Antigravity-Sync (optional)**: Windows-Rechner mit laufender Antigravity IDE, Node.js und PowerShell.
|
|
|
|
### Lokale Installation
|
|
|
|
1. Repository klonen:
|
|
```bash
|
|
git clone https://git.orfel.de/Jannik/TokenWatch.git
|
|
cd TokenWatch
|
|
```
|
|
|
|
2. Abhängigkeiten installieren:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Umgebungsdatei aus `.env.example` erstellen:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
Danach PostgreSQL-Zugangsdaten, `NTFY_URL` und API-Keys in `.env` eintragen.
|
|
|
|
4. Im Entwicklungsmodus (`tsx`) starten oder für Produktion bauen:
|
|
```bash
|
|
# Entwicklung
|
|
npm run dev
|
|
|
|
# Produktions-Build & Start
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
### Docker-Compose-Setup
|
|
|
|
TokenWatch gemeinsam mit PostgreSQL (`postgres:15-alpine`) starten:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# .env mit Zugangsdaten und API-Keys ausfüllen
|
|
docker compose up -d
|
|
```
|
|
|
|
Das Dashboard ist anschließend unter `http://localhost:3000` erreichbar.
|
|
|
|
### Jannik-Cloud-Produktivdeployment
|
|
|
|
Eine fertige Deployment-Vorlage liegt in [`deployment-template/`](deployment-template/README.md):
|
|
|
|
1. Den Inhalt von `deployment-template/` in das Verzeichnis `services/tokenwatch/` im `Jannik-Cloud`-Repository kopieren.
|
|
2. In `services/tokenwatch/` das Skript `bash generate-env.sh` ausführen, um zufällige PostgreSQL-Zugangsdaten zu generieren und optional `.env` nach `.env.age` zu verschlüsseln (über `keys/age-public-key.txt`).
|
|
3. Bei Bedarf Provider-API-Keys (`POE_API_KEY`, `MINIMAX_API_KEY` usw.) ergänzen.
|
|
4. `tokenwatch.caddy` konfiguriert den Reverse-Proxy für `tw.orfel.de`, `token.orfel.de` und `tokenwatch.orfel.de` auf `tokenwatch:3000`; `docker-compose.yml` bindet `127.0.0.1:3500:3000` im externen Netzwerk `jannik-cloud-net`.
|
|
5. Hinweis: `.github/workflows/docker.yml` enthält zudem einen GitHub-Actions-Workflow, der bei Pushes auf `main` oder `master` ein Image nach `ghcr.io/<owner>/<repo>:latest` baut und pusht.
|
|
|
|
---
|
|
|
|
## Konfiguration
|
|
|
|
### Umgebungsvariablen (`.env.example`)
|
|
|
|
| Variable | Beschreibung | Standard / Beispiel |
|
|
| :--- | :--- | :--- |
|
|
| `PORT` | HTTP-Server-Port | `3000` |
|
|
| `DB_USER` | PostgreSQL-Benutzername | `postgres` |
|
|
| `DB_HOST` | PostgreSQL-Hostname | `postgres` |
|
|
| `DB_NAME` | Name der PostgreSQL-Datenbank | `tokenwatch` |
|
|
| `DB_PASSWORD` | PostgreSQL-Passwort | `your_db_password` |
|
|
| `DB_PORT` | PostgreSQL-Port | `5432` |
|
|
| `NTFY_URL` | ntfy-Topic-URL für Schwellenwert-Alerts | `https://ntfy.orfel.de/Token-Watch` (Fallback in `ntfy.ts`: `https://ntfy.orfel.de/tokenwatch_dummy`) |
|
|
| `ALERT_THRESHOLD_PERCENT` | Schwellenwert in Prozent (`>=` verbraucht bzw. `<= 100 - N` verbleibend bei POE) | `80` |
|
|
| `POE_API_KEY` | Bearer-Token für `api.poe.com/usage/current_balance` | — |
|
|
| `MINIMAX_API_KEY` | Bearer-Token für `api.minimax.io/v1/api/openplatform/coding_plan/remains` | — |
|
|
| `ANTIGRAVITY_API_KEY` | Optionaler Platzhalter in `.env.example` / Compose | — |
|
|
| `ANTIGRAVITY_ENDPOINT` | Optionaler Platzhalter in `.env.example` / Compose | `https://api.antigravity.google/v1/quota` |
|
|
|
|
### Docker-Volumes
|
|
|
|
- `pgdata:/var/lib/postgresql/data` — Persistiert in `docker-compose.yml` den Verlauf in `quotas` sowie den Zustand in `antigravity_latest`.
|
|
|
|
---
|
|
|
|
## Nutzung
|
|
|
|
### Web-Dashboard
|
|
|
|
Öffne `http://localhost:3000` (bzw. deine konfigurierte Domain), um:
|
|
- Aktuelle Fortschrittsbalken, Reset-Zeiten (`Heute`/`Morgen`/Wochentag) und Countdowns für POE, Antigravity und MiniMax anzuzeigen.
|
|
- Über das Dropdown **Progress Bar Style** zwischen 6 Designs zu wechseln:
|
|
1. `Standard`
|
|
2. `Pac-Man`
|
|
3. `Battery`
|
|
4. `Nyan Cat`
|
|
5. `Matrix`
|
|
6. `Lava`
|
|
- Den 7-Tage-Verlauf im Chart.js-Bereich **History** zu verfolgen.
|
|
|
|
### API-Endpunkte
|
|
|
|
| Methode | Endpunkt | Beschreibung |
|
|
| :--- | :--- | :--- |
|
|
| `GET` | `/api/quotas` | Liefert die aktuellen Quota-Objekte aller Provider inklusive `meta.todayUsed` für POE. |
|
|
| `GET` | `/api/history` | Liefert die letzten 7 Tage aus der PostgreSQL-Tabelle `quotas` in chronologischer Reihenfolge. |
|
|
| `POST` | `/api/webhook/antigravity` | Aktualisiert die 5 Antigravity-Einträge im Speicher und persistiert sie in `antigravity_latest`. |
|
|
|
|
Beispiel-Payload für `POST /api/webhook/antigravity`:
|
|
|
|
```json
|
|
{
|
|
"gemini_5h_remaining": 85,
|
|
"gemini_weekly_remaining": 90,
|
|
"claude_5h_remaining": 100,
|
|
"claude_weekly_remaining": 75,
|
|
"gemini_argon_weekly_remaining": 100,
|
|
"gemini_5h_reset": "2026-01-01T15:00:00Z",
|
|
"gemini_weekly_reset": "2026-01-07T00:00:00Z",
|
|
"claude_5h_reset": null,
|
|
"claude_weekly_reset": null,
|
|
"gemini_argon_weekly_reset": null
|
|
}
|
|
```
|
|
|
|
### Lokaler Antigravity-Sync (Windows)
|
|
|
|
1. Stelle sicher, dass `url` in `tokenwatch-sync.js` auf deine TokenWatch-Instanz zeigt (Standard: `https://tokenwatch.orfel.de/api/webhook/antigravity`).
|
|
2. Manuell ausführen:
|
|
```powershell
|
|
.\Push-AntigravityQuota.ps1
|
|
```
|
|
Oder direkt per Node:
|
|
```bash
|
|
node tokenwatch-sync.js
|
|
```
|
|
3. **Automatisierung über Windows-Aufgabenplanung**:
|
|
- Trigger: Alle 30 Minuten
|
|
- Aktion: Programm starten
|
|
- Programm: `powershell`
|
|
- Argumente: `-ExecutionPolicy Bypass -File "C:\GitHub\TokenWatch\Push-AntigravityQuota.ps1"`
|
|
4. **Rohdaten des Language Servers debuggen**:
|
|
```bash
|
|
node fetch-quota.js
|
|
```
|
|
Fragt `/exa.language_server_pb.LanguageServerService/GetUserStatus` beim lokalen Language Server ab (unterstützt Windows, macOS und Linux) und gibt die vollständige JSON-Antwort aus.
|
|
|
|
---
|
|
|
|
## Projektstruktur
|
|
|
|
```text
|
|
TokenWatch/
|
|
├── .github/
|
|
│ └── workflows/
|
|
│ └── docker.yml # GitHub-Actions-Workflow zum Bauen/Pushen nach ghcr.io
|
|
├── deployment-template/
|
|
│ ├── README.md # Deployment-Anleitung für Jannik-Cloud
|
|
│ ├── docker-compose.yml # Produktives Compose mit jannik-cloud-net
|
|
│ ├── generate-env.sh # Erzeugt DB-Passwörter & optional .env.age
|
|
│ ├── service.enabled # Aktivierungsdatei für Jannik-Cloud
|
|
│ └── tokenwatch.caddy # Caddy-Reverse-Proxy-Konfiguration
|
|
├── public/
|
|
│ ├── logos/ # Provider-.ico-Dateien
|
|
│ ├── app.js # Frontend-Logik, Countdowns, Chart.js & Themes
|
|
│ ├── favicon.png # TokenWatch-Logo & Favicon
|
|
│ ├── index.html # Dashboard-HTML
|
|
│ ├── logo-*.png / .ico / .svg # Provider-Icons (POE, Gemini, Claude, MiniMax, AG)
|
|
│ └── style.css # Dark-UI & 6 Fortschrittsbalken-Themes
|
|
├── src/
|
|
│ ├── services/
|
|
│ │ ├── db.ts # PostgreSQL-Pool, Tabellen-Init, Verlauf & AG-Persistenz
|
|
│ │ ├── ntfy.ts # ntfy-Benachrichtigungen
|
|
│ │ └── providers.ts # POE-, MiniMax- & Antigravity-Provider-Logik
|
|
│ ├── cron.ts # 30-Minuten-Cron-Job & Schwellenwert-Prüfung
|
|
│ └── server.ts # Express-App & REST-API-Endpunkte
|
|
├── .env.example # Beispiel-Umgebungsvariablen
|
|
├── Dockerfile # Node-24-Alpine-Container mit TypeScript-Build
|
|
├── docker-compose.yml # Lokales/Standalone-Compose mit PostgreSQL 15
|
|
├── fetch-quota.js # Plattformübergreifendes Debug-Skript für Language Server
|
|
├── language-server-process-utils.js# Prozesssuche & CLI-Argument-Extraktion
|
|
├── package.json # Abhängigkeiten und npm-Skripte
|
|
├── Push-AntigravityQuota.ps1 # PowerShell-Wrapper für Windows-Aufgabenplanung
|
|
├── tokenwatch-sync.js # Lokaler Antigravity-Language-Server -> Webhook-Sync
|
|
└── tsconfig.json # TypeScript-Konfiguration
|
|
```
|
|
|
|
---
|
|
|
|
## Lizenz
|
|
|
|
Der eigene Quellcode und die Konfiguration dieses Projekts stehen unter **CC0 1.0 Universal** (Public Domain) — Details in [`LICENSE`](LICENSE).
|
|
|
|
Externe Abhängigkeiten, die über Paketmanager oder Docker-Images installiert werden, behalten ihre jeweiligen eigenen Open-Source-Lizenzen.
|