Agento diegimas

Agentas - duomenų teikimo agentas, teikiantis duomenis pagal UDTS standartą.

Čia rasite informaciją, kaip galite paleisti Agentą, veikiantį Spinta priemonės pagalba savo infrastruktūroje.

Spinta gali veikti kaip komandinės eilutės įrankis, tačiau taip pat gali veikti ir duomenų publikavimo režimu.

Duomenų publikavimas gali veikti dviem režimais:

mode: internal: Duomenys publikuojami iš duomenų bazės, kurioje laikoma šaltinio duomenų kopija. Šiuo atveju, Spinta praturtina šaltinio duomenis metaduomenimis, kurie leidžia užtikrinti sklandesnį duomenų publikavimą.
mode: external: Duomenys gali būti publikuojami tiesiai iš duomenų šaltinio. Šis režimas turėtų būti naudojamas tada, kai nėra galimybės leisti Agentui rašyti papildomus duomenis į šaltinio duomenų bazę, ar šaltinis nėra reliacinė duomenų bazė. Šiuo būdu teikiant duomenis, šaltinio duomenų susiejimui su UDTS formato universaliais identifikatoriais (UUID), naudojama papildoma duomenų bazė (keymap).

Dažniausiai, bus naudojamas external režimas, nebent duomenų teikėjas sutiktų leisti Agentui įrašyti papildomus metaduomenis, kurie padėtų užtikrinti šį ir kitus funkcionalumus.

Agentas veikia ir yra testuotas Linux operacinėse sistemose, konkrečiai naudojant Debian/Ubuntu distribucijas, todėl instrukcijos bus pateiktos būtent Debian/Ubuntu aplinkai. Diegimą galima atlikti ir kitose Linux distribucijose, tačiau tam tikros vietos nurodytos šioje dokumentacijoje turėtu būti priderintos taip, kad veiktų kitoje distribucijoje.

Spinta yra sukurta naudojant Python programavimo kalbą, reikalinga Python 3.10 ar naujesnė versija. Naujose Agento versijose reikalavimas Python versijai gali keistis.

Dėl serverio resursų, tokių kaip CPU, RAM ir HDD, reikalingi resursai tiesiogiai priklauso nuo publikuojamų duomenų kiekio ir naudotojų srauto, kurie naudosis duomenų publikavimo paslauga.

Minimalūs reikalavimai Agentui, be duomenų ir su 5 naudotojais vienu metu besinaudojančiais duomenų teikimo paslauga:

CPU

1 CPU, šiuo metu perduodant duomenis nėra naudojamas lygiagretinimas, todėl bus naudojamas tik vienas CPU, ateityje tai gali keistis.

RAM

512 MB, duomenys skaitomi srautiniu būdu, todėl nepriklausomai nuo šaltinio dydžio, naudojamas fiksuotas RAM kiekis.

Vienas Spinta procesas naudoja apie 100 MB RAM.

HDD

Priklauso nuo duomenų kiekio.

Unikalių identifikatorių duomenų įrašams suteikimui, saugomi papildomi duomenys:

Vidinių ir publikuojamų pirminių raktų sąsaja, saugoma ~/.local/share/spinta/keymap.db Sqlite arba Redis duomenų bazėje. Duomenys atrodo taip:

bb969358-ce9e-4255-b596-c748f6885332|bf8b4530d8d246dd74ac53a13471bba17941dff7|BINDATA...
522a3615-8527-4eb7-8327-977fe4383dcd|c4ea21bb365bbeeaf5f2c654883e56d11e43c44e|BINDATA...
9be3e60b-d557-4596-a370-660f3c337772|9842926af7ca0a8cca12604f945414f07b01e13d|BINDATA...
60c2f4da-c32a-4fba-a39a-8e85252a77ad|a42c6cf1de3abfdea9b95f34687cbbe92b9a7383|BINDATA...
ab2baaa6-508d-4069-9a45-53bce46676ca|8dc00598417d4eb788a77ac6ccef3cb484905d8b|BINDATA...

Saugomas išorinis raktas, vidinio rakto sha1 ir vidinio rakto reikšmė MsgPack formatu.

Šios lentelės dydis tiesiogiai proporcingas šaltinio įrašų skaičiui ir šaltinio lentelių pirminių raktų dydžiui.

Vidutiniškai, 10^6 įrašų telpa į 200 MB.

Pats savaime Agentas su visomis Python priklausomybes diske užima apie 500 MB vietos, tačiau sunaudojamos vietos skaičius gali skirtis, skirtingose distribucijose.

Agento veikimas turėtu būti nuolat stebimas ir reikiami resursai didinami, pagal poreikį.

Operacinės sistemos paruošimas

Agentas turėtu būti diegiamas ir leidžiamas spinta naudotojo teisėmis, todėl reikia sukurti sisteminį naudotoją:

sudo useradd --system -g www-data --create-home --home-dir /opt/spinta spinta

