Як самостійно розгорнути Gitea у 2026 році: репозиторії, SSH і безпечне оновлення

Якщо ви вже намагалися самостійно розгорнути Gitea, вам, імовірно, знайома ця неприємна ситуація: інтерфейс відкривається, але ROOT_URL генерує localhost-посилання для клонування або SSH-порт не проброшено. Повторне створення контейнера рідко усуває розбіжність між URL-адресами, станом і залежностями.

У цьому посібнику використано один конкретний критерій готовності — клонувати через HTTPS і SSH, виконати push коміту та LFS-об’єкта, відкрити issue і запустити одне завдання на окремо зареєстрованому Actions runner. Кожне конфігураційне рішення оцінюється за цим критерієм, а не за зеленим індикатором контейнера.

Знайдіть кожен важливий байт у Gitea

До створення першого реального запису перелічіть увесь стан: репозиторії, LFS-об’єкти, вкладення, конфігурацію та базу даних. Підключіть /data до початкового налаштування, запишіть безпечні тестові дані та замініть контейнер, щоб переконатися, що цей шлях справді зберігає дані. Перевірте монтування: запишіть безпечні тестові дані, замініть Gitea і прочитайте їх знову.

Снапшоти цінні для швидкого відкату, але коли хост або том зникає, потрібна незалежна резервна копія. Відновіть дані в порожньому середовищі з зафіксованим образом і перевірте, що репозиторії успішно проходять fsck, LFS-об’єкти завантажуються, а issues, релізи та дозволи користувачів відповідають стану до створення резервної копії. Використовуйте постійні томи та снапшоти, щоб розділяти ці два механізми відновлення.

Створіть контейнер Gitea, який можна замінити

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

docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v gitea-data:/data \
  -e GITEA__security__SECRET_KEY=replace-with-a-long-random-value \
  gitea/gitea:latest

До відкриття ingress перевірте фактичні змінні середовища, монтування та listener. Для більш завантаженої інсталяції додайте перевірені параметри підключення до Postgres або MySQL і маршрут SSH, якщо він потрібен; для приватних сервісів використовуйте приватні імена. Успішний запуск завершується тоді, коли ви можете клонувати через HTTPS і SSH, виконати push коміту та LFS-об’єкта, відкрити issue і запустити одне завдання на окремо зареєстрованому Actions runner, а не тоді, коли docker ps виводить Up.

Відокремте Gitea від її залежностей

Стан процесу та стан продукту для Gitea — різні речі. Порт 3000 може відповідати, тоді як користувацька транзакція все одно завершується помилкою. Мережева угода Gitea передбачає Postgres або MySQL для більш завантаженої інсталяції та маршрут SSH, якщо він потрібен. Залишайте приватні кінцеві точки у внутрішньому DNS, дозволяйте лише необхідні вихідні підключення та надайте Gitea обмежені права сервісного облікового запису.

Виконуйте цю перевірку готовності після суттєвих змін конфігурації: клонування через HTTPS і SSH, push коміту та LFS-об’єкта, створення issue і запуск одного завдання на окремо зареєстрованому Actions runner. Не включайте дорогі зовнішні перевірки до liveness-проб, щоб збій у провайдера не спричинив цикл перезапусків. Під час роботи з місткістю відстежуйте кількість репозиторіїв, пакування Git-об’єктів, LFS-сховище, затримку бази даних і навантаження runner, а не звичайні запити сторінок — це краще відображає реальне навантаження Gitea.

TLS — це просто, а генеровані URL — ні

Опублікуйте Gitea за одним HTTPS-хостом, а необроблений порт 3000 залиште приватним. Встановіть ROOT_URL і SSH_DOMAIN на адреси, які користувачі фактично використовують для клонування. Це не дасть браузерам і API-клієнтам дізнатися про дві конкуруючі адреси.

Із чистого клієнта виконайте перевірену транзакцію та визначте перший запит, який завершується помилкою. Якщо проблема в DNS або TLS, скористайтеся посібником із користувацьких доменів. Розглядайте проблему «ROOT_URL генерує localhost-посилання для клонування або SSH-порт не проброшено» як окрему діагностику застосунку після підтвердження маршруту.

Перевірте розгортання Gitea наскрізь

Не використовуйте трафік першого користувача як acceptance-тест для Gitea. Підготуйте безпечний тестовий стан і виконайте повну дію «клонувати через HTTPS і SSH, виконати push коміту та LFS-об’єкта, відкрити issue і запустити одне завдання на окремо зареєстрованому Actions runner». Зафіксуйте точну публічну URL-адресу, результат, посилання на образ і інтервал журналу, пов’язані з цим запуском.

Замініть контейнер і повторіть перевірку без повторного створення даних. Потім відновіть систему на порожньому хості; умовою відновлення є те, що репозиторії успішно проходять fsck, LFS-об’єкти завантажуються, а issues, релізи та дозволи користувачів відповідають стану до створення резервної копії. Під час кожного проходу спостерігайте за кількістю репозиторіїв, пакуванням Git-об’єктів, LFS-сховищем, затримкою бази даних і навантаженням runner, а не за звичайними запитами сторінок, і створіть alert на основі погіршення транзакції, а не простою метрик контейнера.

