ВходЗапазете среща

Глава 2.8

Инсталации на една машина

Инсталирайте Nexus на един Linux сървър с nexusctl или го тествайте на лаптоп с k3d и отворете конзолата през HTTPS, за да работят влизането и ключовете за достъп.

Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

18 минути за четене

Преди Harrow Port Authority да разположи Nexus в своя продукционен клъстер, Tomás Reilly искаше две по-малки инсталации. Едната беше пилотна – на свободен Linux сървър в оперативната сграда, за дванадесетте души, които щяха да я изпробват първи. Другата работеше на собствения му лаптоп, за да може да чупи нещата, без никой да забележи. Тази глава разглежда и двете. Те използват същия чарт, същите изображения и същото първо стартиране като пълна инсталация в Kubernetes, така че наученото на една машина се пренася и на друга.

Пътят за сървър се състои от една команда: nexusctl install --single-node изгражда k3s клъстер на машината, инсталира cert-manager и след това инсталира Nexus. Пътят за лаптоп изисква повече ръчна намеса. Сами изграждате k3d клъстер, инсталирате cert-manager и чарта с Helm, а след това вършите една допълнителна работа, която спъва почти всеки: поставяте конзолата зад HTTPS на собствената си машина, защото обикновено пренасочване на портове (port-forward) никога не може да впише никого.

Колко голяма трябва да е машината

Nexus изисква около 2.05 ядра на CPU (централен процесор) и 6.7 GiB памет като заявки (requests) при стандартните настройки на чарта, а неговите томове (volumes) възлизат общо на 142 GiB. Тази обща сума се състои от PostgreSQL – 50, Valkey – 5, Neo4j – 20, Qdrant – 10, хранилището за обекти – 50, двете хранилища на OpenBao – 1 и 5, и тома за разписки (receipts) – 1. Заявките са това, което диспечерът (scheduler) резервира, а реалното потребление е по-високо, след като хората започнат работа.

Машина CPU Памет (RAM, памет с произволен достъп) Диск
Препоръчително за един възел 8 vCPU 32 GiB 250 GB SSD (твърдотелен диск)
Минимум за оценка 4 vCPU 16 GiB 200 GB

Лаптоп, който отговаря на минимума за оценка, ще може да стартира Nexus, но значение има собственият лимит на паметта на Docker, а не този на лаптопа. Задайте на Docker поне 16 GiB, преди да започнете.

И двата пътя изискват Kubernetes 1.33 или по-нова версия. Пътят за един възел носи своя собствена: k3s v1.33.6+k3s1 – дистрибуцията, на която се тества всяко издание.

Част първа: един Linux сървър с nexusctl

Пилотният сървър на Tomás е 8-ядрена машина с 32 GiB памет и 500 GB SSD, работеща с актуален Linux без нищо друго на нея. Инсталацията се нуждае от root права, тъй като инсталира k3s като системна услуга.

Изтегляне и проверка на nexusctl

  1. Изтеглете nexusctl за вашата архитектура от https://downloads.adverant.ai/nexus/1.0.0-alpha.1/, заедно с публичния ключ на изданието. Запазете ключа като release.pub. Глава 2.4, Изтегляне и проверка на издание, обяснява как да проверите отпечатъка (fingerprint) на ключа спрямо този, публикуван от Adverant.
  2. Проверете изпълнимия файл и изданието с ключа:
nexusctl version --json
nexusctl verify

nexusctl verify проверява изтегления файл спрямо ключа на изданието на Adverant и отхвърля всичко, което не може да потвърди. Ако проверката е неуспешна, спрете и изтеглете отново. Никога не стартирайте инсталация от файл, който не е преминал проверка.

Създаване на ключ на пазител (custodian)

Хранилището за ключове на инсталацията запечатва своите ключове за възстановяване към един или повече пазители (custodians). Пазителят е лице, което съхранява офлайн файл с age идентичност, а чартът отказва да се инсталира без поне един такъв. На собствената машина на пазителя:

age-keygen -o custodian.key

Файлът започва с ред # public key: age1.... Тази публична половина е това, което влиза във файла със стойности (values file). Самият файл с идентичност никога не напуска машината на пазителя. На Mac със Secure Enclave, age-plugin-se keygen --access-control=any-biometry -o custodian.key създава ключ, който изисква Touch ID за използване, а неговата публична половина започва с age1se1.

Създаване на файла със стойности

# harrow-pilot-values.yaml (Helm values)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
enterprise:
  enabled: false
tls:
  mode: existing
  existingSecret: harrow-public-tls
keys:
  installationName: harrow-pilot
  custody:
    recipients:
      - "<custodian-age-recipient>"

