Как построить этот проект

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

---

1. Как это устроено

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

• 3000 — ваше приложение. Страницы, которые видят посетители. Именно с ним вы работаете каждый день.
• 3001 — авторизация. Учётные записи, сессии, роли. Настраивается из этой панели, вами не правится.
• 3002 — эта панель управления. То же самое: настраивается, а не правится.
• 3300 — слой данных. Строки, загруженные файлы, векторы — и единственная дверь, через которую достаётся всё остальное. Ваше приложение говорит с ним.
• 3600 — чат. Ваш Telegram-бот и его страницы, адрес chat.<ваш домен>.
• 3700 — память. Служба, которая помнит сказанное вами, адрес memory.<ваш домен>.
• 3800 — ИИ-браузер. Настоящий браузер для ваших служб и агентов: открывает страницы и ролики по адресу, адрес ai-browser.<ваш домен>.

Рядом работают ещё три службы, и ни одна из них не является собственной дверью:

• карта — маршруты, матрицы расстояний и поиск адресов, порт 3400;
• каналы связи — Telegram и то, что появится после него, порт 3500;
• граф знаний — агентное хранилище RAG, порт 9621.

Ни один из этих портов не доступен из интернета: брандмауэр пропускает только веб-порты, и всё публичное приходит через них. Ваше приложение достаёт три службы через слой данных: /service/geo, /service/channels, /service/rag — тем же ключом, который открывает сам слой данных.

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

Разработка идёт только против порта 3000. Это приложение — та часть, которая попадает на ваш компьютер, и та, которую вы призваны развивать. Авторизация, эта панель и архитектура платформы из вашего проекта не правятся: чтобы их менять, пришлось бы взять исходники всей платформы с GitHub и работать со всей системой, а это другая работа, чем создание вашего продукта.

Взамен работа против порта 3000 устроена по упрощённому пути — обо нём всё дальнейшее.

---

2. Прежде чем начать — подключите репозиторий

Пока репозиторий не подключён, ничто не может уехать с сервера.

1. Откройте в меню Подключить GitHub.
2. Адрес репозитория. Создайте на GitHub пустой репозиторий и скопируйте его адрес из строки браузера — https://github.com/владелец/репозиторий.
3. Токен доступа. Панель даёт ссылку на страницу токенов GitHub. Выберите Generate new token (classic) и дайте ему область repo. Поставьте долгий срок жизни: когда токен истекает, отправка просто перестаёт работать, без всякого другого предупреждения.
4. Нажмите сохранение. Панель не просто запоминает набранное — она обращается к GitHub с этими данными и называет настоящую причину, если их отвергли.

Пока это не сделано, в меню самым первым и красным стоит Подключить GitHub: без него ничто построенное здесь не может уехать с сервера.

---

3. Первая отправка — сервер передаёт отправную точку

Ваш проект уже существует на этом сервере. Поэтому первый перенос идёт с сервера на GitHub: нажмите Отправить в подвале. Это наполнит ваш пустой репозиторий отправной точкой проекта.

После этого направление меняется навсегда: вы и ваши коллеги отправляете со своих машин, а сервер забирает.

---

4. Первый запуск у себя — проект на вашей машине

1. Клонируйте репозиторий на свой компьютер.
2. Установите зависимости: npm install.
3. Скачайте файл окружения. В разделе Переменные окружения есть кнопка, которая отдаёт готовый .env.local. Не пишите его руками: файл, который даёт панель, направляет ваше локальное приложение на адрес данных этого сервера, разрешённый для вашей машины, а не на ваш собственный ноутбук.
4. Запустите: npm run dev.

Ваше локальное приложение теперь отдаёт те же страницы и читает те же данные, что и живое.

Одно отличие, о котором стоит помнить. Локальная копия работает без авторизации — удобство, которое убирает стену входа во время работы. Это же означает, что доступ по ролям нельзя проверить простым входом: проверяйте такие пути доступными вам средствами, а не считайте, что локальное поведение совпадает с тем, что получает посетитель.

---

5. Данные остаются на сервере

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

• то, что вы видите у себя, — настоящие данные, а не заготовка;
• несколько разработчиков видят одно и то же одновременно — один источник истины;
• при развёртывании ничего не надо переносить, засеивать и сверять.

Так устроены облачные сервисы, с той разницей, что хранилище — ваше.

---

6. Файлы едут через git, данные — никогда

Это самое полезное различение на всей странице.

• Данные — строки, загруженные файлы, векторы — живут на сервере и общие для всех. Через git они не ездят, и им это не нужно.
• Файлы — страницы, компоненты, настройки — ездят только через git.

Ловушка: настройки, которые вы меняете в этой панели, — это файлы. Включив здесь возможность, вы пишете в настройки проекта, и ваша локальная копия не узнает об этом, пока вы не нажмёте Забрать. Данные ведут себя одним образом, настройки — другим, хотя меняются из одной и той же панели.

