Linux

지원 환경: 커널 4.4 이상, glibc 기반 배포판. Ubuntu 22.04+, Debian 12, Fedora 39+, Alpine 3.19+에서 테스트됨. 아키텍처: amd64, arm64.

설치

빠른 설치

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)에 배치합니다. ~/.config/sotatek-proxy/ 아래에 기본 설정 파일을 생성하고, 세션 시작 시 자동 실행되는 systemd --user 유닛을 등록합니다.

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

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

소스에서 빌드

사전 요구사항

• Go 1.23+ — go.dev/dl - Git — 배포판 패키지 관리자로 설치 (apt install git, dnf install git 등) - make — apt install make / dnf install make

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

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

2. 빌드 후 설치합니다:

   bash scripts/install-from-source.sh

   스크립트는 아키텍처(amd64 또는 arm64)를 감지하여 make build-linux-amd64 / make build-linux-arm64를 실행하고, 바이너리를 /usr/local/bin/sotatek-proxy (또는 /usr/local/bin에 쓰기 권한이 없는 경우 ~/.local/bin/sotatek-proxy)에 복사하며, ~/.config/sotatek-proxy/ 아래에 기본 설정 파일을 생성하고 systemd --user 유닛을 등록합니다.

   선택적 플래그:

   플래그	설명
   --no-service	바이너리만 설치 — systemd 유닛 등록 생략
   --prefix DIR	설치 디렉토리 재정의

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

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

팁

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

부팅 시 자동 시작

기본적으로 systemd --user 서비스는 로그인 시에만 시작됩니다. 부팅 시 자동 시작하려면 (예: 헤드리스 서버), 사용자 linger를 활성화하세요:

loginctl enable-linger $USER

파일 위치

항목	경로
바이너리	/usr/local/bin/sotatek-proxy (또는 ~/.local/bin/sotatek-proxy)
설정	~/.config/sotatek-proxy/config.yaml ($XDG_CONFIG_HOME 준수)
로그	~/.local/state/sotatek-proxy/sotatek-proxy.log
유닛	~/.config/systemd/user/sotatek-proxy.service

서비스 명령어

sotatek-proxy status      # 실행 중 / 정지됨
sotatek-proxy start       # 지금 시작
sotatek-proxy stop        # 지금 정지
sotatek-proxy logs        # 마지막 100줄 출력
sotatek-proxy uninstall   # systemd 유닛 제거

systemd를 직접 사용할 수도 있습니다:

systemctl --user status sotatek-proxy
journalctl --user -u sotatek-proxy -f

문제 해결

command not found

sotatek-proxy status가 command not found를 반환하면, 바이너리가 (/usr/local/bin에 쓸 수 없어) ~/.local/bin에 설치되었고 해당 디렉터리가 PATH에 없는 것입니다.

올바른 셸 rc 파일에 추가한 후 다시 로드하세요:

case "$(basename "${SHELL:-bash}")" in
  zsh) RC="$HOME/.zshrc" ;;
  *)   RC="$HOME/.bashrc" ;;
esac
LINE='export PATH="$HOME/.local/bin:$PATH"'
grep -qxF "$LINE" "$RC" 2>/dev/null || echo "$LINE" >> "$RC"
source "$RC"

또는 현재 셸에서만 임시로 적용 (새 세션 불필요):

export PATH="$HOME/.local/bin:$PATH"
sotatek-proxy status

포트 사용 중

ss -tlnp 'sport = 3817'
sotatek-proxy stop && sotatek-proxy start

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

서비스 시작 실패

sotatek-proxy logs
systemctl --user status sotatek-proxy
journalctl --user -u sotatek-proxy --since "10 min ago"
sotatek-proxy daemon      # 디버깅을 위한 포그라운드 실행

로그아웃 시 서비스 종료

linger를 활성화합니다:

loginctl enable-linger $USER
loginctl show-user $USER | grep Linger

제거

sotatek-proxy uninstall
rm /usr/local/bin/sotatek-proxy   # 또는 ~/.local/bin/sotatek-proxy
rm -rf ~/.config/sotatek-proxy
rm -rf ~/.local/state/sotatek-proxy