Подробное описание структуры директорий ServBay

ServBay — это локальная среда веб-разработки, специально созданная для macOS с продуманной и лаконичной структурой каталогов. Если вы знакомы с Linux/Unix, вы заметите, что организация файлов ServBay во многом повторяет стандартную структуру этих систем, что облегчает быстрое управление и поиск нужных файлов.

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

Типичная структура директорий установки ServBay выглядит так:

ServBay
|____backup                 # Директория для резервных копий
| |____config               # Бэкапы конфигураций
| |____databases            # Бэкапы баз данных
| |____ssl                  # Бэкапы SSL-сертификатов
| |____websites             # Бэкапы файлов сайтов
|____bin                    # Директория пользовательских исполняемых файлов (символическая ссылка на package/bin)
|____data                   # Внутренняя директория данных ServBay
| |____servbay              # Ключевые настройки и служебные данные ServBay
|____db                     # Каталог хранения файлов баз данных
| |____mariadb              # Данные MariaDB
| |____mongodb              # Данные MongoDB
| |____mysql                # Данные MySQL
| |____postgresql           # Данные PostgreSQL
| |____redis                # Данные Redis
|____etc                    # Каталог конфигурационных файлов (символическая ссылка на package/etc)
|____logs                   # Каталог логов (символическая ссылка на package/var/log)
|____package                # Каталог программных пакетов
| |____bin                  # Исполняемые файлы пакетов
| |____common               # Общие и dev-библиотеки
| | |____imap-uw
| | |____include            # Заголовочные файлы (ServBay Development Library)
| | |____lib                # Динамические/статические библиотеки (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Фактическое местоположение конфигов пакетов
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (конфиги других пакетов: Python, Go, Java, Ruby, Rust и др.)
| |____<package_name>       # Главные директории отдельных пакетов
| | |____<major_version>   # Каталог основной версии
| | | |____<full_version> # Каталог полного номера версии (содержит инсталляцию)
| | | |____current         # Символическая ссылка на актуальную/последнюю версию
| | |____...
| |____sbin                 # Системные исполняемые файлы пакетов
| |____var                  # Переменные данные пакетов (напр., где реально хранятся логи)
| | |____log                # Физическое размещение логов
| | |____run                # Файлы работы (например, .pid)
|____sbin                   # Директория системных исполняемых файлов (символическая ссылка на package/sbin)
|____script                 # Служебные внутренние скрипты ServBay
|____ssl                    # Каталог SSL-сертификатов
| |____acme                 # SSL-сертификаты, полученные через ACME
| |____caddy                # Автоматические сертификаты Caddy
| |____import               # Импортированные пользователем сертификаты
| |____private              # Сертификаты пользовательского центра (User CA)
| |____public               # Публичные CA-сертификаты
|____tmp                    # Каталог временных и socket-файлов
|____www                    # Корневая директория сайтов
| |____servbay              # Демо-каталог сайта

Далее подробно разберём назначение каждого каталога.

Главная директория ServBay

Главный каталог ServBay по умолчанию располагается по адресу /Applications/ServBay. Здесь хранятся все связанные с ServBay пакеты, конфигурации, данные, логи и т.п.

Для безопасности среды и ваших данных рекомендуется регулярно создавать резервные копии основной директории с помощью Time Machine или других инструментов — просто бэкапите весь каталог /Applications/ServBay.

Корневая директория сайтов (www)

Основные файлы ваших сайтов располагаются в /Applications/ServBay/www — здесь размещаются все проекты для локальной разработки.

Чтобы хранить проекты удобно и понятно, для каждого отдельного сайта или виртуального хоста (в терминологии ServBay — «сайт») рекомендуется создавать свой уникальный подпапку.

Например, для сайтов web.servbay.demo, api.servbay.demo, new.servbay.local рекомендуемая структура:

/Applications/ServBay/www
|____servbay.demo           # Все сайты для *.servbay.demo
| |____web               # Файлы web.servbay.demo
| |____api               # Файлы api.servbay.demo
|____servbay.local          # Все сайты для *.servbay.local
| |____new               # Файлы new.servbay.local
|____myproject              # Для отдельных проектов, например myproject.local

Эта организация помогает быстро ориентироваться в проектах и доменах.

Директория конфигураций (etc)

Каталог конфигов /Applications/ServBay/etc на самом деле символическая ссылка на /Applications/ServBay/package/etc. Здесь собрано всё: основные конфиги всех установленных пакетов (PHP, MariaDB, Nginx, Caddy и т. д.).

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

Примеры хранения для популярных пакетов:

