> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/ru/nachat/common-issues.md).

# Частые проблемы

## Для кого

Инженеры поддержки и дежурные, которые разбирают сбои подписки и запросов fetcher.

## Что можно сделать

* Быстро проверить подписку без логов backend (самопроверка curl).
* Найти типовые ошибки и способы их исправления.
* Подготовить данные для расследования инцидентов.

## Быстрый чек‑лист валидации (самопроверка)

* **HTTPS 443:** конечный URL отвечает по `https://...:443`, нет редиректов на `http`, нестандартных портов или сторонних доменов.
* **Редиректы только допустимые:** не уводят на файлообменники/драйвы/`file:`/`http:`; не больше 3 подряд.
* **Размер < 2 MB:** тело после возможного декодирования/base64 не превышает 2 MB.
* **VLESS ссылки валидны:** каждая строка `vless://<uuid>@host:port` (без `vmess://`, без пробелов), имя узла после `#` опционально.
* **Base64 тело (если используете):** строка полностью декодируется без ошибок (`base64 -d`), нет пробелов/логов до/после.
* **Метаданные из поддерживаемых ключей:** используйте поля из [subscription/metadata.md](/ru/kontrakt-podpiski/metadata.md); без опечаток и лишних заголовков/мета‑строк.
* **ETag/304 работают:** первый запрос отдаёт сильный `ETag`, второй с `If-None-Match` возвращает `304`.
* **Зеркала:** в `meta.mirrors` только абсолютные `https://` URL, доступные и отдающие тот же `ETag`/тело.

## Типовые проблемы

* **«Ничего не импортируется»** — ответ не в UTF‑8/есть BOM, в начале мусор (HTML, логи), строки не `vless://`, base64 невалиден или обрезан. Проверяйте `Content-Type`, кодировку, убирайте пустые/битые строки, валидируйте UUID/порты.
* **«Обновления не приходят»** — отсутствует `ETag` или при `If-None-Match` всегда `200`; порядок ссылок меняется каждый раз, из-за чего `ETag` скачет. Делайте стабильную сортировку и отдавайте сильный `ETag`, иначе 304 не случится.
* **«Лимит устройств не работает»** — слот установки живёт 24 часа с момента активности (sync/heartbeat/connect). Если устройство молчит >24 часов, слот освобождается; удаление подписки освобождает сразу. Убедитесь, что `installation-limit` задан и пользователи понимают окно 24 часа.
* **`connection-limit` не даёт ≥2** — значения >1 работают только с тарифом **Advanced Connection Control (ACC, платная опция)** (`meta.capabilities=["advanced_connection_control"]`, см. [features/overview.md](/ru/funkcii/overview.md)). Без него сервер приравнивает к `1`.
* **«Mirrors не используются»** — в `meta.mirrors` заданы не абсолютные URL, HTTP вместо HTTPS или зеркало недоступно/отдаёт другое тело. Зеркала применяются только после неуспеха основного URL; они должны отвечать тем же содержимым и `ETag`.
* **«Лимиты не работают / всегда 429»** — слишком маленький `Cache-Control: max-age` или частые изменения тела. Установите разумный `max-age`/`ETag` и убедитесь, что клиенты не шлют ретраи без backoff.

## Диагностика curl (self‑serve)

* Проверка доступности, редиректов и заголовков:

  ```bash
  curl -I -L --max-redirs 3 --connect-timeout 5 https://example.com/sub
  ```

  Убедитесь в коде `200/304`, `Content-Type`, `Cache-Control`, `ETag`, отсутствии переходов на `http` и лишних заголовков.
* Проверка размера тела:

  ```bash
  curl -sSL -w 'download=%{size_download} bytes\n' -o /dev/null https://example.com/sub
  ```

  Если `size_download` ≥ 2\_000\_000, уменьшите количество узлов или отключите лишние поля.
