macOS

Hỗ trợ: macOS 10.15+ (Catalina trở lên), Apple Silicon và Intel.

Cài đặt

Cài đặt nhanh

1. Mở Terminal.

2. Chạy trình cài đặt:

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

   Script tải xuống binary phù hợp, xác minh checksum SHA256, đặt binary tại /usr/local/bin/sotatek-proxy (hoặc ~/.local/bin/sotatek-proxy nếu /usr/local/bin không có quyền ghi), tạo config mặc định, và đăng ký một launchd user agent tự khởi động khi đăng nhập.

3. Xác minh daemon đang chạy:

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

Build từ source

Yêu cầu trước

• Go 1.23+ — go.dev/dl - Git — git-scm.com - make — đi kèm với Xcode Command Line Tools (xcode-select --install)

1. Clone repository:

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

2. Build và cài đặt:

   bash scripts/install-from-source.sh

   Script phát hiện nền tảng của bạn (Apple Silicon hoặc Intel), chạy make build-darwin-arm64 / make build-darwin-amd64, sao chép binary tới /usr/local/bin/sotatek-proxy (hoặc ~/.local/bin/sotatek-proxy nếu /usr/local/bin không có quyền ghi), tạo config mặc định, và đăng ký launchd user agent.

   Các cờ tùy chọn:

   Cờ	Mô tả
   --no-service	Chỉ binary — bỏ qua đăng ký launchd agent
   --prefix DIR	Ghi đè thư mục cài đặt

3. Xác minh daemon đang chạy:

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

Mẹo

Để build mà không cài đặt, chạy make build từ thư mục gốc của repo. Binary được đặt tại ./dist/sotatek-proxy.

Vị trí các file

Thành phần	Đường dẫn
Binary	/usr/local/bin/sotatek-proxy (hoặc ~/.local/bin/sotatek-proxy)
Config	~/Library/Application Support/sotatek-proxy/config.yaml
Logs	~/Library/Logs/sotatek-proxy/sotatek-proxy.log
Service	~/Library/LaunchAgents/com.sotatek.proxy.plist

Lệnh quản lý dịch vụ

sotatek-proxy status      # running / stopped
sotatek-proxy start       # start now
sotatek-proxy stop        # stop now
sotatek-proxy logs        # tail last 100 lines
sotatek-proxy uninstall   # remove launchd agent

Xử lý sự cố

command not found

Nếu sotatek-proxy status báo command not found, binary đã được cài vào ~/.local/bin (do /usr/local/bin không ghi được) và thư mục đó chưa nằm trong PATH. macOS mặc định dùng zsh, nên path nằm trong ~/.zshrc.

Thêm vào file rc của shell đúng, rồi nạp lại:

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

Hoặc sửa nhanh cho phiên shell hiện tại (không cần mở phiên mới):

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

Cổng đang được sử dụng

Một tiến trình khác đang chiếm cổng 3817. Hãy giải phóng cổng hoặc thay đổi config:

lsof -i :3817            # find the holder
sotatek-proxy stop && sotatek-proxy start

Hoặc đặt port: 3818 trong config.yaml và khởi động lại.

Dịch vụ không khởi động được

sotatek-proxy logs
launchctl print gui/$UID/com.sotatek.proxy
sotatek-proxy daemon     # foreground for debugging

Kết nối bị từ chối trên 127.0.0.1:3817

Xác nhận agent đã được tải:

launchctl list | grep com.sotatek.proxy
sotatek-proxy daemon     # foreground sanity check

Mẹo

Quá trình cài đặt mặc định không yêu cầu quyền admin. launchd agent chạy với tư cách người dùng của bạn và tự động khởi động khi đăng nhập.

Gỡ cài đặt

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