ci: verify and deploy lab2
CI / verify (push) Failing after 2m24s
CI / verify (pull_request) Failing after 2m8s

This commit is contained in:
2026-09-24 10:15:43 +03:00
parent 57673f3e38
commit 9cafeff8dd
3 changed files with 338 additions and 17 deletions
+78
View File
@@ -0,0 +1,78 @@
name: CI
on:
pull_request:
branches: [main]
push:
branches: [main, solution/bvt2303-plastinin]
workflow_dispatch:
concurrency:
group: ci-${{ github.repository }}-${{ github.ref }}
cancel-in-progress: true
jobs:
verify:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
cache: true
- uses: actions/setup-python@v5
with:
python-version: "3.13"
- name: Check contract
run: make check
- name: Validate OpenAPI
run: |
python -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
- name: Check formatting
run: test -z "$(gofmt -l cmd internal migrations)"
- name: Lint
uses: golangci/golangci-lint-action@v6.5.2
with:
version: v2.13.2
args: --timeout=5m
- name: Unit tests and build
run: |
go test -race ./...
go build ./cmd/messenger
- name: Prepare local stack
run: |
cp lab2.env.example .env
./scripts/init-local-secrets.sh
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 120
- name: Public smoke
run: make test
- name: PostgreSQL and Valkey integration tests
run: docker compose --profile tests run --rm --build tests
- name: Dependency outage recovery
run: go run ./cmd/dependencycheck
- name: Persistence test
run: make test-persistence ACTION_SCRIPT=scripts/restart.sh
- name: Container logs
if: failure()
run: docker compose logs --no-color --tail=200
- name: Stop local stack
if: always()
run: docker compose --profile tests down -v --remove-orphans
+123
View File
@@ -0,0 +1,123 @@
name: Deploy production
on:
workflow_dispatch:
inputs:
confirmation:
description: Type DEPLOY to release main
required: true
concurrency:
group: production
cancel-in-progress: false
jobs:
deploy:
if: github.ref == 'refs/heads/main' && inputs.confirmation == 'DEPLOY'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
cache: true
- uses: actions/setup-python@v5
with:
python-version: "3.13"
- name: Verify release
run: |
make check
python -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
test -z "$(gofmt -l cmd internal migrations)"
go test -race ./...
go build ./cmd/messenger
- name: Lint
uses: golangci/golangci-lint-action@v6.5.2
with:
version: v2.13.2
args: --timeout=5m
- name: Verify release stack
run: |
cp lab2.env.example .env
./scripts/init-local-secrets.sh
docker compose up -d --build --wait --wait-timeout 120
make test
docker compose --profile tests run --rm --build tests
go run ./cmd/dependencycheck
make test-persistence ACTION_SCRIPT=scripts/restart.sh
- name: Stop release stack
if: always()
run: docker compose --profile tests down -v --remove-orphans
- name: Configure SSH
run: |
install -d -m 700 ~/.ssh
printf '%s\n' '${{ secrets.DEPLOY_SSH_KEY }}' > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
printf '%s\n' '${{ secrets.DEPLOY_KNOWN_HOSTS }}' > ~/.ssh/known_hosts
- name: Pack release
run: tar --exclude=.git --exclude=.env --exclude=secrets --exclude=.venv -czf /tmp/mtusi-lab2-${{ github.sha }}.tar.gz .
- name: Upload release
run: scp /tmp/mtusi-lab2-${{ github.sha }}.tar.gz '${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}:/tmp/'
- name: Deploy exact commit
env:
DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
RELEASE_SHA: ${{ github.sha }}
RELEASE_ATTEMPT: ${{ github.run_attempt }}
run: |
ssh "$DEPLOY_USER@$DEPLOY_HOST" sh -s -- "$RELEASE_SHA" "$RELEASE_ATTEMPT" <<'REMOTE'
set -eu
release_sha=$1
release_attempt=$2
deploy_root=/opt/mtusi-lab2
release_dir=$deploy_root/releases/$release_sha-$release_attempt
archive=/tmp/mtusi-lab2-$release_sha.tar.gz
mkdir -p "$deploy_root/releases" "$deploy_root/shared/backups"
exec 9>"$deploy_root/deploy.lock"
flock -x 9
previous=
previous_image=
if [ -L "$deploy_root/current" ]; then
previous=$(basename "$(readlink "$deploy_root/current")")
previous_image=$(cat "$deploy_root/current/.release-sha")
cd "$deploy_root/current"
docker compose -p mtusi-lab2 exec -T postgres sh -eu -c '
export PGPASSWORD="$(cat /run/secrets/postgres_password)"
pg_dump --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" --format custom
' > "$deploy_root/shared/backups/pre-$release_sha.dump"
fi
mkdir -p "$release_dir"
tar -xzf "$archive" -C "$release_dir"
printf '%s\n' "$release_sha" > "$release_dir/.release-sha"
ln -s "$deploy_root/shared/.env" "$release_dir/.env"
ln -s "$deploy_root/shared/secrets" "$release_dir/secrets"
cd "$release_dir"
if ! API_IMAGE="mtusi-messenger:$release_sha" docker compose -p mtusi-lab2 up -d --build --wait --wait-timeout 120; then
if [ -n "$previous" ]; then
cd "$deploy_root/releases/$previous"
API_IMAGE="mtusi-messenger:$previous_image" docker compose -p mtusi-lab2 up -d --wait --wait-timeout 120
fi
exit 1
fi
ln -sfn "$release_dir" "$deploy_root/current"
rm -f "$archive"
REMOTE
+137 -17
View File
@@ -1,37 +1,157 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Пластинин Денис, БВТ2303
- Целевая оценка: 5; трек 2 «План запроса и восстановление»
- Ветка: `solution/bvt2303-plastinin`; ссылка на PR указывается при публикации
- Основные библиотеки: pgx v5, valkey-go, x/crypto/argon2, Prometheus client_golang
- Источники: документация PostgreSQL по [транзакциям](https://www.postgresql.org/docs/current/tutorial-transactions.html) и [EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html), документация [Valkey persistence](https://valkey.io/topics/persistence/), [RFC 7617](https://www.rfc-editor.org/info/rfc7617/)
- Помощь ИИ: применялась для анализа задания и проверки реализации; команды и наблюдаемые результаты проверены локально
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Требуются Docker с Compose, `make`, Python 3.9 или новее для преподавательских тестов. Go на хосте для обычного запуска не требуется. Версии основных образов закреплены: Go 1.26.5, Alpine 3.24.2, PostgreSQL 17.6, Valkey 8.1.4, Swagger UI 5.31.2.
```sh
cp lab2.env.example .env
./scripts/init-local-secrets.sh
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 120
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
API доступен на `http://localhost:8080`, Swagger UI — на `http://localhost:8081`. Миграции встроены в бинарник и выполняются при запуске до начала приёма запросов. Повторное применение уже записанной версии сверяет checksum и не создаёт объекты повторно.
Собственные integration-тесты запускаются отдельным профилем:
```sh
docker compose --profile tests run --rm --build tests
```
Мониторинг не входит в обязательный путь запуска и включается явно:
```sh
docker compose --profile monitoring up -d
```
После запуска Prometheus доступен на `http://localhost:9090`, Grafana — на `http://localhost:3000`. Пользователь Grafana — `admin`, пароль хранится только в `secrets/grafana_admin_password`. Дашборд `Highload / Messenger overview` создаётся автоматически.
Безопасная остановка сохраняет именованные volumes:
```sh
docker compose --profile monitoring down
```
Намеренное удаление всех локальных учебных данных выполняется отдельно:
```sh
docker compose --profile monitoring down -v
```
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```mermaid
flowchart LR
C[HTTP client] --> A[Go API]
A --> P[(PostgreSQL)]
A --> V[(Valkey AOF)]
S[Swagger UI] --> A
M[Prometheus] --> A
M --> PE[PostgreSQL exporter]
M --> VE[Valkey exporter]
G[Grafana] --> M
```
PostgreSQL является источником истины для пользователей, чатов, участников и сообщений. Внешние ключи не позволяют сообщению ссылаться на отсутствующий чат, пользователя вне чата или удалённое членство. `username` защищён уникальным ограничением базы, поэтому конкурентные запросы не могут создать дубликаты.
Valkey хранит только сессии. Клиент получает 32 случайных байта в виде opaque Base64URL-токена, а в ключе Valkey используется SHA-256 токена. Значение содержит ID пользователя и срок действия. На ключ устанавливается TTL; logout удаляет ключ. Включены AOF и `appendfsync everysec`, поэтому штатный перезапуск сохраняет сессии. При аварийной остановке граница потери последних изменений AOF составляет примерно одну секунду.
Пароли хешируются Argon2id с отдельной случайной солью. Basic принимается только на `POST /api/v1/auth/sessions`. Бизнес-ручки принимают Bearer; `X-User-Id` не участвует в аутентификации и не меняет пользователя. Неверный, истёкший или отозванный токен приводит к `401`. Ошибка PostgreSQL или Valkey приводит к `503`, а не к анонимному обходу проверки.
Создание чата состоит из проверки участников, вставки чата и вставки всех членств в одной транзакции. Любая ошибка вызывает rollback. Все SQL-запросы параметризованы. Пул ограничен переменными `DB_MIN_CONNS` и `DB_MAX_CONNS`, установка соединения и проверки зависимостей имеют таймауты.
История сообщений использует keyset pagination по `(created_at, id)`. Cursor содержит позицию последней строки, тип ресурса и область чата; сервер проверяет его целостность и принадлежность текущему запросу. Запрос использует индекс `(chat_id, created_at, id)` и не пересчитывает полный offset для каждой страницы.
Преподавательский `.env.example` сохранён без изменений. Рабочее соответствие параметров находится в `lab2.env.example`: `SESSION_STORE=valkey`, пути Docker secrets задаются Compose, `SESSION_TTL_SECONDS` задаёт срок сессии, `DB_MIN_CONNS`/`DB_MAX_CONNS` ограничивают пул, `DEPENDENCY_TIMEOUT_SECONDS` ограничивает подключение и каждую операцию с зависимостями.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| Критерий README | Команда или сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Публичный smoke | `make test` | `PASS: lab2 public API scenario` | `evidence/lab2-verification.txt` |
| Сохранение данных и сессии | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | API, PostgreSQL и Valkey перезапущены; старый токен и подтверждённое сообщение сохранились | `evidence/lab2-verification.txt` |
| Миграции и повторный запуск | повторные сборки и перезапуски API на том же volume | checksum миграции совпал, схема не продублировалась, readiness вернулся в `200` | `evidence/lab2-verification.txt` |
| Гонка username | `docker compose --profile tests run --rm --build tests` | из 8 конкурентных вставок успешна одна, остальные получили conflict | `internal/postgres/store_integration_test.go` |
| Rollback чата | тот же integration suite | неизвестный участник дал `ErrInvalidMembers`, число чатов не изменилось | `internal/postgres/store_integration_test.go` |
| TTL и logout | integration suite и `make test` | сессия исчезла после TTL; после logout запрос и повторный logout дали `401` | `internal/session/session_integration_test.go` |
| Неверный пароль и отказ зависимостей | `go test -race ./internal/messenger` | неверный пароль — `401`; ошибки PostgreSQL и Valkey — `503` | `internal/messenger/server_test.go` |
| Реальный отказ зависимостей | `go run ./cmd/dependencycheck` | поочерёдный stop PostgreSQL/Valkey дал `503`; после up восстановились readiness и старый токен | `evidence/lab2-verification.txt` |
| Индекс истории | Go-эксперимент, 100 000 сообщений, `EXPLAIN (ANALYZE, BUFFERS)` | составной индекс: 0,069 мс и 0 отфильтрованных строк; глобальный индекс: 0,597 мс и 1900 отфильтрованных строк | `evidence/lab2-track2.json` |
| Стоимость записи | 5 повторов `CopyFrom` по 10 000 строк, медиана | без вторичного индекса 309 172 строк/с; составной 286 011 строк/с; снижение около 7,5% | `evidence/lab2-track2.json` |
| Backup и restore | `./scripts/backup-restore.sh` | восстановление в `messenger_restore` за 1 с; counts, memberships и digest полей сообщений совпали | `evidence/lab2-backup-restore.txt` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
## Эксперимент с планом запроса
## Эксперименты и отказы
Гипотеза: индекс `(chat_id, created_at, id)` ускорит keyset pagination в небольшом чате относительно индекса `(created_at, id)`, потому что PostgreSQL сможет сразу ограничить диапазон конкретным `chat_id`. Цена улучшения — дополнительное обслуживание более широкого индекса при записи и место на диске.
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Эксперимент выполнен Go-программой `cmd/lab2experiment`. Среда обезличена: контейнер `linux/arm64`, Go 1.26.5, лимит 2 CPU. Создано 100 000 синтетических сообщений в 20 чатах с распределением 60 000, 20 000, 10 000 и от 588 до 592 сообщений в остальных чатах. Времена сообщений разных чатов чередуются, поэтому глобальный индекс не получает преимущества от последовательной загрузки одного чата.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
Проверялся запрос страницы из 100 сообщений после cursor в середине одного из небольших чатов. Для каждого варианта индекс пересоздавался, выполнялся `ANALYZE`, затем сохранялся полный JSON-план `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)`.
| Вариант | Execution time | Строк отброшено фильтром | Shared blocks hit/read |
| --- | ---: | ---: | ---: |
| `(chat_id, created_at, id)` | 0,069 мс | 0 | 6 / 4 |
| `(created_at, id)` | 0,597 мс | 1900 | 1994 / 19 |
В данной точке составной индекс быстрее примерно в 8,7 раза. Причина видна в плане: он сразу выбирает диапазон одного чата, а глобальный индекс идёт по общей временной шкале и проверяет `chat_id` для чужих сообщений.
Стоимость записи измерялась отдельно. Для каждого варианта таблица создавалась заново, пять раз загружалось по 10 000 одинаково сформированных строк, в отчёт взята медиана.
| Вариант | Медиана | Производительность | Размер вторичного индекса |
| --- | ---: | ---: | ---: |
| без вторичного индекса | 0,0323 с | 309 172 строк/с | 0 |
| `(chat_id, created_at, id)` | 0,0350 с | 286 011 строк/с | 991 232 байта |
| `(created_at, id)` | 0,0350 с | 285 326 строк/с | 425 984 байта |
Составной индекс выбран для приложения: потеря около 7,5% в синтетической пакетной записи компенсируется существенным ускорением основной операции чтения истории. Эти числа относятся к прогретой локальной среде, короткому запуску и 100 000 строк; они показывают направление и не являются производственным SLA.
## Backup, восстановление и отказы
`scripts/backup-restore.sh` создаёт временный backup PostgreSQL в custom format, создаёт новую базу `messenger_restore`, выполняет `pg_restore`, затем сравнивает counts пользователей, чатов, членств и сообщений. Для десяти выбранных сообщений сравнивается digest полей `id`, `chat_id`, `sender_id`, `text` и `created_at`. Dump удаляется после проверки и не попадает в Git.
В проверенном запуске восстановлены 35 пользователей, 9 чатов, 17 членств и 8 сообщений; digest совпал, полное время сценария составило 1 секунду. RPO равен моменту snapshot, который видит `pg_dump`: транзакции, зафиксированные после начала snapshot, не входят в этот backup. RTO в 1 секунду относится к малому учебному набору; с ростом объёма он увеличится.
| Воздействие | Ожидаемое поведение | Наблюдение | Восстановление и потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| штатный restart API, PostgreSQL и Valkey | readiness временно недоступен, затем старые данные и токен читаются | persistence-тест прошёл | автоматическое восстановление; подтверждённые данные не потеряны |
| недоступен PostgreSQL | readiness и операции с данными возвращают `503` | реальный контейнер остановлен; после запуска прежний токен снова сработал | после возврата БД; анонимный доступ не разрешается |
| недоступен Valkey | readiness и Bearer-аутентификация возвращают `503` | реальный контейнер остановлен; после запуска AOF восстановил прежний токен | после возврата Valkey; запрос не считается аутентифицированным |
| истёк TTL или logout | токен возвращает `401` | integration и public smoke прошли | повторный login создаёт новую сессию |
| restore из backup | новая БД содержит снимок исходной | counts, memberships и message digest совпали | 1 с на учебном наборе; RPO равен snapshot |
## CI/CD и мониторинг
`.gitea/workflows/ci.yml` запускается для PR в `main`, push в solution/main и вручную. Он проверяет контракт, OpenAPI, форматирование, golangci-lint, race unit-тесты, сборку, public smoke, реальные PostgreSQL/Valkey integration-тесты и persistence.
Production deployment вынесен в `.gitea/workflows/deploy.yml`. Gitea 1.27 не поддерживает обязательное подтверждение environment, поэтому подтверждением служит ручной `workflow_dispatch` со строкой `DEPLOY`. Workflow разрешает только ветку `main` и для exact SHA повторяет OpenAPI, lint, race, smoke, integration, реальный dependency outage и persistence. После зелёных проверок он делает backup, создаёт release-каталог по SHA и номеру попытки и выполняет health check. Для включения требуются repository secrets `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`; на сервере заранее создаются `/opt/mtusi-lab2/shared/.env` и `/opt/mtusi-lab2/shared/secrets`.
Профиль monitoring собирает метрики без пользовательских ID и raw URL в labels. Дашборд содержит RPS, классы HTTP-ответов, p95, in-flight, Go heap, соединения и транзакции PostgreSQL, размер БД, память, ключи и команды Valkey. Мониторинг не участвует в readiness приложения.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Стенд содержит одну API-реплику. Горизонтальное масштабирование и idempotency появляются в лабораторной 3.
- Локальный HTTP не шифруется. На сервере Basic и Bearer должны передаваться только через TLS reverse proxy; это будет частью эксплуатационной защиты последующих лабораторных.
- Valkey AOF `everysec` сохраняет сессии при штатном рестарте, но допускает потерю примерно последней секунды при аварии процесса или узла.
- PostgreSQL `COMMIT` подтверждает фиксацию согласно `synchronous_commit`, `fsync` и надёжности диска. Он не заменяет внешние backup и репликацию.
- Exporters в локальном профиле используют учебные credentials сервисов. Для production следует создать отдельного пользователя PostgreSQL с ролью `pg_monitor` и ограничить сетевой доступ к Prometheus/Grafana.
- Эксперимент измеряет один запрос и короткие локальные серии. Для production нужны длительные прогоны, несколько объёмов данных, холодный cache, конкурентное чтение и запись.
## Ответы на вопросы защиты
`COMMIT` делает изменения транзакции видимыми как единое целое и фиксирует их согласно настройкам durability PostgreSQL. Гарантия пережить отказ зависит от `fsync`, `synchronous_commit`, WAL и физического хранилища.
Сессии находятся в Valkey. TTL удаляет истёкшие ключи, logout удаляет ключ немедленно. AOF сохраняет их при рестарте; `FLUSHDB` удалит сессии, после чего клиенты должны войти заново.
Аутентификация отвечает на вопрос, кто выполняет запрос: Bearer-токен связывается с пользователем. Авторизация дополнительно проверяет членство пользователя в конкретном чате. Валидная сессия не даёт доступ к чужому чату.
Argon2id намеренно медленный и требует память, поэтому усложняет перебор паролей. Быстрый checksum предназначен для обнаружения случайного изменения данных и не подходит для хранения паролей.