명령줄 도구 servbayctl

servbayctl은 ServBay에서 제공하는 강력한 명령줄 도구로, 개발자가 터미널에서 ServBay의 백그라운드 서비스를 직접 관리할 수 있도록 설계되었습니다. servbayctl을 이용하면 서비스의 시작, 중지, 재시작, 재로드, 강제 종료, 상태 확인, 전체 중지 등 다양한 작업을 빠르고 편리하게 수행할 수 있습니다. 이는 자동화 스크립트나 서비스 상태를 신속하게 전환하고자 하거나, 명령줄 환경을 선호하는 개발자에게 특히 유용합니다.

이 문서에서는 servbayctl의 사용법, 지원 명령 및 파라미터, 그리고 서비스 종류에 대해 상세히 설명합니다.

개요

ServBay는 직관적인 그래픽 사용자 인터페이스(GUI)로 로컬 웹 개발 환경 관리를 지원할 뿐만 아니라, servbayctl이라는 명령줄 인터페이스(CLI) 도구도 제공합니다. servbayctl은 ServBay가 설치된 경로의 script 폴더에 위치하며, 간단한 명령어만으로 ServBay가 관리하는 각종 소프트웨어 패키지의 백그라운드 서비스 상태를 통제할 수 있습니다.

servbayctl을 사용할 때 얻을 수 있는 이점은 다음과 같습니다:

• 자동화: 서비스 관리 절차를 개발 워크플로의 스크립트에 쉽고 유연하게 통합할 수 있습니다.
• 효율성: GUI를 별도로 실행하지 않고도, 특정 서비스를 즉시 시작하거나 중지할 수 있습니다.
• 유연성: 원격 SSH 환경이나 GUI가 없는 환경(headless)에 최적화되어 있습니다.
• 정확한 제어: 특정 서비스 또는 버전을 지정하여 세밀하게 관리할 수 있습니다.

사전 준비 사항

servbayctl을 사용하기 전에 다음 사항을 확인하세요:

1. ServBay가 정상적으로 설치되어 있어야 합니다.

2. 터미널에 접근할 수 있어야 합니다.

3. (선택 및 권장) /Applications/ServBay/script 폴더를 시스템 PATH 환경 변수에 추가하면, 어디서든 servbayctl 명령을 경로 없이 바로 실행할 수 있습니다.

   • Bash 또는 Zsh 사용자라면, 자신의 ~/.bash_profile, ~/.bashrc, ~/.zshrc, 또는 ~/.profile 파일에 아래 라인을 추가합니다:

     export PATH="/Applications/ServBay/script:$PATH"

   • 파일 저장 후, source ~/.bash_profile (또는 수정한 파일명)을 실행해 변경사항을 적용하거나 터미널을 재실행하세요.

사용 구문

servbayctl 명령의 기본 사용 구문은 다음과 같습니다:

servbayctl <command> <service> [parameters]

• <command>: 실행할 작업(예: start, stop, restart 등)
• <service>: 관리할 서비스명(예: php, mysql, caddy)
• [parameters]: 옵션 파라미터로 서비스 버전이나 범위를 지정(예: 7.4 또는 -all)

ServBay의 servbayctl 사용 예시에서 제시하는 명령 및 전체 구문은 다음과 같습니다:

Usage: /Applications/ServBay/script/servbayctl {start|stop|reload|restart|kill|status|stop-all} {php|mariadb|mysql|postgresql|redis|memcached|caddy|nginx|apache|dnsmasq|mongodb|rabbitmq|cloudflared|frpc|mailpit|web|ollama} [-all|version]

주의: stop-all 명령은 서비스명이나 기타 파라미터를 받지 않으며, 모든 ServBay 관리 서비스를 중지합니다.

지원 명령어 상세 설명

servbayctl에서 지원하는 주요 명령과 설명, 그리고 예시는 다음과 같습니다:

start - 서비스 시작

지정된 서비스를 시작합니다. 원하는 버전을 지정하거나 -all 파라미터로 모든 설치된 버전을 일괄 시작할 수 있습니다.

servbayctl start <service> [-all|version]

• 예시: PHP 8.1 버전 시작

  servbayctl start php 8.1

• 예시: 설치된 모든 PHP 버전 시작

  servbayctl start php -all

• 예시: 기본 설정의 MySQL 서비스 시작

  servbayctl start mysql