Atkreipkite dėmesį, kad visose komandose, kurios prasideda sudo, komanda turi būti vykdoma administratoriaus teisėmis, tačiau visur kur nėra sudo, komanda turi būti vykdoma spinta naudotojo teisėmis. Tai yra svarbu, todėl nesupainiokite kokio naudotojo teisėmis vykdote komandas, priešingu atveju susidursite su sunkumais susijusiais su failų teisėmis.

Python diegimas

Daugelis Linux distribucijų ateina su įdiegta Python versija, tačiau reikia įsitikinti, ar distribucijos Python versija yra pakankama:

python3 --version

Jei Python versija yra 3.10 ar naujesnė, tada galite pereiti prie sekančio žingsnio.

Jei versija yra žemesnė nei 3.10, tuomet reikės įsidiegti naujesnę Python versiją. Tai galite padaryti naudodami pyenv (dėl pačio pyenv diegimo skaitykite pyenv dokumentacijoje):

sudo apt update
sudo apt upgrade
sudo apt install -y \
  git make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget \
  curl llvm libncurses5-dev libncursesw5-dev \
  xz-utils tk-dev libffi-dev liblzma-dev \
  python-openssl
git clone https://github.com/pyenv/pyenv.git
export PYENV_ROOT=/opt/pyenv
/opt/pyenv/bin/pyenv install --list | grep -v - | tail
/opt/pyenv/bin/pyenv install 3.14.0  # Naudokite naujausią versiją

Naujausia Python versija bus įdiegta į /opt/pyenv/versions/3.14.0/bin/python.

Analogiškai, galite naudotis distribucijos teikiamais paketais, Ubuntu atveju galite daryti taip:

sudo apt update
sudo apt upgrade
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.14-venv

Naujausia python versija bus pasiekiama python3.14 komandos pagalba.

Spinta diegimas

Atkreipkite dėmesį, kad visos komandos diegiant Spinta turi būti vykdoma spinta naudotojo teisėmis ir iš spinta naudotojo namų katalogo /opt/spinta.

Aktyvų naudotoją ir katalogą galite pasikeisti taip:

sudo -Hsu spinta
cd

Agentas veikia Spinta_ priemonės pagalba, kuriai reikia Python. Rekomenduojama visus Python paketus diegti taip vadinamoje izoliuotoje Python aplinkoje, kurią galima susikurti taip (nepamirškite nurodyti jūsų naudojamos Python versijos numerį, kuris gali skirtis):

Jei Python diegėte su venv_:

/opt/pyenv/versions/3.14.0/bin/python -m venv env

Jei Python diegėte distribucijos priemonėmis:
python3.14.0 -m venv env

Toliau diekite spinta:

DVMS partneriams projekto vystymo metu rekomenduojama diegti naujausią pre-release versiją, kadangi joje yra naujausi projekto vystymui ir partnerių darbui atlikti pakeitimai:

env/bin/pip install --pre spinta
env/bin/spinta --version

Agento konfigūravimas

Spinta yra konfigūruojama konfigūracijos failo pagalba, kurio, pagal nutylėjimą, ieškoma aktyviame kataloge. Kur Spinta ieško konfigūracijos failo, galima patikrinti taip:

env/bin/spinta config config

Konfigūracijos failo vieta gali būti keičiama komandinės eilutės:

env/bin/spinta -o config=config.yml

Arba aplinkos kintamųjų pagalba:

SPINTA_CONFIG=/opt/spinta/config.yml

Kuriuos, taip pat galima pateikti ir .env faile.

Pats konfigūracijos failas config.yml turėtu atrodyti panašiai taip:

config_path: /opt/spinta/config
default_auth_client: default
env: production
manifest: default
token_validation_keys_download_url: https://<auth-serverio-adresas>  # auth serverio viešu raktu
                                                                         # (well-known) adresas, jei
                                                                         # naudojate autorizacijos serverį
                                                                         # (ne spinta), kuris palaiko raktų rotavimą

keymaps:
  default:
    type: sqlalchemy
    dsn: sqlite:////opt/spinta/var/keymap.db

backends:
  default:
    type: postgresql
    dsn: postgresql:///spinta

manifests:
  default:
    type: tabular
    path: /opt/spinta/manifest.csv
    backend: default
    mode: external

accesslog:
  type: file
  file: /opt/spinta/logs/access.log

Jei naudojate daugiau, nei vieną manifestą, ir norite, kad Agentas pasiektų juos visus, galima tai atlikti operatoriaus sync pagalba:

manifests:
  default:
    type: tabular
    path: /opt/spinta/manifest.csv
    backend: default
    mode: external
    sync: additional
  additional:
    type: tabular
    path: /opt/spinta/manifest2.csv
    backend: default
    mode: external

Prieš testuojant ar konfigūracija veikia, sukuriame reikalingus katalogus:

mkdir /opt/spinta/config
mkdir /opt/spinta/logs
mkdir /opt/spinta/var

Generuojame kriptografinius autorizacijos raktus:

env/bin/spinta key generate

Nepamirškite, kad /opt/spinta/manifest.csv faile, kaip nurodyta konfigūracijos faile, turite pateikti duomenų struktūros aprašą, kurio pagrindu veiks agentas.

Galiausiai patikriname konfigūraciją:

env/bin/spinta config config backends manifests accesslog

