# Linux/VPS: постоянное хранение и закрытый сервис прав

Это шаблон размещения, а не отчёт о развёрнутом production-сервере.

## Разделение компонентов

Приложение аутентифицирует пользователя и формирует доверенный subject.
OpenFGA проверяет право. PostgreSQL хранит модель и отношения. Браузер не должен
получать служебный API key, URI базы или право произвольного writeTuples.

compose.production.example.yaml публикует только HTTP API на 127.0.0.1:18088.
Порты PostgreSQL, gRPC и Playground наружу не публикуются. Для приложения в той же
сети Compose можно обращаться к openfga:8080 без публикации порта вообще.

## Подготовка секретов

Создайте отдельный закрытый env-файл вне Git и public. Шаблон требует значения
POSTGRES_PASSWORD, OPENFGA_DATASTORE_URI и OPENFGA_API_KEY. Для локальной сети
Compose URI имеет вид
postgres://openfga:URL_ENCODED_PASSWORD@postgres:5432/openfga?sslmode=disable.
Отключение TLS для БД здесь относится только к выбранной изолированной сети
одного хоста. Для удалённой БД используйте TLS с проверкой сертификата.

```bash
sudo install -d -m 700 -o "$USER" /srv/openfga
install -m 600 /dev/null /srv/openfga/secrets.env
# Заполните файл своим способом управления секретами.
docker compose --env-file /srv/openfga/secrets.env \
  -p private-fga -f compose.production.example.yaml config --quiet
docker compose --env-file /srv/openfga/secrets.env \
  -p private-fga -f compose.production.example.yaml up -d
```

Обычный compose config без --quiet может показать раскрытые значения. Не копируйте
их в журналы. Переменные среды контейнера доступны администратору Docker;
такой доступ уже означает управление сервисом. Выберите хранилище секретов и
процедуру ротации под свою инфраструктуру.

Preshared-ключ идентифицирует сервисный клиент. Он не превращает его в конечного
пользователя и не ограничивает его вашими прикладными ролями. Здесь используется
простая конфигурация доверенного внутреннего клиента; для более сложного доступа
изучите поддерживаемые OpenFGA способы аутентификации и изоляции.

## Миграции перед запуском

В Compose PostgreSQL сначала становится healthy, затем migrate подготавливает
схему, затем OpenFGA стартует. Успех миграции проверяйте отдельно. Образ OpenFGA
закреплён версией и digest. Для PostgreSQL выбран 17.12-bookworm: выпуск 17.12
проверен по официальным release notes от 12 ноября 2026 года. Перед следующим
развёртыванием сверяйте исправления и повторяйте проверки миграции и восстановления.

## TLS и сетевой доступ

Если сервис прав расположен на отдельном хосте, поместите его за приватный
reverse proxy, ограничьте сетевой доступ и используйте HTTPS. Не заменяйте
Authorization на пустое значение при передаче запроса через прокси.

```nginx
server {
    listen 443 ssl;
    server_name fga.internal.example;
    ssl_certificate /etc/ssl/fga/fullchain.pem;
    ssl_certificate_key /etc/ssl/fga/privkey.pem;
    allow 10.20.0.0/16;
    deny all;
    location / {
        proxy_pass http://127.0.0.1:18088;
        proxy_set_header Host $host;
        proxy_connect_timeout 2s;
        proxy_read_timeout 5s;
    }
}
```

Домен, подсеть и пути — пример. Сертификат и DNS нужно настроить в вашей среде.
Не открывайте этот virtual host всему интернету, если архитектура не предполагает
такого доступа. SDK должен проверять TLS; отключение проверки сертификата не
является исправлением сетевой ошибки.

## Backup и восстановление

Сохраняйте резервную копию PostgreSQL, model ID, исходную модель, версию OpenFGA
и конфигурацию сервиса. Volume сам по себе не является backup. Для небольшого
стенда можно использовать pg_dump из закрытой сети, сохранив пароль в защищённом
pgpass-файле, а не в командной строке или history. Проверяйте восстановление в
отдельной БД, не поверх рабочего экземпляра.

Пример резервной копии для Linux выполняйте под оператором, которому разрешены
чтение закрытого env-файла и управление этим Compose. Каталог backup заранее
создайте с ограниченными правами. Пароль читается внутри контейнера; содержимое
env и дампа не выводится в терминал.

```bash
set -eu
umask 077
mkdir -p /srv/openfga/backups
backup_path="/srv/openfga/backups/fga-$(date -u +%Y%m%dT%H%M%SZ).dump"
docker compose --env-file /srv/openfga/secrets.env \
  -p private-fga -f compose.production.example.yaml exec -T postgres \
  sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' \
  > "$backup_path"
test -s "$backup_path"
sha256sum "$backup_path"
```

Ненулевой файл ещё не доказывает восстановление: проверьте код выхода pg_dump,
структуру архива через pg_restore --list и контрольный restore в отдельном
экземпляре PostgreSQL. Не запускайте автоматическое восстановление поверх
действующей базы. Дамп содержит полномочия пользователей: храните его закрыто.

Перед переходом на обновлённую версию восстановите копию, запустите миграцию и
положительные и отрицательные тесты политики. Старый model ID и связи нельзя
удалять раньше, чем все клиенты перестали от них зависеть. Возврат старого
бинарника после миграции БД не обязательно обеспечивает безопасный откат.

## Мониторинг

Наблюдайте задержки Check/ListObjects, таймауты, долю ошибок, готовность БД,
исчерпание пула и некорректные запросы к модели. Ответы allowed:false могут быть
нормальными; HTTP503 и подобные ошибки нужны для диагностики инфраструктуры.
Не сохраняйте служебный токен и полные документы в access logs. Приложение
должно иметь ограниченный таймаут и предсказуемое поведение при отказе проверки.
