Comarch Optima — instalacja

Integracja działa na hoście Windows, na którym zainstalowany jest Comarch ERP Optima. Łączy się z bazą MS SQL Optima (odczyt), z COM API Optima (zapis), a do Sancho WMS dociera przez chmurową magistralę wiadomości (RabbitMQ TLS).

Komponent dostarczany jest jako pojedynczy archiwum zip publikowane per DEPLOY_ENV:

Kanał	Zip	Instalator
dev	https://download.sancho-wms.pl/dev/latest/comarch-optima.zip	https://download.sancho-wms.pl/dev/latest/comarch-optima-install.ps1
prod	https://download.sancho-wms.pl/prod/latest/comarch-optima.zip	https://download.sancho-wms.pl/prod/latest/comarch-optima-install.ps1

Buildy są również przypięte per commit pod <channel>/<short-sha>/... (niezmienne).

Wymagania wstępne

• 64-bit Windows 10 1607 lub Windows Server 2016+ z TLS 1.2.
• PowerShell 5.1 lub nowszy uruchomiony jako Administrator.
• Zainstalowany Comarch ERP Optima na tym samym hoście (instalacja używa lokalnego COM API).
• Dostęp wychodzący do download.sancho-wms.pl (pobranie obrazu) i do hosta RabbitMQ Sancho po porcie TLS.

Co przygotować przed uruchomieniem instalatora

1. Login SQL Server (czytanie bazy Optima). W SQL Server Management Studio włącz tryb mieszanego uwierzytelniania (SQL Server and Windows Authentication mode), utwórz login (np. sancho) z uwierzytelnianiem SQL i przypisz uprawnienie db_datareader do baz CDN_KNF_Konfiguracja oraz bazy firmowej Optima. Po włączeniu trybu mieszanego zrestartuj usługę SQL Server.

2. Operator Optima. Operator z uprawnieniami do tworzenia dokumentów i kart towarów — używany przez COM API do zapisu. Zapisz login i hasło operatora.

3. Poświadczenia AMQP. Host, użytkownik, hasło i wirtualny host RabbitMQ — wydawane przez Sancho przy aktywacji integracji. Bez tych danych instalator nie zakończy konfiguracji.

Bitowość COM API

SanchoWMSComarchOptimaCOM.exe jest 64-bitowy i wymaga 64-bitowej instalacji Optimy (2026+, 64-bitowe COM API). Starsze 32-bitowe instalacje Optimy nie są obsługiwane przez dostarczany build — niezgodność bitowości kończy CoCreateInstance błędem 0x8007007E (ERROR_MOD_NOT_FOUND). Konto operatora Optima musi mieć uprawnienia w lokalnej instalacji Optima.

Instalacja

Uruchom z elewowanego prompta PowerShell na hoście Windows, na którym zainstalowany jest Comarch Optima:

prod

irm https://download.sancho-wms.pl/prod/latest/comarch-optima-install.ps1 | iex

dev

irm https://download.sancho-wms.pl/dev/latest/comarch-optima-install.ps1 | iex

Co robi instalator

1. Weryfikuje wymagania: Administrator, PowerShell 5.1+, 64-bit Windows 10 1607 / Server 2016 lub nowszy, TLS 1.2.

2. Pobiera kanałowy comarch-optima.zip do %TEMP% i loguje odcisk SHA-256.

3. Pyta o poświadczenia MSSQL / operatora Optima / AMQP (sekrety przez Read-Host -AsSecureString).

4. Instaluje binarki do C:\Program Files\SanchoWMS\ComarchOptima\bin\.

5. Zapisuje .env do C:\ProgramData\SanchoWMS\ComarchOptima\.env.

6. Rejestruje dwie usługi Windows przez NSSM (auto-start): SanchoWMSComarchOptima (główna integracja) oraz SanchoWMSComarchOptimaUpdater (poller auto-aktualizacji).

7. Uruchamia obie usługi.

Aktualizacje automatyczne

SanchoWMSComarchOptimaUpdater co godzinę wysyła żądanie HEAD do <channel>/latest/comarch-optima.zip. Kiedy ETag odpowiedzi się zmieni, pobiera nowy zip, zatrzymuje SanchoWMSComarchOptima, podmienia SanchoWMSComarchOptima.exe + SanchoWMSComarchOptimaCOM.exe + duckdb.dll (zachowując kopie .previous do rollback-u) i restartuje usługę. Jeśli nowy build nie osiągnie stanu Running w 30 sekund, updater przywraca poprzednie binarki i zapisuje ETag nieudanego buildu do state\last-failed-etag.txt — ten build jest pomijany aż do publikacji nowego.

