Qwatroni MySQL API server on mõeldud selleks, et mitu arvutit saaksid kasutada ühist andmeseisu üle võrgu või interneti. Igas arvutis jääb alles kohalik ladu.db andmebaas, kuid ühine keskne andmete vahetus toimub MySQL serveri ja HTTP API kaudu.

See tähendab, et programm ei pea jagama ühte SQLite faili üle võrgu. Selle asemel saadab iga Qwatroni programm oma muudatused API serverisse ning küsib sealt vastu teiste kasutajate uuemad muudatused.

Kuidas Lahendus Töötab

Qwatron töötab kasutaja arvutis endiselt lokaalselt. Kõik andmed salvestatakse esmalt kohalikku ladu.db faili. Kui kasutaja vajutab sünkroniseerimise nuppu või kui automaatne sünkroniseerimine on sisse lülitatud, suhtleb programm MySQL API serveriga.

Tööprotsess on järgmine:

1. Kasutaja teeb programmis muudatuse, näiteks lisab kliendi, muudab toodet või salvestab sündmuse.
2. Muudatus salvestatakse kohalikku ladu.db andmebaasi.
3. Sünkroniseerimisel loeb programm kohalikud muutunud kirjed.
4. Iga kirje muudetakse JSON kujule.
5. Programm saadab andmed API serverisse endpointi POST /sync/push.
6. API server salvestab need MySQL andmebaasi tabelisse sync_records.
7. Seejärel küsib programm serverist teiste arvutite uuemad muudatused endpointiga GET /sync/changes.
8. Saadud muudatused kirjutatakse tagasi kohalikku ladu.db faili.
9. Programm jätab meelde viimase sünkroniseerimise järjehoidja, et järgmisel korral küsida ainult uusi muudatusi.

Selline lahendus võimaldab töötada ka siis, kui internet ajutiselt kaob. Kohalik programm jääb tööle ning sünkroniseerimine tehakse siis, kui ühendus taastub.

MySQL Roll Süsteemis

MySQL server on keskne andmevahetuse koht. Seal ei hoita programmi tabeleid üks-ühele eraldi äriloogika tabelitena, vaid muudatused salvestatakse üldisesse sünkroniseerimistabelisse.

Põhitabel on sync_records.

Selles hoitakse:

• tabeli nimi, kust kirje pärineb;
• kirje stabiilne identifikaator;
• kirje sisu JSON kujul;
• muutmise aeg;
• kustutamise info;
• serveripoolne versioon;
• arvuti või kliendi tunnus, kes muudatuse saatis;
• serveri uuendamise aeg.

Lisaks on tabel sync_clients, kus hoitakse sünkroniseerivate arvutite tunnuseid ja viimase ühenduse aega.

Selle lahenduse eelis on paindlikkus. Kui Qwatroni programmi lisandub uusi välju või mooduleid, ei pea MySQL serverisse iga kord kõiki äriloogika tabeleid käsitsi ümber ehitama. Server toimib pigem turvalise keskse sünkroniseerimiskihina.

API Serveri Endpointid

API server kasutab peamiselt kolme olulist aadressi:

GET /health
Kontrollib, kas API server töötab ja kas MySQL ühendus on korras.

POST /sync/push
Qwatroni programm saadab siia oma kohalikud muudatused.

GET /sync/changes?since=...
Qwatroni programm küsib siit muudatused, mis on serveris uuemad kui viimati teada olnud sünkroniseerimise aeg.

Kui API võti on määratud, peavad sünkroniseerimise päringud sisaldama päist:

X-API-Key: sinu-salajane-api-voti

Juurutamine Üle Interneti Kasutamiseks

Kui soovitakse, et API server oleks kasutatav üle maailma ainult nendele kasutajatele, kellel on ligipääsuõigus, tuleks API paigaldada avaliku interneti serverisse. Sobiv koht on näiteks VPS, pilveserver või ettevõtte enda server, millel on avalik IP aadress või domeeninimi.

Soovituslik ülesehitus on:

MySQL andmebaasi ei tohiks otse internetti avada. Internetist peaks nähtav olema ainult HTTPS API aadress. API server suhtleb MySQL-iga serveri enda sisemises võrgus või samas masinas.

Paigalduse Põhisammud

1. Loo server

Vali Linuxi või Windowsi server. Praktiline valik on Linux VPS, näiteks Ubuntu server. Serveril peaks olema avalik IP aadress ja ligipääs tulemüüri seadistamiseks.

1. Paigalda MySQL või MariaDB

Loo Qwatroni jaoks eraldi andmebaas ja kasutaja. Kasutajal peaks olema õigus ainult Qwatroni andmebaasile.

Näide:

