Сайдкар

Обязанности во время выполнения

Sidecar — это серверная часть Bun, используемая для интеграции настольных компьютеров и локальной разработки. Он открывает SQLite, предоставляет репозитории и доменные службы, обслуживает HTTP API, определенный схемой, а также размещает помощника и интеграцию рабочих процессов. Оболочка Tauri запускает упакованный двоичный файл и определяет назначенный ему порт из машиночитаемого события запуска.

apps/sidecar/src/layers.ts составляет обслуживаемый API, обработчики, авторизацию, репозитории и сервисы. Дополнительные поставщики, такие как платные кассы и модели искусственного интеллекта, настраиваются через их услуги; их отсутствие не превращает запись базы данных в работающую внешнюю интеграцию.

Протокол процесса и остановки

Основной HTTP-сервер связывается только 127.0.0.1, с портом 0 поэтому операционная система выбирает доступный порт. Тайм-аут простоя HTTP отключен, чтобы позволить длительному вызову помощника сохранять молчание между потоковыми событиями. Грациозное завершение работы HTTP настроено на 500 миллисекунды, прежде чем продолжится завершение области.

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

{"event":"ready","port":53211}
{"event":"error","message":"Startup failure details"}

Сообщение стандартного ввода, завершающееся новой строкой, с event: "shutdown", закрытие стандартного ввода, SIGINT или SIGTERM освобождает область сервера. Неверно сформированные родительские сообщения игнорируются, а неполная строка слишком большого размера отбрасывается. Финализаторы останавливают принадлежащие им службы и устанавливают контрольную точку/закрывают SQLite. О завершении только прерывания сообщается как о чистом выходе.

Требуемая конфигурация

AppConfigService считывает конфигурацию процесса один раз в apps/sidecar/src/config.ts. CADCAMFUN_TOKEN требуемый токен носителя приложения и CADCAMFUN_DATA_DIR — это необходимый каталог данных приложения. Путь к базе данных <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR является необязательным и предоставляет папку миграции SQL; без него уровень базы данных не будет применять миграцию приложений.

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

bun run --filter @cadcamfun/sidecar start

Пакет сайдкара определяет start и typecheck сценарии. Упакованная двоичная компиляция принадлежит сценариям выпуска репозитория, а не дополнительному пакету. build команда.

Дополнительная конфигурация

• CADCAMFUN_APP_URL устанавливает базу для ссылок аутентификации; CADCAMFUN_DEBUG_LINKS позволяет возвращать ссылки сброса отладки/магические ссылки и по умолчанию имеет значение false.
• CADCAMFUN_AI_HOST это nikcli (по умолчанию; чат работает через встроенный узел беседы) или direct (только AI SDK). CADCAMFUN_AI_OFFLINE (логическое значение, по умолчанию false) отключает дополнительный сетевой путь к каталогу модели. CADCAMFUN_AI_MINIMAX_BASE_URL переопределяет конечную точку MiniMax.
• STRIPE_SECRET_KEY включает поставщика Stripe; STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, и STRIPE_PRICE_ENTERPRISE поставка платного плана по ценам. STRIPE_WEBHOOK_SECRET требуется для проверки подписанного веб-перехватчика.
• CRON_SECRET предоставляет секретный маршрут cron; без него локальное приложение может вызвать этот маршрут без дополнительного секрета cron. ADMIN_EMAIL — это устаревшая проверка личности администратора; по умолчанию локальный профиль является администратором собственной установки.
• OTEL_EXPORTER_OTLP_ENDPOINT включает настроенный экспорт телеметрии OTLP. Без конечной точки экспорт внешних телеметрических данных отключен.

Все эти имена читаются в одном месте, AppConfigService; токен и секретный ключ Stripe сохраняются как отредактированные значения, поэтому они не отображаются в журналах. Ключи поставщика ИИ управляются через API учетных данных и специальный файл учетных данных. Они не считываются как настройки среды API-ключа поставщика AppConfigService.

HTTP-доступ и обнаружение API

Сайдкар публикует /api/openapi.json для своего обслуживаемого контракта и использует промежуточное программное обеспечение носителя в защищенных группах. Второй необязательный заголовок сеанса выбирает действующую учетную запись. Локальный профиль создается или повторно используется в local@cadcamfun.local, что позволяет использовать установку без входа в учетную запись.

