ServBay 目录结构详解

ServBay 是一个专为 macOS 设计的本地 Web 开发环境，其目录结构设计简洁且有条理。如果您熟悉 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               # 公共库和开发库
| | |____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                  # 软件包变量数据 (如 logs 的实际位置)
| | |____log                # 日志实际存储位置
| | |____run                # 运行时文件 (如 .pid 文件)
|____sbin                   # 系统可执行文件目录 (软链接至 package/sbin)
|____script                 # ServBay 内部管理脚本
|____ssl                    # SSL 证书目录
| |____acme                 # 通过 ACME 协议申请的 SSL 证书
| |____caddy                # Caddy 自动生成的 SSL 证书
| |____import               # 用户导入的第三方 SSL 证书
| |____private              # ServBay User CA
| |____public               # ServBay 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。这是 ServBay 安装的所有软件包（如 PHP、MariaDB、Nginx、Caddy 等）存放其主要配置文件的位置。

在日常使用中，您可以直接通过 /Applications/ServBay/etc 路径访问和修改配置文件。修改大多数配置文件后，通常需要重启对应的服务才能使更改生效。

以下是常见软件包的配置文件存放示例：

PHP (`etc/php`)

PHP 配置文件目录采用两层结构，区分不同的 PHP 大版本。例如，在 etc/php 下，您会看到 5.6、7.4、8.3 等目录，每个目录对应一个 PHP 大版本。典型结构如下：

php
|____5.6                    # PHP 5.6 的配置
| |____conf.d               # 扩展配置文件目录
| |____php.ini              # PHP 主配置文件
|____7.4                    # PHP 7.4 的配置
| |____conf.d               # 扩展配置文件目录
| |____php-fpm.d            # PHP-FPM 池配置目录
| |____php-fpm.conf         # PHP-FPM 主配置文件
| |____php.ini              # PHP 主配置文件
|____8.3                    # PHP 8.3 的配置
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (其他 PHP 版本)

每个版本目录中包含 php.ini（PHP 主配置文件）、php-fpm.conf（PHP-FPM 主配置文件，如果该版本支持 FPM）、pear.conf 等文件。修改这些文件后，需要通过 ServBay 控制面板或 servbayctl 命令重启对应的 PHP-FPM 服务以应用最新设置。

conf.d 目录是 PHP 扩展配置目录，其中包含 xdebug.ini、opcache.ini、redis.ini 等文件。编辑这些文件可以加载、卸载或修改各个 PHP 扩展的设置。同样地，修改后需要重启对应的 PHP-FPM 服务。

注意：ServBay 设计为每个 PHP 小版本与同一大版本共用一份配置文件。例如，PHP 8.3.3 和 8.3.5 都使用 etc/php/8.3 目录下的配置文件。

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

数据库软件的配置文件目录也采用版本区分结构，例如 etc/mariadb/11.2。通常在这些文件夹中会找到主配置文件（如 MariaDB/MySQL 的 my.cnf，PostgreSQL 的 postgresql.conf）。修改这些文件后，需要重启对应的数据库服务才能生效。每个小版本与同一大版本共用一份配置。

重置 MariaDB、MySQL 或 PostgreSQL 数据库的 root 用户密码通常不直接修改配置文件，而是通过特定的命令行工具或 ServBay 控制面板功能完成。

Caddy (`etc/caddy`)

Caddy 的配置文件（Caddyfile）位于 etc/caddy 目录下。

重要提示：ServBay 会根据您在控制面板中配置的“网站”信息自动生成 Caddyfile。请勿手动修改此文件，因为您的更改可能会在 ServBay 下次生成配置文件时被自动覆盖。如需为特定网站添加自定义 Caddy 配置，请直接在 ServBay 控制面板的网站设置中进行。

Nginx (`etc/nginx`)

Nginx 的主配置文件 nginx.conf 位于 etc/nginx 目录下。与 Caddy 类似，ServBay 也会根据网站配置自动生成或包含网站相关的配置片段。手动修改主配置文件需谨慎，通常建议通过 ServBay 控制面板管理网站配置。

dnsmasq (`etc/dnsmasq`)

dnsmasq 的配置文件目录包含 dnsmasq.conf（默认配置文件）和 domains.conf（ServBay 根据您配置的本地域名自动生成的文件）。

重要提示：dnsmasq.conf 和 domains.conf 文件均由 ServBay 自动生成和管理，以确保本地域名解析正常工作。请勿手动修改这些文件，否则可能导致本地网站无法访问。

其他软件包配置

对于 ServBay 支持的其他软件包，如 Node.js、Python、Go、Java、Ruby、Rust 等，如果它们有全局或服务级别的配置文件，通常也会存放在 etc 目录下对应的子目录中，遵循类似的按版本组织的结构。

ServBay 内部数据目录 (`data/servbay`)

/Applications/ServBay/data/servbay

此目录保存了 ServBay 应用程序自身正常运行所需的关键配置文件、状态信息以及用户特定的设置。这些文件对于 ServBay 控制面板的功能、软件包的管理、网站和数据库的配置等至关重要。

重要提示：请注意备份此目录。不要手动删除或改动其中的任何文件，否则可能导致 ServBay 无法启动或配置丢失。

可执行文件及脚本目录 (`bin`, `sbin`, `script`)

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

ServBay 的所有可执行文件都组织在 bin 和 sbin 目录下，这两个目录是软链接，实际指向 package/bin 和 package/sbin。这里包含了 ServBay 集成的各种工具和语言运行时。