stop - 서비스 중지

지정된 서비스를 중지합니다. 특정 버전을 지정하거나 -all로 전체 버전을 중지할 수 있습니다.

servbayctl stop <service> [-all|version]

• 예시: PHP 7.4 버전 중지

  servbayctl stop php 7.4

• 예시: 설치된 모든 MariaDB 버전 중지

  servbayctl stop mariadb -all

• 예시: Redis 서비스 중지

  servbayctl stop redis

reload - 서비스 설정 재적용

변경된 설정 파일을 서비스에 적용할 때 주로 사용하며, 서비스 전체 재시작 없이 바로 반영됩니다. 단, 모든 서비스가 핫 리로드를 지원하는 것은 아닙니다.

servbayctl reload <service> [-all|version]

• 예시: Caddy 웹 서버 설정 재적용

  servbayctl reload caddy

• 예시: 설치된 모든 PHP 버전 설정 재적용(지원 시)

  servbayctl reload php -all

restart - 서비스 재시작

서비스를 중지 후 다시 시작합니다.

servbayctl restart <service> [-all|version]

• 예시: PostgreSQL 데이터베이스 서비스 재시작

  servbayctl restart pgsql

• 예시: 여러 버전이 설치된 경우, 모든 Redis 버전 재시작

  servbayctl restart redis -all

kill - 서비스 강제 종료

지정된 서비스의 프로세스를 강제로 종료합니다. 데이터 손실 또는 손상 위험이 있으므로(특히 데이터베이스 서비스) 정상 중지가 불가할 때만 신중히 사용하세요.

servbayctl kill <service> [-all|version]

• 예시: PHP 7.4 서비스 강제 종료

  servbayctl kill php 7.4

• 예시: 모든 Memcached 서비스 강제 종료

  servbayctl kill memcached -all

status - 서비스 상태 확인

지정된 서비스가 현재 실행 중인지 확인합니다.

servbayctl status <service> [-all|version]

• 예시: Caddy 서비스 상태 확인

  servbayctl status caddy

• 예시: 설치된 모든 MySQL 버전 상태 확인

  servbayctl status mysql -all

stop-all - 모든 ServBay 서비스 중지

ServBay에서 관리하는 모든 백그라운드 서비스를 한 번에 중지합니다. 이 명령은 서비스명이나 버전 파라미터 없이 사용합니다.

servbayctl stop-all

• 예시: 모든 ServBay 백그라운드 서비스 중지

  servbayctl stop-all

지원 서비스 목록

servbayctl 사용 정보에 따르면, 아래와 같은 주요 백그라운드 서비스들을 직접 제어할 수 있습니다:

• php: 다양한 버전의 PHP-FPM 프로세스 관리
• mariadb: MariaDB 데이터베이스 서비스
• mysql: MySQL 데이터베이스 서비스
• postgresql: PostgreSQL 데이터베이스 서비스
• redis: Redis 캐시/데이터베이스 서비스
• memcached: Memcached 캐시 서비스
• caddy: Caddy 웹 서버 서비스
• nginx: Nginx 웹 서버 서비스
• apache: Apache HTTP 서버 서비스
• dnsmasq: ServBay 내장 DNS 서비스
• mongodb: MongoDB 데이터베이스 서비스
• rabbitmq: RabbitMQ 메시지 큐 서비스
• cloudflared: Cloudflare Tunnel 서비스(설치 및 설정 시)
• frpc: Fatedier/frp 클라이언트(설치 및 설정 시)
• mailpit: Mailpit 이메일 캡처 도구
• web: 웹 서비스(구체적 사용 예는 실제 설정에 따라 다름. 예: 웹 서버, ServBay 관련 웹 API 등)
• ollama: Ollama 로컬 대형 언어 모델 서비스

참고로, servbayctl은 Nginx, Apache를 비롯해 주요 백엔드 서비스를 모두 직접 관리할 수 있습니다. Java, Python, Go, .NET, Ruby, Rust 등 기타 소프트웨어 패키지들도 ServBay에 설치는 가능하지만, 이들은 보통 servbayctl로 직접 서비스 관리 대상이 아니며, 별도의 명령어 또는 각각의 관리 방식을 통해 실행하게 됩니다. servbayctl은 위 목록처럼 데몬 형태로 운영되는 핵심 서비스 관리에 집중합니다.

실전 사용 예시

