MAIA PlusDokumentacja

Istniejąca instalacja

Upgrade pod kontrolą.

Sprawdź plan, zatwierdź aktualizację i zweryfikuj wynik. MAIA-MAINTENANCE zarządza podpisanym pakietem, backupem, migracjami i restartem usługi.

Podpisany ZIPPreflight przed zmianamiZaplanowany restart

1. Zanim zaczniesz

  • Zaplanuj okno serwisowe i powiadom użytkowników. Aktualizacja restartuje MAIA.
  • Ustal katalog i nazwę usługi: np. C:\MAIA i MAIA lub /opt/maia i maia.service.
  • Sprawdź trwające workflow, harmonogramy i zadania. Uwzględnij przerwę; nie zakładaj bezprzerwowego wykonania.
  • Przygotuj trwały, chroniony katalog backupów i miejsce na dump bazy oraz poprzedni payload.
  • Sprawdź narzędzia pg_dump i pg_restore, zgodne z serwerem PostgreSQL.
  • Pobierz właściwą paczkę i przeczytaj changelog oraz wymagania.
Nie podmieniaj EXE ani WebUI ręcznie

Nie kopiuj plików do current, nie usuwaj poprzedniego payloadu i nie instaluj od zera na aktywnym katalogu. Aktualizuj przez MAIA-MAINTENANCE, nie przez ponowną instalację PostgreSQL lub proxy SDP.

2. Pobierz i sprawdź paczkę

Wybierz ZIP Windows lub ZIP Linux ze strony pobierania. Porównaj SHA-256 i rozpakuj do nowego katalogu poza instalacją, np. D:\MAIA-Releases\1.1.0.

W przykładach jest 1.1.0 — użyj swojej pobranej wersji i nie nadpisuj wcześniejszego wydania. Z katalogu update:

.\MAIA-MAINTENANCE.exe check --package .

To sprawdzenie podpisu i plików bez aktualizacji. Zachowaj manifesty JSON/SIG. Nieprawidłowy podpis lub zmieniony plik to powód do zatrzymania, nie do obejścia walidacji.

Sprzęt bez AVX2?

Używaj MAIA-MAINTENANCE-baseline.exe dla każdego polecenia. Na Linux: maia-maintenance-linux-baseline. Dla Baseline wybierz jawne polecenia, bo skrypty pomocnicze mogą wybierać runtime standardowy.

3. Windows — ścieżka z przewodnikiem

  1. Otwórz katalog update

    Uruchom update.bat jako administrator.

  2. Wskaż istniejącą instalację

    Podaj prawdziwy katalog MAIA i nazwę usługi, nie katalog nowo rozpakowanej paczki.

  3. Przeczytaj preflight

    Kontroluje usługę, PostgreSQL, backup, historię migracji i lokalne API bez zmian. Kontynuuj tylko po READY TO UPDATE.

  4. Potwierdź UPDATE

    Updater zarządza zatrzymaniem usługi, backupem bazy, nowym payloadem i migracjami, potem startem oraz health check. Zachowaj log i ścieżkę dumpa.

Nie zatrzymuj zarządzanej usługi ręcznie i nie zmieniaj NSSM. Tryb bez usługi jest dla administratora zarządzającego procesem samodzielnie, po potwierdzeniu jego zatrzymania.

PowerShell — jawny preflight i aktualizacja

Uruchom PowerShell jako administrator. Podstaw własne ścieżki. Przykład dla PostgreSQL 18 zakłada narzędzia w bin; mogą znajdować się gdzie indziej.

Set-Location "D:\MAIA-Releases\1.1.0\update"

# Weryfikacja paczki
.\MAIA-MAINTENANCE.exe check --package .

