FAQ и решение проблем

Ответы на частые вопросы и решения типичных проблем.

Часто задаваемые вопросы

Общие вопросы

Чем Runium отличается от PM2?

Аспект	Runium	PM2
Фокус	Управление множеством разнородных процессов	Управление Node.js приложениями
Зависимости	Встроенная поддержка зависимостей между задачами	Нет встроенной поддержки
Триггеры	Таймеры, события, file watchers	Ограниченно (watch mode)
Конфигурация	Единый JSON с макросами	ecosystem.config.js
Плагины	Расширяемая архитектура	Ограниченно

Runium лучше подходит для сложных сценариев с множеством взаимосвязанных процессов, в то время как PM2 оптимизирован для production-деплоя Node.js приложений.

Чем Runium отличается от Docker Compose?

Docker Compose управляет контейнерами, Runium - процессами. Runium может:

• запускать обычные процессы без контейнеризации
• использовать Docker через плагин @runium/plugin-docker
• комбинировать контейнеры и обычные процессы в одном проекте
• предоставлять более гибкую логику зависимостей и триггеров

Поддерживается ли Windows?

Да, Runium работает на Windows, macOS и Linux. Используйте макрос $platform() для кроссплатформенных конфигураций:

{
  "command": "$eq($platform(), win32, cmd, /bin/sh)",
  "arguments": ["$eq($platform(), win32, /c, -c)", "echo Hello"]
}

Конфигурация

Как передать переменные окружения в задачу?

Через свойство env в опциях задачи:

{
  "id": "my-task",
  "options": {
    "command": "node",
    "arguments": ["app.js"],
    "env": {
      "NODE_ENV": "development",
      "PORT": "3000",
      "API_KEY": "$env(API_KEY)"
    }
  }
}

Как использовать переменные из .env файла?

Укажите путь к файлу при запуске проекта:

runium project start my-project --env .env

Или в файле .runiumrc.json:

{
  "env": {
    "path": [".env", ".env.local"]
  }
}

Как сделать задачу, которая не запускается автоматически?

Установите mode: "deferred":

{
  "id": "non-automatic-task",
  "mode": "deferred",
  "options": {
    "command": "echo",
    "arguments": ["This task is started by handler of another task or trigger"]
  }
}

Как запустить задачу в определённой директории?

Используйте свойство cwd:

{
  "id": "frontend",
  "options": {
    "command": "npm",
    "arguments": ["run", "dev"],
    "cwd": "./packages/frontend"
  }
}

Как указать относительный путь?

Используйте макрос $path():

{
  "options": {
    "command": "node",
    "arguments": ["$path(../scripts/build.js)"]
  }
}

Зависимости и порядок запуска

Как дождаться полной готовности сервиса, а не только запуска?

По умолчанию status: "started" означает, что процесс запущен. Для проверки реальной готовности используйте health-check задачу:

{
  "tasks": [
    {
      "id": "database",
      "options": {
        "command": "docker",
        "arguments": ["run", "postgres"]
      }
    },
    {
      "id": "db-health-check",
      "options": {
        "command": "pg_isready",
        "arguments": ["-h", "localhost", "-p", "5432"]
      },
      "dependencies": [
        { "taskId": "database", "condition": { "status": "started" } }
      ],
      "restart": {
        "policy": "on-failure",
        "maxRetries": 10,
        "delay": 1000
      }
    },
    {
      "id": "api",
      "options": { "command": "npm", "arguments": ["start"] },
      "dependencies": [
        { "taskId": "db-health-check", "condition": { "status": "completed" } }
      ]
    }
  ]
}

Что делать при циклических зависимостях?

Runium автоматически обнаруживает циклические зависимости и выдаёт ошибку. Пересмотрите архитектуру:

• возможно, одна из зависимостей не нужна
• используйте триггеры вместо зависимостей для сложных сценариев

Триггеры

Как запустить задачу по расписанию?

Используйте триггер interval:

{
  "triggers": [
    {
      "id": "every-hour",
      "type": "interval",
      "options": { "interval": 3600000 },
      "action": {
        "type": "start-task",
        "options": { "taskId": "backup" }
      }
    }
  ]
}

Как запустить задачу при изменении файлов?

Установите плагин @runium/plugin-file-watch:

npm install @runium/plugin-file-watch
runium plugin add @runium/plugin-file-watch

И добавьте триггер:

{
  "triggers": [
    {
      "id": "watch-src",
      "type": "file-watch",
      "options": {
        "watch": {
          "path": ["./src"],
          "events": ["change", "add"]
        }
      },
      "action": {
        "type": "start-task",
        "options": { "taskId": "server" }
      }
    }
  ]
}

---

Решение проблем

Ошибки при запуске

Error: ENOENT: no such file or directory

Причина: Указанный файл или команда не найдены.

Решение:

1. Проверьте, что команда доступна в PATH: which <command>
2. Используйте абсолютный путь или макрос $path()
3. Проверьте свойство cwd - возможно, рабочая директория неверна

Error: spawn EACCES

Причина: Нет прав на выполнение файла.

Решение:

chmod +x ./script.sh

Error: Invalid project configuration

Причина: Ошибка в JSON-конфигурации.

Решение:

1. Проверьте синтаксис JSON (запятые, кавычки, скобки)
2. Используйте команду валидации:

   runium project validate -f project.json

3. Проверьте, что все обязательные поля заполнены (id, tasks, options.command)

Error: Circular dependency detected

Причина: Задачи зависят друг от друга циклически (A → B → C → A).

Решение:

1. Проверьте цепочку зависимостей
2. Удалите лишнюю зависимость
3. Используйте триггеры вместо зависимостей

Проблемы с задачами

Задача сразу переходит в completed

Причина: Команда выполняется мгновенно (например, echo).

Решение: Это нормальное поведение для команд, которые завершаются сразу. Если нужен долгоживущий процесс, убедитесь, что команда не завершается (например, сервер должен оставаться запущенным).

Задача зависает в starting

Причина: Процесс не переходит в состояние started.

Решение:

1. Проверьте, что процесс действительно запускается
2. Проверьте логи: runium project status my-project
3. Попробуйте запустить команду напрямую в терминале

Переменные окружения не применяются

Причина: Переменные не передаются в дочерний процесс.

Решение:

1. Проверьте синтаксис макроса $env():

   "env": {
     "MY_VAR": "$env(MY_VAR, default_value)"
   }

2. Убедитесь, что .env файл загружен (опция --env)

Плагин установлен, но не работает

Причина: Плагин отключён.

Решение:

1. Проверьте статус: runium plugin list
2. Включите плагин: runium plugin enable <plugin-name>

Проблемы с профилями

Изменения не применяются

Причина: Используется другой профиль или файл .runiumrc.json переопределяет настройки.

Решение:

1. Проверьте текущий профиль: настройки применяются из ~/.runium по умолчанию
2. Проверьте наличие .runiumrc.json в текущей директории
3. Явно укажите профиль: runium --profile ./my-profile project start

---

Отладка

Включение режима отладки

runium --debug project start my-project

Или в .runiumrc.json:

{
  "output": {
    "debug": true
  }
}

Валидация конфигурации

Перед запуском проверьте конфигурацию:

runium project validate -f project.json

Просмотр состояния проекта

runium project status my-project