forked from mtusi2026/mtusi2026lab2
Вернул потерянный infra/README.md
This commit is contained in:
+233
@@ -0,0 +1,233 @@
|
||||
# Инфраструктура лабораторной 2
|
||||
|
||||
Рабочая топология описана в корневом [docker-compose.yml](../docker-compose.yml). API собирается из исходников проекта
|
||||
по [Dockerfile](../Dockerfile). Этот каталог содержит эксплуатационное описание решения; конфигурации сервисов остаются
|
||||
в корне репозитория.
|
||||
|
||||
[compose.example.yaml](../compose.example.yaml) — учебный worksheet,
|
||||
а [contracts/infrastructure.json](../contracts/infrastructure.json) — требования к ролям. Для запуска используется
|
||||
именно docker-compose.yml. Подробные инструкции подготовки окружения и описание реализации находятся
|
||||
в [REPORT.md](../REPORT.md).
|
||||
|
||||
## Сервисы и топология
|
||||
|
||||
| Роль | Service name | Образ / версия | Healthcheck / readiness | Постоянное хранилище | Сеть и порты | Credentials |
|
||||
|--------------------------|--------------|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
|
||||
| HTTP API | `api` | Локальная сборка `mtusi-messenger:lab2`; builder `golang:1.27.2-alpine3.23`, runtime `alpine:3.23.6` | Docker healthcheck вызывает `/health/ready`; обработчик проверяет HTTP-сервер и PING PostgreSQL с бюджетом 200 мс | Прикладные данные находятся в PostgreSQL; `./certs` смонтирован в `/run/certs` только для чтения | Внутри `0.0.0.0:8080`; на хосте `127.0.0.1:${HOST_PORT:-8080}` | Подключения к хранилищам из env; RSA-ключи из bind mount; клиентские запросы — Basic при входе и Bearer после входа |
|
||||
| Источник истины | `postgres` | `postgres:17.11-alpine3.23` | `pg_isready` по TCP localhost с заданными пользователем и БД | `postgres_data:/var/lib/postgresql/data` | `postgres:5432` внутри сети, порт на хост не опубликован | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`; Compose получает имя БД из `POSTGRES_DATABASE` |
|
||||
| Необязательный кэш чатов | `redis` | `redis:8.2.11-alpine3.22` | Аутентифицированный `redis-cli PING`, ожидается `PONG` | `redis_data:/data`; AOF включён | `redis:6379` внутри сети, порт на хост не опубликован | `REDIS_PASSWORD`; сервер запущен с `--requirepass`, API использует пользователя `default` и выбранную Redis DB |
|
||||
|
||||
Compose создаёт проектную bridge-сеть `<project>_default`; сервисы обращаются друг к другу по именам `postgres` и
|
||||
`redis`. Отдельная сеть с `internal: true` не настроена. Именованные volumes получают префикс проекта:
|
||||
`<project>_postgres_data` и `<project>_redis_data`. В стандартном запуске контейнер API явно называется `api`.
|
||||
|
||||
PostgreSQL обязателен: `depends_on` API ожидает его `service_healthy` при запуске. Redis в `depends_on` API не включён;
|
||||
ошибка стартового PING логируется, приложение продолжает работать через PostgreSQL. Его реквизиты подключения всё равно
|
||||
должны присутствовать в конфигурации.
|
||||
|
||||
API работает от UID/GID `65532:65532`. Политика перезапуска всех трёх сервисов — `unless-stopped`. Время штатной
|
||||
остановки контейнера: API 10 секунд, PostgreSQL 60 секунд, Redis 30 секунд; HTTP graceful shutdown по умолчанию
|
||||
ограничен 8 секундами.
|
||||
|
||||
### Health и готовность
|
||||
|
||||
- `/health/live` возвращает состояние HTTP-процесса и не проверяет хранилища.
|
||||
- `/health/ready` возвращает 200 при работающем HTTP-сервере и доступном PostgreSQL; при отказе БД — 503. Redis не
|
||||
влияет на readiness.
|
||||
- Docker healthcheck API выполняется каждые 10 секунд, timeout 3 секунды, start period 5 секунд, retries 3.
|
||||
- Healthcheck PostgreSQL выполняется каждые 5 секунд, timeout 3 секунды, start period 30 секунд, retries 12.
|
||||
- Healthcheck Redis выполняется каждые 5 секунд, timeout 3 секунды, start period 5 секунд, retries 12. Пароль передаётся
|
||||
redis-cli через `REDISCLI_AUTH` внутри контейнера, его значение в вывод не включается.
|
||||
|
||||
Версии базовых образов закреплены тегами в Dockerfile и Compose. Тег собственного образа `mtusi-messenger:lab2`
|
||||
обновляется при локальной сборке. ID образа, на котором прошла приёмка уровней 3/4:
|
||||
`sha256:0effe11ab9f4d860b5b79d6096ff95325336c752c0d5ca335878ec89baf4f269`. Это идентификатор проверенной сборки, а не
|
||||
утверждение о текущем содержимом локального тега или registry digest. Commit, SHA-256 исходников и параметры того
|
||||
прогона находятся в [summary.json](../evidence/levels-3-4/summary.json).
|
||||
|
||||
## Окружение и ключи
|
||||
|
||||
Все команды ниже выполняются **из корня репозитория**. Нужны Docker Compose v2 с поддержкой `--wait`, OpenSSL и Make;
|
||||
для проверок также Python 3.9+. На Linux для показанной настройки доступа к ключам нужна утилита `setfacl`.
|
||||
|
||||
На первом запуске создать локальный `.env` из [.env.example](../.env.example), не перезаписывая существующий:
|
||||
|
||||
```sh
|
||||
umask 077
|
||||
cp -n .env.example .env
|
||||
```
|
||||
|
||||
Перед запуском заменить оба password-placeholder на разные локальные пароли PostgreSQL и Redis. В REPORT.md
|
||||
приведена [инструкция](../REPORT.md) автоматической генерации `.env` без вывода паролей. Оставить
|
||||
`POSTGRES_RUN_MIGRATIONS=true`. Для стандартного Compose использовать `POSTGRES_HOST=postgres`, `REDIS_HOST=redis`,
|
||||
внутренние порты 5432/6379 и `APP_PORT=8080`. `HOST_PORT` меняет только порт API на хосте; целевой порт публикации
|
||||
закреплён на 8080.
|
||||
|
||||
На чистом окружении создать ключи подписи JWT:
|
||||
|
||||
```sh
|
||||
umask 077
|
||||
if [ ! -e certs/private_key.pem ] && [ ! -e certs/public_key.pem ]; then
|
||||
make key-gen
|
||||
fi
|
||||
test -f certs/private_key.pem && test -f certs/public_key.pem
|
||||
chmod 600 certs/private_key.pem
|
||||
chmod 644 certs/public_key.pem
|
||||
```
|
||||
|
||||
Команда генерирует пару только при отсутствии обоих файлов. Если сохранилась только одна часть, сначала нужно восстановить согласованную пару; автоматически перезаписывать оставшуюся часть нельзя. Повторно генерировать уже используемую пару при обычном запуске или рестарте не нужно: прежние сессии требуют прежнего
|
||||
ключа проверки подписи. Ключи не являются TLS-сертификатами; локальный API использует HTTP.
|
||||
|
||||
На Linux предоставить контейнерному UID чтение файлов и доступ к каталогу:
|
||||
|
||||
```sh
|
||||
setfacl -m u:65532:rx certs
|
||||
setfacl -m u:65532:r certs/private_key.pem certs/public_key.pem
|
||||
```
|
||||
|
||||
На Docker Desktop отображение прав зависит от файлового backend. Проверка чтения из контейнера приведена в разделе
|
||||
запуска. Приватный ключ не требуется делать общедоступным. В `.env` задаются контейнерные пути
|
||||
`/run/certs/private_key.pem` и `/run/certs/public_key.pem`; bind mount доступен только для чтения, а
|
||||
`create_host_path: false` не позволяет незаметно создать отсутствующий каталог.
|
||||
|
||||
`.env`, каталог `certs/`, локальные `secrets/`, данные и volumes исключены из Git правилами [.gitignore](../.gitignore).
|
||||
Пароли передаются через environment контейнеров; Docker secrets в этом Compose не используются. Не сохранять полный
|
||||
вывод `docker compose config` или credentials в отчёт; для проверки конфигурации достаточно `config --quiet`.
|
||||
|
||||
### Основные параметры
|
||||
|
||||
| Настройка | Значение и поведение |
|
||||
|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `POSTGRES_RUN_MIGRATIONS`, `POSTGRES_VERSION_TABLE` | `true`, `versions` в примере; включают миграции API и учёт их версии |
|
||||
| `POSTGRES_MAX_CONNECTIONS` | Максимум соединений пула API, по умолчанию 10 |
|
||||
| `POSTGRES_CONNECT_TIMEOUT` | По умолчанию 500 мс |
|
||||
| `POSTGRES_QUERY_TIMEOUT` | По умолчанию 2 секунды; контекст бизнес-запроса и statement_timeout соединений приложения |
|
||||
| `SESSION_TTL_SECONDS` | Положительное целое число секунд; в примере 3600. Имеет приоритет над legacy `JWT_REFRESH_TOKEN_LIFETIME`; при отсутствии обеих переменных — 3600 секунд |
|
||||
| `REDIS_DB` | По умолчанию 0; ключи кэша находятся в выбранной DB |
|
||||
| Таймауты Redis | Dial/read/write/pool по 200 мс; отдельный бюджет GET/SET/PING 300 мс; повторы команд отключены |
|
||||
| `APP_READ_TIMEOUT`, `APP_WRITE_TIMEOUT`, `APP_IDLE_TIMEOUT` | По умолчанию 5, 10 и 60 секунд |
|
||||
|
||||
Параметры Compose и содержимое `.env.example` не заменяют настройки уже существующего хранилища. Например, замена
|
||||
`POSTGRES_PASSWORD` в `.env` не меняет пароль роли, ранее созданной в сохранённом PostgreSQL volume. При повторном
|
||||
использовании данных сохранять согласованные реквизиты, имя БД и ключи JWT.
|
||||
|
||||
## Bootstrap и повторный запуск
|
||||
|
||||
На новом volume entrypoint PostgreSQL создаёт роль и БД из environment. Схему приложения создаёт API:
|
||||
SQL-миграции [service/migrations](../service/migrations) встроены в бинарник через `go:embed` и применяются Tern до
|
||||
запуска HTTP-сервера. Отдельного SQL-bootstrap в Compose нет.
|
||||
|
||||
Пять миграций создают `users`, `refresh_tokens`, `chats`, `chat_members`, `messages`, ограничения и индексы. Таблица
|
||||
`versions` хранит версию Tern. При повторном запуске применяются только ещё не выполненные миграции; данные не
|
||||
пересоздаются и не заполняются повторно. Обычный старт не создаёт экспериментальные fixtures. При ошибке миграции API
|
||||
завершает запуск с ошибкой. Отключать миграции на пустом volume нельзя, если схема не подготовлена отдельно.
|
||||
|
||||
Redis запускается с `appendonly yes` и `appendfsync everysec`. Отдельного bootstrap кэша нет: первый доступный участнику
|
||||
GET чата читает PostgreSQL и сохраняет `chat:<UUID>` в Redis. Значение содержит метаданные и MemberIDs. Чат хранится без
|
||||
TTL; обязательный API не меняет состав участников. При добавлении таких изменений потребуется инвалидация, чтобы
|
||||
кэшированная проверка доступа не устаревала.
|
||||
|
||||
Сессии находятся в PostgreSQL, поэтому Redis не является единственным хранилищем аутентификации. Ошибки чтения/записи
|
||||
кэша обходятся через PostgreSQL. AOF и volume позволяют сохранять кэш при проверенном корректном stop/start, но не
|
||||
заменяют backup PostgreSQL и не доказывают сохранность при потере питания.
|
||||
|
||||
Собрать API, проверить доступ к ключам и запустить сервисы:
|
||||
|
||||
```sh
|
||||
docker compose --env-file .env config --quiet
|
||||
docker compose --env-file .env build api
|
||||
docker compose --env-file .env run --rm --no-deps --entrypoint sh api \
|
||||
-c 'test -r /run/certs/private_key.pem && test -r /run/certs/public_key.pem'
|
||||
docker compose --env-file .env up -d --no-build --wait --wait-timeout 120
|
||||
curl --fail --silent --show-error http://127.0.0.1:8080/health/live
|
||||
curl --fail --silent --show-error http://127.0.0.1:8080/health/ready
|
||||
docker compose --env-file .env ps -a
|
||||
```
|
||||
|
||||
При изменённом `HOST_PORT` заменить порт в curl. Повторный `up` использует прежние volumes. После изменения исходников
|
||||
нужна новая сборка API; после изменения environment — пересоздание соответствующего контейнера, а не только `start`.
|
||||
|
||||
Выборочные логи приложения:
|
||||
|
||||
```sh
|
||||
docker compose --env-file .env logs --tail 100 api
|
||||
```
|
||||
|
||||
## Перезапуск, проверки отказов и остановка
|
||||
|
||||
[Restart-hook](../scripts/restart.sh) сначала проверяет конфигурацию и собирает API, затем останавливает API,
|
||||
пересоздаёт PostgreSQL и Redis с прежними volumes, ждёт healthchecks и пересоздаёт API. Ключи и `.env` должны быть
|
||||
подготовлены заранее; hook их не генерирует и volumes не удаляет.
|
||||
|
||||
Обычный полный перезапуск:
|
||||
|
||||
```sh
|
||||
./scripts/restart.sh
|
||||
```
|
||||
|
||||
Hook поддерживает `COMPOSE_ENV_FILE` (по умолчанию `.env`), `COMPOSE_OVERRIDE_FILE` (дополнительный файл при наличии) и
|
||||
стандартный `COMPOSE_PROJECT_NAME`. Для параллельных стендов одного project name недостаточно: override должен также
|
||||
заменить фиксированное имя контейнера API, опубликованный порт и bind mount ключей. Это реализовано
|
||||
в [автоматизированном runner](../scripts/verify_lab2.py).
|
||||
|
||||
Публичные проверки выполняют реальные операции с синтетическими данными указанного стенда:
|
||||
|
||||
```sh
|
||||
make check
|
||||
make test BASE_URL=http://127.0.0.1:8080
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
|
||||
```
|
||||
|
||||
Проверить все критерии на отдельном проекте, сохраняя новый прогон отдельно от уже приложенных доказательств:
|
||||
|
||||
```sh
|
||||
python3 scripts/verify_lab2.py --port 18084 --output evidence/levels-3-4-repeat
|
||||
```
|
||||
|
||||
Runner создаёт собственные ключи, пароли и volumes, проверяет миграции, полный рестарт, expiry и отказы. В конце
|
||||
проверочный проект останавливается без удаления volumes; основной стенд на 8080 не перезапускается.
|
||||
|
||||
Для отдельной проверки отказа Redis используются команды ниже. Между stop и start авторизованный GET должен
|
||||
обслуживаться из PostgreSQL. После start дождаться готовности Redis и повторить запрос; действительный Bearer-токен не
|
||||
следует сохранять в журналы команд или evidence.
|
||||
|
||||
```sh
|
||||
docker compose --env-file .env stop redis
|
||||
docker compose --env-file .env start redis
|
||||
```
|
||||
|
||||
При остановленном PostgreSQL действующая сессия получает 503, анонимный и неверный Bearer — 401; readiness возвращает
|
||||
503, liveness остаётся 200. После восстановления БД прежняя сессия продолжает работать. Подробная безопасная проверка
|
||||
этого сценария выполняется runner на отдельном стенде.
|
||||
|
||||
Обычная остановка всего проекта сохраняет volumes и локальные ключи:
|
||||
|
||||
```sh
|
||||
docker compose --env-file .env down
|
||||
```
|
||||
|
||||
**Намеренный сброс учебных данных:** следующая команда удаляет оба именованных volume текущего проекта, включая
|
||||
пользователей, сообщения, сессии и кэш. Она не используется в restart-hook и не является обычным перезапуском:
|
||||
|
||||
```sh
|
||||
docker compose --env-file .env down --volumes
|
||||
```
|
||||
|
||||
При потере ключей JWT записи сессий в PostgreSQL сами по себе недостаточны для проверки ранее подписанных токенов.
|
||||
Volumes и ключи нужно сохранять согласованно. Backup → restore, потеря диска, HA и многорепличный failover не входят в
|
||||
проведённые исследования этой инфраструктуры.
|
||||
|
||||
## Подтверждённые результаты
|
||||
|
||||
- [Приёмка уровней 3/4](../evidence/levels-3-4/README.md): 16 групп PASS; собственный стенд, версии и image ID,
|
||||
ограничения, миграции, pool/SQL timeouts, история 20 001 сообщений с EXPLAIN, expiry и отказы.
|
||||
- [Реальный вывод check/smoke/persistence](../evidence/levels-3-4/checks.txt)
|
||||
и [summary.json](../evidence/levels-3-4/summary.json): IDs всех трёх контейнеров до/после перезапуска и сохранённые
|
||||
volumes.
|
||||
- [Демонстрация кэша и отказа Redis](../evidence/redis-cache.md)
|
||||
и [эксперимент stampede](../evidence/cache-stampede/README.md): результаты предшествующих сборок с их собственными
|
||||
параметрами и ограничениями.
|
||||
- [Полный отчёт](../REPORT.md): реализация, соответствие критериям, запуск и границы проведённых проверок.
|
||||
|
||||
Эта инструкция основана на текущих конфигурационных файлах и сохранённых результатах. При её оформлении сервисы не
|
||||
запускались и не перезапускались, новые тесты не добавлялись.
|
||||
Reference in New Issue
Block a user