Руководство по ручной настройке

Процесс автоматической подготовки можно использовать для развертывания сервера тегов в App Engine всего за несколько кликов. Если вы хотите настроить сервер тегов в других средах, вы можете сделать это вручную. Сервер тегов — это сервер Node.js внутри образа Docker .

Для ручной подготовки сервера тегов требуется отдельная подготовка кластера тегов на стороне сервера (SST) и сервера предварительного просмотра. Кластер SST является точкой входа для всех запросов к серверу тегов и будет обрабатывать запросы, как описано в разделе Введение в тегирование на стороне сервера . Сервер предварительного просмотра необходим для предварительного просмотра контейнера.

На рисунке 1 показана иллюстрация взаимодействия данных между серверами тегов и сервером предварительного просмотра.

Рис. 1. Схема серверов тегов и потока данных сервера предварительного просмотра.

В этом руководстве объясняется, как:

• Просмотрите все доступные настройки образа Docker.
• (Необязательно) Включите учетные данные BigQuery.
• Вручную подготовьте сервер предварительного просмотра с помощью образа SST Docker.
• Подготовьте кластер SST вручную с помощью образа SST Docker.
• Убедитесь, что сервер предварительного просмотра и кластер SST настроены правильно.
• Обновляйте версию сервера тегов после подготовки сервера.

Чтобы запускать команды Docker в этом руководстве, вы должны сначала установить Docker на свой компьютер.

Примечание. Когда вы настраиваете свой сервер тегов, владелец серверной среды (будь то облачный провайдер или локальный) может иметь доступ к вашим данным. Дополнительные сведения см. в условиях обслуживания этой организации.

Посмотреть все доступные настройки образа Docker

Образ Docker сервера тегов можно найти по этому URL-адресу:

gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Сервер тегов и сервер предварительного просмотра используют один и тот же образ Docker с разными флагами. В этом разделе мы рассмотрим, как найти все доступные настройки, которые можно использовать с образом Docker.

Чтобы увидеть все доступные настройки, запустите с помощью инструмента командной строки docker следующее:

docker run gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable server_bin.js --help

(Необязательно) Включите учетные данные Google Cloud

Чтобы использовать BigQuery или Firestore API за пределами Google Cloud, вы должны предоставить учетные данные сервисного аккаунта, которым разрешен доступ к этим ресурсам.

1. Следуйте этому руководству , чтобы создать учетную запись службы с ролью редактора данных BigQuery для доступа к BigQuery или ролью пользователя облачного хранилища данных для доступа Firestore и экспортировать свои учетные данные JSON с именем файла local_service_account_key.json .
2. Смонтируйте учетные данные JSON в томе, доступном для образа. Используя docker run , вы можете указать -v local_service_account_key.json:/app/service_account_key.json для монтирования учетных данных в образе.
3. Укажите переменную среды GOOGLE_APPLICATION_CREDENTIALS на учетные данные.
4. При необходимости укажите идентификатор вашего проекта Google Cloud в переменной среды GOOGLE_CLOUD_PROJECT , чтобы сервер тегов неявно выбрал проект.

5. Запустите сервер. Следующая команда запускает сервер тегов с включенными учетными данными:

   docker run -v local_service_account_key.json:/app/service_account_key.json \
   -p 8080:8080 \
   -e GOOGLE_APPLICATION_CREDENTIALS='/app/service_account_key.json' \
   -e GOOGLE_CLOUD_PROJECT='<your project id>' \
   -e CONTAINER_CONFIG='<config string>' \
   gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable
   

В зависимости от того, в какой системе развернут сервер тегов, могут быть разные способы подключения учетных данных. Например, Kubernetes и Docker Swarm предоставляют руководства по управлению секретами. Дополнительную информацию см. в руководстве по соответствующей системе.

Обязательно следуйте рекомендациям по защите своих учетных данных.

Вручную подготовить сервер предварительного просмотра

Сервер предварительного просмотра позволяет просмотреть контейнер сервера. Чтобы запустить сервер предварительного просмотра, запустите образ Docker со следующими переменными среды , переданными в среду Docker.

Требуемые настройки

• CONTAINER_CONFIG — строка конфигурации для контейнера сервера. В Диспетчере тегов перейдите в рабочую область контейнера сервера и щелкните идентификатор контейнера в правом верхнем углу страницы. Нажмите «Подготовить сервер тегов вручную» , чтобы найти значение «Конфигурация контейнера» .

• RUN_AS_PREVIEW_SERVER — установите для этого параметра значение true , чтобы подготовить сервер в качестве сервера предварительного просмотра.

Пример использования инструмента командной строки Docker

Чтобы подготовить сервер предварительного просмотра локально, выполните следующее:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e RUN_AS_PREVIEW_SERVER=true gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Вы должны увидеть ответ 200 на запрос к http://localhost:8080/healthz . При необходимости используйте переменную среды PORT для изменения порта.

Лучшие практики

• Необходимо развернуть ровно 1 сервер предварительного просмотра. Не настраивайте автомасштабирование более чем на 1 экземпляр.
• После настройки сервера предварительного просмотра с помощью Docker настройте URL-адрес HTTPS, чтобы он указывал на сервер предварительного просмотра. Это необходимо для настройки кластера SST.
• Ваш балансировщик нагрузки или CDN должен иметь тайм-аут более 20 секунд, иначе режим предварительного просмотра не будет работать правильно.

Вручную подготовить кластер тегов на стороне сервера

Кластер SST служит точкой входа, передает запросы предварительного просмотра на сервер предварительного просмотра и обрабатывает все остальные запросы, как описано в разделе Введение в тегирование на стороне сервера . Используйте следующие обязательные параметры с образом Docker сервера тегов, чтобы подготовить кластер SST в любой среде, поддерживающей Docker.

