Путь диагностики для инженеров

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

От первого SSH-подключения и инструментов Xcode до CI/CD-исполнителей и сети узла: сначала приведены команды проверки, затем условия интерпретации. Если восстановить работу не удаётся, приложите номер заказа, узел, время и обезличенные логи к обращению.

Приоритетный путь
Первое подключение за 4 шага
Область проблемы
6 типовых задач
Связь с поддержкой
Электронная почта и обращения из консоли
ONCEMAC SUPPORT BOARD Чек-лист узла
Можно начинать диагностику
A1
Проверьте данные подключения Адрес хоста, имя пользователя, файл ключа
Подключение
B2
Проверьте инструменты Xcode, путь к CLT, логи сборки
Сборка
C3
Проверьте границы выполнения Диск, сеть, процессы и история перезапусков
Узел
Перед отправкой удалите ключи, токены доступа и полный IP-адрес
Быстрый поиск

Находите ответы по задаче — читать всё с начала не нужно.

Выберите подключение, Xcode, CI/CD, хранилище, сеть или продление аренды — страница покажет нужный раздел. Также можно искать по команде, симптому или названию инструмента.

Сейчас показаны все 6 категорий справки.

В первую очередь для новых пользователей

Первое SSH-подключение за четыре шага.

Используйте данные со страницы сведений о текущем экземпляре в консоли. Не восстанавливайте адрес хоста по старым обращениям или историческим командам: после повторной выдачи узла заново скопируйте актуальные данные.

  1. 01

    Скопируйте актуальные данные подключения

    Откройте сведения об экземпляре в консоли и скопируйте адрес хоста, имя пользователя SSH, порт и данные ключа. Сначала убедитесь, что заказ и узел выбраны верно, затем вставьте команду в локальный терминал.

  2. 02

    Сохраните закрытый ключ в защищённом каталоге

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

  3. 03

    Ограничьте права локального файла

    В локальном терминале macOS или Linux выполните chmod 600 ~/.ssh/oncemac_key. Если SSH сообщает, что права на закрытый ключ слишком широкие, сначала исправьте права — не отключайте проверки безопасности в обход проблемы.

  4. 04

    Подключитесь и проверьте идентификатор узла

    Выполните команду SSH из консоли. При первом подключении проверьте источник отпечатка хоста; после входа на узел выполните hostname,sw_vers и whoami, чтобы подтвердить хост, систему и текущего пользователя.

Порядок выполнения команд

Сначала проверьте подключение и версии, затем запускайте полную сборку.

За один цикл диагностики меняйте только одну переменную. Сначала убедитесь в стабильности SSH-сеанса, затем проверьте версию Xcode и только после этого запускайте сборку с пакетом результатов и логами. Так можно отделить проблемы подключения от проблем инструментов и самого проекта.

  • Слой подключенияПосле успешного SSH-подключения запишите имя узла и текущего пользователя.
  • Слой инструментовПроверьте используемую версию Xcode и каталог разработчика.
  • Слой проектаСохраните scheme, destination, код выхода и логи.
  • Слой автоматизацииДля обращения прикладывайте только обезличенный вывод fastlane.
once-node / build-diagnostics
SSH
$ ssh -i ~/.ssh/oncemac_key user@host
Last login: current session
connected: once-node

$ xcodebuild -version
Xcode 16.x
Build version 16x

$ xcode-select -p
/Applications/Xcode.app/Contents/Developer

$ set -o pipefail
$ xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -destination 'generic/platform=iOS' \
  -resultBundlePath ./BuildResults.xcresult \
  build | tee build.log

** BUILD SUCCEEDED **

$ bundle exec fastlane ios build
[fastlane] resolving dependencies
[fastlane] archive completed
[fastlane] lane finished successfully
Проверка инструментов

Разберите проблемы Xcode на версии, пути, подпись и логи.

Фразы вроде «локально собирается, а на узле — нет» обычно недостаточно для поиска причины. Сопоставьте один и тот же коммит, lock-файл зависимостей, scheme, destination и переменные среды, затем сравните вывод в обеих средах.

XC-01

Проверьте версию Xcode

Выполните xcodebuild -version, запишите основную версию и Build version. Если конвейер зависит от конкретной версии, выводите её в начале задачи, а не проверяйте только при первоначальной настройке.

xcodebuild -version
xcrun --find simctl
swift --version
XC-02

Проверьте каталог разработчика

Выполните xcode-select -p для проверки текущего пути Command Line Tools. Если используется несколько версий Xcode, явно задайте в среде исполнителя DEVELOPER_DIR, чтобы интерактивный сеанс и автоматизированная задача не читали разные пути.

xcode-select -p
echo "$DEVELOPER_DIR"
xcrun --sdk iphoneos --show-sdk-path
XC-03

Проверьте среду подписи