다음은 servbayctl을 활용하는 대표적인 시나리오 예시입니다:

1. 테스트 목적으로 PHP 버전을 빠르게 전환:

   servbayctl stop php -all
   servbayctl start php 8.2

2. 데이터베이스 재시작으로 설정 변경 적용:

   # my.cnf나 my.ini 파일 수정 후
   servbayctl restart mysql

3. 모든 서비스 완전 중지(시스템 종료 전, ServBay 업데이트 전 등):

   servbayctl stop-all

4. 웹 서버 동작 여부 확인:

   servbayctl status caddy

5. 스크립트로 개발 환경 자동화 실행:

   #!/bin/bash
   
   echo "모든 ServBay 서비스 중지 중..."
   servbayctl stop-all
   
   echo "필요한 서비스 시작 중..."
   servbayctl start php 8.1
   servbayctl start mysql
   servbayctl start caddy
   servbayctl start redis
   
   echo "ServBay 서비스가 시작되었습니다."

주의사항 및 권장 방식

• PATH에 추가: 경로를 시스템 PATH에 추가하면 명령 입력이 훨씬 간편합니다.
• kill 명령의 신중한 사용: kill은 강제 종료이므로 미저장 데이터 손실, 서비스 상태 이상 등의 위험이 있습니다. 불가피하지 않다면 우선적으로 stop 또는 restart를 사용하세요.
• stop-all은 전체 중지: 모든 백엔드 서비스가 일괄 중지되므로 실행 전 반드시 확인하세요.
• 버전 파라미터 주의: version 옵션 사용 시 해당 버전이 ServBay 내에 설치되어 있는지 확인하세요. GUI에서 설치 버전 확인이 가능합니다.
• 오류 발생시: 명령 실패 시 터미널에 에러 메시지가 출력되며, ServBay 설치 경로의 logs 폴더에서 상세 로그를 확인할 수 있습니다.
• GUI와 CLI의 병행 활용: servbayctl은 GUI를 보완하는 도구이므로, 전체 상황 파악이나 복잡한 환경 구성에는 GUI가 더 편리할 수 있습니다.

자주 묻는 질문 (FAQ)

Q: servbayctl 명령을 실행했는데 command not found라고 나옵니다. 어떻게 해야 하나요?

A: /Applications/ServBay/script 경로가 시스템 PATH 환경 변수에 추가되지 않은 경우 발생합니다. 본 문서의 “사전 준비 사항”을 참고하여 해당 경로를 PATH에 추가하세요.

Q: servbayctl start <service>로 서비스를 시작했지만 정상적으로 동작하지 않습니다. 문제 해결 방법은?

A:

1. servbayctl status <service>로 서비스 상태를 다시 확인합니다.
2. ServBay 설치 디렉토리의 logs 폴더에서 해당 서비스의 오류 로그를 확인하면 실패 원인을 알 수 있습니다.
3. 동일 서비스의 GUI 시작 시 보다 친절한 오류 메시지가 제공될 수 있습니다.
4. 서비스 설정 파일 내 잘못된 부분이 없는지 점검하세요.

Q: -all 파라미터는 모든 서비스에 사용할 수 있나요?

A: -all은 PHP처럼 다중 버전 관리가 가능한 서비스에 주로 사용됩니다. MySQL, PostgreSQL, Caddy 등 대다수 데이터베이스나 웹 서버는 하나의 인스턴스만 실행되므로, 버전 미지정과 -all이 사실상 동일합니다. Redis, Memcached처럼 여러 포트로 여러 인스턴스를 운영할 수 있는 서비스의 경우, -all은 이들 전체를 관리할 수 있습니다(실제 동작은 ServBay 내부 구현에 따름).

요약

servbayctl은 ServBay가 제공하는 강력한 명령줄 인터페이스로, 로컬 개발 환경의 서비스 관리에 탁월한 유연성과 효율성을 제공합니다. start, stop, reload, restart, kill, status, stop-all 명령과 version, -all 옵션을 조합해, PHP, MySQL, MariaDB, PostgreSQL, MongoDB, Redis, Memcached, Caddy 등 다양한 핵심 서비스를 터미널에서 손쉽게 컨트롤할 수 있습니다. 이를 통해 자동화된 워크플로와 고도화된 개발 환경 관리가 가능하며, 한층 향상된 개발 경험을 누릴 수 있습니다.