Требуемые настройки

• CONTAINER_CONFIG — строка конфигурации для контейнера сервера. В Диспетчере тегов перейдите в рабочую область контейнера сервера и щелкните идентификатор контейнера в правом верхнем углу страницы. Нажмите «Подготовить сервер тегов вручную» , чтобы найти значение «Конфигурация контейнера» .

• PREVIEW_SERVER_URL — URL-адрес HTTPS для сервера предварительного просмотра. Этот параметр следует устанавливать только для подготовки сервера тегов и не требуется для подготовки сервера предварительного просмотра. См. раздел выше для руководства по настройке сервера предварительного просмотра.

Пример использования инструмента командной строки Docker

Чтобы настроить один сервер тегов локально, выполните следующее:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e PREVIEW_SERVER_URL='<HTTPS preview server url>' gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Вы должны увидеть ответ 200 на запрос к http://localhost:8080/healthz . При необходимости используйте переменную среды PORT для изменения порта.

Лучшие практики

• Серверы тегов на стороне сервера могут быть подготовлены либо как отдельный сервер, либо как кластер. Мы рекомендуем подготовить его как кластер для повышения доступности, масштабируемости и производительности. Обратите внимание, что при подготовке в качестве кластера каждый экземпляр сервера должен быть настроен с использованием одних и тех же переменных среды CONTAINER_CONFIG и PREVIEW_SERVER_URL .
• Обязательно укажите развертывание кластера SST на новый поддомен на вашем веб-сайте, который отделен от поддомена, который обслуживает ваше приложение. Например, если ваше приложение обслуживает веб-трафик по адресу example.com , используйте субдомен, такой как analytics.example.com, для сервера тегов.
• После настройки кластера SST с помощью Docker настройте URL-адрес HTTPS, чтобы он указывал на кластер SST.
• Обязательно периодически перезагружайте серверы, чтобы на них были установлены последние обновления кода для SST. Невыполнение этого требования может привести к несовместимости функций новых функций SST. Один из способов узнать, когда сервер необходимо перезагрузить, — это настроить проверки работоспособности, как описано ниже. Также обратите внимание, что любые опубликованные обновления контейнера вашего сервера будут по-прежнему применяться без перезагрузки.
• Используйте существующую конечную точку /healthz (например, https://analytics.example.com/healthz ) на ваших серверах тегов для настройки проверки жизнеспособности. Неработоспособный ответ указывает на необходимость перезапуска сервера.
• Контейнер Docker включает команду проверки работоспособности по умолчанию HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"] которая периодически запрашивает конечную точку /healthz . Если вы зависите от проверки работоспособности Docker, вы можете изменить настройки, следуя инструкциям Docker .
• Если сервер предварительного просмотра и сервер тегов находятся в одном источнике, разместите сервер предварительного просмотра по другому пути, чем сервер тегов. Укажите PREVIEW_SERVER_URL , включая путь.
• Подготовленные серверы должны иметь не более 1 виртуального ЦП. Дополнительные виртуальные ЦП не используются и негативно влияют на автомасштабирование.

Проверка

Настройте URL-адрес контейнера сервера

В Диспетчере тегов перейдите к контейнеру вашего сервера. В разделе «Администрирование» > «Настройки контейнера» введите URL-адрес сервера тегов в поле «URL-адрес контейнера сервера» и нажмите «Сохранить» .

Проверка в режиме предварительного просмотра

В рабочей области Диспетчера тегов просмотрите контейнер, нажав «Предварительный просмотр» , и убедитесь, что страница предварительного просмотра загружается. На другой вкладке браузера перейдите к любому пути в URL-адресе контейнера сервера. Если на странице предварительного просмотра отображается отправленный запрос, значит, все настроено правильно.

Если вы сопоставили несколько поддоменов с одним сервером тегов и хотите предварительно просмотреть каждый поддомен, добавьте дополнительные URL-адреса контейнеров серверов в разделе «Администрирование» > «Настройки контейнера» . Если указано несколько URL-адресов, все пути URL-адресов должны совпадать (строка информации, которая следует после имени домена). Например, предварительный просмотр доступен на example.com/abc и example2.com/abc , но недоступен на example.com/abc и example2.com/def . Если добавлено несколько URL-адресов, вы увидите значок рядом с кнопкой «Предварительный просмотр» , который позволяет выбрать URL-адрес для предварительного просмотра.

Обновите версию сервера тегов

Примечание. Если вы подготовили серверы тегов с помощью руководства по установке App Engine или руководства по установке Cloud Run , следуйте приведенным там инструкциям.

Образ gtm-cloud-image содержит Node.js и библиотеки, необходимые для работы сервера тегов. Образ Docker периодически обновляется для исправления безопасности и новых функций. Мы рекомендуем как минимум обновлять ваш сервер тегов для выпуска каждой основной версии (например, обновление с версии 1.xx до 2.xx).

Чтобы обновить образ Docker:

1. Получите текущую версию образа по gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable .
2. Разверните сервер с теми же настройками, что и при предыдущем развертывании.
3. Обновите один сервер предварительного просмотра и все серверы тегов в кластере .
4. Выключите все старые серверы.

Чтобы убедиться, что обновление прошло успешно:

1. В контейнере сервера нажмите кнопку Предварительный просмотр , чтобы начать новый сеанс отладки и отправить запрос на отдельной вкладке.
2. В сводке выберите вкладку Консоль и убедитесь, что нет сообщений с просьбой обновить сервер тегов.

Диспетчер тегов может отображать сообщения с просьбой обновить сервер тегов в течение дня после успешного обновления сервера. Однако на странице предварительного просмотра будет отображаться актуальное сообщение о версии сервера тегов.