<custodian-age-recipient> е редът age1... от custodian.key. Добавете по един запис в списъка за всеки пазител.

keys.installationName е постоянно. Първото стартиране на хранилището за ключове създава идентичността на инсталацията под това име и нищо не може да го преименува впоследствие. То трябва да отговаря на ^[a-z][a-z0-9-]{0,62}$: малки букви, започващо с буква, най-много 63 знака. Не копирайте nexus-example или примерния получател от собствените примерни файлове на чарта. Чартът отхвърля и двете по име, а предварителната проверка (preflight) докладва същите кодове още в началото.

Трите хоста представляват идентичността на инсталацията. Всяка услуга отказва да стартира без тях, а всяко вписване, бисквитка и ключ за достъп (passkey) са обвързани с hosts.console. Изберете имена, които ще искате да ползвате и след пет години.

Насочване на трите имена към сървъра

Хората достигат до конзолата, API (интерфейса за приложно програмиране) и услугата за вписване чрез вградения в k3s ingress контролер – Traefik, на портове 80 и 443 на сървъра. Добавете три записа в DNS (системата за имена на домейни) за console.harrow.example, api.harrow.example и auth.harrow.example, като всеки сочи към адреса на сървъра. Предварителната проверка (preflight) проверява всяко име и ви казва за кое липсва запис.

Мрежовата политика на чарта позволява само на едно пространство от имена (namespace) да достига до трите публични услуги. Неговата стойност по подразбиране, kube-system, е мястото, където k3s стартира Traefik, така че при един възел оставяте networkPolicy.ingressNamespace непроменено.

Изпълнение на предварителна проверка и инсталиране

  1. Стартирайте предварителната проверка с флага за един възел. Тя прочита машината и вашия файл със стойности и не променя нищо.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml
  1. Прочетете обобщаващия ред в края. Предупреждението никога не блокира инсталацията, но грешката го прави, като всеки ред с грешка съдържа ред fix.
 ────────────────────────────────────────────────────────────
 9 passed · 1 warning · 0 failed   You can install. Warnings do not block; fix them when you can.
 Report saved to preflight-2026-11-12-0902.txt · nothing was changed
  1. Инсталирайте. Флагът --edition трябва да съвпада с edition във файла със стойности.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community
  1. Наблюдавайте изпълнението. Процесът отново стартира предварителна проверка, инсталира k3s v1.33.6+k3s1, инсталира cert-manager v1.21.3, инсталира Nexus и изчаква всяка услуга да отговори на проверката за изправност (health check). На сървъра на Tomás това отне малко под десет минути.
 done   Preflight again        9 passed · 1 warning
 done   k3s v1.33.6+k3s1       node Ready
 done   cert-manager v1.21.3   ready
 done   Database and search    ready
 done   Engines                started
 done   Console                https://console.harrow.example
 Installed. Nobody can sign in yet.
 Open https://console.harrow.example/claim
 Code <code>  works once, for 30 minutes
 Fingerprint of this installation, to compare in the browser:
 3F9A C21B 77E0 5D4C 9B12 A6F3 0E88 41D7

Оставете този отпечатък на екрана. Ще го сравните в браузъра, когато заявите собственост над инсталацията с кода. Ако валидността на кода изтече, преди да го използвате, nexusctl claim-code --administrator <email> създава нов. Глава 2.12, Първото стартиране, поема нещата оттук нататък.

Инсталиране на изданието Community
Инсталиране на изданието Community
Инсталацията на Community на един сървър включва изтегляне, проверка, предварителна проверка и инсталиране, след което се настройва първият администратор. Няма стъпка за лиценз.

Поставяне на сертификата на място

С tls.mode: existing, трите ingress маршрута обслужват сертификата в обекта Secret, именуван от tls.existingSecret. Той трябва да покрива и трите хоста. Предварителната проверка прочита този Secret, когато той съществува, и предупреждава, ако сертификатът изтича в рамките на 30 дни. Когато обектът Secret все още не е там, редът ви указва да го създадете, като това е предупреждение, а не грешка.

На един възел клъстерът не съществува, докато инсталацията не го създаде, затова създайте обекта Secret веднага след инсталацията. Първо запишете kubeconfig файла на клъстера (последният раздел на тази глава обяснява това), а след това създайте обекта Secret с него:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus create secret tls harrow-public-tls --cert=harrow-public.crt --key=harrow-public.key