CORS признает tauri://localhost, HTTP/HTTPS tauri.localhostи источник HTTP localhost или 127.0.0.1 с необязательным портом. Другие источники не получают заголовок ответа о разрешенном источнике. CORS — это политика браузера; промежуточное программное обеспечение носителя остается контролем доступа для защищенных маршрутов.

Обслуживаемые группы охватывают ресурсы проектирования, создание и проверку производства, точное САПР, библиотеки, затраты, искусственный интеллект, VCS/рабочие процессы, события, сопутствующие элементы управления, идентификацию, организации, уведомления, файлы, плагины, выставление счетов, аналитику, список ожидания, MCP и локальное состояние. Обратитесь к работающему документу OpenAPI для получения подробной информации о методе и полезной нагрузке.

Заголовок действующего аккаунта x-session-token. Без него или с токеном, который не проверяется как токен сеанса для существующего пользователя, запросы действуют как локальный профиль (src/http/authorization.ts).

Исходная организация

main.ts запускает ограниченный сервер и родительский протокол. config.ts конфигурация расходных материалов, layers.ts зависимости проводов, startup.ts разделяет готовность и порт обратной связи, shutdown.ts читает родительские сообщения о завершении работы и observability.ts настраивает дополнительную телеметрию.

http/ сопоставляет проверенные запросы с услугами. repos/ сопоставляет ресурсы с запросами Drizzle и правилами доступа к ресурсам. services/ координирует межресурсное поведение и plugins/ содержит реализации рабочего хоста и браузера.

Группы обработчиков

Обработчики сгруппированы по ресурсам: проекты, чертежи, компоненты, траектории и дополнительные функции, генератор траекторий, точная САПР, конфигурации материалов/инструментов/станков и маршруты их хранения, библиотека, затраты, файлы, организации, уведомления, пользователи/аутентификация, выставление счетов, аналитика, список ожидания, MCP, различные службы приложений, состояние «ключ-значение», AI, VCS, события и сопутствующее управление.

entity-io.ts общие помощники по импорту/экспорту сущностей. authorization.ts применяет учетные данные приложения и моста с определенной областью действия. Объявленные полезные данные обработчика уже прошли декодирование схемы; Проверка уровня обслуживания по-прежнему проверяет ссылки, право собственности, согласованность доказательств и ограничения домена.

Состав доменной службы

Службы искусственного интеллекта предоставляют чертежи и действия CAM, параметрический/точный контроль, контекст проекта, память, рабочие журналы и подключаемые инструменты. cam-program.ts повторно запускает записанные производственные запросы и проверяет собственные данные во время сохранения. Службы истории применяют моментальные снимки, правила защищенных ветвей, транспорт GitHub и выполнение рабочих процессов.

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

Граница репозитория

Репозитории используют общий Database.query сервис для персистентности и сбоев типизированного хранилища. Они декодируют сохраненный JSON и обеспечивают доступ к конкретному ресурсу или предоставляют помощники авторизации. Обработчики HTTP преобразуют сбои домена/хранилища в объявленные ошибки ответа; расчеты геометрии остаются в @cadcamfun/core.

Интеграция плагинов

Общий рабочий хост находится в plugins/host.ts. Служба плагина помощника по производству загружается явно включенной ai:tool расширения из каталога плагинов приложения. Установщик ZIP браузера и API начальной загрузки используют собственные пути манифеста и хранилища. Видеть Плагины прежде чем выбирать формат расширения или предполагать, что функция подключена.

Сопутствующий HTTPS-шлюз

Сопутствующий шлюз — это отдельный прослушиватель HTTPS, который может возобновить ранее включенную настройку. Он связывает IPv4 для сетевых клиентов, предоставляет сгенерированный сертификат, сохраняемый под <dataDir>/companionи использует отзывные токены устройств с ограниченной областью действия. При сопряжении предоставляется отпечаток сертификата, чтобы мобильный транспорт мог закрепить рабочий стол.

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

Готовность и диагностика

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

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

Владение данными

Постоянные данные включают базу данных SQLite и резервные копии миграции, хранилище файлов, состояние учетных данных/конфигурации AI, секретные данные аутентификации и записи отзыва, ресурсы подключаемых модулей и сопутствующие сертификаты. Защитите весь каталог данных приложения при его резервном копировании или переносе установки. Сайдкар имеет срок службы соединения; клиенты не владеют ни дескриптором SQLite, ни выпуском основного токена-носителя.

Запустите одноразовый локальный экземпляр

