Українська
Активація релізу
Крок 1. Що має гарантувати «активація»
Навіщо. Реліз надходить у /opt/chatex/incoming/<sha>. Перетворення його на працюючу версію – найделікатніший момент усього конвеєра, і воно має бути безпечним, навіть коли щось іде не так:
- користувачі ніколи не повинні бачити недокопійовану чи змішану версію;
- базу даних треба змігрувати до запуску нового коду, якому потрібна нова схема;
- версія, що не запускається, не має лишатися робочою;
- повернення до старішої версії має бути однією командою;
- диск не повинен заповнюватися старими релізами.
Chatex розв’язує це розташуванням папок з теми 23 – повні релізи поруч і символічне посилання current – та одним скриптом Bash, що працює на сервері від імені root, chatex-activate. Рис. 24.2 показує, що він робить.
Рис. 24.2. Активація релізу з відкатом
Крок 2. Скрипт
Що зробити. На своєму комп’ютері створіть скрипт у папці Deploy:
bash
#!/usr/bin/env bash
# Activates a Chatex release on the production server.
#
# Install once as root (see Docs/Deployment.md):
# install -o root -g root -m 755 Deploy/activate-release.sh /usr/local/bin/chatex-activate
# The deploy workflow connects as root (Docs/Deployment.md) and calls it through sudo, which also works for a
# dedicated deploy user allowed only this command in sudoers. Keep it root-owned and outside anything that user
# can write, otherwise sudo on it would grant root.
#
# Usage: chatex-activate <git sha>
# - If /opt/chatex/incoming/<sha> exists (uploaded by the deploy workflow), it becomes
# /opt/chatex/releases/<sha>.
# - Otherwise /opt/chatex/releases/<sha> must already exist: this is how you roll back.
# Then it runs the database migrations, switches /opt/chatex/current, restarts the API and checks
# /health. If the API does not come up, it switches back to the previous release.
set -euo pipefail
readonly ROOT=/opt/chatex
readonly INCOMING="$ROOT/incoming"
readonly RELEASES="$ROOT/releases"
readonly CURRENT="$ROOT/current"
readonly ENV_FILE=/etc/chatex/chatex.env
readonly SERVICE=chatex-api
readonly HEALTH_URL=http://127.0.0.1:5000/health
readonly KEEP_RELEASES=5
log() { printf '[chatex-activate] %s\n' "$*"; }
fail() { log "error: $*" >&2; exit 1; }
[[ $EUID -eq 0 ]] || fail "must run as root"
[[ $# -eq 1 ]] || fail "usage: chatex-activate <git sha>"
readonly SHA="$1"
[[ $SHA =~ ^[0-9a-f]{7,40}$ ]] || fail "not a git sha: $SHA"
readonly SRC="$INCOMING/$SHA"
readonly DST="$RELEASES/$SHA"
PREVIOUS="$(readlink -f "$CURRENT" 2>/dev/null || true)"
readonly PREVIOUS
# 1. Move the upload into releases/ and make it read-only for the service user.
if [[ -d $SRC ]]; then
if [[ $PREVIOUS == "$DST" ]]; then
# A re-run of the same commit: keep the running files, just restart below.
rm -rf "$SRC"
log "$SHA is already installed and running"
else
rm -rf "$DST"
mv "$SRC" "$DST"
log "installed $DST"
fi
elif [[ -d $DST ]]; then
log "no upload for $SHA, re-activating the existing release"
else
fail "neither $SRC nor $DST exists"
fi
chown -R root:chatex "$DST"
chmod -R u=rwX,go=rX "$DST"
chmod 755 "$DST/efbundle"
[[ -f $DST/api/Chatex.Api.dll ]] || fail "$DST/api/Chatex.Api.dll is missing"
[[ -f $DST/web/index.html ]] || fail "$DST/web/index.html is missing"
# 2. Migrate. Migrations run while the old release still serves traffic, so they must stay
# compatible with it. Rolling back does not undo migrations.
# The env file uses systemd syntax, so read the value instead of sourcing it (';' would split).
CONNECTION="$(grep -m1 '^ConnectionStrings__Chatex=' "$ENV_FILE" | cut -d= -f2- || true)"
CONNECTION="${CONNECTION#\"}"
CONNECTION="${CONNECTION%\"}"
[[ -n $CONNECTION ]] || fail "ConnectionStrings__Chatex is not set in $ENV_FILE"
log "applying migrations"
"$DST/efbundle" --connection "$CONNECTION"
# 3. Switch the symlink atomically and restart.
switch_to() {
ln -sfn "$1" "$CURRENT.tmp"
mv -T "$CURRENT.tmp" "$CURRENT"
systemctl restart "$SERVICE"
}
healthy() {
local _
for _ in $(seq 1 30); do
if curl --fail --silent --max-time 2 "$HEALTH_URL" > /dev/null; then
return 0
fi
sleep 1
done
return 1
}
log "switching to $SHA"
switch_to "$DST"
if ! healthy; then
if [[ -n $PREVIOUS && -d $PREVIOUS && $PREVIOUS != "$DST" ]]; then
log "health check failed, rolling back to $(basename "$PREVIOUS")"
switch_to "$PREVIOUS"
fi
journalctl -u "$SERVICE" -n 50 --no-pager >&2 || true
fail "$SHA did not pass the health check"
fi
log "$SHA is live"
# 4. Clean up: leftover uploads and all but the newest releases (never the running one).
find "$INCOMING" -mindepth 1 -maxdepth 1 -type d -mmin +60 -exec rm -rf {} +
# Release folder names are hex SHAs, so parsing ls output is safe here.
# shellcheck disable=SC2012
ls -1dt "$RELEASES"/*/ | tail -n +$((KEEP_RELEASES + 1)) | while read -r old; do
old="${old%/}"
if [[ $old != "$DST" ]]; then
rm -rf "$old"
log "removed old release $(basename "$old")"
fi
doneЗаголовок документує встановлення й використання. Далі йдуть частини скрипта.
Суворий режим, константи й аргумент
set -euo pipefail– «суворий режим» Bash:-eзупиняє скрипт на першій невдалій команді,-uтрактує незадану змінну як помилку, а не порожній рядок,-o pipefailзмушує конвеєр завершуватися невдачею, якщо збій у будь-якій його частині, а не лише в останній. Без нього після невдалогоmvбадьоро перезапускався б реліз, якого немає.- Константи
readonlyназивають усі шляхи, службу, URL перевірки стану й кількість релізів для збереження в одному місці. logіfailдрукують із префіксом[chatex-activate];failпише в стандартний потік помилок і завершується з кодом 1, що робить крок робочого процесу червоним.[[ $EUID -eq 0 ]]– скрипт змінює власників, перезапускає служби й видаляє папки; він відмовляється працювати від імені будь-кого, крімroot.[[ $SHA =~ ^[0-9a-f]{7,40}$ ]]– аргумент має виглядати як хеш коміту: від 7 до 40 шістнадцяткових символів нижнього регістру. Це перевірка безпеки, а не формальність: значення стає частиною шляхів, що видаляються черезrm -rf. Аргумент на кшталт../../etcдо цього ніколи не дійде.PREVIOUSзапам’ятовує, куди зараз указуєcurrent, як повний шлях релізу, для відкату.|| trueне даєset -eзупинити скрипт, коли посилання ще немає.
1. Переміщення вивантаженого до releases/
Є чотири випадки:
- Вивантаження існує, і його реліз уже працює – повторний запуск того самого коміту, наприклад через Run workflow. Працюючі файли зберігаються, вивантаження видаляється, а скрипт іде далі до міграції та перезапуску.
- Вивантаження існує – звичайний випадок. Старішу папку з тією самою назвою видаляють, а вивантаження переміщують до
releases/.mvу межах однієї файлової системи – це перейменування: миттєве, ніколи не напівзавершене. - Вивантаження немає, але реліз існує – відкат вручну:
chatex-activate <older sha>повторно активує збережений реліз. - Нічого немає – помилка.
Потім реліз робиться доступним лише для читання для служби: chown -R root:chatex віддає його root із групою chatex, а chmod -R u=rwX,go=rX дозволяє root писати, а всім іншим лише читати (велика X додає біт виконання до папок, яким він потрібен для входу, але не до звичайних файлів). efbundle знову отримує 755, бо він має бути виконуваним, а вивантаження надходить без бітів виконання. Нарешті дві перевірки адекватності: реліз без api/Chatex.Api.dll або web/index.html відхиляється, перш ніж щось зміниться.
2. Міграція бази даних
- Рядок підключення береться з
/etc/chatex/chatex.env. Скрипт не виконуєsourceдля файлу: він записаний у синтаксисі systemd, а не оболонки, і;усередині рядка підключення розбило б його на кілька команд оболонки.grep -m1бере перший рядок із ключем,cut -d= -f2-– усе після першого=, а два розкриття параметрів прибирають необов’язкові лапки. "$DST/efbundle" --connection "$CONNECTION"застосовує міграції, яких база даних ще не має, і виводить їх. Під час першого розгортання він створює всю схему; пізніше зазвичай виводитьNo migrations were applied. The database is already up to date.
Міграції виконуються, поки старий реліз ще обслуговує користувачів. Тому міграція має лишатися сумісною з попереднім кодом: додавайте стовпець як nullable або зі значенням за замовчуванням, перейменовуйте за два релізи (додайте новий, скопіюйте, а старий видаліть пізніше). Це шаблон розширення–стиснення (expand–contract). Зворотне теж правда, і коментар скрипта каже про це прямо: відкат не скасовує міграцій. Попередній реліз має вміти працювати на новішій схемі.
3. Перемикання й перевірка стану
switch_toстворює нове посилання під тимчасовою назвоюcurrent.tmpі перейменовує його поверхcurrentчерезmv -T. Перейменування в Linux атомарне: у кожну митьcurrentуказує або на старий, або на новий реліз, ніколи на ніщо. (ln -sfnбезпосередньо наcurrentвидалив би й створив посилання заново – дві операції з проміжком між ними.) Потім він перезапускає службу, і systemd запускаєcurrent/api– новий код.healthyзвертається доhttp://127.0.0.1:5000/healthдо 30 разів, раз на секунду.curl --failтрактує503 Unhealthyяк збій,--max-time 2не дає завислому запиту заблокувати цикл. API відповідаєHealthyлише тоді, коли запустилося і може дістатися бази даних (тема 5), тож перевірка охоплює хибні налаштування, відсутню бібліотеку й зламаний рядок підключення однаково. Запит іде безпосередньо до Kestrel із хостом127.0.0.1, томуAllowedHostsйого містить.- Якщо перевірка не пройшла, скрипт перемикається назад на
PREVIOUSі перезапускає стару версію – але лише якщо попередній реліз є й це не та сама папка. Потім він виводить останні 50 рядків журналу служби, які зазвичай містять причину, і завершується невдачею. Новий реліз лишається вreleases/для огляду.
4. Прибирання
find "$INCOMING" … -mmin +60 -exec rm -rf {} +видаляє вивантаження, старші за годину, – залишки розгортань, перерваних між вивантаженням і активацією.ls -1dt "$RELEASES"/*/ | tail -n +$((KEEP_RELEASES + 1))перелічує релізи від найновішого й пропускає перші п’ять; кожен старший видаляється – крім активного релізу, який ніколи не видаляється. П’ять релізів – це п’ять можливих відкатів.
Невдале перше розгортання
Під час самого першого розгортання current ще не існує, але readlink -f усе одно виводить шлях, який він мав би, /opt/chatex/current. Якщо цей перший реліз не пройде перевірку стану, скрипт повідомить health check failed, rolling back to current і залишить current посиланням, що вказує на себе. Нічого іншого не пошкоджено: API не працювало раніше й не працює після. Наступне розгортання робочого релізу замінить посилання. (Вправа 2 контрольної точки виправляє цей крайній випадок.)
Крок 3. Встановлення скрипта
Навіщо. Скрипт працює від імені root, тож змінити його, не будучи root, має бути неможливо: він лежить у /usr/local/bin, належить root і розташований поза всіма папками, куди пише розгортання. Тому ж копія всередині кожного релізу ніколи не виконується.
Що зробити. Закомітьте скрипт і надішліть його:
powershell
git add Deploypowershell
git commit -m "Add the release activation script"powershell
git pushНа сервері, в папці chatex:
bash
git pullbash
cp Deploy/activate-release.sh /usr/local/bin/chatex-activate && chmod 755 /usr/local/bin/chatex-activate/usr/local/bin входить до PATH, тож команда тепер доступна як chatex-activate.
Перевірка
Нехай Bash розбере скрипт, не виконуючи його:
bash
bash -n /usr/local/bin/chatex-activateВідсутність виводу означає відсутність синтаксичних помилок. Потім викличте його без аргумента і з хибним аргументом:
bash
chatex-activate[chatex-activate] error: usage: chatex-activate <git sha>bash
chatex-activate 12345[chatex-activate] error: not a git sha: 12345ls -l /usr/local/bin/chatex-activate показує -rwxr-xr-x 1 root root.
Як це тестувалося
Скрипт, файл служби й сайт Nginx цього модуля запускали в контейнері Ubuntu 26.04 із пакетами з теми 23: перше розгортання, повторний запуск того самого коміту, відкат вручну, реліз зі відсутньою бібліотекою – відкочений через 30 секунд із помилкою у виведеному журналі – і шість розгортань поспіль, після яких лишилося рівно п’ять релізів.