Cloudflare Turnstile не проходит серверную проверку: диагностика

Token Turnstile короткоживущий и одноразовый. Его нельзя проверять поздно, использовать дважды или спутать secret разных environments. За reverse proxy также легко передать неправильный remote IP.

Сохраните error-codes и метаданные проверки без самого token и secret. Сопоставьте sitekey на странице с secret на сервере и временем между выдачей token и submit.

Что проверить в первую очередь

Для ситуации «виджет Turnstile выдаёт token, но сервер отклоняет проверку» сначала зафиксируйте один воспроизводимый пример: время, идентификатор объекта, пользователя или операции, входные данные, версию приложения и фактический результат. Отдельно запишите ожидаемое поведение: сервер отправляет свежий одноразовый token на siteverify с правильным secret, проверяет success, hostname и action и корректно сообщает пользователю о повторе. Не меняйте сразу несколько настроек: один контролируемый шаг должен подтверждать или исключать одну гипотезу.

Начинайте с чтения состояния и журналов. До массового перерасчёта, повторной отправки, удаления записей или изменения прав подготовьте резервную копию и способ отката. Секреты, токены, персональные данные и содержимое документов в диагностические выгрузки не включайте.

• Проверьте environment pair sitekey-secret.
• Сверьте имя поля response.
• Уточните TTL и повтор submit.
• Проверьте hostname и action.

Почему возникает проблема

Видимый симптом обычно появляется в конце цепочки. Первичная ошибка может находиться в API, фоновой задаче, кеше, очереди, базе, правах доступа или внешнем сервисе. Основной риск этого сценария: легитимные формы не отправляются или разработчики временно отключают защиту, открывая путь автоматическому спаму. Поэтому ручная правка итогового статуса часто временно скрывает проблему, но не устраняет причину.

Разбирайте события по хронологии и ищите первую точку расхождения с бизнес-правилом. Учитывайте повтор запроса, задержку события, параллельное выполнение и восстановление после временного отказа: именно в этих условиях проявляются ошибки согласованности и идемпотентности.

• Используется secret другого виджета.
• Token уже проверен.
• Frontend отправляет устаревшее значение.
• Сервер неверно разбирает JSON siteverify.

Пошаговая диагностика

Создайте безопасный тестовый сценарий, который не затрагивает реальные списания, рассылки и клиентские данные. Назначьте операции единый correlation ID и проследите его через запрос, бизнес-логику, базу, очередь и внешние интеграции. Для каждого этапа сохраните вход, результат, код ответа, длительность и версию записи.

Сравните рабочий и ошибочный случаи по одним полям. Проверьте формат идентификаторов, часовой пояс, порядок событий, права сервисной учётной записи и актуальность конфигурации на каждом экземпляре. Если результат зависит от повтора, задержки или конкретного узла, это важная часть причины, а не случайность.

• Запишите error-codes.
• Проверьте server time.
• Сравните production и test keys.
• Проследите один request ID до siteverify.

Как выполнять server-side проверку

Решение принимает сервер после прямого запроса siteverify; наличие token на клиенте само по себе ничего не доказывает.

Надёжная реализация хранит бизнес-состояние явно. У каждого значимого действия есть стабильный идентификатор, владелец, версия правила и проверяемый переход статуса. Повторная доставка события не создаёт второе действие, а запоздавший ответ не возвращает объект в невозможное состояние.

• Secret хранится только на сервере.
• Token проверяется один раз сразу.
• Hostname и action входят в policy.
• Ошибка допускает безопасный новый challenge.

Как исправить проблему

Разделите исправление кода и восстановление исторических данных. Сначала устраните подтверждённую первопричину, затем повторите исходный сценарий и только после этого готовьте контролируемую коррекцию записей. Для финансовых данных, прав и аудита предпочтительны компенсирующие действия, а не переписывание истории.