Запустите эти команды в корне репозитория на выделенном терминале. Каталог новый, токен генерируется локально без его печати, миграция является явной, а режим прямого/автономного искусственного интеллекта позволяет избежать импорта встроенного хоста диалога для этой проверки при запуске. openssl предоставляет токен случайного запуска в этом примере оболочки.

export CADCAMFUN_DATA_DIR="$(mktemp -d /tmp/cadcamfun-docs.XXXXXX)"
export CADCAMFUN_TOKEN="$(openssl rand -hex 32)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=1
bun run --filter @cadcamfun/sidecar start

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

Имея URL-адрес подключения и его токен, уже доступные в клиентской оболочке, сравните общедоступную активность с защищенным доступом:

curl --fail-with-body "$CADCAMFUN_URL/api/health"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/version"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/projects"

Источник: apps/sidecar/src/main.ts, config.ts, shutdown.ts, и test/process.test.ts.

Журналы и дополнительная телеметрия

Журналы Stderr JSON и события готовности/ошибки стандартного вывода имеют разных потребителей. Средство запуска должно анализировать полные строки стандартного вывода и пересылать или сохранять стандартный вывод отдельно. Запрос, который завершается сбоем после готовности, является ошибкой приложения, а не вторым событием запуска.

Когда OTEL_EXPORTER_OTLP_ENDPOINT настроен, ObservabilityLive настраивает пакетную обработку промежутков/журналов и периодический экспорт метрик. Он добавляет /v1/traces, /v1/metrics, и /v1/logs к прилагаемому основанию коллектора после удаления косых черт. Поставьте базу коллекторов, такую как http://collector:4318, а не URL-адрес сигнала с уже добавленным суффиксом.

Имя службы ресурсов cadcamfun-sidecar и его версия берется из конфигурации приложения. Стандартные настройки среды ресурсов OpenTelemetry обрабатываются пакетом SDK. Сетевой экспорт не является обязательным, а локальный поток stderr остается доступным, если сборщик не настроен.

Источник: apps/sidecar/src/observability.ts и main.ts.

Определите неверную границу

Тесты жизненного цикла реального процесса охватывают EOF, строку JSON разделенного завершения работы и SIGTERM, затем перезапускают тот же каталог данных и проверяют сохраненные проекты. Они также проверяют WAL после выхода. Это устанавливает поведение жизненного цикла исходного процесса; упакованная оболочка и доставка для конкретной машины по-прежнему требуют собственной проверки.

Источник: apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts, и src/services/companion.ts.

Подробная последовательность запуска

1. Оболочка генерирует токен запуска из 32 случайных байтов, закодированных в шестнадцатеричном виде как 64 символов, и запускает вспомогательную программу с помощью CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR, и CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService читает все настройки один раз. Отсутствие обязательного параметра приводит к сбою при запуске с error событие.
3. Уровень базы данных открывается <dataDir>/cadcamfun.db, включает режим WAL и внешние ключи, а также применяет миграции из каталога миграций.
4. Слои состоят из: базы данных, затем репозиториев, затем сервисов, затем обработчиков HTTP. Каждый ресурс принадлежит определенному слою, поэтому при завершении работы он освобождается в обратном порядке зависимости.
5. HTTP-сервер связывается 127.0.0.1 на порту 0, и операционная система выбирает свободный порт.
6. Путь общественного здравоохранения исследован. Только после того, как он ответит, {"event":"ready","port":N} записано в стандартный вывод.
7. Оболочка ожидает этой строки до 60 секунд и перезапускает сайдкар не более одного раза. Веб-просмотр ожидает до 125 секунд для get_sidecar_endpoint, затем подключается.

Модель аутентификации

Подписанные токены используют HS256 с эмитентом. cadcamfun. Отозванные токены проверяются как invalid, а неизвестные или поддельные токены игнорируются при отзыве. Секрет подписи генерируется один раз за установку и сохраняется в каталоге данных, поэтому ссылки, выданные до перезапуска, все равно проверяются впоследствии.

Что находится в каталоге данных

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

Готовая линия, захваченная

CADCAMFUN_TOKEN=t CADCAMFUN_DATA_DIR="$(mktemp -d)" \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct CADCAMFUN_AI_OFFLINE=true \
bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":43461}

Порт выбирается операционной системой при каждом запуске. Эта строка является первым выводом стандартного вывода после того, как миграции и слои готовы, поэтому клиент, который ее увидит, может немедленно вызвать API. Держите stdin открытым: его закрытие является сигналом выключения.

Через 3Д