Patikriname ar konfigūracijoje ir pateiktame struktūros apraše nėra klaidų.

env/bin/spinta check

Patikriname ar Spinta gali prisijungti prie duomenų bazės.

env/bin/spinta wait 1

Keymap

Keymap naudojamas susieti išorinius identifikatorius su vidiniais identifikatoriais. Gali būti konfigūruojama. Pagal numatytuosius nustatymus naudojama SQLite, kaip parodyta aukščiau pateiktame konfigūracijos pavyzdyje, tačiau galima pakeisti į kitą, pvz. - greitesnę ar stabilesnę saugyklą. Čia pateikiamas pilnas galimų variantų sąrašas:

SQLite duomenų bazė su SQLAlchemy backend'u, konfigūruojama taip:

keymaps:
  default:
    type: sqlalchemy
    dsn: sqlite:////path/to/keymap.db

Redis persistent saugykla su Redis, konfigūruojama taip:

keymaps:
  default:
    type: redis
    dsn: redis://redis-address:6379/1

Redis rekomenduojame diegti Docker konteineryje. Docker paleidimo konfigūracija:

redis-keymap: # sqlite faster alternative
  image: valkey/valkey:9
  restart: always
  command: [ "redis-server", "--appendonly", "yes" ] # persistence settings to persist always, without any data loss.
  volumes:
    - redis_keymap_data:/data
  ports:
    - "6379:6379"

volumes:: redis_keymap_data:

SVARBU! Redis turi būti būtinai leidžiamas persistent režimu (appendonly yes parametras) Yra keli persistent režimai (žr. Redis/Valkey dokumentaciją). Numatytasis režimas (appendonly) užtikrina didžiausią duomenų nepraradimo patikimumą, tačiau turi mažiausią greitį, lyginant su kitais režimais.

Web serverio diegimas ir konfigūravimas

Į Python virtualią aplinką įdiegiame Gunicorn:

env/bin/pip install gunicorn uvloop httptools

Sukuriame SystemD servisą (atkreipkite dėmesį, kad jūsų pasirinkta distribucija gali naudoti kitą servisų valdymo priemonę, tuomet šis pavyzdys netiks):

# /etc/systemd/system/gunicorn.service
[Unit]
Description=gunicorn daemon
After=network.target

[Service]
Type=notify
RuntimeDirectory=gunicorn
WorkingDirectory=/opt/spinta
EnvironmentFile=/opt/spinta/.env
ExecStart=/opt/spinta/env/bin/gunicorn -b 127.0.0.1:8000 -u spinta -g www-data -k uvicorn.workers.UvicornWorker spinta.asgi:app
ExecReload=/bin/kill -s HUP $MAINPID
KillMode=mixed
TimeoutStopSec=5
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Aktyvuokite servisą:

sudo systemctl enable gunicorn
sudo systemctl daemon-reload
sudo systemctl start gunicorn

Patikrinkite ar servisas veikia:

sudo systemctl status gunicorn

Įdiegiame pasirinktą Web serverio paketą, šiuo atveju pavyzdys pateiktas Nginx:

sudo apt update
sudo apt install nginx

Sukuriame pasirinkto Web serverio, šiuo atveju Nginx, konfigūracijos failą (pakeiskite example.org į jūsų domeno pavadinimą):

# /etc/nginx/sites-available/example.org
server {
  listen 80;
  server_name example.org;

  location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Aktyvuojame konfigūracijos failą:

sudo ln -s /etc/nginx/sites-available/example.org /etc/nginx/sites-enabled/

Patikriname ar konfigūracija veikia:

sudo nginx -t

Perkraukite Nginx:

sudo systemctl restart nginx

Patikrinkite ar servisas veikia:

sudo systemctl restart nginx

Detalesnės instrukcijos apie tai, kaip konfigūruoti SSL sertifikatus ir kitus Gunicorn ar Nginx parametrus rasite minėtų projektų dokumentacijoje.

Spintos naujinimas

Norint atnaujinti Spinta versiją, jums reikia įvykdyti tokias komandas:

sudo -Hsu spinta
cd
env/bin/pip install --upgrade --pre spinta

Struktūros aprašo naujinimas

Jei pasikeitė struktūros aprašas, jį galite atnaujinti taip:

scp manifest.csv example.org:/opt/spinta/manifest-new.csv
ssh example.org
sudo chown spinta:www-data /opt/spinta/manifest-new.csv
sudo -Hsu spinta
cd
env/bin/spinta check manifest-new.csv
cp manifest.csv manifest-old.csv
mv manifest-new.csv manifest.csv

diff -y --suppress-common-lines manifest-old.csv manifest-new.csv

exit  # spinta user
sudo systemctl restart gunicorn
sudo systemctl status gunicorn
exit  # server

Problemos ir sprendimai

Jei kažkas neveikia, pirmiausiai reikėtų žiūrėti servisų žurnalus, pavyzdžiui:

journalctl -u gunicorn -xe
journalctl -u nginx -xe

Žurnaluose dažniausiai būna pateikta informacija, leidžianti suprasti kas ir kodėl neveikia.