Одна фінальна перевірка має навмисно завершитися помилкою: тимчасово забороніть тестовій ідентичності доступ до Postgres або MySQL для більш завантаженої інсталяції та до маршруту SSH, якщо він потрібен. Переконайтеся, що отримане повідомлення Gitea визначає відповідну межу, а не запускає видалення даних чи нескінченний перезапуск. Відновіть правильну умову та підтвердьте, що та сама тестова транзакція знову виконується успішно. Додайте цю коротку вправу до release checklist.

Відпрацюйте ризиковану зміну Gitea

Для Gitea відстежуйте транзакцію, а не процес: клонування через HTTPS і SSH, push коміту та LFS-об’єкта, створення issue і запуск одного завдання на окремо зареєстрованому Actions runner. Поєднуйте її затримку та частоту помилок із кількістю репозиторіїв, пакуванням Git-об’єктів, LFS-сховищем, затримкою бази даних і навантаженням runner, а не зі звичайними запитами сторінок, щоб alert визначав компонент, який став вузьким місцем.

Репетиція оновлення має враховувати, що міграції схеми, repository hooks, пакети та сторонні runner потребують поетапного оновлення Gitea. Відновіть дані, виконайте міграцію та запустіть транзакцію до заміни production-інсталяції. Якщо ROOT_URL генерує localhost-посилання для клонування або SSH-порт не проброшено, не стирайте дані заради зеленого статусу запуску; послідовно порівняйте версію, змінні, монтування та доступність залежностей.

Захистіть найціннішу частину Gitea

Після першого входу перевірте, що можуть робити анонімний відвідувач, звичайний користувач і адміністратор. Проблема Gitea, якої слід уникати, — залишити installer або перший обліковий запис адміністратора доступними довше, ніж потрібно. Запланована політика — закрити installer після початкового налаштування, обмежити адміністрування сайту та зробити токени реєстрації runner короткоживучими.

Використовуйте GITEA__security__SECRET_KEY відповідно до її ролі в Gitea: зберігайте чутливі значення поза Git, документуйте наслідки ротації й ніколи не підставляйте публічний приклад у production. Розділяйте облікові записи залежностей і людей, де можливо забороняйте невикористовуваний egress і обмежуйте роботу, на яку впливають кількість репозиторіїв, пакування Git-об’єктів, LFS-сховище, затримка бази даних і навантаження runner, а не звичайні запити сторінок.

Що Dockup має автоматизувати для Gitea

Для Gitea Dockup може створити маршрут і TLS-сертифікат, зберегти монтування, доставити секрети та розмістити Postgres або MySQL для більш завантаженої інсталяції і маршрут SSH, якщо він потрібен, у приватній мережі, розгортаючи систему в Dockup або на підключених серверах.

Критерієм для релізу все одно залишається конкретна транзакція Gitea: клонування через HTTPS і SSH, push коміту та LFS-об’єкта, створення issue і запуск одного завдання на окремо зареєстрованому Actions runner. Також перевірте умову відновлення — репозиторії успішно проходять fsck, LFS-об’єкти завантажуються, а issues, релізи та дозволи користувачів відповідають стану до створення резервної копії. Ці дві перевірки показують, чи працює розгортання і чи можна його відновити.

Поширені запитання

Що потрібно Gitea для production-розгортання?

Спрямуйте контейнер Gitea на порту 3000 через один HTTPS-origin. Мережева вимога для залежностей — Postgres або MySQL для більш завантаженої інсталяції та маршрут SSH, якщо він потрібен. Не вважайте Gitea готовою, доки не зможете клонувати через HTTPS і SSH, виконати push коміту та LFS-об’єкта, відкрити issue і запустити одне завдання на окремо зареєстрованому Actions runner.

Які дані Gitea потрібно включити до резервної копії?

Зберігайте /data і включіть репозиторії, LFS-об’єкти, вкладення, конфігурацію та базу даних до одного маніфесту відновлення. Відновлення Gitea можна вважати успішним лише тоді, коли репозиторії проходять fsck, LFS-об’єкти завантажуються, а issues, релізи та дозволи користувачів відповідають стану до створення резервної копії.

Чи потрібен Gitea HTTPS за reverse proxy?

Використовуйте HTTPS для публічного origin Gitea, а порт 3000 залиште у внутрішньому маршруті. Правильно застосуйте параметри Gitea: встановіть ROOT_URL і SSH_DOMAIN на адреси, які користувачі фактично використовують для клонування. Для Gitea HTTPS захищає облікові дані або користувацький вміст під час передавання та забезпечує узгоджену поведінку клієнтів, чутливу до origin.

Як тестувати оновлення Gitea?

Відновіть поточний стан Gitea в ізольованому розгортанні, застосуйте кандидатну версію та повторіть acceptance-транзакцію. Зверніть особливу увагу: міграції схеми, repository hooks, пакети та сторонні runner потребують поетапного оновлення Gitea. Зберігайте попередній образ Gitea, доки не зрозумієте межі міграції даних і відкату.