Linux

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

머신당 데몬 하나

Linux에서 sotatek-proxy는 전용 시스템 사용자 sotatek-proxy로 실행되는 시스템 전역 systemd 서비스로 설치됩니다. 127.0.0.1:3817의 단일 데몬이 머신의 모든 계정을 처리하므로, 사용자를 전환해도 포트 충돌이 발생하지 않습니다. 설치 및 서비스 명령에는 sudo가 필요합니다.

설치

빠른 설치

1. 셸을 엽니다.

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

   curl -sSL https://proxy.sotatek.works/releases/download/latest/install.sh | bash
   export PATH="$HOME/.local/bin:$PATH" && hash -r

   스크립트는 해당 바이너리를 내려받아 SHA256 체크섬을 검증하고 /usr/local/bin/sotatek-proxy에 배치한 뒤, 시스템 전역 systemd 서비스를 등록합니다(이 단계에서 sudo를 요청합니다). 서비스는 즉시 시작되며 부팅 시에도 자동 시작됩니다.

3. 데몬이 실행 중인지 확인합니다:

   sudo 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로 복사한 뒤 시스템 전역 systemd 서비스를 등록합니다(sudo 요청).

   선택 플래그:

   플래그	설명
   --no-service	바이너리만 설치 — systemd 등록 건너뜀
   --prefix DIR	설치 디렉터리 재정의

3. 데몬이 실행 중인지 확인합니다:

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

팁

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

기존 사용자 단위 설치에서 업그레이드

이전 버전은 사용자별 systemd --user 유닛을 등록했습니다. 설치 스크립트는 본인의 기존 유닛을 자동으로 제거합니다. 머신의 다른 사용자가 아직 예전 데몬을 실행 중이라면 그 데몬이 3817 포트를 점유하므로, 해당 사용자를 알려주는 메시지와 함께 설치가 중단됩니다. 먼저 그 데몬을 중지하세요:

sudo -u <user> systemctl --user disable --now sotatek-proxy
sudo sotatek-proxy install

이제 user linger(loginctl enable-linger)는 필요하지 않습니다 — 시스템 서비스가 부팅 시 시작됩니다.

속성(attribution) 동작 방식

데몬은 각 요청을 보낸 프로세스를 식별하고 그 작업 디렉터리를 읽은 뒤, 해당 사용자의 uid로 권한을 낮춰 git remote -v를 실행합니다. 따라서 각 사용자의 저장소를 그 사용자의 권한으로만 읽으며, 상승된 권한으로는 절대 읽지 않습니다. 결과는 X-Git-Remote 헤더로 업스트림에 전달됩니다.

이를 위해 서비스는 CAP_SYS_PTRACE, CAP_SETUID, CAP_SETGID를 보유하며, root가 아닌 시스템 사용자로 샌드박스(NoNewPrivileges, ProtectSystem=strict, ProtectHome=read-only) 안에서 실행됩니다.

파일 위치

항목	경로
바이너리	/usr/local/bin/sotatek-proxy
설정	/etc/sotatek-proxy/config.yaml (선택)
로그	/var/log/sotatek-proxy/sotatek-proxy.log
유닛	/etc/systemd/system/sotatek-proxy.service
실행 계정	시스템 사용자 sotatek-proxy (nologin)

서비스 명령어

sudo sotatek-proxy status      # running / stopped
sudo sotatek-proxy start       # 즉시 시작
sudo sotatek-proxy stop        # 중지 (재부팅 후에도 중지 상태 유지)
sotatek-proxy logs             # 최근 100줄 확인
sudo sotatek-proxy uninstall   # 서비스, 시스템 사용자, 설정, 로그 제거

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

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

systemd가 없는 환경 (컨테이너, WSL, Alpine)

systemd나 useradd를 사용할 수 없는 환경에서는 서비스 설치가 지원되지 않습니다. 대신 프록시를 포그라운드로 실행하세요 — 사용자별 경로(~/.config/sotatek-proxy/config.yaml, ~/.local/state/sotatek-proxy/)로 대체되며 root 권한이 필요 없습니다:

sotatek-proxy daemon

문제 해결

command not found

sotatek-proxy status가 command not found를 반환하면 /usr/local/bin이 PATH에 없는 것입니다.

셸 rc 파일에 추가한 뒤 다시 로드하세요:

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

포트 사용 중

다른 프로세스 — 대개 다른 사용자의 예전 사용자별 sotatek-proxy — 가 3817 포트를 점유하고 있습니다. 소유자를 확인하세요:

sudo ss -tlnp 'sport = 3817'

해당 사용자의 예전 유닛을 중지한 뒤 시스템 서비스를 시작합니다:

sudo -u <user> systemctl --user disable --now sotatek-proxy
sudo sotatek-proxy start

포트가 사용 중일 때 데몬은 크래시 루프에 빠지지 않습니다. 점유 중인 사용자를 로그에 남기고 종료하므로 journalctl -u sotatek-proxy에서 누가 점유했는지 정확히 확인할 수 있습니다.

서비스 시작 실패

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

X-Git-Remote 헤더 누락

업스트림 요청에 저장소 정보가 실리지 않는다면, 서비스의 capabilities가 유효하지 않을 가능성이 큽니다 (하드닝된 커널, capabilities가 없는 컨테이너, MAC 정책 등). 데몬은 시작 시 이를 로그로 남깁니다:

journalctl -u sotatek-proxy | grep -i "capability self-test"

요청 자체는 정상 동작하며, 속성 헤더만 누락됩니다.

제거

주의

Linux에서 uninstall은 파괴적입니다: 서비스와 sotatek-proxy 시스템 사용자, 그리고 /etc/sotatek-proxy와 /var/log/sotatek-proxy(로그 이력 포함)를 모두 삭제합니다. 보관할 로그가 있다면 먼저 복사하세요.

sudo sotatek-proxy uninstall
sudo rm /usr/local/bin/sotatek-proxy