CREATE DATABASE qwatron CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'qwatron'@'localhost' IDENTIFIED BY 'vali_tugev_parool'; GRANT ALL PRIVILEGES ON qwatron.* TO 'qwatron'@'localhost'; FLUSH PRIVILEGES;

Seejärel käivita Qwatroni skeem:

mysql -u qwatron -p qwatron < server_api/schema.sql

1. Paigalda API rakendus

Serverisse tuleb paigaldada Python ja vajalikud paketid:

python -m pip install -r server_api/requirements.txt

Seejärel määratakse keskkonnamuutujad:

QWATRON_MYSQL_HOST=127.0.0.1 QWATRON_MYSQL_PORT=3306 QWATRON_MYSQL_USER=qwatron QWATRON_MYSQL_PASSWORD=vali_tugev_parool QWATRON_MYSQL_DATABASE=qwatron QWATRON_API_KEY=vali-vaga-pikk-salajane-api-voti

1. Käivita API server

Testimiseks saab API käivitada käsuga:

python -m uvicorn server_api.qwatron_api:app --host 127.0.0.1 --port 8080

Tootmises võiks API töötada teenusena, näiteks systemd, Docker, Windows Service või muu protsessihalduri kaudu. Oluline on, et API käivituks automaatselt pärast serveri taaskäivitust.

1. Lisa HTTPS

Avalikuks kasutamiseks ei tohiks API töötada palja http:// aadressiga. Selle ette tuleks panna HTTPS reverse proxy, näiteks Nginx, Apache või IIS.

Kasutajatele antav aadress võiks olla näiteks:

https://api.sinufirma.ee

HTTPS sertifikaadi saab tavaliselt paigaldada Let’s Encrypti abil. See võimaldab krüpteeritud ühendust, et API võti ja andmed ei liiguks üle interneti loetaval kujul.

1. Ava tulemüüris ainult vajalik port

Avalikult peaks olema avatud ainult HTTPS port 443. MySQL port 3306 ei tohiks olla internetist ligipääsetav.

Soovitus:

• 443 avatud internetti;
• 8080 ainult kohalikule masinale või reverse proxy jaoks;
• 3306 ainult serveri sees või piiratud sisevõrgule;
• SSH või haldusport ainult administraatorile.

Sisseehitatud API Server Programmis

Qwatronis on MySQL API serveri kasutamiseks kaks võimalust. API serverit saab käivitada eraldi serverirakendusena, näiteks VPS-is või ettevõtte serveris, kuid API server on olemas ka Qwatroni rakenduse enda sees.

See tähendab, et üks Qwatroni programmiga arvuti saab toimida API serverina. Sellisel juhul ei pea API serverit eraldi käsitsi Pythoniga käivitama, vaid selle saab käivitada otse programmist.

Sisseehitatud API serveri seadistamine toimub menüüpunktis:

Seaded > Sisseehitatud API server

Seal saab määrata:

• API serveri hosti või kuulamisaadressi
• API serveri pordi
• MySQL serveri aadressi
• MySQL pordi
• MySQL kasutajanime
• MySQL parooli
• MySQL andmebaasi nime
• API võtme

Kui need andmed on sisestatud, saab programmist API serveri käivitada. Programm loob ühenduse MySQL andmebaasiga ning hakkab pakkuma samu API endpoint’e, mida kasutab ka eraldi paigaldatav API server.

Sisseehitatud API server sobib eriti hästi väiksemas kasutuses või ettevõtte sisemises võrgus, kus üks arvuti töötab keskse Qwatroni serverina. Näiteks võib kontoriarvutis või väikeses serverarvutis käivitada Qwatroni, avada Seaded > Sisseehitatud API server ja panna selle arvuti vahendama teiste Qwatroni töökohtade sünkroniseerimist MySQL andmebaasiga.

Teised arvutid seadistatakse seejärel menüüpunktis:

Seaded > MySQL API sünkroniseerimine

Seal sisestatakse API aadressiks selle arvuti aadress, kus sisseehitatud API server töötab, näiteks:

http://192.168.1.20:8080

või üle interneti kasutamisel domeeni kaudu:

https://api.sinufirma.ee

Sisseehitatud API serveri kasutamisel kehtivad samad turvanõuded nagu eraldi API serveri puhul. Kui serverit kasutatakse üle interneti, peab ühendus olema kaitstud HTTPS-iga, API võti peab olema tugev ja MySQL andmebaasi ei tohi otse internetti avada.

Millal Kasutada Sisseehitatud API Serverit

Sisseehitatud API server sobib siis, kui soovitakse lihtsamat paigaldust ja üks Qwatroni arvuti saab olla keskne server. See on mugav lahendus väiksemale ettevõttele või olukorda, kus ei soovita eraldi serverirakendust hallata.

Millal Kasutada Eraldi API Serverit