Updater nie podmienia nssm.exe, samego siebie (SanchoWMSComarchOptimaUpdater.exe) ani schematu .env — te są pod blokadą lub wymagają interakcji i są aktualizowane tylko ponownym ręcznym uruchomieniem instalatora (który zatrzymuje obie usługi przed podmianą).

Stan auto-aktualizacji:

Cel	Ścieżka
Ostatnio widziany ETag (usunięcie wymusza ponowną weryfikację)	C:\ProgramData\SanchoWMS\ComarchOptima\state\last-etag.txt
ETag ostatniego nieudanego upgrade-u (usunięcie pozwala ponowić ten sam build)	C:\ProgramData\SanchoWMS\ComarchOptima\state\last-failed-etag.txt
Logi updater-a (przechwycone przez NSSM, rotacja co 10 MB)	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-updater.log (własny log updater-a), comarch-optima-updater-service.log (połączony stdout + stderr NSSM)

Wyłączenie auto-aktualizacji:

Set-Service SanchoWMSComarchOptimaUpdater -StartupType Disabled
Stop-Service SanchoWMSComarchOptimaUpdater

Ręczna aktualizacja

Uruchom ponownie ten sam one-liner. Instalator wykryje istniejące usługi, zatrzyma obie, podmieni wszystkie binarki (w tym nssm.exe i SanchoWMSComarchOptimaUpdater.exe), zachowa .env i zrestartuje obie. Każdy nowy klucz dodany do .env.example jest pytany interaktywnie i dopisywany do istniejącego .env.

Deinstalacja

irm https://download.sancho-wms.pl/prod/latest/comarch-optima-install.ps1 -OutFile $env:TEMP\install.ps1
& $env:TEMP\install.ps1 -Uninstall

Usuwa obie usługi i kasuje C:\Program Files\SanchoWMS\ComarchOptima\ oraz C:\ProgramData\SanchoWMS\ComarchOptima\ (.env, logi, stan). Nie ma częściowej deinstalacji — wykonaj kopię .env przed odinstalowaniem, jeśli planujesz późniejszą reinstalację.

Konfiguracja (.env)

Plik .env mieszka pod C:\ProgramData\SanchoWMS\ComarchOptima\.env. Edycja wymaga restartu głównej usługi:

Restart-Service SanchoWMSComarchOptima

Logowanie

Klucz	Wymagany	Domyślnie	Przeznaczenie
LOG_PRETTY	nie	false	true włącza format Pino pretty (tylko do interaktywnego użycia)
LOG_LEVEL	nie	info	Poziom Pino (trace, debug, info, warn, error, fatal, silent)
LOG_FILE	nie	logs\comarch-optima-integration.log	Ścieżka do logu integracji (względem katalogu roboczego, czyli ProgramData). Rotacja dzienna; 14 ostatnich dni trzymane.

MSSQL (baza Optima)

Klucz	Wymagany	Domyślnie	Przeznaczenie
MSSQL_SERVER	tak	localhost	Host SQL Server z Optimą
MSSQL_INSTANCE	nie	OPTIMA (podpowiedź instalatora)	Nazwa instancji nazwanej; puste = instancja domyślna
MSSQL_DATABASE	nie	(domyślna)	Nazwa bazy; puste = baza domyślna loginu
MSSQL_USER	tak	sancho	Login SQL
MSSQL_PASSWORD	tak	—	Hasło SQL

Optima (zapis przez COM)

Klucz	Wymagany	Domyślnie	Przeznaczenie
OPTIMA_OPERATOR_NAME	nie	—	Operator Optima używany do zapisów COM-API
OPTIMA_OPERATOR_PASSWORD	nie	—	Hasło operatora (puste = pomiń)
OPTIMA_FIRM_INDEX	nie	0 (zapisywane przez instalator)	0-bazowa pozycja firmy na liście firm Optimy (pierwsza/jedyna firma = 0). Odczytasz z CDN_KNF_Konfiguracja.CDN.Bazy (ROW_NUMBER() OVER (ORDER BY Baz_BazID) - 1)
OPTIMA_LICENSE_MODEL	nie	auto	Model licencji klucza Optimy: classic (klucz HASP / Menadżer Kluczy), subscription (model usługowy) lub auto (próbuje classic, potem subscription). Klasyczny klucz Handel musi mieć classic — fallback subskrypcyjny kończy się błędem “Nie masz uprawnień do korzystania z modułu [Podstawowy]”
OPTIMA_SERVE	nie	true	Trwała sesja COM (“serve mode”): true uruchamia COM CLI raz i trzyma jedno logowanie Optimy z auto-reconnectem; false startuje CLI per żądanie