# Preflight: bez zmian
.\MAIA-MAINTENANCE.exe update `
  --package . `
  --install-root "C:\MAIA" `
  --service "MAIA" `
  --service-driver auto `
  --backup-dir "D:\MAIA-Backups\release-1.1.0" `
  --pg-dump "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe" `
  --pg-restore "C:\Program Files\PostgreSQL\18\bin\pg_restore.exe"

Po READY TO UPDATE powtórz te same parametry z --confirm:

.\MAIA-MAINTENANCE.exe update `
  --package . `
  --install-root "C:\MAIA" `
  --service "MAIA" `
  --service-driver auto `
  --backup-dir "D:\MAIA-Backups\release-1.1.0" `
  --pg-dump "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe" `
  --pg-restore "C:\Program Files\PostgreSQL\18\bin\pg_restore.exe" `
  --confirm

Linux / systemd

W katalogu update sprawdź paczkę i wykonaj preflight. Użyj prawdziwej nazwy usługi i katalogu instalacji.

./maia-maintenance-linux check --package .

sudo ./maia-maintenance-linux update \
  --package . \
  --install-root /opt/maia \
  --service maia.service \
  --service-driver auto \
  --backup-dir /var/backups/maia/release-1.1.0

Po READY TO UPDATE wykonaj potwierdzoną operację:

sudo ./maia-maintenance-linux update \
  --package . \
  --install-root /opt/maia \
  --service maia.service \
  --service-driver auto \
  --backup-dir /var/backups/maia/release-1.1.0 \
  --confirm

Jeśli narzędzi PostgreSQL nie ma na PATH, podaj bezwzględne --pg-dump i --pg-restore w obu poleceniach. Bez AVX2 wybierz maintenance baseline.

4. Sprawdź wynik, nie tylko wersję

Windows

Get-Service MAIA
Invoke-RestMethod http://127.0.0.1:3000/api/v1/status

Linux

systemctl status maia.service --no-pager
curl --fail http://127.0.0.1:3000/api/v1/status
  • Usługa jest Running/active, API zwraca HTTP 200 z komunikatem MAIA.
  • WebUI działa przez prawidłowy adres publiczny; przy starym widoku odśwież cache.
  • Działają logowanie, dane, wiedza i konfiguracja dostawców AI.
  • Wybrane workflow przechodzą świadomy test — może on wykonywać rzeczywiste operacje.
  • Log potwierdza sukces, backup i poprzedni payload pozostają dostępne.

Zachowaj previous, dump i logi do odbioru wydania. Dwa buildy z tym samym numerem rozróżniaj również paczką i sumami.

Co się zmienia, a co zostaje?

Nowy payload trafia do current, poprzedni do previous. Konfiguracja, certyfikaty, stan i logi pozostają pod katalogiem instalacji. Możliwe migracje bazy są powodem wykonywania backupu.

Gdy preflight lub update zgłasza błąd

UPDATE BLOCKED — przed zmianami

Napraw wskazaną przyczynę i ponów preflight. Typowe blokady: brak narzędzi PostgreSQL, niewystarczający dostęp, zmieniona paczka, nieweryfikowalna historia migracji lub inny proces na porcie MAIA. Nie kasuj historii migracji i nie wykonuj ręcznie starych SQL.

Przerwana aktualizacja — zachowaj dowody

Zachowaj konsolę, dump, log maintenance i state\maintenance-update-v2.json. Nie ponawiaj UPDATE w ciemno ani nie podmieniaj samego EXE.

Odzyskiwanie przerwanej aktualizacji Windows
Recover może przywrócić bazę i restartować usługę

To odzyskiwanie po przerwanej aktualizacji, nie uniwersalny downgrade udanego wdrożenia. Sprawdź dziennik, backup i ryzyko utraty późniejszych zmian. Przy wątpliwościach skontaktuj się z MAIA Plus: stanislaw.rogasik@maiaplus.eu.

.\MAIA-MAINTENANCE.exe recover `
  --install-root "C:\MAIA" `
  --service "MAIA" `
  --backup-dir "D:\MAIA-Backups\release-1.1.0" `
  --pg-dump "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe" `
  --pg-restore "C:\Program Files\PostgreSQL\18\bin\pg_restore.exe"

Recovery korzysta z dziennika i zaufanego backupu. Sprawdź końcowy wynik i zdrowie aplikacji. Nie usuwaj archiwów z nieudanej próby.

Repair bazy nie jest zwykłą aktualizacją. Stosuj go po diagnozie administratora/DBA, przy uszkodzeniu bazy lub niemożności migracji — nie jako obejście blokady.

Skontaktuj się z MAIA Plus: stanislaw.rogasik@maiaplus.eu. Podaj wersję, platformę, etap błędu i zanonimizowany log. Nie wysyłaj sekretów ani pełnego dumpa zwykłym kanałem kontaktowym.