* Проверка `ETag`/`304`:

  ```bash
  # Извлекаем первый ETag, убираем префикс ETag:/W/, кавычки и \r
  etag=$(curl -sD - -o /dev/null https://example.com/sub \
    | awk 'BEGIN{IGNORECASE=1} /^etag:/ {gsub(/^etag:[[:space:]]*/, ""); gsub(/^W\//, ""); gsub(/"/, ""); gsub(/\r/, ""); print; exit}')
  curl -s -o /dev/null -D - -H "If-None-Match: ${etag}" https://example.com/sub
  ```

  Команда извлекает первый `ETag`, убирает префикс `ETag:`, слабый префикс `W/`, кавычки и `\r`. Ожидается `304 Not Modified`. Если снова `200`, сервер не использует `If-None-Match`.
* Проверка base64 тела (если подписка отдаёт base64):

  ```bash
  curl -sSL https://example.com/sub | base64 -d >/tmp/subscription.raw && wc -c /tmp/subscription.raw
  ```

  Ошибка `invalid input` = лишние символы/пробелы/мусор в ответе.
* Поиск битых VLESS ссылок:

  ```bash
  # Базовая проверка UUID/хоста/порта (порт — любые цифры, диапазон 1–65535 не проверяется; UUID не проверяется на версию)
  curl -sSL https://example.com/sub \
    | grep -nEv '^$|^#|^vless://[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}@[^\s:]+:[0-9]+(#.*)?$'
  ```

  Паттерн проверяет UUID в формате `8-4-4-4-12`, хост без пробелов/двоеточий, порт из цифр и опциональный `#комментарий` в конце строки. Пустой вывод = все строки валидны. Ненулевой вывод означает наличие невалидных строк — проверьте номера, которые показал `grep`. Паттерн базовый (не проверяет порт на диапазон 1–65535 или версию UUID v4) и служит для отлова мусора; для строгой валидации применяйте дополнительную проверку.
* Проверка зеркал:

  ```bash
  curl -sSL https://example.com/sub | grep -iE '^(#\s*)?(mirrors|x-subscription-mirrors)'
  # Затем явно запросите каждое зеркало:
  curl -I https://mirror1.example.com/sub
  ```

  Все зеркала должны быть доступны по HTTPS и возвращать тот же `ETag`/тело. Значение берётся из `meta.mirrors`; оно может прийти из meta-строк (`# mirrors:`) или эквивалентного заголовка `X-Subscription-Mirrors`.

## FAQ для провайдера (что отвечать пользователям)

* **Не импортируется / «конфиг пустой»** — проверьте, что подписка в UTF-8, без HTML/логов и содержит хотя бы один валидный `vless://...` или поддерживаемый JSON/Xray/sing-box outbound. Дайте пользователю актуальную add link и время последней проверки.
* **«Обновлений нет»** — обновления приходят при смене тела подписки/`ETag`. Если контент не менялся или порядок строк случайный, клиент видит старую версию либо скачивает одно и то же тело снова. Дайте ориентир по `Cache-Control` и стабильной сортировке.
* **«Лимит устройств/подключений сработал»** — слот высвобождается через 24h без активности или сразу после удаления подписки. Для >1 одновременного подключения нужен тариф ACC (`advanced_connection_control`).
* **«Зеркало не помогает»** — зеркала используются как fallback. Убедитесь, что указаны полные HTTPS URL и что они отдают то же содержимое; если основная площадка отвечает 200, клиент не переключится.
* **«Почему 304 не приходит?»** — сервер не поддерживает `If-None-Match` или `ETag` меняется слишком часто (плавающий порядок ссылок). Закрепите порядок, отдавайте сильный `ETag`.

## См. также

* [operations/caching-and-304.md](/ru/uluchsheniya-posle-pervogo-zapuska/caching-and-304.md)
* [operations/mirrors-and-migration.md](/ru/uluchsheniya-posle-pervogo-zapuska/mirrors-and-migration.md)
* [features/overview.md](/ru/funkcii/overview.md)
* [subscription/metadata.md](/ru/kontrakt-podpiski/metadata.md)
* [subscription/examples.md](/ru/kontrakt-podpiski/examples.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tumbler.app/ru/nachat/common-issues.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.