harrow-public.crt съдържа сертификата, последван от всички междинни сертификати, а harrow-public.key – неговия частен ключ. Ако вашите сертификати идват от частен CA (сертифициращ орган), nexusctl preflight и nexusctl install приемат --ca-bundle <file>, за да могат да проверят веригата. Другите начини за управление на TLS (защита на транспортния слой) са описани в глава 2.11, Вариации: външни хранилища, TLS и ingress.

Ако това не успее

Какво виждате Какво означава Какво да предприемете
PREFLIGHT_FAILED (409) Предварителната проверка откри грешка, поради което инсталацията не стартира. Нищо не беше инсталирано. Коригирайте всеки ред с грешка, като използвате неговия ред fix, и стартирайте инсталацията отново.
INSTALLATION_NAME_MISSING keys.installationName е празно. Задайте собственото постоянно име на инсталацията.
INSTALLATION_NAME_EXAMPLE Името е това от примерните стойности на чарта. Изберете свое собствено име.
KEYS_CUSTODIAN_MISSING keys.custody.recipients е празно. Добавете публичния age1... получател на всеки пазител.
KEYS_CUSTODIAN_EXAMPLE Получател е примерният пазител от чарта, чиято идентичност никой не притежава. Заменете го с получателите на вашите пазители.

nexusctl завършва с код 0, когато може да продължи, 1, когато проверка го е блокирала, и 2, когато изобщо не е могъл да се изпълни (нечетим файл със стойности, грешен флаг). Един скрипт може да се разклони въз основа на тези три стойности.

Част втора: тестване на лаптоп с k3d

k3d стартира k3s вътре в Docker контейнери, така че цял клъстер живее на един лаптоп и изчезва с една команда. Инструментите за издания, които тестват всяко издание на Nexus, изграждат своите клъстери точно по този начин и копирането на техните настройки ви спестява повторното откриване на проблеми, с които те вече са се сблъскали.

Нуждаете се от Docker, k3d 5.8.3, kubectl, Helm v4 и Chrome. Tomás използва своя Mac.

Създаване на клъстера

k3d cluster create harrow-eval --agents 0 --wait --timeout 300s \
  --image rancher/k3s:v1.33.6-k3s1 \
  --k3s-arg "--disable=traefik@server:0"
k3d kubeconfig get harrow-eval > harrow-eval.kubeconfig
chmod 600 harrow-eval.kubeconfig
export KUBECONFIG=$PWD/harrow-eval.kubeconfig

Всеки флаг си има причина.

  • --agents 0 осигурява един сървърен възел и никакви работни възли (workers). Nexus работи безпроблемно на един възел, а втори само би изразходвал памет.
  • --image rancher/k3s:v1.33.6-k3s1 фиксира версията на k3s, на която се тества всяко издание. Без него получавате версията по подразбиране на k3d.
  • --disable=traefik@server:0 пропуска Traefik. Лаптопът няма публичен адрес, който да обслужва, и вместо това достигате до конзолата чрез ваш собствен преден HTTPS слой (по-долу).
  • --wait --timeout 300s връща резултат само когато клъстерът отговори, или се проваля след пет минути.

Ако поддържате огледално копие (mirror) на регистъра с изданията на вашия лаптоп, добавете --registry-config <registries.yaml>, за да насочите изтеглянето на изображения към огледалния регистър, и --k3s-arg "--disable-default-registry-endpoint@server:0", така че нищо да не се връща към основния регистър. Инструментите за издания работят по този начин, като всяко изображение идва само през огледалния регистър.

Инсталиране на cert-manager

Чартът създава свой собствен локален CA, nexus-local-ca, като издател (issuer) в cert-manager, и всяка услуга получава своя сертификат от него. Без ресурсите на cert-manager в клъстера, helm install отхвърля чарта в рамките на секунди. Инсталирайте първо cert-manager v1.21.3 от чарта, който проектът cert-manager публикува:

helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
  --create-namespace --set crds.enabled=true --wait --timeout 10m

Nexus не се нуждае от нищо друго от cert-manager и по-специално не се нуждае от trust-manager.

Инсталиране на Nexus

  1. Създайте файл със стойности за лаптопа. TLS терминира при вашия собствен преден слой, така че tls.mode е none.
# harrow-eval-values.yaml (Helm values)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
tls:
  mode: none
keys:
  installationName: harrow-eval
  custody:
    recipients:
      - "<custodian-age-recipient>"
  1. Инсталирайте чарта от регистъра и пропуснете --wait (предупреждението по-долу обяснява защо).
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
  -n nexus --create-namespace -f harrow-eval-values.yaml --timeout 45m
  1. След това сами изчакайте работните натоварвания (workloads):
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
for s in $(kubectl -n nexus get sts -o name); do
  want=$(kubectl -n nexus get "$s" -o jsonpath='{.spec.replicas}')
  kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'="$want" --timeout=900s
