Перейти к основному содержимому

Переход на сессии и API-ключи

Начиная с версии 0.39 tuna-cli входит в аккаунт не по токену, а через сессию устройства. Для серверов, CI и всего, что работает без человека, вместо токена используется API-ключ. Старые токены продолжают работать, но устарели.

Что поменялось​

Раньше у аккаунта был один токен tt_… на все устройства. tuna login сохранял его в конфигурационный файл, а тот же токен копировали в CI, Docker и сервисы. Отозвать доступ одного устройства было нельзя: перевыпуск токена ломал туннели везде.

Теперь доступ разделён:

ГдеЧем входитГде хранится
CLI на ноутбукесессия устройствасистемное хранилище ключей
Tuna Desktopпока токен, как раньше; сессии появятся в следующей версиикак раньше
Сервер без браузерасессия, подтверждённая по ссылке с другого устройства, или API-ключхранилище ключей или конфигурационный файл
CI, Docker, Kubernetes, TerraformAPI-ключпеременная TUNA_API_KEY или секрет CI
Фоновый сервис tuna serviceотдельный ключ сервисафайл, доступный только пользователю сервиса

Что это даёт:

  • Каждое устройство — отдельная сессия. Список сессий виден в профиле и в tuna session list. Если ноутбук потерян, завершите его сессию: туннели этого устройства остановятся сразу, остальные продолжат работать.
  • Сессию нельзя тихо скопировать. Сессия хранит короткоживущий токен доступа и токен обновления, который меняется при каждом обновлении. Если старый токен обновления попытаются использовать повторно, сервер завершит сессию целиком.
  • Ключ — по задаче. Для CI, сервера или коллеги можно выпустить отдельный API-ключ с нужными правами и удалить его, не затрагивая остальные.

Жёсткого срока у сессии нет. Она завершается, если устройство не пользовалось ею 30 дней. Запущенный туннель продлевает сессию сам.

Что будет со старым токеном​

Ничего не сломается. Все токены tt_… перенесены в API-ключи с правом на запуск туннелей (tunnels:connect): они поднимают туннели, как раньше, а в API, как и раньше, не ходят. Старые версии CLI и Tuna Desktop продолжают работать.

Новый CLI принимает старый токен, но предупреждает о замене:

  • переменная TUNA_TOKEN → используйте TUNA_API_KEY;
  • флаг --token → --api-key;
  • поле token в конфигурационном файле → войдите через tuna login или сохраните API-ключ;
  • команда tuna config save-token → tuna login --with-api-key.

Сроков отключения старых токенов пока нет. Когда решим, предупредим заранее.

При регистрации токен больше не выпускается: вместо страницы токена в кабинете теперь страница API-ключей.

Как перейти​

Ноутбук​

Войдите заново:

tuna login

Откроется браузер, после подтверждения CLI сохранит сессию в системное хранилище ключей: Keychain в macOS, Credential Manager в Windows, Secret Service в Linux. Если хранилища нет, добавьте --insecure-storage: сессия сохранится в файл credentials.json рядом с конфигурационным файлом.

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

tuna login --hostname=work-laptop

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

Tuna Desktop пока входит как раньше, по токену: вход через сессии в нём появится в следующей версии. Делать в нём ничего не нужно.

Сервер без браузера​

Если вы заходите на сервер по SSH, войдите по ссылке:

tuna login --no-browser

CLI покажет ссылку и код. Откройте ссылку на любом устройстве, где вы вошли в кабинет, и проверьте, что код совпадает. CLI сам распознаёт SSH-сессию и предлагает этот способ первым.

Сессия на сервере привязана к вашему аккаунту. Если сервером пользуется команда или туннели должны работать после вашего ухода, используйте API-ключ, как для CI.

CI, Docker и скрипты​

  1. Создайте API-ключ. Выберите набор «Для туннелей» или включите «Запуск туннелей»: без права tunnels:connect ключ не поднимает туннели.
  2. Положите ключ в секреты CI или окружение контейнера под именем TUNA_API_KEY вместо TUNA_TOKEN.
export TUNA_API_KEY=<ваш_ключ>
tuna http 8080 -s=myapp

В Docker Compose:

services:
  tuna:
    image: yuccastream/tuna:latest
    command: http web:80 -s=myapp --inspect=false
    environment:
      - TUNA_API_KEY=<ваш_ключ>

Сохранить ключ на машине, чтобы не передавать его каждый раз, можно командой tuna login --with-api-key. Она читает ключ из стандартного ввода, поэтому он не останется в истории оболочки:

echo "$TUNA_API_KEY" | tuna login --with-api-key

Если ключ без права на туннели, CLI предупредит об этом при входе.

Фоновые сервисы​

Сервисы, установленные старым CLI, работают со старым токеном и продолжат работать. Чтобы перевести сервис на отдельный ключ, войдите через tuna login и переустановите его с той же командой. Старый CLI ставил на Linux и FreeBSD системные сервисы, поэтому удаляйте их через sudo, а в Windows — из PowerShell от имени администратора:

tuna service list
sudo tuna service uninstall --name=web
tuna service install --name=web -- tuna http 8080 -s=web

Без sudo новый CLI на Linux ставит пользовательский сервис systemd --user. Если нужен системный, запустите install через sudo: root не видит вашу сессию, поэтому CLI попросит подтвердить выпуск ключа по ссылке.

install выпустит ключ только для этого сервиса и привяжет его к типу туннеля и адресу, если в команде есть --subdomain, --domain или --port. uninstall отзовёт ключ. Подробнее — в разделе Запуск в фоне.

Terraform и Kubernetes-оператор​

Terraform-провайдер и Kubernetes-оператор с самого начала работают на API-ключах: api_key или TUNA_API_KEY у провайдера, credentials.apiKey у оператора. Менять в них ничего не нужно.

Вопросы и ответы​

Мой CI с TUNA_TOKEN перестанет работать после обновления?​

Нет. Новый CLI принимает TUNA_TOKEN и только пишет предупреждение в лог. Переименуйте переменную в TUNA_API_KEY, когда будет удобно: значение подойдёт то же самое, старый токен уже перенесён в API-ключ.

Где взять токен, если его больше не показывают в кабинете?​

Для своего компьютера токен не нужен: войдите через tuna login. Для CI и серверов создайте API-ключ с правом на запуск туннелей.

Как проверить, что CLI больше не использует старый токен?​

tuna whoami

Команда покажет аккаунт. Если CLI всё ещё берёт переменную TUNA_TOKEN или поле token из конфигурационного файла, он предупредит об этом.

Как выйти на одном устройстве и не задеть остальные?​

На самом устройстве выполните tuna logout. Если доступа к устройству нет, завершите его сессию в профиле: туннели устройства остановятся сразу, а CLI завершится.

Что будет с сервисами после tuna logout?​

Сервисы, установленные новым CLI, работают на своих ключах, и tuna logout их не трогает. Сервисы на старом токене или на ключе из конфигурационного файла перестанут работать, если удалить этот ключ, — поэтому logout спрашивает, удалять ли его. Без терминала ключ остаётся, удалить его можно флагом --yes.

В системе нет хранилища ключей. Что делать?​

На серверах без графической сессии хранилища часто нет. Войдите с флагом --insecure-storage, чтобы сохранить сессию в файл, или используйте API-ключ.