Сначала убедитесь, что связка ключей доступна, а имя сертификата соответствует условиям provisioning profile, затем проверьте Team, Bundle Identifier и способ подписи в проекте. В обращение достаточно добавить обезличенный фрагмент ошибки — не прикладывайте сертификаты, закрытые ключи или пароли.

security list-keychains
security find-identity -v -p codesigning
xcodebuild -showBuildSettings
XC-04

Экспортируйте проверяемые логи

С помощью set -o pipefail сохраните реальный статус выхода, а с помощью tee запишите данные в лог. При сложных сбоях рекомендуется создать .xcresultи перед отправкой удалить имена пользователей, пути, токены и рабочие данные.

set -o pipefail
xcodebuild build | tee build.log
echo "${PIPESTATUS[0]}"
Автоматизированные исполнители

Перед подключением CI/CD зафиксируйте пользователя выполнения и рабочий каталог.

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

RUNNER / 01

Самостоятельно размещаемый исполнитель GitHub Actions

  • Убедитесь, что пользователь macOS службы исполнителя совпадает с пользователем ручного SSH-тестирования.
  • Проверьте место регистрации на уровне репозитория, организации или предприятия, чтобы задача не получила неверные метки.
  • Назначьте узлу понятные метки и явно используйте соответствующее условие runs-on .
  • Убедитесь, что неинтерактивная оболочка видит нужные PATH, Ruby, Homebrew и пути Xcode.
  • Перед запуском параллельных задач проверьте DerivedData, кэш менеджера пакетов и свободное место на диске.
RUNNER / 02

GitLab Runner

  • Проверьте тип executor, метки runner, правила защищённых веток и условия соответствия задач.
  • Проверьте пользователя, HOME и контекст связки ключей для LaunchAgent или процесса службы.
  • В начале задачи выведите whoami,pwd, версию Xcode и доступное место на диске.
  • Ключ кэша должен включать lock-файл зависимостей или версию инструментов, чтобы не использовать несовместимый кэш.
  • При сбое сохраните логи job, код выхода и состояние службы runner.
RUNNER / 03

Узел Jenkins

  • Убедитесь, что способ запуска agent, рабочий каталог и метки узла соответствуют условиям Pipeline.
  • Проверьте, что пользователь Jenkins может читать репозиторий, каталог сборки и нужную связку ключей.
  • Внесите выбор Xcode, установку зависимостей и команду сборки в проверяемый Pipeline.
  • Ограничьте число параллельных исполнителей на одном физическом узле, чтобы избежать конкуренции за диск и память.
  • Перед архивацией запишите размер workspace, путь к результатам сборки и стратегию очистки.
Воспроизводимая миграция

Переносите файлы, а не непроверяемую старую среду.

Восстанавливайте инструменты прежде всего из Git, lock-файлов и Brewfile; переносите только необходимые рабочие каталоги и кэши. Копирование всей среды старого пользователя переносит на новый узел устаревшие настройки, абсолютные пути и конфиденциальные данные.

MIGRATION MANIFEST Чек-лист миграции среды
Исходный код Клонируйте Git и проверьте хэш коммита Не копируйте старое рабочее дерево с незакоммиченными секретами
Системные инструменты Декларативное восстановление через Brewfile После восстановления повторно проверьте версии и PATH
Файлы проекта Инкрементальная передача через rsync Явно исключите каталоги кэша, логов и учётных данных
Кэш сборки Переносите выборочно с учётом версии инструментов При изменении версии сначала создайте кэш заново

Перенесите рабочий каталог с помощью rsync

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

rsync -avhn \
  --exclude '.git' \
  --exclude 'DerivedData' \
  ./Project/ user@host:~/Project/

Зафиксируйте состояние кода в Git

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

git status --short
git rev-parse HEAD
git clone repository-url
git checkout commit-hash

Восстановите инструменты через Brewfile

Перед экспортом проверьте список и удалите ненужное ПО. После восстановления проверьте версии команд по отдельности: успешное завершение установки само по себе не подтверждает работоспособность среды.

brew bundle dump --file Brewfile
brew bundle check --file Brewfile
brew bundle install --file Brewfile
Отдельно проверьте конфиденциальные данные перед миграцией

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

Краткий путь диагностики

Сначала исключите проверяемые условия, затем передайте полный контекст.

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

Не удаётся подключиться Тайм-аут SSH, отказ в подключении или ошибка аутентификации ключа
  1. Заново скопируйте из сведений о текущем экземпляре адрес хоста, порт и имя пользователя; убедитесь, что не используете данные старого заказа.
  2. Выполните chmod 600 для проверки прав локального закрытого ключа и убедитесь, что путь к ключу в команде существует.
  3. Используйте ssh -vvv для получения данных о подключении; перед отправкой обращения удалите персональные данные из полного адреса, имени пользователя и пути к ключу.
  4. Повторите проверку через другую доверенную сеть, чтобы отличить локальные ограничения выхода от проблемы подключения к узлу.
  5. Укажите в обращении номер заказа, узел, время, тип ошибки и обезличенный фрагмент отладочного вывода.