您可以在终端中直接访问这些可执行文件，因为 ServBay 会将这些目录添加到系统的 PATH 环境变量中（通常是在 ServBay 启动时）。这包括：

各种常用工具：如 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) 包含 ServBay 内部使用的系统管理脚本，例如用于启动/停止服务、初始化数据库、执行维护任务等。这些脚本是 ServBay 核心功能的一部分。虽然您可以直接执行它们，但通常更推荐使用 ServBay 提供的 servbayctl 命令行工具，它封装了这些底层脚本，提供了更友好的接口。

例如，要启动 PHP 7.4 FPM 服务，可以使用：

bash

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 的数据文件。

ServBay 设计为每个数据库软件的大版本共用一份数据文件。例如，MariaDB 11.2.x 系列版本都使用 /Applications/ServBay/db/mariadb/11.2 目录下的数据文件。

重要提示：此目录包含您所有的本地数据库数据。在进行任何重要操作前（如 ServBay 升级、系统迁移等），务必完整备份 /Applications/ServBay/db 目录。ServBay 提供的自动备份功能也会包含数据库备份。

日志目录 (`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 主要记录未被 PHP 框架或应用自身捕获并处理的致命错误。
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。

您可以通过 ServBay 控制面板方便地安装、卸载和切换不同版本的软件包。

对于升级后不再需要的旧版本软件包，您可以手动删除其对应的完整版本目录（例如 /Applications/ServBay/package/php/8.2/8.2.10）来节省磁盘空间。

重要提示：在每个软件包的大版本目录下（例如 /Applications/ServBay/package/php/8.3），通常会有一个名为 current 的软链接，指向该大版本下当前激活或最新的小版本目录。请勿手动删除或修改这些 current 软链接，否则可能导致 ServBay 无法正确找到软件包的可执行文件或库文件，从而导致服务无法启动。

SSL 证书目录 (`ssl`)

/Applications/ServBay/ssl

此目录用于存放与 SSL/TLS 相关的证书文件。其中包括：

ServBay 自动为您的本地网站通过 ACME 协议申请的 SSL 证书（通常存放在 ssl/caddy 或 ssl/acme 等子目录中，取决于您使用的 Web 服务器）。
ServBay 生成的用于本地 HTTPS 开发的根证书（ServBay User CA）和公共证书（ServBay Public CA），通常位于 ssl/private 和 ssl/public 目录下。安装这些 CA 证书到您的系统信任库后，即可在浏览器中信任 ServBay 为本地网站签发的证书，避免 HTTPS 警告。

备份目录 (`backup`)

/Applications/ServBay/backup

此目录是 ServBay 内置自动备份功能存放备份文件的地方。ServBay 的备份功能可以帮助您轻松备份关键的开发数据和配置，包括：

backup/config: ServBay 核心配置文件和软件包配置文件的备份。
backup/databases: MariaDB, MySQL, PostgreSQL, MongoDB 等数据库的数据备份。
backup/ssl: SSL 证书文件的备份。
backup/websites: 您在 /Applications/ServBay/www 目录下存放的网站项目文件的备份。

建议定期检查此目录，并根据需要将备份文件迁移到外部存储设备，以实现更完善的数据灾备策略。

临时文件目录 (`tmp`)

/Applications/ServBay/tmp

此目录存放各服务运行时生成的临时文件，其中最常见的是 .pid 文件和服务通信所需的 Socket 文件。

.pid 文件：用于记录运行中服务的进程 ID。
Socket 文件：例如 php-cgi.sock、mysql.sock、pgsql.sock 等。这些文件允许本地程序通过 Unix Domain Socket 的方式与 php-fpm、数据库等服务进行通信。相较于通过 TCP 端口通信，使用 Socket 文件通常具有更高的吞吐量、更好的性能和更低的延迟，特别适用于同一台机器上的进程间通信。

公共组件及开发库 (`package/common`)

/Applications/ServBay/package/common

此目录包含 ServBay 安装的所有软件包所依赖的公共组件、共享库文件（如 *.dylib）以及可选的开发库。

如果安装了 ServBay Development Library（一个可选软件包，提供编译依赖），此目录下还会包含 include 目录（存放头文件）和 lib 目录（存放静态库 *.a 和链接库 *.la）。这些文件对于需要从源代码编译 PHP 扩展或其他需要依赖 ServBay 内置库的软件非常有用。

重要提示：请勿手动删除 package/common/lib 目录下的 *.dylib 文件，这些是 ServBay 集成软件正常运行所必需的共享库。删除它们会导致程序因缺少依赖库而运行异常。

总结

ServBay 的目录结构清晰地划分了软件包、配置、数据、日志和网站文件，借鉴了标准的 Unix 文件系统约定，使得开发者能够直观地管理本地开发环境。熟悉这些目录的用途，将极大地提升您使用 ServBay 进行 Web 开发的效率和便利性。定期备份关键目录（特别是 data 和 db）是保障您的开发工作不受损失的重要措施。

ServBay 目录结构详解 ​

ServBay 主目录 ​

网站根目录 (www) ​

配置文件目录 (etc) ​

PHP (etc/php) ​

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

Caddy (etc/caddy) ​

Nginx (etc/nginx) ​

dnsmasq (etc/dnsmasq) ​

其他软件包配置 ​

ServBay 内部数据目录 (data/servbay) ​

可执行文件及脚本目录 (bin, sbin, script) ​

数据库文件目录 (db) ​

日志目录 (logs) ​

软件包目录 (package) ​

SSL 证书目录 (ssl) ​

备份目录 (backup) ​

临时文件目录 (tmp) ​

公共组件及开发库 (package/common) ​

总结 ​