a.tolmachev
143 lines
4.7 KiB
Markdown
143 lines
4.7 KiB
Markdown
# Runtime Config
|
||
|
||
## 1. Назначение документа
|
||
|
||
Этот документ фиксирует конфигурацию окружения, storage и базовые operational assumptions для MVP.
|
||
|
||
Его задача - убрать неявные решения, которые обычно всплывают уже в процессе написания кода.
|
||
|
||
## 2. Базовые решения для MVP
|
||
|
||
- каноническая БД: `PostgreSQL`
|
||
- допустимый упрощенный режим разработки: `SQLite`
|
||
- artifact storage: локальная файловая система
|
||
- MCP transport: `Streamable HTTP`
|
||
- admin API и mcp-server запускаются как отдельные приложения
|
||
|
||
## 3. Artifact storage
|
||
|
||
В MVP sample JSON, `.proto`, `descriptor set` и YAML import payload должны храниться в локальном файловом storage.
|
||
|
||
Требования:
|
||
|
||
- все файлы кладутся в контролируемый базовый каталог;
|
||
- в БД хранится только `storage_ref`;
|
||
- структура каталогов должна быть детерминированной;
|
||
- storage слой должен быть абстрагирован, чтобы потом заменить его на S3-compatible backend.
|
||
|
||
Рекомендуемая структура:
|
||
|
||
```text
|
||
var/mcpaas/
|
||
samples/
|
||
descriptors/
|
||
yaml-imports/
|
||
```
|
||
|
||
## 4. Секреты и auth profiles
|
||
|
||
Для MVP:
|
||
|
||
- operation хранит только `auth_profile_ref`;
|
||
- auth profile хранит только `secret_ref`;
|
||
- реальные секреты не должны попадать в YAML export;
|
||
- секреты не должны логироваться.
|
||
|
||
Допустимые варианты secret storage:
|
||
|
||
- env-backed secret store;
|
||
- encrypted local secret storage.
|
||
|
||
Минимальный безопасный вариант для MVP:
|
||
|
||
- `secret_ref` указывает на env variable alias или key в локальном secret store;
|
||
- приложение резолвит его на runtime.
|
||
|
||
## 5. Переменные окружения
|
||
|
||
Минимально ожидаются:
|
||
|
||
- `MCPAAS_DATABASE_URL`
|
||
- `MCPAAS_STORAGE_ROOT`
|
||
- `MCPAAS_ADMIN_BIND`
|
||
- `MCPAAS_MCP_BIND`
|
||
- `MCPAAS_LOG_LEVEL`
|
||
- `MCPAAS_SECRET_PROVIDER`
|
||
- `MCPAAS_PUBLIC_BASE_URL`
|
||
- `MCPAAS_MCP_PUBLIC_URL`
|
||
|
||
Опционально:
|
||
|
||
- `MCPAAS_ADMIN_TOKEN`
|
||
- `MCPAAS_MASTER_KEY`
|
||
|
||
## 6. Логирование и трассировка
|
||
|
||
Для MVP нужно использовать:
|
||
|
||
- structured logging через `tracing`;
|
||
- correlation id для test runs и runtime execution;
|
||
- раздельные стадии ошибок: schema, mapping, adapter, external service.
|
||
|
||
## 7. Таймауты и retries
|
||
|
||
Рекомендуемые стартовые значения:
|
||
|
||
- default timeout: `10s`
|
||
- retry default: `1` attempt, то есть без автоматического повтора
|
||
|
||
Причина:
|
||
|
||
- сначала важнее детерминированность и прозрачность;
|
||
- aggressive retries могут маскировать реальные ошибки интеграции.
|
||
|
||
## 8. Режимы запуска
|
||
|
||
Минимально нужны два режима:
|
||
|
||
- local development
|
||
- demo/deployment
|
||
|
||
Local development:
|
||
|
||
- `SQLite` допустим;
|
||
- локальный storage;
|
||
- упрощенная auth-модель admin-api.
|
||
|
||
Demo/deployment:
|
||
|
||
- `PostgreSQL`;
|
||
- локальный или сетевой storage;
|
||
- включенная auth-защита admin-api;
|
||
- стабильный `Streamable HTTP` endpoint для MCP.
|
||
- containerized runtime через `Docker` и `docker-compose`.
|
||
|
||
## 8.1. Delivery artifacts
|
||
|
||
Для production-like запуска проект должен поставляться с:
|
||
|
||
- `Dockerfile` для backend приложений;
|
||
- `docker-compose.yml`;
|
||
- `.env.example`;
|
||
- healthcheck endpoints;
|
||
- reverse proxy configuration examples.
|
||
|
||
Подробности вынесены в `docs/deployment.md`.
|
||
|
||
## 9. Что важно не допустить
|
||
|
||
- пути к storage, зашитые в код;
|
||
- секреты в `.yaml` exports;
|
||
- разные конфигурационные модели для local и production без причины;
|
||
- смешивание runtime config и business config operation.
|
||
|
||
## 10. Практический итог
|
||
|
||
До старта разработки должны быть приняты как минимум такие решения:
|
||
|
||
- где лежит БД;
|
||
- где лежат artifacts;
|
||
- как резолвятся `secret_ref`;
|
||
- на каких bind-address запускаются `admin-api` и `mcp-server`;
|
||
- какой transport использует MCP server.
|