done

Цикълът за StatefulSet е там, защото някои от тях обновяват по един под (pod) при поискване, а kubectl rollout status ги отхвърля. Изчакването на readyReplicas работи за всяка стратегия за обновяване.

Когато и двете команди завършат, всеки Deployment е наличен (Available) и всеки StatefulSet е с готови подове. Все още никой не може да се впише. Това е нормално: собствеността над инсталацията не е заявена.

Защо пренасочването на портове никога не позволява влизане

Очевидният следващ ход е kubectl port-forward svc/nexus-alpha 3000:3000 и браузър на http://127.0.0.1:3000. Страниците на конзолата се зареждат, така че изглежда сякаш работи. Но не е така и никаква настройка няма да го накара да проработи. Три неща стоят на пътя, всяко от тях умишлено.

Какво го спира Защо
Произходът (origin) Вписването в конзолата отхвърля заявка, чийто произход (origin) не е https://<hosts.console>, в случая https://console.harrow.example. Страница, обслужена от http://127.0.0.1:3000, има грешен произход, така че вписването изобщо не стартира.
Бисквитката Сесията представлява бисквитка __Host-, маркирана като Secure. Браузърите съхраняват такава бисквитка само през HTTPS, без атрибут за домейн, точно за хоста, който я е задал. През обикновен HTTP браузърът я изхвърля.
Ключът за достъп (passkey) Първият администратор се вписва с ключ за достъп (passkey), а той се нуждае от защитен контекст с валиден сертификат. Chrome отказва да създаде ключ за достъп зад предупреждение за сертификат, дори и такова, което сте прескочили с кликване.

Следователно браузърът трябва да комуникира с https://console.harrow.example, със сертификат, на който има доверие, и това име трябва да води към вашия лаптоп.

Достъп до конзолата през HTTPS на Вашия лаптоп

Методът по-долу използва собствения CA на чарта за издаване на сертификата, пренасочване на портове за достигане до конзолата и отделен профил в Chrome, който се доверява само на този CA и съпоставя името на конзолата с вашия лаптоп. Вашето системно хранилище за доверие и /etc/hosts остават непроменени.

Диаграмата показва Chrome отляво с надпис „separate profile: trusts nexus-local-ca only; console.harrow.example:443 mapped to 127.0.0.1:28443“. Стрелка с надпис „HTTPS“ води към блок „HTTPS front on 127.0.0.1:28443 (certificate from nexus-local-ca)“. Стрелка с надпис „HTTP, Host kept, X-Forwarded-Proto https“ води към „kubectl port-forward 127.0.0.1:3000“, а последната стрелка влиза в блока на k3d клъстера към „Service nexus-alpha, port http (3000)“. Пунктирана линия от cert-manager вътре в клъстера към предния блок е с надпис „issues the certificate“.
Как браузър на лаптопа достига до конзолата в k3d клъстера през HTTPS.

Издаване на сертификат за името на конзолата

  1. Поискайте от cert-manager сертификат за хоста на конзолата, подписан от издателя на чарта:
# console-front-certificate.yaml (a cert-manager Certificate)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nexus-console-front
  namespace: nexus
spec:
  secretName: nexus-console-front-tls
  dnsNames: [console.harrow.example]
  duration: 24h
  usages: [server auth, digital signature, key encipherment]
  privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
  issuerRef: { name: nexus-local-ca, kind: Issuer, group: cert-manager.io }
kubectl apply -f console-front-certificate.yaml
kubectl -n nexus wait --for=condition=Ready certificate/nexus-console-front --timeout=120s

cert-manager го подписва вътре в клъстера. Вие никога не четете частния ключ на CA.

  1. Копирайте сертификата, неговия ключ и сертификата на CA от обекта Secret:
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
chmod 600 tls.key
  1. Изчислете пина (pin) на CA. Chrome идентифицира доверен ключ чрез base64 SHA-256 хеша на неговия публичен ключ:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64

Фиксирайте (pin) ключа на CA, а не този на сертификата. Сертификатът е валиден един ден и получава нов ключ всеки път, когато cert-manager го поднови, докато CA остава същият.

Поставяне на преден HTTPS слой пред пренасочването на портове

  1. Пренасочете обекта Service на конзолата. Неговият порт е този с име http, който в това издание е 3000:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000
  1. Стартирайте HTTPS слушател (listener) на 127.0.0.1:28443, който препраща към 127.0.0.1:3000. Всеки обратен прокси сървър (reverse proxy), на който вече имате доверие, ще свърши работа, стига да прави четири неща:
    • обслужва tls.crt, последван от ca.crt като верига, с tls.key;
    • запазва хедъра Host като console.harrow.example;
    • задава X-Forwarded-Proto: https;
    • пропуска надгражданията към WebSocket, тъй като конзолата ги използва.

