Вкладка Secrets это зашифрованное хранилище для конфиденциальных значений конфигурации, которые нужны приложению на Node.js, таких как API-ключи, подписывающие секреты и токены сторонних сервисов, хранящихся отдельно для каждого окружения, чтобы ваши продакшн-учётные данные и тестовые учётные данные никогда не смешивались.
Где хранятся секреты
Откройте Веб-сайты, нажмите на сайт, откройте группу Environment в левом меню сайта и выберите Секреты. Вкладка называется Секреты.
Вкладка отображается только для сайтов на Node.js. WordPress, PHP и статические сайты её не показывают, потому что их конфигурация хранится в файлах на диске: wp-config.php для WordPress, и то, что читает ваш фреймворк, для обычного PHP-приложения.
Как защищены значения
Каждое значение шифруется до того, как попадёт в базу данных. Ничего не хранится в виде читаемого текста, и в списке никогда не показывается полное значение: отображается маска, в которой видны только последние четыре символа, чтобы вы могли отличить два похожих ключа друг от друга, не раскрывая ни один из них.
Каждая строка несёт пометку Encrypted как напоминание об этом. Чтение значения обратно это отдельное, осознанное действие, а не то, что происходит просто при открытии страницы.
Установка, раскрытие и удаление секрета требуют разрешения sites:write. Участник команды с доступом только для чтения может видеть, какие ключи существуют, и их маски, но не сами значения.
Два окружения
Сегментированный переключатель вверху страницы переключается между production и preview. Это полностью раздельные наборы ключей. Установка STRIPE_SECRET_KEY в production не создаёт его в preview, а удаление его из preview не затрагивает production.
В этом и заключается суть функции. Тестовые сборки (preview) это одноразовые окружения, которые может запустить любой, у кого есть доступ к репозиторию, поэтому в них должны находиться тестовые учётные данные, а не рабочие. См. Тестовые развёртывания для pull request'ов, чтобы узнать, как создаются тестовые окружения.
Добавление или обновление секрета
- Выберите окружение с помощью сегментированного переключателя.
- Введите имя в поле KEY_NAME. Поле автоматически переводит ввод в верхний регистр.
- Введите значение во втором поле. Оно маскируется по мере ввода.
- Нажмите Set.
Установка ключа, который уже существует, перезаписывает его. Отдельного действия для редактирования и шага подтверждения перезаписи нет, поэтому проверьте вкладку окружения перед тем, как нажать Set.
Правила имён ключей
Ключ должен начинаться с заглавной буквы и затем может содержать заглавные буквы, цифры и подчёркивания, до 128 символов. DATABASE_URL, API_KEY_V2 и SENTRY_DSN все допустимы. Всё остальное отклоняется с сообщением key должен быть UPPER_SNAKE_CASE с буквами/цифрами/подчёркиванием.
Стоит знать ещё два ограничения:
- Значение не может быть пустым. Отправка пустого значения вернёт value требуется.
- Значение не может превышать 16 КБ. Этого достаточно для токена, но недостаточно, например, для полной цепочки сертификатов, которой место в файле, а не в секрете.
Чтение значения обратно
Нажмите Copy в строке. KPanel расшифровывает значение на стороне сервера и сразу помещает его в буфер обмена, с подтверждением Значение скопировано в буфер обмена. Значение не выводится на экран, поэтому демонстрация экрана или подглядывающий через плечо не увидит его.
Каждое раскрытие значения записывается в журнал аудита сайта вместе с тем, кто это сделал и какой ключ использовался, и отображается в Журнале активности сайта.
Если вам нужно проверить, что значение верное, не раскрывая его, сравните маску вместо этого. Последних четырёх символов достаточно, чтобы подтвердить, что у вас правильный токен, и они уже отображаются на экране.
Использование секрета в вашем приложении
Скопируйте значение туда, откуда ваше приложение читает конфигурацию на сервере. Для приложения на Node.js это обычно переменная окружения, устанавливаемая вашим менеджером процессов, или файл .env в корне приложения, который ваш код загружает при запуске.
Не коммитьте этот файл в ваш репозиторий. Добавьте .env в .gitignore до того, как создадите его. Секрет, который был отправлен в удалённый git-репозиторий, нужно считать скомпрометированным и сменить у провайдера, потому что он остаётся в истории даже после удаления файла.
Вкладка Secrets это ваша запись о том, каким является значение, хранимая зашифрованной и под аудитом, а не заметка в менеджере паролей или в переписке. Держите её как единственный достоверный источник: когда вы меняете ключ у провайдера, обновляйте его здесь же, чтобы у следующего человека, выполняющего развёртывание, было актуальное значение.
Удаление секрета
Нажмите Delete в строке. KPanel попросит подтвердить с сообщением Delete API_TOKEN? и предупредит, что приложение потеряет доступ к этому значению при следующем перезапуске. Отмены нет, и копия не сохраняется, поэтому если значение может понадобиться снова, скопируйте его заранее.
Удаляйте секрет, когда соответствующая учётная запись была отозвана у провайдера, или когда код, который её использовал, был удалён. Если оставлять неактуальные ключи, позже будет сложнее понять, какие из них действительно важны.
Безопасная смена учётных данных
Безопасный порядок действий всегда такой: создайте новую учётную запись у провайдера, обновите её здесь, разверните приложение, убедитесь, что оно работает, а затем отзовите старую учётную запись у провайдера.
Если сделать это в обратном порядке, сначала отозвав старые данные, возникнет промежуток времени, когда работающее приложение будет использовать недействительную учётную запись, и каждый запрос, которому она нужна, будет завершаться ошибкой. Если изменение рискованное, сначала сделайте резервную копию, чтобы иметь возможность вернуться к заведомо исправному состоянию: см. Создание резервной копии.
Устранение неполадок
Вкладки Secrets нет в меню. Сайт не является сайтом на Node.js. Проверьте пометку стека рядом с именем сайта вверху страницы.
Кнопка Set ничего не делает. Оба поля обязательны. Кнопка показывает сообщение Требуется ключ и значение, если хотя бы одно из полей пустое.
Ключ был отклонён. Строчные буквы, дефисы, точки и пробелы не допускаются. api-key и Api_Key оба не проходят проверку; API_KEY проходит.
Copy ничего не скопировал в буфер обмена. Некоторые браузеры блокируют запись в буфер обмена на неактивной вкладке. Сначала щёлкните по странице, затем снова нажмите Copy.
Куда двигаться дальше
- Тестовые развёртывания для pull request'ов, вторая половина разделения на production и preview.
- Git-развёртывание для сайта для отправки кода, который читает эти значения.
- Журнал активности сайта, чтобы увидеть, кто установил, раскрыл или удалил секрет.