Linux

Hỗ trợ: kernel 4.4+, các distro dùng glibc có systemd. Đã kiểm tra trên Ubuntu 22.04+, Debian 12, Fedora 39+. Kiến trúc: amd64, arm64.

Một daemon cho cả máy

Trên Linux, sotatek-proxy cài dưới dạng systemd service toàn máy, chạy bằng system user riêng sotatek-proxy. Một daemon duy nhất trên 127.0.0.1:3817 phục vụ mọi tài khoản trên máy — nên chuyển đổi user không còn xung đột cổng. Lệnh cài đặt và quản lý dịch vụ cần sudo.

Cài đặt

Cài đặt nhanh

1. Mở một shell.

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

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

   Script tải binary phù hợp, xác minh checksum SHA256, đặt binary tại /usr/local/bin/sotatek-proxy, và đăng ký systemd service toàn máy (script sẽ hỏi sudo ở bước này). Dịch vụ khởi động ngay và tự chạy khi boot.

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

   sudo 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 — có sẵn qua package manager của distro (apt install git, dnf install git, v.v.) - make — apt install make / dnf install make

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 kiến trúc của bạn (amd64 hoặc arm64), chạy make build-linux-amd64 / make build-linux-arm64, sao chép binary tới /usr/local/bin/sotatek-proxy, và đăng ký systemd service toàn máy (sẽ hỏi sudo).

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

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

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

   sudo 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.

Nâng cấp từ bản cài per-user cũ

Các phiên bản cũ đăng ký systemd --user unit riêng cho từng user. Trình cài đặt sẽ tự gỡ unit cũ của bạn. Nếu một user khác trên máy vẫn còn daemon cũ đang chạy, họ giữ cổng 3817 và việc cài đặt sẽ bị chặn kèm thông báo nêu tên user đó. Hãy dừng daemon của họ trước:

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

Không cần user linger (loginctl enable-linger) nữa — system service tự khởi động khi boot.

Cơ chế attribution

Daemon xác định process đã gửi request, đọc thư mục làm việc của process đó, rồi chạy git remote -v hạ quyền xuống đúng uid của user đó — nên nó đọc repo của mỗi user bằng chính quyền của user ấy, không bao giờ bằng quyền cao hơn. Kết quả được gửi lên upstream qua header X-Git-Remote.

Để làm được điều này, dịch vụ giữ CAP_SYS_PTRACE, CAP_SETUID và CAP_SETGID, chạy trong sandbox (NoNewPrivileges, ProtectSystem=strict, ProtectHome=read-only) dưới một system user không phải root.

Vị trí các file

Thành phần	Đường dẫn
Binary	/usr/local/bin/sotatek-proxy
Config	/etc/sotatek-proxy/config.yaml (tùy chọn)
Logs	/var/log/sotatek-proxy/sotatek-proxy.log
Unit	/etc/systemd/system/sotatek-proxy.service
Chạy dưới	system user sotatek-proxy (nologin)

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

sudo sotatek-proxy status      # running / stopped
sudo sotatek-proxy start       # khởi động ngay
sudo sotatek-proxy stop        # dừng (giữ trạng thái dừng qua reboot)
sotatek-proxy logs             # xem 100 dòng log cuối
sudo sotatek-proxy uninstall   # gỡ dịch vụ, system user, config và logs

Bạn cũng có thể dùng systemd trực tiếp:

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

Khi không có systemd (container, WSL, Alpine)

Ở môi trường không có systemd hoặc không có useradd, việc cài dịch vụ không được hỗ trợ. Thay vào đó hãy chạy proxy ở foreground — nó tự dùng đường dẫn theo user (~/.config/sotatek-proxy/config.yaml, ~/.local/state/sotatek-proxy/) và không cần root:

sotatek-proxy daemon

Xử lý sự cố

command not found

Nếu sotatek-proxy status báo command not found, /usr/local/bin chưa nằm trong PATH.

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

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"

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

Một process khác — thường là sotatek-proxy per-user cũ của user khác — đang giữ cổng 3817. Tìm chủ sở hữu:

sudo ss -tlnp 'sport = 3817'

Dừng unit cũ của user đó, rồi khởi động system service:

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

Daemon không crash-loop khi cổng bận: nó ghi log tên user đang giữ cổng rồi thoát, nên journalctl -u sotatek-proxy cho biết chính xác ai đang chiếm.

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

sotatek-proxy logs
systemctl status sotatek-proxy
journalctl -u sotatek-proxy --since "10 min ago"
sudo sotatek-proxy daemon      # chạy foreground để debug

Thiếu header X-Git-Remote

Nếu request lên upstream không kèm thông tin repository, nhiều khả năng capabilities của dịch vụ không có hiệu lực (kernel đã hardening, container thiếu caps, chính sách MAC). Daemon ghi log việc này ngay khi khởi động:

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

Request vẫn hoạt động bình thường — chỉ mất header attribution.

Gỡ cài đặt

Chú ý

uninstall trên Linux có tính hủy dữ liệu: nó xóa dịch vụ, system user sotatek-proxy, và cả /etc/sotatek-proxy lẫn /var/log/sotatek-proxy (bao gồm lịch sử log). Hãy sao lưu log bạn muốn giữ trước khi chạy.

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