3ae5d736ce
- T55: Setup APScheduler with AsyncIOScheduler and @scheduled_job decorator - T56: Implement hourly usage stats sync from OpenRouter API - T57: Implement daily API key validation job - T58: Implement weekly cleanup job for old usage stats - Add usage_stats_retention_days config option - Integrate scheduler with FastAPI lifespan events - Add 26 unit tests for scheduler, sync, and cleanup tasks - Add apscheduler to requirements.txt The background tasks now automatically: - Sync usage stats every hour from OpenRouter - Validate API keys daily at 2 AM UTC - Clean up old data weekly on Sunday at 3 AM UTC
174 lines
4.3 KiB
Markdown
174 lines
4.3 KiB
Markdown
# OpenRouter API Key Monitor
|
|
|
|
Applicazione web multi-utente per monitorare l'utilizzo delle API key della piattaforma [OpenRouter](https://openrouter.ai/).
|
|
|
|
## 🚀 Caratteristiche
|
|
|
|
- **🔐 Autenticazione Sicura**: Registrazione e login con JWT
|
|
- **🔑 Gestione API Key**: CRUD completo con cifratura AES-256
|
|
- **📊 Dashboard Statistiche**: Visualizzazione utilizzo, costi, modelli
|
|
- **🔓 API Pubblica**: Accesso programmatico con token API
|
|
- **📈 Monitoraggio**: Tracciamento richieste, token, costi
|
|
|
|
## 📋 Requisiti
|
|
|
|
- Python 3.11+
|
|
- SQLite (incluso)
|
|
- Docker (opzionale)
|
|
|
|
## 🛠️ Installazione
|
|
|
|
### Installazione Locale
|
|
|
|
```bash
|
|
# Clona il repository
|
|
git clone https://github.com/username/openrouter-watcher.git
|
|
cd openrouter-watcher
|
|
|
|
# Crea virtual environment
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate # Linux/Mac
|
|
# oppure: .venv\Scripts\activate # Windows
|
|
|
|
# Installa dipendenze
|
|
pip install -r requirements.txt
|
|
|
|
# Configura variabili d'ambiente
|
|
cp .env.example .env
|
|
# Modifica .env con le tue configurazioni
|
|
|
|
# Esegui migrazioni database
|
|
alembic upgrade head
|
|
|
|
# Avvia applicazione
|
|
uvicorn src.openrouter_monitor.main:app --reload
|
|
```
|
|
|
|
### Installazione con Docker
|
|
|
|
```bash
|
|
# Avvia con Docker Compose
|
|
docker-compose up -d
|
|
|
|
# L'applicazione sarà disponibile su http://localhost:8000
|
|
```
|
|
|
|
## 🔧 Configurazione
|
|
|
|
Crea un file `.env` con le seguenti variabili:
|
|
|
|
```env
|
|
# Database
|
|
DATABASE_URL=sqlite:///./data/app.db
|
|
|
|
# Sicurezza (genera con: openssl rand -hex 32)
|
|
SECRET_KEY=your-super-secret-jwt-key-min-32-chars
|
|
ENCRYPTION_KEY=your-32-byte-encryption-key-here
|
|
|
|
# OpenRouter
|
|
OPENROUTER_API_URL=https://openrouter.ai/api/v1
|
|
|
|
# Limiti
|
|
MAX_API_KEYS_PER_USER=10
|
|
MAX_API_TOKENS_PER_USER=5
|
|
RATE_LIMIT_REQUESTS=100
|
|
RATE_LIMIT_WINDOW=3600
|
|
|
|
# JWT
|
|
JWT_EXPIRATION_HOURS=24
|
|
```
|
|
|
|
## 📚 API Endpoints
|
|
|
|
### Autenticazione (JWT)
|
|
|
|
| Metodo | Endpoint | Descrizione |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/auth/register` | Registrazione utente |
|
|
| POST | `/api/auth/login` | Login utente |
|
|
| POST | `/api/auth/logout` | Logout utente |
|
|
|
|
### Gestione API Keys OpenRouter
|
|
|
|
| Metodo | Endpoint | Descrizione |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/keys` | Aggiungi API key |
|
|
| GET | `/api/keys` | Lista API keys |
|
|
| PUT | `/api/keys/{id}` | Aggiorna API key |
|
|
| DELETE | `/api/keys/{id}` | Elimina API key |
|
|
|
|
### Statistiche
|
|
|
|
| Metodo | Endpoint | Descrizione |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/stats/dashboard` | Dashboard statistiche |
|
|
| GET | `/api/usage` | Dettaglio utilizzo |
|
|
|
|
### Gestione Token API
|
|
|
|
| Metodo | Endpoint | Descrizione |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/tokens` | Genera token API |
|
|
| GET | `/api/tokens` | Lista token |
|
|
| DELETE | `/api/tokens/{id}` | Revoca token |
|
|
|
|
### API Pubblica (Autenticazione con Token API)
|
|
|
|
| Metodo | Endpoint | Descrizione |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/stats` | Statistiche aggregate |
|
|
| GET | `/api/v1/usage` | Dettaglio utilizzo |
|
|
| GET | `/api/v1/keys` | Lista API keys con stats |
|
|
|
|
## 🧪 Test
|
|
|
|
```bash
|
|
# Esegui tutti i test
|
|
pytest tests/unit/ -v
|
|
|
|
# Con coverage
|
|
pytest tests/unit/ -v --cov=src/openrouter_monitor
|
|
|
|
# Test specifici
|
|
pytest tests/unit/routers/test_auth.py -v
|
|
pytest tests/unit/routers/test_api_keys.py -v
|
|
pytest tests/unit/routers/test_public_api.py -v
|
|
```
|
|
|
|
## 📁 Struttura Progetto
|
|
|
|
```
|
|
openrouter-watcher/
|
|
├── src/openrouter_monitor/ # Codice sorgente
|
|
│ ├── schemas/ # Pydantic schemas
|
|
│ ├── models/ # SQLAlchemy models
|
|
│ ├── routers/ # FastAPI routers
|
|
│ ├── services/ # Business logic
|
|
│ ├── dependencies/ # FastAPI dependencies
|
|
│ └── main.py # Entry point
|
|
├── tests/ # Test suite
|
|
├── docs/ # Documentazione
|
|
├── export/ # Specifiche e progresso
|
|
└── prompt/ # Prompt per AI agents
|
|
```
|
|
|
|
## 🔒 Sicurezza
|
|
|
|
- **Cifratura**: API keys cifrate con AES-256-GCM
|
|
- **Password**: Hash con bcrypt (12 rounds)
|
|
- **Token JWT**: Firma HMAC-SHA256
|
|
- **Token API**: Hash SHA-256 nel database
|
|
- **Rate Limiting**: 100 richieste/ora per token
|
|
|
|
## 📄 Licenza
|
|
|
|
MIT License
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributi sono benvenuti! Segui le linee guida in `.opencode/WORKFLOW.md`.
|
|
|
|
## 📞 Supporto
|
|
|
|
Per domande o problemi, apri un issue su GitHub.
|