Для существующих записей сформируйте dry-run: объект, старое значение, предлагаемое новое значение и основание. Обновление должно быть идемпотентным, ограниченным точной выборкой и создавать отчёт. Любой временный обход ограничьте сроком, пользователями и областью действия.

• Исправьте mapping keys по environment.
• Обновляйте widget после неуспешной отправки.
• Валидируйте ответ siteverify.
• Настройте trusted proxy chain для IP.

Безопасный порядок внедрения

• Сохраните конфигурацию, связанные записи и необходимые журналы; отдельно проверьте реальное восстановление резервной копии.
• Воспроизведите проблему на тестовом объекте и сохраните результат до изменения для последующего сравнения.
• Внесите минимальное изменение под контролем версий, опишите причину, ожидаемый эффект и точный откат.
• Проверьте нормальный сценарий, ошибочный ввод, повтор запроса, параллельную операцию и временный отказ зависимости.
• Выпустите изменение на ограниченную долю трафика или один процесс, если архитектура это позволяет.
• После стабильного наблюдения исправьте исторические данные отдельным контролируемым запуском.

Как проверить результат

Один успешный пример недостаточен. Проверьте крайние значения, одновременные действия, перезапуск процесса и восстановление после сбоя сети. Результат подтверждайте не только интерфейсом, но и состоянием базы, очереди, внешнего сервиса и журналом аудита. Особенно важна повторная доставка уже обработанного события.

Критерии приёмки сформулируйте заранее. Каждый пункт должен давать однозначный ответ, а не субъективную оценку. Если тест нельзя автоматизировать, сохраните короткий регрессионный чек-лист с тестовыми данными и ожидаемыми статусами.

• Свежий token проходит.
• Повтор отклоняется.
• Чужой hostname не принимается.
• Недоступность Cloudflare даёт контролируемое поведение.

Типичные ошибки при исправлении

• Проверять только на клиенте.
• Логировать полный token и secret.
• Повторно использовать token после validation error формы.
• Отключать проверку при первом сбое.

Не отключайте авторизацию, валидацию, TLS, аудит или контроль дублей ради исчезновения симптома. Такое изменение может сделать интерфейс успешным, но увеличить ущерб при следующем сбое. Временная мера должна иметь владельца, наблюдаемость и дату удаления.

Как предотвратить повторение

Профилактика строится вокруг явных контрактов, идемпотентных обработчиков, наблюдаемости и повторяемых релизов. Система должна быстро показывать нарушение правила после обновления, роста нагрузки или отказа интеграции. Ошибку, которая уже привела к потере денег, данных или заявок, закрепите автоматическим тестом.

Мониторьте полный пользовательский путь, а не только доступность серверов. Техническая метрика должна быть связана с бизнес-результатом: заказ завершён, доступ выдан, файл восстановлен, событие обработано один раз, данные изолированы. Уведомление должно содержать контекст для первого решения.

• Success rate и error-codes.
• Время от выдачи до verify.
• Повторное использование token.
• Спам после изменений policy.

Что подготовить для технического разбора

• Описание ожидаемого и фактического поведения с точной последовательностью действий.
• Время возникновения, идентификатор тестового объекта и версии затронутых компонентов.
• Обезличенные журналы до и после ошибки с единым correlation ID.
• Список последних изменений, выполненных проверок и условий исчезновения симптома.
• Безопасный доступ к тестовой среде либо минимальный пример без паролей, токенов и персональных данных.

Частые вопросы

Нужно ли передавать remoteip?

Это необязательный параметр; если используете, корректно определяйте IP через доверенные proxy.

Почему повтор формы не работает?

Token одноразовый, после попытки виджет должен получить новый.

Можно ли доверять success без hostname?

Лучше проверять ожидаемый hostname и action как часть policy.

Когда нужна помощь специалиста

Если Turnstile не проходит siteverify, я могу проверить keys, payload, proxy и policy. Для оценки нужны error-codes, hostname и обезличенный trace без token.