Запуск из исходного кода

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

Требования: Bun v1.3 или новее и доступная база данных: MongoDB или PostgreSQL — какую вам удобнее запускать.

1. Клонируйте репозиторий и установите зависимости:

   git clone https://github.com/RedFox-Soft/OAuth-server.ts.git
   cd OAuth-server.ts
   bun install

2. Создайте файл .env с обязательными переменными:

   ISSUER=http://localhost:3000
   MONGODB_URI=mongodb://localhost:27017
   DATABASE_NAME=OAuth

   Для PostgreSQL вместо этого задайте POSTGRES_URL, а две другие переменные не указывайте. Имя базы данных входит в этот URL, поэтому DATABASE_NAME не используется:

   ISSUER=http://localhost:3000
   POSTGRES_URL=postgres://user:password@localhost:5432/oauth

   Если задать обе строки подключения, сервер откажется запускаться, а не выберет одну из них; см. PostgreSQL. Bun загружает .env автоматически; больше ничего настраивать не нужно. Каждая переменная описана в справочнике переменных окружения. ISSUER — канонический публичный URL этого сервера: iss каждого токена, основа каждого эндпоинта в discovery и адрес перенаправления клиента консоли администратора, — поэтому задайте ему окончательное значение до следующего шага.

3. Подготовьте базу данных:

   bun run db:setup      # MongoDB
   bun run db:setup:pg   # PostgreSQL

4. Соберите консоль и экраны входа в public/:

   bun run build

5. Запустите сервер:

   bun start

   Он слушает порт 3000. Откройте http://localhost:3000/admin, чтобы попасть в консоль, или http://localhost:3000/.well-known/openid-configuration, чтобы получить документ discovery.

Что подготавливает bun run db:setup

db:setup выполняет database/mongodb.ts для MONGODB_URI / DATABASE_NAME, и именно он превращает пустую базу данных в работающее развёртывание:

• Коллекции — по одной на каждую область хранения, в которую пишет сервер.
• Индексы: TTL-индексы, по которым истекают токены, коды, сессии и взаимодействия, и уникальный индекс по e-mail в коллекции конечных пользователей каждого бакета. Кроме того, он удаляет устаревшие индексы истечения, оставшиеся на коллекциях, которые больше не записывают это поле.
• Начальный ключ подписи RS256, который хранится вместе с ключами всех издателей (issuer) в области bucketKeys, — поэтому ключи здесь и не задаются переменной окружения. (Если сервер когда-либо запустится с пустым хранилищем ключей, он сам сгенерирует и сохранит ключ.)
• Начальные данные панели администратора: зарезервированный проект администрирования, его бакет пользователей «Administrators» с закрытой регистрацией, собственный (first-party) OAuth-клиент admin-panel с redirect URI $ISSUER/admin/callback, зарезервированный клиент агента admin-mcp, системная группа, которой принадлежат контейнеры, не управляемые ни одним администратором, и бакет конечных пользователей по умолчанию redfox.

Он идемпотентен: каждая запись — это upsert или создание при отсутствии, поэтому повторный запуск не меняет ничего из того, что уже существует. Запускайте его повторно после обновления существующей установки: релиз, добавляющий коллекцию, индекс или документ начальных данных, применяет его здесь и больше нигде. Затем выполните bun run db:migrate — он применяет то, что релиз должен перестроить, а не просто добавить; пока это не сделано, сервер отказывается запускаться. Некоторые миграции нельзя отменить, поэтому сделайте резервную копию, если такая миграция названа в примечаниях к релизу.

В PostgreSQL ту же работу выполняет bun run db:setup:pg, с таблицами вместо коллекций. Единственное структурное различие — истечение срока: в PostgreSQL нет TTL-индексов, поэтому работающий сервер сам удаляет просроченные строки. bun run db:migrate — одна и та же команда для обоих бэкендов.

Заметка

db:setup завершается с ненулевым кодом, если объявленное им ограничение не действует: например, уникальный индекс, который не удалось создать, потому что данные его уже нарушают. Конвейер развёртывания должен проваливать деплой по этому коду выхода, а не записывать предупреждение в лог; поставляемый fly.toml делает именно так.

Примечания

• Консоли администратора нужно развёртывание с базой данных. NODE_ENV=test подставляет адаптер в памяти, который не сохраняет начальные данные между перезапусками.
• Настройки сервера считываются при запуске из хранилища конфигурации, а изменение, сохранённое в консоли, сразу применяется на том экземпляре, где его сохранили; остальные экземпляры получают его при следующем перезапуске. Все настройки перечислены в справочнике настроек.