PHP (etc/php)

Настройки PHP структурированы по принципу «двухуровневой версии», то есть для каждой основной версии (5.6, 7.4, 8.3 и др.) есть свой каталог со структурой:

php
|____5.6                    # Настройки PHP 5.6
| |____conf.d               # Конфиги расширений
| |____php.ini              # Глобальный php.ini
|____7.4                    # Настройки PHP 7.4
| |____conf.d               # Конфиги расширений
| |____php-fpm.d            # Конфиги пулов FPM
| |____php-fpm.conf         # Главный конфиг PHP-FPM
| |____php.ini              # Глобальный php.ini
|____8.3                    # Настройки PHP 8.3
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (другие версии PHP)

В каталоге каждой версии лежат php.ini (глобальные настройки PHP), php-fpm.conf (если поддерживается FPM), pear.conf и пр. После правки обязательно перезапускайте соответствующий PHP-FPM сервис через панель или команду servbayctl.

В conf.d содержатся расширения (например, xdebug.ini, opcache.ini, redis.ini и прочее) — редактируйте здесь загрузку расширений, потом перезапускайте PHP-FPM.

Примечание: ServBay использует одну и ту же конфигурацию для всех минорных версий одной основной ветки PHP. Например, 8.3.3 и 8.3.5 читают настройки из etc/php/8.3.

MariaDB / MySQL / PostgreSQL (etc/mariadb, etc/mysql, etc/postgresql)

Конфиги баз данных также организованы по версиям: например, etc/mariadb/11.2. Внутри таких папок вы найдёте ключевые файлы my.cnf (для MariaDB/MySQL), postgresql.conf (PostgreSQL). После изменения всегда перезапускайте сервис. Минорные версии используют одну конфигу на основную ветку.

Сброс пароля пользователя root для MariaDB/MySQL/PostgreSQL выполняется не по редактированию конфигов, а с помощью специальных команд или функций панели ServBay.

Caddy (etc/caddy)

Основной файл настроек Caddy (Caddyfile) располагается в etc/caddy.

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

Nginx (etc/nginx)

Главный конфиг nginx.conf лежит в etc/nginx. Как и с Caddy, ServBay самостоятельно включает в него ваши сайты; ручное редактирование главного файла через чур, рекомендуем через панель.

dnsmasq (etc/dnsmasq)

В папке лежат dnsmasq.conf (базовая настройка) и domains.conf — файл, который ServBay сам создаёт на основе локальных доменов.

Важное предупреждение: Оба файла управляются ServBay. Не изменяйте их вручную — иначе сайты могут стать недоступны.

Другие конфиги пакетов

Все поддерживаемые ServBay языки и платформы (Node.js, Python, Go, Java, Ruby, Rust и др.) — если требуется глобальный сервистный конфиг — хранятся в подкаталогах etc с той же структурой по версиям.

Внутренняя директория данных ServBay (data/servbay)

/Applications/ServBay/data/servbay

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

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

Исполняемые файлы и скрипты (bin, sbin, script)

/Applications/ServBay/bin -> package/bin
/Applications/ServBay/sbin -> package/sbin
/Applications/ServBay/script

Все исполняемые файлы ServBay размещены в bin (пользовательские, runtime) и sbin (системные). Обе директории — символические ссылки на реальные папки package/bin и package/sbin. Сюда попадают инструменты и все языковые рантаймы.

Благодаря тому, что ServBay добавляет эти папки в переменную PATH (при запуске), вы можете вызывать команды прямо из терминала:

• Утилиты (curl, openssl, frpc и др.)
• Рантаймы языков с разными версиями (php (по умолчанию), php-5.6, php-7.4, php-8.3, node, node-16, node-18, python3, go, java, ruby, rustc и др.)
• Клиенты баз данных (mysql, psql, mongosh, redis-cli и др.)

В папке script (/Applications/ServBay/script) находятся служебные внутренние скрипты — запуск/остановка сервисов, инициализация БД, системные задачи. Чаще используйте оболочку servbayctl вместо непосредственного вызова этих скриптов — она всё упрощает.

Пример для запуска PHP 7.4 FPM:

servbayctl start php 7.4

Утилита servbayctl лежит в /Applications/ServBay/bin.

Каталог файлов баз данных (db)

/Applications/ServBay/db

В этой директории хранятся данные всех установленных баз данных ServBay, организованные по типу и версии:

• /Applications/ServBay/db/mariadb/<major_version>: данные MariaDB
• /Applications/ServBay/db/mysql/<major_version>: данные MySQL
• /Applications/ServBay/db/postgresql/<major_version>: данные PostgreSQL
• /Applications/ServBay/db/mongodb: данные MongoDB
• /Applications/ServBay/db/redis: данные Redis