Сбой сборки Завершение на этапе xcodebuild, разрешения зависимостей или подписи
  1. Запишите хэш коммита, scheme, destination, версию Xcode и каталог разработчика.
  2. Чётко разделите ошибки разрешения зависимостей, компиляции, тестов, подписи и архивации.
  3. Используйте set -o pipefail для сохранения реального кода выхода и экспортируйте .xcresult или полный лог.
  4. Не обновляйте одновременно зависимости, не переключайте Xcode и не очищайте весь кэш: за раз меняйте только одну переменную.
  5. Приложите к обращению логи до и после первой ключевой ошибки, удалив токены репозитория, материалы подписи и рабочие данные.
Недостаточно места на диске Прерывание сборки, сбой архивации или постоянный рост рабочего каталога
  1. Выполните df -h для проверки свободного места на томах, затем используйте du -sh для поиска рабочих областей, DerivedData, архивов и кэшей зависимостей.
  2. Убедитесь, что для логов, результатов тестов и старых артефактов задан срок хранения, а не удаляйте весь каталог пользователя.
  3. Перед очисткой сохраните артефакты, которые ещё потребуется скачать, и убедитесь, что соответствующие каталоги не используются выполняемой задачей.
  4. Если постоянная потребность в месте превышает базовый SSD, рассмотрите в конфигурации дополнительные варианты +1TB SSD или +2TB SSD.
  5. Приложите к обращению сводку использования диска, растущий каталог и время сбойной задачи; не загружайте исходные файлы проекта.
Нестабильная сеть Зависание SSH, ошибка загрузки зависимостей или нестабильное соединение с репозиторием
  1. Отдельно зафиксируйте симптомы на участке от локальной сети до узла и от узла до целевого репозитория или источника зависимостей; не объединяйте эти участки в один вывод.
  2. При непрерывном измерении укажите место тестирования, оператора связи, узел, команду и число образцов: единичный ping не отражает стабильность соединения.
  3. Проверьте DNS-разрешение, переменные среды прокси, удалённый Git и источники менеджера пакетов на соответствие конфигурации команды.
  4. Для сравнения используйте другую доверенную локальную сеть, чтобы не принять локальный Wi‑Fi или политику выхода за неисправность узла.
  5. Приложите к обращению период возникновения, тип цели, долю сбоев и обезличенный вывод.
Перезапуск узла Разрыв сеанса, невосстановившаяся служба или отключённый исполнитель
  1. Сначала проверьте состояние текущего узла в консоли; не отправляйте повторно команды управления питанием.
  2. После восстановления подключения выполните uptimeи сопоставьте время запуска со временем возникновения проблемы.
  3. Проверьте способ запуска и текущее состояние службы self-hosted executor, GitLab Runner или агента Jenkins.
  4. Убедитесь, что рабочая область сборки цела, и повторно проверьте артефакты незавершённых задач; не используйте архив с неизвестным состоянием.
  5. Приложите к обращению номер заказа, узел, время, симптомы до и после перезапуска и названия служб, которые нужно восстановить.
Поддержка специалистов

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

По вопросам текущих заказов, состояния узла и продления аренды прежде всего создавайте обращение в консоли; вопросы конфигурации и использования до оформления заказа можно отправить по электронной почте. Единственный адрес для связи: support@oncemac.com.

SUPPORT PACKET Пакет данных для обращения
01

Заказ и узел

Укажите номер заказа, название конфигурации и регион узла; не передавайте платёжные реквизиты или полные данные счёта.

02

Время возникновения

Укажите часовой пояс, время первого появления, время последнего воспроизведения и сохраняется ли проблема.

03

Действия для воспроизведения

Перечислите команды, ожидаемый и фактический результат и код выхода — не ограничивайтесь фразой «не работает».

04

Обезличенные логи

Сохраните контекст ошибки, удалив ключи, токены, пароли, полный IP-адрес, материалы подписи и рабочие данные.

05

Уже выполненные проверки

Опишите проверенные сеть, версии, пути, диск и результаты повторных попыток, чтобы не повторять неэффективные шаги.

Текущий заказ

Создать обращение в консоли

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

Открыть консоль
Вопросы до покупки и общие консультации

Отправить структурированное письмо

Укажите назначение, целевой узел, версию Xcode, число параллельных сборок, потребность в хранилище и желаемое время активации.

support@oncemac.com
Выделенный физический узел Mac mini

Нужен новый узел? Выберите конфигурацию и срок аренды.

OnceMac предлагает 3 конфигурации в продаже и 6 узлов, работающих 365 дней в году. Все заказы рассчитываются в долларах США; управлять заказами, узлами и обращениями можно из одной консоли.