13. Створюємо перший том — studiofs init¶

Work in progress

S3 уже має місце для файлів, PostgreSQL готовий пам’ятати їхню структуру, Tailscale з'єднує, а StudioFS встановлено. Тепер об’єднаємо ці складники в том — окремий диск StudioFS зі своїм ім’ям, налаштуваннями та ключем шифрування.

Для цього є команда studiofs init. Вона створює новий том, але ще не підключає його як диск у системі. Літера диска або каталог монтування з’являться на наступному кроці. Новосілля вже можна планувати, меблі поки не заносимо.

Що має бути готове¶

Запускайте команду на комп’ютері, з якого почнете працювати з томом, під своїм звичайним обліковим записом. Локальні метадані створюються для цього користувача; запуск через sudo може залишити їх у домашньому каталозі іншого користувача.

Потрібні адреса S3 API, приватний bucket, регіон та окремі ключі доступу з глави 06. Також знадобиться DSN PostgreSQL — рядок підключення з адресою, користувачем і паролем. Перевірки з глави 09 мають проходити саме з цього комп’ютера.

Віддалений PostgreSQL має бути доступний приватним шляхом, наприклад через Tailscale або NetBird. Не відкривайте порт 5432 для всього інтернету. Саме встановлення VPN не закриває публічний порт: перевірте прив’язку порту та правила firewall сервера.

Оберіть коротке зрозуміле ім’я, наприклад studio-projects. Це ім’я тому, а не bucket і не майбутня літера диска. Для початку зручно використовувати латинські літери, цифри й дефіси. Не вставляйте шлях: /, \ та : у назві заборонені. StudioFS використовуватиме це ім’я і в префіксі об’єктів: studio-projects/objects/.

Команда створення¶

Спершу можна звірити доступні параметри зі встановленою версією:

studiofs init --help

Нижче — шаблон, усі значення великими літерами потрібно замінити своїми. Адреси з .invalid навмисно не ведуть до справжніх сервісів. Команду показано одним рядком, щоб її можна було адаптувати для Bash, PowerShell або іншої оболонки без різних символів перенесення:

studiofs init studio-projects --endpoint 'https://S3_API_HOST:PORT' --bucket 'YOUR_PRIVATE_BUCKET' --region 'YOUR_S3_REGION' --access-key 'YOUR_ACCESS_KEY_ID' --secret-key 'YOUR_SECRET_ACCESS_KEY' --meta 'postgresql://YOUR_PG_USER:YOUR_URL_ENCODED_PASSWORD@PRIVATE_PG_HOST:5432/studiofs?sslmode=require'

Частина команди	Що вказати
`studio-projects`	Нове ім’я тому. Це позиційний аргумент, без окремого прапорця.
`--endpoint`	Адресу S3 API, а не панелі керування чи окремого об’єкта. Для віддаленого сховища — `https://`.
`--bucket`	Точну назву bucket для вмісту файлів.
`--region`	Регіон із налаштувань провайдера. Якщо параметр пропустити, буде `us-east-1`; для хмари краще вказати явно.
`--access-key`	Access Key ID окремого ключа StudioFS.
`--secret-key`	Secret Access Key цього ключа.
`--meta`	DSN сервера PostgreSQL. Обов’язковий параметр.

У прикладі PRIVATE_PG_HOST означає приватне ім’я вашого сервера.

У URL пароль зі знаками на кшталт @, :, / або # потрібно правильно закодувати як компонент URL. Лапки навколо DSN захищають рядок від оболонки, але не виконують це кодування. Неправильно записаний пароль легко перетворюється на «дивну адресу сервера».

Що відбудеться після запуску¶

StudioFS спочатку підключається до службової бази PostgreSQL postgres і перевіряє наявність бази studiofs. Якщо її немає, намагається створити. Назва бази фіксована: інша назва в DSN не створить окрему базу для цього тому — StudioFS перепише її на потрібну.

Далі команда перевіряє S3 bucket. Якщо перевірка не проходить, вона пробує створити bucket. Це може вимагати додаткового права CreateBucket. Повідомлення про спробу створення не доводить, що bucket відсутній: причиною початкової невдачі можуть бути неправильні ключі, endpoint або права. Заздалегідь створений доступний bucket дозволяє уникнути потреби в праві на його створення.

Після перевірок StudioFS готує спільні метадані, перевіряє, чи немає тому з таким ім’ям, створює локальну базу, кореневий каталог і ключ шифрування нового тому. Початковий стан публікується в PostgreSQL.

За замовчуванням локальна база лежить у ~/.studiofs/meta/studio-projects/studio-projects.db, де ~ — домашній каталог користувача. Якщо ви налаштували STUDIOFS_CLIENT_ROOT, коренем буде цей каталог. Точний шлях команда покаже наприкінці.

Налаштування містять облікові дані, а PostgreSQL також зберігає ключовий матеріал тому. Не вважайте локальну базу або спільні метадані безпечними для публікації лише тому, що вміст файлів шифрується.

Як зрозуміти, що все вдалося¶

Дочекайтеся завершення команди без помилки. Наприкінці має з’явитися рядок:

✓ Volume 'studio-projects' initialized

Поруч будуть UUID тому, розмір блока, endpoint і bucket, позначка Metadata backend: Postgres, ідентифікатор тому та шлях до локальних метаданих. Звірте ім’я й bucket зі своїм задумом. Самого повідомлення про успішне підключення до PostgreSQL ще недостатньо: після нього ініціалізація продовжується.

Додатково можна переглянути стан:

studiofs status studio-projects

Очікуйте інформацію про свій том, а не повідомлення Volume ... not found.

Якщо потрібно спробувати ще раз¶

init створює новий том і не є командою безпечного «оновлення налаштувань». Після помилки спершу прочитайте її та з’ясуйте, на якому кроці зупинилася команда.

Помилка S3: перевірте endpoint, регіон, ключі та доступ до наявного bucket. Не додавайте адміністративні права навмання лише через повідомлення про його створення.
Помилка PostgreSQL: перевірте приватний маршрут, пароль, TLS і доступ до обох баз — postgres та studiofs. Помилка створення бази може означати, що її потрібно попередньо підготувати з адміністратором.
Том уже існує в PostgreSQL: не запускайте destroy, навіть якщо текст помилки це пропонує. Це не звичайний крок повторної спроби. Якщо том уже створений і треба підключити інший комп’ютер, потрібен studiofs discover, описаний у главі 16.
Запит Do you want to CLEAR it and start fresh? [y/N]:: StudioFS знайшов локальний каталог метаданих і пропонує видалити його. Якщо не впевнені, що там лише непотрібний залишок невдалого тесту, натисніть Enter або введіть n. Значення y видаляє каталог, а не просто повторює перевірку.

Не розраховуйте, що будь-яка невдала ініціалізація автоматично скасує всі попередні дії. Уже могли з’явитися база, bucket, локальні файли або запис тому. Якщо фінального повідомлення немає, але ім’я вже зайняте чи виник запит очищення, збережіть знеособлений текст помилки й розберіться зі станом перед продовженням. Ручне видалення метаданих або створення іншого тому поверх того самого префікса — погана заміна діагностиці.

Коли команда успішно завершилася, повторювати init не потрібно. Том створено; у наступній главі підключимо його до файлової системи комп’ютера.

Зміст · English · ← Попередня · Наступна →