Backup automatico script del 2026-08-23 12:04
This commit is contained in:
daniele committed
1 parent
11823447a2
commit
795a15a7b6
66 files changed
+8546
No files matched your search
@@ -0,0 +1,190 @@
|
||||
# Guida amministratore — Daniele
|
||||
|
||||
Guida operativa per gestire e usare Loogle MCP Hub.
|
||||
|
||||
---
|
||||
|
||||
## Accesso rapido
|
||||
|
||||
| Cosa | URL / comando |
|
||||
|------|----------------|
|
||||
| Dashboard admin | https://mcp.loogle.it/dashboard (login `daniele`) |
|
||||
| Health | `curl -sf https://mcp.loogle.it/health` |
|
||||
| Log gateway | `docker logs -f loogle-mcp` |
|
||||
| Log indexer | `docker logs -f loogle-mcp-indexer` |
|
||||
| Compose | `cd /home/daniely/docker/loogle-mcp` |
|
||||
|
||||
---
|
||||
|
||||
## Configurazione iniziale (checklist)
|
||||
|
||||
- [x] Stack Docker avviato (`docker compose up -d`)
|
||||
- [x] DNS Pi-hole: `mcp.loogle.it` → `192.168.128.85`
|
||||
- [x] NPM proxy host 30 + TLS Let's Encrypt
|
||||
- [ ] Token Paperless in `.env` — vedi [PAPERLESS-TOKEN.md](PAPERLESS-TOKEN.md) (Profilo utente, non «Applicazione social»)
|
||||
- [ ] `MCP_JWT_SECRET` robusto in `.env`
|
||||
- [ ] Ollama su DS920 con `ollama pull nomic-embed-text`
|
||||
- [ ] Qdrant su DS920 (opzionale, vedi compose extrema)
|
||||
- [ ] Password cambiate per tutta la famiglia
|
||||
- [ ] Ogni familiare ha collegato almeno un client AI
|
||||
|
||||
**Script utili:**
|
||||
```bash
|
||||
sudo /home/daniely/rete/scripts/setup-mcp-dns-npm.sh # DNS + NPM
|
||||
./scripts/deploy.sh # rebuild + restart
|
||||
/home/daniely/rete/scripts/npm-failover-route.sh normal # upstream failover
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Come usare tu (Daniele)
|
||||
|
||||
### Dashboard
|
||||
|
||||
1. https://mcp.loogle.it/dashboard — login `daniele`
|
||||
2. Vedi progetti, audit log completo, revoca refresh token (sezione admin)
|
||||
|
||||
### Con Cursor / Claude / ChatGPT
|
||||
|
||||
Stesso URL MCP: `https://mcp.loogle.it/mcp`
|
||||
|
||||
**Cursor** — aggiungi in `.cursor/mcp.json` del progetto:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"loogle-mcp": {
|
||||
"url": "https://mcp.loogle.it/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Workflow consigliato per un task
|
||||
|
||||
1. **create_project** — es. «Homelab MCP», tag `rete`, `2026`
|
||||
2. Lavori con l’AI (Cursor, Claude, ecc.)
|
||||
3. **save_context** — a fine sessione salvi decisioni e stato
|
||||
4. **search_knowledge** — recuperi doc da Paperless quando serve
|
||||
5. **search_context** — ritrovi discussioni passate semanticamente
|
||||
|
||||
### Tool solo admin
|
||||
|
||||
- `reindex_document` — forza re-indicizzazione di un doc Paperless
|
||||
- Revoca token refresh da dashboard
|
||||
- Audit log di tutti gli utenti via `/api/audit`
|
||||
|
||||
---
|
||||
|
||||
## Gestione utenti
|
||||
|
||||
Gli utenti sono in SQLite (`loogle_mcp.db`). Password hash PBKDF2.
|
||||
|
||||
| Utente | Admin | Reset password |
|
||||
|--------|-------|----------------|
|
||||
| daniele | sì | dashboard o diretto DB |
|
||||
| lucia, davide, luca | no | dashboard (self-service) |
|
||||
|
||||
Password iniziale = username. `must_change_password` è attivo al primo login consigliato.
|
||||
|
||||
Per aggiungere utenti in futuro: estendi `FAMILY_USERS` in `app/auth.py` e redeploy.
|
||||
|
||||
---
|
||||
|
||||
## Paperless → knowledge base
|
||||
|
||||
Vedi guida completa: [PAPERLESS-TOKEN.md](PAPERLESS-TOKEN.md)
|
||||
|
||||
**Non usare** i token «Applicazione social» dell'admin Django (schermata nell'immagine): servono al login OAuth web di Paperless, non all'API REST MCP.
|
||||
|
||||
**Usa** i token API utente: docs.loogle.it → menu utente → **Profilo** → pulsante freccia circolare accanto a «Token API».
|
||||
|
||||
Configura in `.env` (un token per ogni account Paperless della famiglia):
|
||||
|
||||
```bash
|
||||
PAPERLESS_API_TOKEN_DANIELE=<token account Daniele>
|
||||
PAPERLESS_API_TOKEN_LUCIA=<token account Lucia>
|
||||
PAPERLESS_API_TOKEN_DAVIDE=<token account Davide>
|
||||
PAPERLESS_API_TOKEN_LUCA=<token account Luca>
|
||||
```
|
||||
|
||||
Ogni familiare genera il proprio token da docs.loogle.it → **Profilo** → Token API. Se un utente non ha ancora account Paperless, lascia la riga vuota finché non lo crei.
|
||||
|
||||
Alternativa: solo `PAPERLESS_API_TOKEN=` con token admin (Daniele superuser) — tutti gli utenti MCP condividono lo stesso scope.
|
||||
|
||||
Riavvia indexer:
|
||||
```bash
|
||||
cd /home/daniely/docker/loogle-mcp && docker compose restart loogle-mcp loogle-mcp-indexer
|
||||
```
|
||||
|
||||
**Visibilità documenti (tag Paperless):**
|
||||
- Tag `personal` / `privato` → solo collection personale del owner
|
||||
- Senza tag personali → `kb_shared_family` (tutti in famiglia)
|
||||
|
||||
---
|
||||
|
||||
## Embedding e Qdrant
|
||||
|
||||
| Componente | Dove | Note |
|
||||
|----------|------|------|
|
||||
| Ollama | DS920 `:11434` | `OLLAMA_EMBED_MODEL=nomic-embed-text` |
|
||||
| Qdrant | DS920 `:6333` | Non gira su Pi5 (limitazione ARM) |
|
||||
| Fallback | `/data/vector_fallback.db` | Automatico se Qdrant non raggiungibile |
|
||||
|
||||
Deploy Qdrant su DS920:
|
||||
```bash
|
||||
# sul DS920, path mirror extrema
|
||||
docker compose -f /volume1/extrema/compose/extrema-ds920/loogle-mcp-compose.yml up -d qdrant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DNS e NPM — cosa è stato configurato
|
||||
|
||||
**Pi-hole** (`/etc/pihole/pihole.toml`):
|
||||
```
|
||||
"192.168.128.85 mcp.loogle.it"
|
||||
```
|
||||
|
||||
**NPM** proxy host ID 30:
|
||||
- Dominio: `mcp.loogle.it`
|
||||
- Backend: `192.168.128.80:8700`
|
||||
- Cert: `npm-65`
|
||||
|
||||
**Failover** (`npm-routes.conf`):
|
||||
```
|
||||
30|mcp.loogle.it|8700|pi1|pi1|local|ds920
|
||||
```
|
||||
|
||||
Se reinstalli NPM da zero, riesegui:
|
||||
```bash
|
||||
sudo /home/daniely/rete/scripts/setup-mcp-dns-npm.sh
|
||||
/home/daniely/sync-npm-full.sh # sync Pi2 + DS920
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoraggio e backup
|
||||
|
||||
- **Failover status:** probe `mcp_ok` / `mcp_be` in `failover-status.sh`
|
||||
- **Runbook incidenti:** `/home/daniely/rete/ha/RUNBOOK-mcp.md`
|
||||
- **Backup restic:** `/home/daniely/rete/infra-monitor/mcp-restic-backup.sh`
|
||||
|
||||
---
|
||||
|
||||
## Onboarding famiglia
|
||||
|
||||
Invia a ciascuno:
|
||||
|
||||
- [Guida utenti](GUIDA-UTENTI.md) — istruzioni semplici per ChatGPT/Claude/Gemini
|
||||
- URL dashboard per cambio password
|
||||
- Username personale (non condividere password)
|
||||
|
||||
Progetto demo già creato per ogni utente (es. `progetti-personali` per Lucia).
|
||||
|
||||
---
|
||||
|
||||
## Documentazione tecnica
|
||||
|
||||
- [Architettura e parametri](ARCHITETTURA.md)
|
||||
- [Onboarding client AI (dettaglio)](ONBOARDING.md)
|
||||
- [Runbook HA](/home/daniely/rete/ha/RUNBOOK-mcp.md)
|
||||
Reference in new issue
Block a user