Версія 1.0.0-alpha.1найновіша
Розділ 2.8
Встановлення на одну машину
Встановіть Nexus на один сервер Linux за допомогою nexusctl або протестуйте його на ноутбуці через k3d і підключіться до консолі за протоколом HTTPS, щоб працювали вхід у систему та ключі доступу (passkeys).
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

Перш ніж 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 пам'яті, а загальний обсяг його томів становить 142 GiB. Ця сума складається з PostgreSQL — 50, Valkey — 5, Neo4j — 20, Qdrant — 10, об'єктного сховища — 50, двох сховищ OpenBao — 1 і 5, а також тому для квитанцій — 1. Запити (requests) — це те, що резервує планувальник, а реальне споживання зростає, коли люди починають працювати.
| Машина | 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 пам'яті та накопичувачем SSD на 500 GB під керуванням актуальної версії Linux без жодного іншого програмного забезпечення. Для встановлення потрібні права root, оскільки k3s встановлюється як системна служба.
Отримання та перевірка nexusctl
- Завантажте
nexusctlдля вашої архітектури зhttps://downloads.adverant.ai/nexus/1.0.0-alpha.1/разом із відкритим ключем релізу. Збережіть ключ якrelease.pub. У розділі 2.4 «Отримання та перевірка релізу» пояснюється, як звірити відбиток ключа з тим, який публікує Adverant. - Перевірте бінарний файл і реліз за допомогою ключа:
nexusctl version --json
nexusctl verifynexusctl verify перевіряє завантажений файл за ключем релізу Adverant і відхиляє все, що не вдається верифікувати. У разі помилки зупиніться та завантажте файл знову. Ніколи не запускайте встановлення з файлу, який не пройшов перевірку.
Створення ключа зберігача
Сховище ключів інсталяції запечатує свої ключі відновлення для одного або кількох зберігачів (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) одразу повідомляє про відповідні коди помилок.
Три хости визначають ідентичність інсталяції. Жодна служба не запуститься без них, а кожен вхід у систему, файл cookie та ключ доступу (passkey) прив'язуються до hosts.console. Обирайте імена, які залишатимуться актуальними для вас і через п'ять років.
Спрямування трьох імен на сервер
Користувачі звертаються до консолі, API (інтерфейсу прикладного програмування) та служби входу через вбудований у k3s ingress-контролер Traefik на портах 80 і 443 сервера. Додайте три записи DNS (системи доменних імен) для console.harrow.example, api.harrow.example і auth.harrow.example, кожен з яких вказує на адресу сервера. Попередня перевірка перевіряє кожне ім'я та повідомляє, для якого з них немає запису.
Мережева політика чарту дозволяє доступ до трьох публічних служб лише з одного простору імен. За замовчуванням це kube-system — саме там k3s запускає Traefik, тому на одному вузлі параметр networkPolicy.ingressNamespace змінювати не потрібно.
Попередня перевірка та встановлення
- Запустіть попередню перевірку з прапорцем для одного вузла. Вона зчитує параметри машини та вашого файлу значень, нічого не змінюючи.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml- Прочитайте підсумковий рядок у кінці. Попередження ніколи не блокує встановлення, але помилка блокує, і кожен рядок із помилкою містить підказку
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
- Виконайте встановлення. Прапорець
--editionмає збігатися зі значеннямeditionу файлі значень.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community- Спостерігайте за процесом виконання. Команда знову запускає попередню перевірку, встановлює 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 «Перший запуск».
Розміщення сертифіката
Якщо вказано 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.keyharrow-public.crt містить сам сертифікат, за яким ідуть будь-які проміжні сертифікати, а harrow-public.key — його закритий ключ. Якщо ваші сертифікати видані приватним CA (центром сертифікації), команди nexusctl preflight і nexusctl install приймають параметр --ca-bundle <file>, щоб мати змогу перевірити ланцюжок сертифікатів. Інші способи роботи з TLS (Transport Layer Security) описано в розділі 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повертає керування лише тоді, коли кластер починає відповідати, або завершується помилкою через п'ять хвилин.
Якщо ви використовуєте локальне дзеркало реєстру релізів на своєму ноутбуці, додайте --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 10mNexus не потребує нічого іншого від cert-manager, зокрема не потрібен trust-manager.
Встановлення Nexus
- Напишіть файл значень для ноутбука. З'єднання 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>"- Встановіть чарт із реєстру, не вказуючи прапорець
--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- Потім самостійно дочекайтеся готовності робочих навантажень:
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 потрібен тому, що деякі з них оновлюють по одному поду за раз за запитом, і команда kubectl rollout status відмовляється працювати з ними. Очікування на readyReplicas працює для будь-якої стратегії оновлення.
Коли обидві команди завершать виконання, кожен об'єкт Deployment матиме статус Available, а всі поди кожного StatefulSet будуть готові. Увійти в систему ще ніхто не може. Так і має бути: інсталяцію ще не активовано.
Чому перенаправлення портів (port-forward) ніколи не дасть змоги увійти
Очевидний наступний крок — виконати 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, має неправильне джерело, тому процес входу навіть не розпочинається. |
| Файл cookie | Сесія зберігається у файлі cookie __Host- з позначкою Secure. Браузери зберігають такий файл cookie лише через HTTPS, без атрибута домену, виключно для того хоста, який його встановив. Через звичайний HTTP браузер просто відкидає його. |
| Ключ доступу (passkey) | Перший адміністратор входить за допомогою ключа доступу (passkey), а для нього потрібен захищений контекст із дійсним сертифікатом. Chrome відмовляється створювати ключ доступу за наявності попередження про сертифікат, навіть якщо ви натиснули кнопку, щоб проігнорувати його. |
Отже, браузер має звертатися до https://console.harrow.example із сертифікатом, якому він довіряє, а це ім'я має вести на ваш ноутбук.
Доступ до консолі через HTTPS на ноутбуці
Наведений нижче метод використовує власний центр сертифікації (CA) чарту для випуску сертифіката, перенаправлення портів для доступу до консолі та окремий профіль Chrome, який довіряє цьому єдиному CA і зіставляє ім'я консолі з вашим ноутбуком. Системне сховище довірених сертифікатів і файл /etc/hosts залишаються без змін.
Випуск сертифіката для імені консолі
- Запитайте у 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=120scert-manager підписує його всередині кластера. Ви ніколи не зчитуєте закритий ключ CA.
- Скопіюйте сертифікат, його ключ і сертифікат 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- Обчисліть хеш-прив'язку (pin) для CA. Chrome ідентифікує довірений ключ за хешем SHA-256 його відкритого ключа у форматі base64:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64Прив'язуйте ключ CA, а не ключ самого сертифіката. Сертифікат діє один день і отримує новий ключ щоразу, коли cert-manager оновлює його, тоді як CA залишається незмінним.
Розміщення інтерфейсу HTTPS перед перенаправленням портів
- Налаштуйте перенаправлення для об'єкта Service консолі. Його порт має назву
http, що в цьому релізі відповідає порту 3000:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000- Запустіть прослуховувач HTTPS на
127.0.0.1:28443, який перенаправляє трафік на127.0.0.1:3000. Підійде будь-який зворотний проксі-сервер, якому ви вже довіряєте, за умови, що він виконує чотири речі:- віддає
tls.crt, за яким ідеca.crtяк ланцюжок сертифікатів, використовуючи ключtls.key; - зберігає заголовок
Hostзі значеннямconsole.harrow.example; - встановлює
X-Forwarded-Proto: https; - пропускає запити на перехід до протоколу WebSocket (WebSocket upgrades), оскільки консоль використовує їх.
- віддає
Перенаправлення портів до об'єкта 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. Окремий профіль ізолює цей виняток від вашого повсякденного перегляду вебсторінок. Це не глобальний перемикач «ігнорувати помилки сертифікатів»: усе, що не підписано центром сертифікації кластера, як і раніше, блокуватиметься.
У відкритому вікні цього профілю адреса https://console.harrow.example/install веде на сторінку активації, де можна створити ключ доступу (passkey). Продовження процесу описано в розділі 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Цей файл надає повний адміністративний доступ до кластера. Зберігайте його з правами доступу 600 на машинах тих людей, які обслуговують інсталяцію, і більше ніде. Кожна наступна команда в Частині 2, яка приймає --context або зчитує KUBECONFIG, працює з одновузловою системою через цей файл. Те саме стосується й оновлення: nexusctl upgrade plan --bundle <file> та nexusctl upgrade apply --bundle <file> на одному вузлі також оновлюють кластер k3s, яким керує nexusctl.
nexusctl install --single-node розгортає на одному сервері Linux.Що переноситься у кластер
Усе, що ви робили на одній машині, має свій відповідник у кластері. Файл значень залишається тим самим, змінюється лише реєстр, режим TLS або клас сховища (storage class), як показано в розділі 2.11 «Варіації: зовнішні сховища, TLS та ingress». Перший запуск відбувається ідентично. Єдине, що не переноситься, — це сама інсталяція: ім'я інсталяції фіксується назавжди, і систему не можна перенести з ноутбука на сервер. Коли Tomás перейшов зі свого ноутбука на пілотний сервер, він почав усе спочатку з новим іменем, harrow-pilot, а harrow-eval залишив для експериментів.