Ещё один файл ведёт себя иначе, и его стоит знать по имени. Всё, что лежит в Настройках приложения — название, описание, изображения, иконки, SEO, аналитика, — хранится на сервере в APP-CONFIG/app-config.json, и этот файл намеренно вынесен за пределы репозитория. Он никогда не едет с отправкой или получением, его нет в вашем клоне, и свежий сервер стартует без него, на значениях по умолчанию, зашитых в код, — пока вы однажды не сохраните здесь свои настройки.

Два следствия, оба практические:

• Изменение этих настроек не требует развёртывания. Приложение читает файл на каждом запросе; сохранение видно на следующей загрузке страницы.
• Ваш ИИ-агент не может изменить их с вашей машины — там просто нечего менять. Если агент предлагает править брендинг или SEO в коде, правильный ответ: это живёт в панели. Кодом решается только по-настоящему отсутствующее поле, и это правка платформы, а не вашего проекта.

---

7. Как отправить работу назад

Закончив что-то у себя, сделайте коммит и отправьте его в репозиторий со своей машины.

---

8. Получение, и когда нужно развёртывание

Обратно в панели: нажмите Забрать, чтобы получить отправленное.

Нужно ли после этого Развернуть — зависит от того, что изменилось.

• Развёртывание не нужно. Создание страниц и размещение в них содержимого действует сразу: архитектура отдаёт их из данных на каждой загрузке.
• Развёртывание нужно. Функциональные компоненты с настоящей логикой обязаны быть скомпилированы. На вашей машине они работали в момент сохранения, потому что локальная копия запущена в режиме разработки; живой сервер отдаёт скомпилированный результат, и компиляция — это ровно то, что делает Развернуть.

Что развёртывание делает на самом деле: пересобирает ваше приложение на порте 3000 и перезапускает его. Авторизацию и эту панель оно не трогает — они принадлежат платформе, а не вашему проекту. Через несколько минут, если ошибок нет, ваши изменения публичны.

---

9. Когда развёртывание падает

Журнал появляется внизу экрана во время сборки и остаётся там, если сборка упала.

1. Нажмите Копировать или Скачать в заголовке журнала.
2. Отнесите этот текст на свою машину и отдайте своему ИИ-агенту: это собственное сообщение компилятора, ровно то, что нужно агенту, чтобы устранить причину.
3. Отправьте исправление, нажмите здесь Забрать, затем Развернуть снова.

Что происходит, когда вы нажимаете «Развернуть»

Это стоит знать подробно, потому что ответ на вопрос «может ли плохая сборка положить мой сайт» живёт в этих пяти шагах.

1. Компиляция. Ваше приложение собирается в папку со скомпилированным результатом. Работающее приложение при этом не затрагивается: оно уже в памяти, обслуживает посетителей и новых файлов не читает.
2. Проверка кода выхода. Если компилятор упал, развёртывание останавливается здесь. Ничего не перезапускается.
3. Перезагрузка. Загружается только та сборка, которая скомпилировалась: процесс аккуратно перезапускается на новый результат.
4. Проверка здоровья. Перезагруженное приложение просят ответить трижды, с интервалом десять секунд.
5. Сохранение как запасной вариант. Сборка, которая и скомпилировалась, и ответила, откладывается копией как последняя заведомо рабочая версия. Только такая сборка получает это место.

Две защиты и что покрывает каждая

Ничто никогда не перезапускается на код, который не скомпилировался. Это шаг 2, и именно он держит посетителей на рабочей версии, пока вы устраняете ошибку. Ваш сайт не мигает.

Последняя рабочая сборка хранится копией и возвращается, когда сборка падает. Эта защита менее очевидна, и она важнее. Упавшая сборка не оставляет прежний результат вежливо в покое — она убирает метку, которая делает этот результат запускаемым. Замер на этой платформе: после нарочно сломанной сборки сайт продолжал отвечать, но вторая копия приложения не запустилась вовсе, с сообщением «Could not find a production build».

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

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

От чего это НЕ защищает

Точность на границах — то, что делает гарантию применимой:

• Возвращается код, а не данные. Строки, файлы и векторы развёртыванием не версионируются и вместе с ним не откатываются. Изменение, удалившее данные, возвратом прежней сборки не отменяется.
• Сборка, которая скомпилировалась и отвечает, считается хорошей — даже если страница неверна, цена неверна или ссылка сломана. Правильность — не то, что видит проверка здоровья: она охотно примет работающее приложение, которое делает не то.
• Настройки времени работы в это не входят. Настройки, изменённые в панели, применяются без сборки, поэтому возврат сборки не возвращает настройки.
• Запасной вариант ровно настолько свеж, насколько свежо ваше последнее удачное развёртывание. Если на свежем сервере ещё ничего не удавалось, установщик засевает копию самой первой сборкой, так что откатиться всегда есть куда, — но на проекте, где все последние развёртывания падали, «последняя рабочая версия» означает именно это и может оказаться старше, чем вы ожидаете. История развёртываний скажет, какая именно.

---

10. История развёртываний

