TanStack Start на VPS: серверные функции, вход и рабочий выпуск

MAATRIX · 17 октября 2026 · 8 мин чтения

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

TanStack Start нужно разворачивать с учётом используемого сборщика и серверного окружения. Ниже разберём понятный вариант для VPS: приложение с Vite и Nitro, один серверный процесс за обратным прокси, отдельные настройки секретов и постоянная база. Это маршрут для существующего проекта, который уже работает в разработке; создание самой системы авторизации остаётся частью приложения.

Зафиксируйте отправную точку

Проверьте версии TanStack Start, Node.js и сборщика в проекте. Сохраните lock-файл и рабочий коммит. Документация развивается быстро, поэтому пример для другой версии нельзя механически вставлять поверх действующей конфигурации.

Посмотрите, чем собирается проект. В актуальном руководстве по размещению для Vite и Rsbuild показаны разные выходные файлы и способы запуска. Здесь используем вариант Vite с Nitro. Если ваш проект использует Rsbuild, следуйте соответствующему разделу документации и не ожидайте появления того же каталога сервера.

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

Подготовьте серверную сборку

Если Nitro ещё не подключён, добавьте его способом, совместимым с текущей версией проекта. В варианте из документации используется пакет nitro и плагин nitro/vite. В существующей конфигурации сохраните плагины, алиасы и прочие настройки; важен их корректный состав, а не копирование минимального примера целиком.

Для этого варианта скрипты проекта содержат сборку через Vite и запуск готового сервера:

{
  "scripts": {
    "build": "vite build",
    "start": "node .output/server/index.mjs"
  }
}

Это фрагмент package.json, а не замена всего файла. Установите зависимости выбранным пакетным менеджером с соблюдением lock-файла, затем выполните сборку. Проверьте, что появился серверный результат и клиентские ресурсы. Ошибки типов, импорта серверных модулей и отсутствующих переменных исправляйте до доставки на рабочий домен.

В чистой тестовой среде запустите именно production-сборку. Команда разработки проверяет другой режим и не доказывает работоспособность адаптера. Откройте вложенный маршрут напрямую, затем перейдите на него через интерфейс. Оба способа должны давать согласованный результат.

Настройки окружения: граница проходит не по названию файла

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

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

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

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

Вход на страницу и право выполнить действие — разные проверки

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

Для учебного примера возьмите приложение с заметками. Пользователь А создаёт заметку, пользователь Б пытается получить её по известному идентификатору. Затем Б пытается изменить и удалить её прямым запросом. Все три действия должны быть отклонены без изменения данных. Такой тест полезнее одного успешного входа администратором.

Проверьте истечение сессии, выход и переключение аккаунтов в одном браузере. После выхода старые личные данные не должны оставаться в клиентском состоянии или общем кеше. Cookies должны соответствовать HTTPS и принятой политике безопасности приложения.

Для операций записи проверяйте входные данные и защиту от нежелательных межсайтовых запросов. Важно тестировать её с действующей сессией: отказ из-за отсутствия входа ещё не подтверждает корректную защиту самой операции. Практические проверки собраны в production checklist TanStack.

Обратный прокси и постоянный процесс

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

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

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

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

Публичная страница глазами поискового робота

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

Посмотрите коды ответов для существующей страницы, отсутствующего объекта, перенаправления и контролируемой ошибки. Отсутствующая заметка не должна отвечать успешным статусом с сообщением «ничего не найдено», если это публичный самостоятельный ресурс. Личные разделы при этом требуют ограничения доступа независимо от правил индексирования.

Проверьте карту сайта и robots.txt на рабочем домене. Тестовые запреты индексирования иногда переезжают в production вместе с хорошими намерениями. Обратная ошибка тоже встречается: закрытая тестовая копия становится доступна поисковику. Доступ и индексирование настраивайте отдельно.

Выпуск, который можно повторить и откатить

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

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

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

Небольшой журнал приёмки

Для первого выпуска достаточно таблицы с действиями и ожидаемыми результатами. Например: гость открывает публичную статью, вошедший пользователь сохраняет черновик, второй пользователь получает отказ, просроченная сессия отправляет на повторный вход. Рядом записывайте время проверки и версию приложения. Такая таблица не заменяет автоматические тесты, но делает решение о публикации понятным.

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

VPS для TanStack Start

Для небольшого пилота можно рассматривать MAATRIX Uab Start с 2 vCPU и 4 ГБ памяти. Если рядом работают база, очередь и сборка, начните оценку с Heka Standard: 4 vCPU и 8 ГБ. Это ориентир для проверки, а не универсальная вместимость приложения.

Ubuntu или Debian выбирайте по совместимости Node.js и системных зависимостей. Учитывайте диск для данных, логов, сборок и резервного запаса. Копию базы и файлов храните отдельно, а восстановление проверяйте до того, как оно понадобится срочно.

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