macOS

지원 환경: macOS 10.15 이상 (Catalina 또는 이후 버전), Apple Silicon 및 Intel.

설치

빠른 설치

1. 터미널을 엽니다.

2. 설치 스크립트를 실행합니다:

   curl -sSL https://proxy.sotatek.works/releases/download/latest/install.sh | bash

   스크립트는 해당 아키텍처에 맞는 바이너리를 다운로드하고 SHA256 체크섬을 검증한 후 /usr/local/bin/sotatek-proxy (또는 /usr/local/bin에 쓰기 권한이 없는 경우 ~/.local/bin/sotatek-proxy)에 배치합니다. 기본 설정 파일을 생성하고, 로그인 시 자동 시작되는 launchd 사용자 에이전트를 등록합니다.

3. 데몬이 정상적으로 실행 중인지 확인합니다:

   sotatek-proxy status
   curl http://127.0.0.1:3817/_proxy/healthz

소스에서 빌드

사전 요구사항

• Go 1.23+ — go.dev/dl - Git — git-scm.com - make — Xcode Command Line Tools에 포함 (xcode-select --install)

1. 저장소를 클론합니다:

   git clone https://github.com/sotatek-dev/sotatek-proxy.git
   cd sotatek-proxy

2. 빌드 후 설치합니다:

   bash scripts/install-from-source.sh

   스크립트는 현재 플랫폼(Apple Silicon 또는 Intel)을 감지하여 make build-darwin-arm64 / make build-darwin-amd64를 실행하고, 바이너리를 /usr/local/bin/sotatek-proxy (또는 /usr/local/bin에 쓰기 권한이 없는 경우 ~/.local/bin/sotatek-proxy)에 복사하며, 기본 설정 파일을 생성하고 launchd 사용자 에이전트를 등록합니다.

   선택적 플래그:

   플래그	설명
   --no-service	바이너리만 설치 — launchd 에이전트 등록 생략
   --prefix DIR	설치 디렉토리 재정의

3. 데몬이 정상적으로 실행 중인지 확인합니다:

   sotatek-proxy status
   curl http://127.0.0.1:3817/_proxy/healthz

팁

설치 없이 빌드만 하려면 저장소 루트에서 make build를 실행하세요. 바이너리는 ./dist/sotatek-proxy에 생성됩니다.

파일 위치

항목	경로
바이너리	/usr/local/bin/sotatek-proxy (또는 ~/.local/bin/sotatek-proxy)
설정	~/Library/Application Support/sotatek-proxy/config.yaml
로그	~/Library/Logs/sotatek-proxy/sotatek-proxy.log
서비스	~/Library/LaunchAgents/com.sotatek.proxy.plist

서비스 명령어

sotatek-proxy status      # 실행 중 / 정지됨
sotatek-proxy start       # 지금 시작
sotatek-proxy stop        # 지금 정지
sotatek-proxy logs        # 마지막 100줄 출력
sotatek-proxy uninstall   # launchd 에이전트 제거

문제 해결

포트 사용 중

다른 프로세스가 3817 포트를 사용 중입니다. 포트를 해제하거나 설정을 변경하세요:

lsof -i :3817            # 사용 중인 프로세스 찾기
sotatek-proxy stop && sotatek-proxy start

또는 config.yaml에서 port: 3818로 설정하고 재시작하세요.

서비스 시작 실패

sotatek-proxy logs
launchctl print gui/$UID/com.sotatek.proxy
sotatek-proxy daemon     # 디버깅을 위한 포그라운드 실행

127.0.0.1:3817 연결 거부됨

에이전트가 로드되어 있는지 확인합니다:

launchctl list | grep com.sotatek.proxy
sotatek-proxy daemon     # 포그라운드 동작 확인

팁

기본 설치는 관리자 권한이 필요하지 않습니다. launchd 에이전트는 현재 사용자 권한으로 실행되며 로그인 시 자동으로 시작됩니다.

제거

sotatek-proxy uninstall
rm /usr/local/bin/sotatek-proxy   # 또는 ~/.local/bin/sotatek-proxy
rm -rf ~/Library/Application\ Support/sotatek-proxy
rm -rf ~/Library/Logs/sotatek-proxy