Каждая основная версия пакета БД использует одну папку данных, все минорные используют её же (например, MariaDB 11.2.x — каталог 11.2).

Важно: тут хранятся все ваши локальные БД! Обязательно делайте полный бэкап /Applications/ServBay/db перед апгрейдами ServBay или переносом системы. Автоматическое резервное копирование также включает папку db.

Каталог логов (logs)

/Applications/ServBay/logs -> package/var/log

Вся логика и состояния сервисов ServBay ведутся в /Applications/ServBay/logs, что фактически является ссылкой на /Applications/ServBay/package/var/log. Такая централизация облегчает просмотр и мониторинг ошибок и активности.

Логи сервисов структурированы по подпапкам:

• logs/caddy/ или logs/nginx/: логи доступа и ошибок Caddy/Nginx, разложенные по доменам сайтов
• logs/php/: логи работы PHP-FPM (php-fpm.log) и ошибок исполнения PHP (errors.log). errors.log — все фатальные ошибки, не перехваченные вашим приложением или фреймворком.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: логи ошибок, медленных запросов и т.п. для соответствующих БД
• Другое (Python, Go, Java, Ruby, Rust и др.) — логи размещены в аналогичных подпапках

Примечание: логи могут со временем занимать довольно много места (особенно в активных проектах). Регулярно следите и очищайте старые/ненужные логи для экономии диска.

Каталог пакетов (package)

/Applications/ServBay/package

Здесь размещаются все установленные пакеты ServBay — каждый в собственной папке по схеме имя/основная_версия/полная_версия. Для примера: PHP установлен в /Applications/ServBay/package/php/8.3/8.3.7.

Управление версиями (установка, удаление, переключение) удобно реализовано через панель управления.

Неиспользуемые старые версии можно вручную удалить (например, /Applications/ServBay/package/php/8.2/8.2.10) для экономии места.

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

Каталог SSL сертификатов (ssl)

/Applications/ServBay/ssl

В этой папке — все SSL/TLS сертификаты:

• Автоматически полученные сертификаты ACME для ваших локальных сайтов (ssl/caddy или ssl/acme, в зависимости от используемого веб-сервера)
• Корневой CA для локального HTTPS от ServBay (User CA) и публичный CA (public CA) — в ssl/private и ssl/public. Добавьте их в доверенные сертификаты macOS, чтобы не видеть предупреждений при работе под HTTPS в браузере.

Каталог резервных копий (backup)

/Applications/ServBay/backup

В этом каталоге хранятся резервные копии, созданные встроенной системой ServBay:

• backup/config: Бэкапы всех ключевых конфигов
• backup/databases: Бэкапы всех баз данных MariaDB, MySQL, PostgreSQL, MongoDB и других
• backup/ssl: Резервные копии SSL сертификатов
• backup/websites: Резервные копии всех сайтов из /Applications/ServBay/www

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

Каталог временных файлов (tmp)

/Applications/ServBay/tmp

Здесь размещаются временные файлы и сокеты, создаваемые сервисами во время работы.

• .pid — хранят PID-идентификаторы запущенных процессов
• Файлы socket — например, php-cgi.sock, mysql.sock, pgsql.sock и др., они нужны для взаимодействия между локальными сервисами посредством Unix-сокета (как правило, такое соединение быстрее, чем по TCP и с минимальными задержками).

Общие компоненты и dev-библиотеки (package/common)

/Applications/ServBay/package/common

Каталог со всеми общими библиотеками, компонентами и (опционально) dev-заголовками, от которых зависят все пакеты ServBay.

Если вы установили ServBay Development Library, внутри появятся include (заголовочные .h-файлы) и lib (статические .a или .la библиотеки). Это крайне полезно для тех, кто компилирует PHP модули или другие расширения с опорой на внутренние библиотеки ServBay.

Важно: не удаляйте файлы *.dylib из package/common/lib — они критически важны для работы приложений! Их отсутствие приведёт к ошибкам запуска из-за недостающих зависимостей.

Итоги

Структура директорий ServBay строго разделяет пакеты, настройки, данные, логи и сайт-файлы, ориентируясь на стандарты Unix-систем. Это делает локальную разработку максимально управляемой и прозрачной. Хорошее знание структуры позволит вам ускорить workflow и проще администрировать проекты. Настоятельно советуем регулярно бэкапить критические каталоги (data, db), чтобы обезопасить ваши разработки от потери данных.