Пренасочването на портове към Service се обвързва с конкретния под, който е избрало при стартирането си. След като обновяване или рестартиране замени пода на конзолата, пренасочването остава активно, но препраща към нищото, а браузърът показва грешка „bad gateway“. Рестартирайте пренасочването на портове всеки път, когато подът на конзолата се промени.

Отваряне на Chrome с пина и съпоставянето на името

На Mac:

open -na "Google Chrome" --args --user-data-dir="$HOME/.nexus-eval-chrome" \
  "--host-resolver-rules=MAP console.harrow.example:443 127.0.0.1:28443" \
  "--ignore-certificate-errors-spki-list=<ca-pin>" \
  https://console.harrow.example/install

<ca-pin> е изходният резултат от реда с openssl. На Linux стартирайте Chrome със същите три флага.

Трите флага работят заедно. --host-resolver-rules изпраща console.harrow.example на порт 443 към вашия преден слой, само в рамките на този профил. --ignore-certificate-errors-spki-list се доверява на сертификати, издадени от този конкретен CA ключ, а Chrome го зачита само с --user-data-dir. Отделният профил държи изключението далеч от вашето ежедневно сърфиране. Това не е общ превключвател за „игнориране на грешки в сертификатите“: всичко, което не е подписано от CA на клъстера, продължава да се отхвърля.

С отворен такъв профил, https://console.harrow.example/install води до страницата за заявяване на собственост и може да бъде създаден ключ за достъп. Глава 2.12, Първото стартиране, поема нещата оттук.

Когато лаптопът се рестартира

Хранилището за ключове се състои от две части: самото хранилище за ключове и малък модул за разпечатване (unsealer), който държи неговия ключ за отключване. След всяко рестартиране на възела (рестартиране на Docker, рестартиране на лаптопа, k3d cluster stop и start) модулът за разпечатване стартира запечатан. Хранилището за ключове се разпечатва само чрез него, така че докато пазител не разпечата модула със собствената си age идентичност, нищо, което се нуждае от ключ, не работи. Това е свойство на дизайна и е същото и при продукционен клъстер. Глава 2.15, Ден втори: работа с Nexus, показва процеса на разпечатване.

Когато приключите с оценката:

k3d cluster delete harrow-eval

Изтриването на клъстера изтрива инсталацията и всичко в нея.

nexusctl kubeconfig

Клъстер, който nexusctl install --single-node е изградил, принадлежи на nexusctl. За да достигнете до него с kubectl, helm или друг инструмент, поискайте неговия kubeconfig:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulset

Файлът дава пълен административен достъп до клъстера. Съхранявайте го с права за достъп (mode) 600 на машините на хората, които поддържат инсталацията, и никъде другаде. Всяка следваща команда в Част 2, която приема --context или чете KUBECONFIG, работи спрямо един възел чрез този файл. Същото се отнася и за обновяване: nexusctl upgrade plan --bundle <file> и nexusctl upgrade apply --bundle <file> на един възел обновяват също и k3s клъстера, притежаван от nexusctl.

Диаграмата представлява стек от четири слоя върху блок с надпис „one Linux server“. Отдолу нагоре: „k3s v1.33.6+k3s1 (Traefik in kube-system, ports 80 and 443)“, след това „cert-manager v1.21.3 and the chart's local CA nexus-local-ca“, след това „Nexus data tier: PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS, OpenBao“, и накрая „Nexus services: console, sign-in, gateway, and the rest“. Вдясно три стрелки от най-горния слой напускат блока с надписи console.harrow.example, api.harrow.example и auth.harrow.example. Вляво икона на терминал с надпис „nexusctl kubeconfig“ сочи към слоя k3s.
Какво поставя nexusctl install --single-node на един Linux сървър.

Какво се пренася към клъстер

Всичко, което направихте на една машина, има еквивалент в клъстер. Файлът със стойности е същият файл, но с различен регистър, TLS режим или клас за съхранение (storage class), както показва глава 2.11, Вариации: външни хранилища, TLS и ingress. Първото стартиране е идентично. Това, което не се пренася, е самата инсталация: името на инсталацията е фиксирано завинаги и една инсталация не може да бъде преместена от лаптоп на сървър. Когато Tomás премина от своя лаптоп към пилотния сървър, той започна отначало с ново име, harrow-pilot, и запази harrow-eval за експерименти.