Eraldi API server sobib paremini siis, kui Qwatronit kasutavad paljud kasutajad, ühendus peab olema ööpäevaringselt kättesaadav või teenus peab töötama ka siis, kui ükski tööarvuti ei ole sisse lülitatud. Sellisel juhul on mõistlik paigaldada API server VPS-i, pilveserverisse või ettevõtte serverisse teenusena.

Programmi Seadistamine Kasutaja Arvutis

Qwatroni programmis tuleb avada:

Seaded > MySQL API sünkroniseerimine

Seal tuleb sisestada:

• API aadress
  Näiteks https://api.sinufirma.ee
• API võti
  Sama salajane võti, mis on serveris määratud QWATRON_API_KEY väärtuseks.
• Arvuti tunnus
  Iga arvuti kohta eraldi nimi, näiteks KONTOR-1, LADU-1, TEHNIK-MATI või TALLINN-MYYK.

Seejärel tuleb vajutada Salvesta API ja Testi ühendust. Kui ühendus töötab, saab vajutada Sünkroniseeri MySQL API-ga.

Kui automaatne sünkroniseerimine on lubatud, teeb programm sünkroniseerimist määratud intervalliga ise. Kui kasutaja soovib täielikku kontrolli, võib automaatse sünkro välja jätta ja vajutada sünkroniseerimise nuppu käsitsi.

Ligipääsuõigused Üle Maailma Kasutamiseks

Selleks, et API serverit saaksid kasutada ainult õigustatud kasutajad, tuleks kasutada mitut kaitsekihti.

Kõige olulisemad kaitsed:

• API peab töötama üle HTTPS ühenduse.
• Kõigil klientidel peab olema õige API võti.
• API võti peab olema pikk ja juhuslik.
• MySQL ei tohi olla avalikult internetis.
• Serveri tulemüür peab lubama ainult vajalikud pordid.
• Soovi korral saab piirata ligipääsu IP aadresside järgi.
• Administraatori ligipääs serverile peab olema eraldi kaitstud.
• API logisid tuleks jälgida, et näha vigaseid või võõraid päringuid.

API võti on sisuliselt ligipääsuluba. Kui keegi saab API võtme kätte, võib ta proovida serveriga suhelda. Seetõttu tuleb API võtit hoida samamoodi nagu parooli.

Soovituslik Avalik Kasutusmudel

Kõige turvalisem ja praktilisem mudel on selline:

• üks keskne server;
• üks MySQL andmebaas;
• üks API teenus;
• HTTPS domeen;
• igal Qwatroni arvutil oma arvuti tunnus;
• kõigil lubatud kasutajatel sama või vajadusel eraldi API võti;
• serveri tulemüüris avatud ainult HTTPS;
• MySQL ainult serveri sisekasutuses.

Nii saavad kontoriarvutid, laoarvutid, müügitöötajad või kaugtöötajad kasutada sama andmeseisu sõltumata asukohast. Nad ei pea olema samas LAN võrgus, vaid vajavad internetiühendust ja õiget API seadistust.

Andmete Konfliktid

Kui kaks arvutit muudavad sama kirjet, eelistab süsteem uuemat updated_at väärtust. Vanem muudatus jäetakse vahele. API vastuses võib sellisel juhul suureneda skipped_stale arv.

Praktikas tähendab see, et sama kirjet ei ole mõistlik mitmes arvutis korraga muuta. Näiteks kui kaks kasutajat muudavad sama kliendi andmeid, jääb peale hilisem muudatus.

Miks See On Parem Kui Ühine Fail Serveris

Vana lihtne lahendus oleks panna ladu.db võrgukausta ja lasta kõigil sama faili kasutada. See võib aga üle interneti olla aeglane ja riskantne. SQLite fail ei ole mõeldud paljude kaugarvutite samaaegseks üle interneti kasutamiseks.

MySQL API lahendus on töökindlam, sest:

• iga arvuti töötab oma kohaliku andmebaasiga;
• interneti katkestus ei peata kogu programmi;
• server vahendab ainult muudatusi, mitte tervet andmebaasifaili;
• andmeid saab kasutada eri asukohtadest;
• keskserverisse saab teha regulaarseid varukoopiaid;
• õiguseid ja ühendusi saab paremini kontrollida.

Kokkuvõte

Qwatroni MySQL API server võimaldab kasutada programmi mitmes arvutis ja eri asukohtades nii, et kõigil õigustatud kasutajatel oleks ligipääs samale andmeseisule. Kasutaja arvutis jääb programm kiireks ja kohalikuks, kuid muudatused liiguvad API kaudu keskserverisse. Avalikuks kasutamiseks tuleb API paigaldada serverisse, panna selle ette HTTPS, kaitsta ühendus API võtmega ja mitte avada MySQL andmebaasi otse internetti.