Каждое нажатие «Развернуть» записывается — не в файл, который забудет следующий перезапуск, а в базу вашего проекта. Откройте в меню История развёртываний, рядом с записью о GitHub.

В каждой строке — что собиралось, когда началось, сколько заняло, чем закончилось, и весь журнал сборки. Выберите прогон, чтобы прочитать его журнал; нажмите Скачать, чтобы забрать файлом.

Как делать это автоматически

Наверху той страницы стоит переключатель на три положения.

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

Сервер спрашивает репозиторий раз в минуту и действует лишь после того, как тот две минуты неподвижен, — так череда отправок превращается в одну сборку. На стороне GitHub для этого ничего не настраивается.

Он отказывается, а не импровизирует. Если на сервере есть незакоммиченные изменения, если истории разошлись или если сборка уже идёт, ход пропускается, а причина появляется в списке. Автоматически берётся только чистое ускоренное слияние — вашу работу никогда не похоронят, чтобы освободить место.

Почему это выключено по умолчанию. Этот сервер собирает на той же машине, которая обслуживает ваших посетителей. Платформа хостинга собирает в другом месте и лишь подменяет результат; здесь сборка соперничает с сайтом за один и тот же процессор. На проекте с настоящими клиентами это решение принимают осознанно — поэтому это выбор, а не значение по умолчанию. Знак «?» рядом с переключателем перечисляет, чего стоит каждый режим.

Три причины, по которым это стоит иметь:

• Упавшая сборка перестаёт быть мгновением. Журнал будет там и завтра, после перезагрузки, после перезапуска панели — вам не нужно воспроизводить падение, чтобы снова прочитать его причину.
• Ваш ИИ-агент может это прочитать. История живёт в том же хранилище и за тем же ключом, что и остальные ваши данные. «Что было на последних пяти развёртываниях» — это запрос, а не расследование; а запись прошлых ошибок — то, что позволяет агенту выучить ошибки, которые этот проект действительно совершает.
• Она отвечает на вопрос «моё изменение доехало?» — временем, длительностью и результатом, а не воспоминанием.

---

11. Конфликты версий — почему возникают и как их избежать

Конфликт означает, что репозиторий и ваша копия изменили одно и то же по-разному. При таком устройстве у него одна частая причина: работа в панели и на своей машине одновременно.

Правило, которое устраняет это полностью:

Пользуйтесь чем-то одним за раз. Начинайте каждый сеанс с Забрать, заканчивайте каждый сеанс Отправить.

Если конфликт всё же случился, вам скажут об этом прямыми словами. Отнесите сообщение на свою машину, разрешите его там с помощью агента, затем отправьте и заберите как обычно.

---

12. Индикатор коммита в левом нижнем углу

Угол показывает состояние вашего проекта, а не платформы:

• имя репозитория и короткий коммит — точная версия вашего кода, которую отдаёт сервер;
• точка состояния — чисто, или есть незакоммиченные изменения, или отстаёт от репозитория.

Нажмите на него, чтобы увидеть подробности и то, что следует нажать.

Почему это важно:

• Поиск причины. Прежде чем заключить, что исправление не сработало, проверьте, что коммит здесь — тот, который его содержит. Большинство сообщений «исправление ничего не дало» — это исправление, которое не доехало.
• Согласованность. Отстаёт значит, что кто-то отправил, а вы не забрали. Незакоммиченные изменения значит, что сервер держит работу, которой больше нигде нет, — отправьте её прежде, чем что-то трогать у себя.
• Сообщение о проблеме. Когда что-то ломается, коммит — тот единственный факт, который делает сообщение воспроизводимым.

Та же карточка называет и версию платформы — выпуск Fractera, на котором работает ваш сервер; он меняется только при обновлении самого сервера.

---

13. Чем это отличается от Vercel и подобных сервисов

Большинство проектов начинается на ноутбуке: вы строите неделями, постепенно присоединяете базу, хранилище и службы и только потом синхронизируете всё это с сервером. Здесь наоборот — проект находится в продакшене с первой минуты, уже работает, и вы развиваете его дальше оттуда.

Более глубокое отличие — в том, что сервер умеет и чего те платформы не могут.

Vercel и ему подобные — не серверы. Это платформы для бессерверных функций: ваш код работает недолго в ответ на запрос и затем перестаёт существовать. Такая модель прекрасна для страниц и API и структурно не может дать:

• процесс, который продолжает работать — слушателя, ждущего сообщений, обработчика очереди, бота;
• работу по расписанию — cron в настоящем смысле, а не его приближение;
• интеграции, удерживающие соединение, а не отвечающие по одному запросу за раз.

Автоматизациям нужны все три. Поэтому ваш проект живёт на сервере, которым вы владеете, а перед ним стоит эта панель.

---

Где снова найти эту страницу

Нажмите Как построить этот проект в подвале, слева от «Развернуть». Она здесь всегда, когда нужна.

Запрос на разработку платформы

Запрос на разработку платформы от http://158.220.98.143:3000.