solar-pv-dashboard/README.md

PV Insight

Dashboard fotowoltaiki pod InfluxDB, z naciskiem na prosty dev na Pythonie 3.14 i gotowy deploy produkcyjny bez zewnetrznego CDN.

Najwazniejsze cechy

• dev uruchamiany zwyklym python run.py
• prod uruchamiany przez waitress, bez serwera developerskiego Flask
• frontend React + TypeScript + Vite + ECharts
• stylowanie w oparciu o Tabler 1.4.0, zwendorowane offline w repo
• tryb jasny / ciemny
• interfejs PL / EN
• logowanie sesyjne
• tryb kiosku z recznym doborem widgetow
• lokalny cache historii w SQLite
• import archiwum z InfluxDB chunkami

Co aplikacja liczy sama

Aplikacja nie wymaga encji typu energy_today, energy_monthly czy energy_yearly. Najpierw liczy energie z PV_TOTAL_ENERGY_ENTITY jako licznika calkowitego, a jesli go nie ma, moze estymowac dane z PV_AC_POWER_ENTITY.

Struktura projektu

• backend/config.py - glowna konfiguracja, encje i moduly
• backend/run.py - start developerski
• backend/run_prod.py - start produkcyjny przez Waitress
• backend/backfill.py - reczny import historii
• backend/app/routes - endpointy API
• backend/app/services - logika Influx, energii, auth i historii
• backend/app/storage/sqlite_repository.py - lokalny cache historii
• frontend/src - UI operatora, kiosk, logowanie, i18n
• frontend/public/vendor/tabler - lokalny, offline Tabler
• frontend/nginx.conf - serwowanie SPA i proxy /api w prod
• scripts/dev_*.sh - start developerski
• scripts/prod_*.sh - build / start produkcyjny

Konfiguracja

1. Skopiuj .env.example do .env
2. Uzupelnij polaczenie do InfluxDB
3. Ustaw encje PV
4. Ustaw login i haslo do panelu

Najwazniejsze pola:

• INFLUXDB_*
• PV_AC_POWER_ENTITY
• PV_TOTAL_ENERGY_ENTITY
• PV_STRING_1_*, PV_STRING_2_*, PV_STRING_3_*, PV_STRING_4_*
• PV_INVERTER_TEMP_ENTITY opcjonalnie
• APP_SQLITE_PATH
• HISTORY_*
• AUTH_USERNAME
• AUTH_PASSWORD lub AUTH_PASSWORD_HASH
• APP_SECRET_KEY
• AUTH_COOKIE_SECURE

Dla HTTPS w produkcji ustaw AUTH_COOKIE_SECURE=true. Flask wyraznie zaznacza, ze w produkcji nie nalezy uzywac wbudowanego dev servera, tylko dedykowany serwer WSGI, a Waitress dobrze pasuje do tego projektu jako prosty, czysto pythonowy serwer WSGI.

Dev bez Dockera

Backend

cp .env.example .env
./scripts/dev_backend.sh

Frontend

W drugim terminalu:

./scripts/dev_frontend.sh

Razem

./scripts/dev.sh

Demo UI bez backendu

./scripts/dev_frontend_demo.sh

Lokalny smoke-test builda bez Dockera

Backend przez Waitress

./scripts/prod_backend.sh

Build frontendu

./scripts/prod_frontend_build.sh

Podglad zbudowanego frontendu

./scripts/prod_frontend_preview.sh

Po buildzie frontend statyczny bedzie w frontend/dist. To jest dobre do lokalnego sprawdzenia builda. Docelowy deploy produkcyjny jest opisany nizej w sekcji Docker / deploy produkcyjny.

Docker / deploy produkcyjny

Domyslny docker-compose.yml jest przygotowany pod prosty deploy produkcyjny:

• backend: Flask + Waitress
• frontend: nginx serwujacy build Vite
• nginx proxuje /api/* do backendu
• Tabler jest lokalny, wiec nie ma zaleznosci od CDN

Start:

docker compose up -d --build

UI bedzie pod adresem:

http://localhost:8080

Zatrzymanie:

./scripts/prod_down.sh

Docker dev

Jesli chcesz kontenery developerskie:

docker compose -f docker-compose.dev.yml up --build

Import historii

Z UI: zakladka Ustawienia -> Import archiwalny z InfluxDB

Z CLI:

./scripts/import_history.sh --start-date 2022-01-01 --end-date 2025-12-31 --chunk-days 7

Uwagi

• jesli masz mniej stringow, ustaw tylko istniejace encje
• gdy temperatura falownika nie istnieje, modul temperatury schowa sie automatycznie
• kiosk zapisuje widok lokalnie w localStorage
• backend trzyma cache dziennych agregatow w SQLite
• frontend w dev na porcie 5173 automatycznie gada z backendem na tym samym hoscie, port 8105
• frontend w prod korzysta domyslnie z /api/v1, czyli przez proxy nginx

cd backend export FLASK_APP=app.main:app

python -m flask create-admin --username admin2 --password 'SuperHaslo123' python -m flask create-user --username user1 --password 'SuperHaslo123' python -m flask reset-password --username user1 --password 'NoweHaslo123'

Produkcja

Uruchomienie produkcyjne przez reverse proxy:

docker compose -f docker-compose.prod.yml up -d --build