AMQP (magistrala Sancho)

Klucz	Wymagany	Domyślnie	Przeznaczenie
AMQP_HOST	tak	—	Host RabbitMQ po stronie Sancho
AMQP_PORT	tak	5671	Port RabbitMQ (TLS)
AMQP_VHOST	tak	/	Wirtualny host
AMQP_USER	tak	—	Użytkownik RabbitMQ (per-klient)
AMQP_PASSWORD	tak	—	Hasło RabbitMQ

Ścieżki na hoście

Cel	Ścieżka
Binarki (SanchoWMSComarchOptima.exe, SanchoWMSComarchOptimaCOM.exe, SanchoWMSComarchOptimaUpdater.exe, duckdb.dll, nssm.exe)	C:\Program Files\SanchoWMS\ComarchOptima\bin\
Konfiguracja (.env)	C:\ProgramData\SanchoWMS\ComarchOptima\.env
Log integracji (Pino, rotacja dzienna, 14 dni)	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration.log (+ .1 … .14 dla zrolowanych dni)
Połączony stdout + stderr głównej usługi (NSSM, rotacja co 10 MB)	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration-service.log
Logi updater-a + stdout NSSM	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-updater.log, comarch-optima-updater-service.log
Stan auto-aktualizacji	C:\ProgramData\SanchoWMS\ComarchOptima\state\last-etag.txt, last-failed-etag.txt
Transkrypt instalacji	C:\Program Files\SanchoWMS\ComarchOptima\install.log

Eksploatacja

Get-Service Sancho*
Restart-Service SanchoWMSComarchOptima
Get-Content -Wait 'C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration.log'
Get-Content -Wait 'C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration-service.log'
Get-Content -Wait 'C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-updater.log'

Po zmianie .env wykonaj Restart-Service SanchoWMSComarchOptima, aby zastosować zmiany.

Rozwiązywanie problemów

Logowanie do SQL nieudane (Login failed for user)

Tryb uwierzytelniania mieszanego nie jest włączony, login nie istnieje albo nie ma uprawnienia db_datareader na bazie konfiguracyjnej CDN_KNF_Konfiguracja lub na bazie firmowej. Otwórz SSMS, sprawdź właściwości serwera → Security (Zabezpieczenia), upewnij się, że “SQL Server and Windows Authentication mode” jest aktywne, a użytkownik jest zmapowany na obie bazy.

Failed to connect to AMQP / TLS handshake error

Sprawdź firewall hosta i sieć — port AMQP_PORT (5671) musi być osiągalny wychodząco. Niektóre instalacje Windows Server mają wyłączone TLS 1.2 na poziomie systemu — sprawdź konfigurację SCHANNEL w rejestrze. Poświadczenia AMQP są wydawane per-klient — jeśli zgubisz hasło, poproś Sancho o nowe.

Updater nie pobiera nowego buildu

Skasuj C:\ProgramData\SanchoWMS\ComarchOptima\state\last-etag.txt, aby wymusić ponowną weryfikację, i Restart-Service SanchoWMSComarchOptimaUpdater. Jeśli poprzednia próba upgrade-u się nie powiodła, ETag tego buildu jest zapisany w state\last-failed-etag.txt i build jest pomijany — skasuj również ten plik, aby ponowić ten sam build. Logi: comarch-optima-updater.log pokaże, czy HEAD doszło do download.sancho-wms.pl.

CO_E_CLASSSTRING (0x800401F3) lub błąd ProgID COM

Subproces COM nie potrafi załadować klasy Optima. Częste przyczyny: konto operatora nie ma uprawnień w lokalnej Optima, instalacja Optima jest uszkodzona, albo COM API nie jest zarejestrowane (uruchom Optimę raz interaktywnie, by zarejestrować klasy). Sprawdź comarch-optima-integration.log — pokaże dokładną nazwę klasy i kod błędu.

Usługa nie startuje po reboocie

Get-Service SanchoWMSComarchOptima raportuje Stopped. Sprawdź comarch-optima-integration-service.log — najczęstsze przyczyny: nie da się zalogować do SQL (zła konfiguracja .env po edycji), brak dostępu do download.sancho-wms.pl przy starcie updater-a (nie jest krytyczne — updater retry-uje), albo brakujący klucz .env po częściowej edycji.