pia-proxy 1.0.0__tar.gz

pia_proxy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zSOCKS Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pia_proxy-1.0.0/MANIFEST.in

@@ -0,0 +1,28 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include cli/templates *
+
+# Exclude sensitive secrets and runtime files
+prune credentials
+prune prod/credentials
+prune prod
+prune app
+prune gateway
+prune installers
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude .env
+global-exclude .env*
+include cli/templates/.env.example
+global-exclude *.json
+global-exclude *.log
+global-exclude *.sh
+global-exclude check_*.py
+global-exclude monitor_*.py
+global-exclude launch_*.py
+global-exclude run_*.py
+global-exclude verify_*.py
+global-exclude deploy_*.py
+global-exclude connect_*.py
+global-exclude debug_*.py

pia_proxy-1.0.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: pia-proxy
+Version: 1.0.0
+Summary: High-Performance PIA SOCKS5 Multi-Worker Proxy Gateway CLI
+Author: zSOCKS Team
+License: MIT
+Project-URL: Homepage, https://github.com/videoveo3pro-debug/pia
+Project-URL: Repository, https://github.com/videoveo3pro-debug/pia.git
+Keywords: proxy,socks5,pia,vpn,vpn-gateway,rotate-ip,proxy-pool,haproxy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+# PIA SOCKS5 Multi-Worker Proxy Gateway & CLI
+
+Hệ thống Proxy SOCKS5 tập trung hiệu năng cao, điều phối **32 Worker VPN Private Internet Access (PIA)** hoạt động song song trong các container biệt lập, đảm bảo **luôn có ít nhất 20 IP công khai độc lập hoạt động đồng thời**, hỗ trợ tự động xoay IP (Auto-Rotate) mượt mà với **100% Uptime (Zero-Downtime)**.
+
+---
+
+## ⚡ Ứng Dụng Quản Lý CLI (`pia-proxy` / `zsocks`)
+
+Toàn bộ hệ thống hiện đã được tích hợp bộ công cụ CLI hiện đại, trực quan giúp quản trị, vận hành, kiểm thử và mở rộng pool proxy chỉ bằng các câu lệnh đơn giản:
+
+```bash
+# Cài đặt symlink CLI vào PATH (nếu chưa có):
+chmod +x bin/pia-proxy
+ln -sf $(pwd)/bin/pia-proxy ~/.local/bin/pia-proxy
+ln -sf $(pwd)/bin/pia-proxy ~/.local/bin/zsocks
+```
+
+### Các lệnh CLI chính:
+
+| Lệnh | Chức năng |
+| :--- | :--- |
+| `pia-proxy doctor` | Kiểm tra môi trường hệ thống: Docker, TUN device, Swap, RAM, Port |
+| `pia-proxy config show` | Xem thông tin cấu hình, credentials, ports |
+| `pia-proxy config set-credentials` | Nhập tài khoản PIA (Username / Password) |
+| `pia-proxy config set-proxy-auth` | Đổi thông tin đăng nhập SOCKS5 (`user`, `pass`) |
+| `pia-proxy start` | Khởi động hệ thống thông minh (Staggered Boot chống nghẽn CPU) |
+| `pia-proxy stop` | Dừng an toàn toàn bộ hệ thống hoặc từng worker cụ thể |
+| `pia-proxy restart [-W worker]` | Khởi động lại cụm proxy hoặc một worker chỉ định |
+| `pia-proxy status [-w]` | Xem bảng trạng thái trực tiếp: Exit IP, Uptime, Worker READY, Unique IPs |
+| `pia-proxy scale <N>` | **Mở rộng / thu gọn quy mô động** (ví dụ: `scale 20`, `scale 32`) Zero-Downtime |
+| `pia-proxy rotate [ID] [--all]` | Kích hoạt xoay IP ngay lập tức cho 1 worker hoặc toàn bộ pool |
+| `pia-proxy test [-n 5]` | Kiểm tra kết nối SOCKS5 gateway, đo độ trễ, đếm IP và xác nhận Zero-Leak |
+| `pia-proxy export [-f format]` | **Xuất proxy định dạng sẵn** cho tool nuôi nick, Gologin, AdsPower, bot |
+| `pia-proxy logs [-f]` | Theo dõi log real-time của worker hoặc gateway |
+
+---
+
+## 🚀 Đặc Điểm Nổi Bật
+
+- **Cổng SOCKS5 Duy Nhất Cho Mọi Ứng Dụng:**  
+  `socks5h://proxy_user:proxy_password_secure123@<IP_SERVER>:1087`
+- **Cân Bằng Tải Thông Minh (Round-Robin):**  
+  Mỗi kết nối / request mới tự động chuyển hướng qua một Worker VPN khác nhau, mang lại dải IP đa dạng và phân bổ đều.
+- **Quy Tắc Xoay Vòng IP (Strict Rotation Rules):**
+  - Chu kỳ tự động xoay: **36s – 69s**.
+  - Giới hạn cứng Uptime: **70s** (Bất kỳ IP nào đạt 70s sẽ bị ép rotate ngay lập tức).
+  - Khống chế dung lượng: Không bao giờ để số worker khả dụng tụt dưới **20 IP**.
+- **Tối Ưu Phần Cứng Tuyệt Đối (Zero CPU Overhead):**
+  - Chạy mượt mà ngay cả trên VPS 1 vCPU / 1GB RAM.
+  - Sử dụng lightweight TCP healthchecks trên cổng 1080, loại bỏ hoàn toàn hiện tượng 503 flapping và CPU spikes.
+- **Bảo Mật Zero-Leak:**
+  - Tường lửa iptables killswitch trong từng worker chặn 100% rò rỉ IP gốc của VPS.
+
+---
+
+## 📖 Ví Dụ Sử Dụng Nhanh
+
+### 1. Xuất chuỗi proxy dùng cho phần mềm:
+```bash
+# Định dạng chuẩn IP:PORT:USER:PASS (dùng cho antidetect browser, bot, tool)
+pia-proxy export --format standard
+# Kết quả: 14.169.55.237:1087:proxy_user:proxy_password_secure123
+
+# Định dạng URL:
+pia-proxy export --format url
+# Kết quả: socks5h://proxy_user:proxy_password_secure123@14.169.55.237:1087
+```
+
+### 2. Xem bảng trạng thái trực quan:
+```bash
+pia-proxy status
+# Giám sát trực tiếp liên tục mỗi 2 giây:
+pia-proxy status --watch -i 2
+```
+
+### 3. Mở rộng số lượng worker khi cần:
+```bash
+# Tăng lên 32 worker:
+pia-proxy scale 32
+
+# Giảm xuống 20 worker:
+pia-proxy scale 20
+```
+
+### 4. Kiểm thử chất lượng proxy & Zero-leak:
+```bash
+pia-proxy test --count 5
+```
+
+---
+
+## 🛠️ Triển Khai Thủ Công & Link Trực Tiếp
+
+- **Web Dashboard:** `http://<IP_SERVER>:8007/`
+- **API Status:** `http://<IP_SERVER>:8007/api/status`
+- **HAProxy Live Stats:** `http://<IP_SERVER>:8411/`
+- **Hướng dẫn cấu hình nâng cao:** [prod/README.md](prod/README.md)

pia_proxy-1.0.0/README.md

@@ -0,0 +1,97 @@
+# PIA SOCKS5 Multi-Worker Proxy Gateway & CLI
+
+Hệ thống Proxy SOCKS5 tập trung hiệu năng cao, điều phối **32 Worker VPN Private Internet Access (PIA)** hoạt động song song trong các container biệt lập, đảm bảo **luôn có ít nhất 20 IP công khai độc lập hoạt động đồng thời**, hỗ trợ tự động xoay IP (Auto-Rotate) mượt mà với **100% Uptime (Zero-Downtime)**.
+
+---
+
+## ⚡ Ứng Dụng Quản Lý CLI (`pia-proxy` / `zsocks`)
+
+Toàn bộ hệ thống hiện đã được tích hợp bộ công cụ CLI hiện đại, trực quan giúp quản trị, vận hành, kiểm thử và mở rộng pool proxy chỉ bằng các câu lệnh đơn giản:
+
+```bash
+# Cài đặt symlink CLI vào PATH (nếu chưa có):
+chmod +x bin/pia-proxy
+ln -sf $(pwd)/bin/pia-proxy ~/.local/bin/pia-proxy
+ln -sf $(pwd)/bin/pia-proxy ~/.local/bin/zsocks
+```
+
+### Các lệnh CLI chính:
+
+| Lệnh | Chức năng |
+| :--- | :--- |
+| `pia-proxy doctor` | Kiểm tra môi trường hệ thống: Docker, TUN device, Swap, RAM, Port |
+| `pia-proxy config show` | Xem thông tin cấu hình, credentials, ports |
+| `pia-proxy config set-credentials` | Nhập tài khoản PIA (Username / Password) |
+| `pia-proxy config set-proxy-auth` | Đổi thông tin đăng nhập SOCKS5 (`user`, `pass`) |
+| `pia-proxy start` | Khởi động hệ thống thông minh (Staggered Boot chống nghẽn CPU) |
+| `pia-proxy stop` | Dừng an toàn toàn bộ hệ thống hoặc từng worker cụ thể |
+| `pia-proxy restart [-W worker]` | Khởi động lại cụm proxy hoặc một worker chỉ định |
+| `pia-proxy status [-w]` | Xem bảng trạng thái trực tiếp: Exit IP, Uptime, Worker READY, Unique IPs |
+| `pia-proxy scale <N>` | **Mở rộng / thu gọn quy mô động** (ví dụ: `scale 20`, `scale 32`) Zero-Downtime |
+| `pia-proxy rotate [ID] [--all]` | Kích hoạt xoay IP ngay lập tức cho 1 worker hoặc toàn bộ pool |
+| `pia-proxy test [-n 5]` | Kiểm tra kết nối SOCKS5 gateway, đo độ trễ, đếm IP và xác nhận Zero-Leak |
+| `pia-proxy export [-f format]` | **Xuất proxy định dạng sẵn** cho tool nuôi nick, Gologin, AdsPower, bot |
+| `pia-proxy logs [-f]` | Theo dõi log real-time của worker hoặc gateway |
+
+---
+
+## 🚀 Đặc Điểm Nổi Bật
+
+- **Cổng SOCKS5 Duy Nhất Cho Mọi Ứng Dụng:**  
+  `socks5h://proxy_user:proxy_password_secure123@<IP_SERVER>:1087`
+- **Cân Bằng Tải Thông Minh (Round-Robin):**  
+  Mỗi kết nối / request mới tự động chuyển hướng qua một Worker VPN khác nhau, mang lại dải IP đa dạng và phân bổ đều.
+- **Quy Tắc Xoay Vòng IP (Strict Rotation Rules):**
+  - Chu kỳ tự động xoay: **36s – 69s**.
+  - Giới hạn cứng Uptime: **70s** (Bất kỳ IP nào đạt 70s sẽ bị ép rotate ngay lập tức).
+  - Khống chế dung lượng: Không bao giờ để số worker khả dụng tụt dưới **20 IP**.
+- **Tối Ưu Phần Cứng Tuyệt Đối (Zero CPU Overhead):**
+  - Chạy mượt mà ngay cả trên VPS 1 vCPU / 1GB RAM.
+  - Sử dụng lightweight TCP healthchecks trên cổng 1080, loại bỏ hoàn toàn hiện tượng 503 flapping và CPU spikes.
+- **Bảo Mật Zero-Leak:**
+  - Tường lửa iptables killswitch trong từng worker chặn 100% rò rỉ IP gốc của VPS.
+
+---
+
+## 📖 Ví Dụ Sử Dụng Nhanh
+
+### 1. Xuất chuỗi proxy dùng cho phần mềm:
+```bash
+# Định dạng chuẩn IP:PORT:USER:PASS (dùng cho antidetect browser, bot, tool)
+pia-proxy export --format standard
+# Kết quả: 14.169.55.237:1087:proxy_user:proxy_password_secure123
+
+# Định dạng URL:
+pia-proxy export --format url
+# Kết quả: socks5h://proxy_user:proxy_password_secure123@14.169.55.237:1087
+```
+
+### 2. Xem bảng trạng thái trực quan:
+```bash
+pia-proxy status
+# Giám sát trực tiếp liên tục mỗi 2 giây:
+pia-proxy status --watch -i 2
+```
+
+### 3. Mở rộng số lượng worker khi cần:
+```bash
+# Tăng lên 32 worker:
+pia-proxy scale 32
+
+# Giảm xuống 20 worker:
+pia-proxy scale 20
+```
+
+### 4. Kiểm thử chất lượng proxy & Zero-leak:
+```bash
+pia-proxy test --count 5
+```
+
+---
+
+## 🛠️ Triển Khai Thủ Công & Link Trực Tiếp
+
+- **Web Dashboard:** `http://<IP_SERVER>:8007/`
+- **API Status:** `http://<IP_SERVER>:8007/api/status`
+- **HAProxy Live Stats:** `http://<IP_SERVER>:8411/`
+- **Hướng dẫn cấu hình nâng cao:** [prod/README.md](prod/README.md)

pia_proxy-1.0.0/cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+PIA SOCKS5 Multi-Worker Proxy Pool - CLI Management Suite
+"""
+
+__version__ = "1.0.0"

pia_proxy-1.0.0/cli/api_client.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+class APIClientError(Exception):
+    def __init__(self, message: str, status_code: int | None = None, response_body: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class APIClient:
+    def __init__(self, base_url: str, token: str = "", timeout: float = 10.0):
+        self.base_url = base_url.rstrip("/")
+        self.token = token.strip()
+        self.timeout = timeout
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        if params:
+            query = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+            if query:
+                url = f"{url}?{query}"
+
+        headers = {
+            "User-Agent": "pia-proxy-cli/1.0",
+            "Accept": "application/json",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        data_bytes = None
+        if json_data is not None:
+            data_bytes = json.dumps(json_data).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        req = urllib.request.Request(url, data=data_bytes, headers=headers, method=method.upper())
+
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                if not raw.strip():
+                    return {}
+                return json.loads(raw)
+        except urllib.error.HTTPError as e:
+            raw_err = e.read().decode("utf-8", errors="ignore")
+            try:
+                body = json.loads(raw_err)
+            except Exception:
+                body = raw_err
+            raise APIClientError(
+                message=f"HTTP {e.code}: {e.reason}",
+                status_code=e.code,
+                response_body=body,
+            ) from e
+        except urllib.error.URLError as e:
+            raise APIClientError(message=f"Connection failed: {e.reason}") from e
+        except Exception as e:
+            raise APIClientError(message=f"Request error: {str(e)}") from e
+
+    def is_alive(self) -> bool:
+        try:
+            res = self._request("GET", "/healthz", timeout=3.0)
+            return bool(res.get("ok"))
+        except Exception:
+            return False
+
+    def get_status(self, refresh: bool = False) -> dict[str, Any]:
+        return self._request("GET", "/api/status", params={"refresh": refresh}, timeout=12.0)
+
+    def get_nodes(self, refresh: bool = False) -> list[dict[str, Any]]:
+        res = self._request("GET", "/api/nodes", params={"refresh": refresh}, timeout=10.0)
+        return res.get("nodes", [])
+
+    def get_healthy_nodes(self) -> dict[str, Any]:
+        return self._request("GET", "/api/nodes/healthy", timeout=6.0)
+
+    def get_node(self, node_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/nodes/{node_id}", timeout=6.0)
+
+    def set_mode(self, worker_count: int) -> dict[str, Any]:
+        return self._request("POST", "/api/mode", json_data={"worker_count": worker_count}, timeout=30.0)
+
+    def get_mode(self) -> dict[str, Any]:
+        return self._request("GET", "/api/mode", timeout=5.0)
+
+    def rotate_any(self, country: str | None = None, server: str | None = None, wait_for_ready: bool = False) -> dict[str, Any]:
+        payload: dict[str, Any] = {"wait_for_ready": wait_for_ready}
+        if country:
+            payload["country"] = country
+        if server:
+            payload["server"] = server
+        return self._request("POST", "/api/rotate-any", json_data=payload, timeout=20.0)
+
+    def rotate_node(self, node_id: str, country: str | None = None, server: str | None = None, wait_for_ready: bool = False) -> dict[str, Any]:
+        payload: dict[str, Any] = {"wait_for_ready": wait_for_ready}
+        if country:
+            payload["country"] = country
+        if server:
+            payload["server"] = server
+        return self._request("POST", f"/api/nodes/{node_id}/rotate", json_data=payload, timeout=25.0)
+
+    def recover_all(self, force: bool = False) -> dict[str, Any]:
+        return self._request("POST", "/api/recover", json_data={"force": force}, timeout=15.0)
+
+    def recover_node(self, node_id: str, force: bool = False) -> dict[str, Any]:
+        return self._request("POST", f"/api/nodes/{node_id}/recover", json_data={"force": force}, timeout=15.0)
+
+    def test_proxy(self) -> dict[str, Any]:
+        return self._request("GET", "/api/test-proxy", timeout=15.0)
+
+    def get_countries(self, refresh: bool = False) -> dict[str, Any]:
+        return self._request("GET", "/api/countries", params={"refresh": refresh}, timeout=15.0)
+
+    def get_logs(self, tail: int = 100) -> dict[str, Any]:
+        return self._request("GET", "/api/logs", params={"tail": tail}, timeout=10.0)

pia_proxy-1.0.0/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""
+CLI Subcommands package
+"""

pia_proxy-1.0.0/cli/commands/config.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from cli.config import CLIConfig
+
+
+@click.group("config", help="Manage proxy gateway credentials, environment settings, and ports.")
+def config_group() -> None:
+    pass
+
+
+@config_group.command("show", help="Display all active configuration parameters.")
+@click.pass_obj
+def config_show(obj: dict[str, Any]) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    table = Table(title="[bold cyan]PIA Proxy Configuration Summary[/bold cyan]", expand=True)
+    table.add_column("Parameter", style="bold white", width=24)
+    table.add_column("Value", style="yellow")
+    table.add_column("Location / Source", style="dim")
+
+    table.add_row("Project Root", str(config.project_root), "Detected")
+    table.add_row("Compose Dir", str(config.compose_dir), "Detected")
+    table.add_row(".env File", str(config.env_file), "Detected")
+    table.add_row("Credentials Dir", str(config.credentials_dir), "Detected")
+    table.add_row("SOCKS5 Proxy Port", str(config.proxy_port), ".env (PROXY_PORT)")
+    table.add_row("SOCKS5 Username", config.socks5_user, ".env (SOCKS5_USERNAME)")
+    table.add_row("SOCKS5 Password", "***" + config.socks5_pass[-4:] if len(config.socks5_pass) > 4 else "***", ".env (SOCKS5_PASSWORD)")
+    table.add_row("Backend API Port", str(config.api_port), ".env (API_PORT)")
+    table.add_row("Active Worker Count", str(config.worker_count), ".env (WORKER_COUNT)")
+    table.add_row("Max Worker Count", str(config.max_worker_count), ".env (MAX_WORKER_COUNT)")
+
+    u, p = config.get_pia_account()
+    if u and p:
+        table.add_row("PIA Account", f"{u} / {'*' * len(p)}", "credentials/pia_account_1")
+    else:
+        table.add_row("PIA Account", "[bold red]Not Configured![/bold red]", "credentials/pia_account_1")
+
+    session_file = config.credentials_dir / "pia_session_slot_1.json"
+    table.add_row("PIA Session Cache", "Present" if session_file.exists() else "Missing", "credentials/pia_session_slot_1.json")
+
+    console.print(table)
+
+
+@config_group.command("set-credentials", help="Configure PIA account username and password.")
+@click.option("--username", "-u", prompt=True, help="PIA Username (e.g. p1234567)")
+@click.option("--password", "-p", prompt=True, hide_input=True, confirmation_prompt=True, help="PIA Password")
+@click.pass_obj
+def config_set_credentials(obj: dict[str, Any], username: str, password: str) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    if not username.strip() or not password.strip():
+        console.print("[bold red]Username and password cannot be empty.[/bold red]")
+        raise SystemExit(1)
+
+    config.set_pia_account(username.strip(), password.strip())
+    console.print(f"[bold green]✔ Saved PIA account credentials to {config.credentials_dir / 'pia_account_1'}.[/bold green]")
+
+
+@config_group.command("set-proxy-auth", help="Set username and password required for SOCKS5 proxy clients.")
+@click.option("--username", "-u", prompt=True, help="Proxy username")
+@click.option("--password", "-p", prompt=True, hide_input=True, confirmation_prompt=True, help="Proxy password")
+@click.pass_obj
+def config_set_proxy_auth(obj: dict[str, Any], username: str, password: str) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    config.update_env_value("SOCKS5_USERNAME", username.strip())
+    config.update_env_value("SOCKS5_PASSWORD", password.strip())
+    console.print("[bold green]✔ Updated SOCKS5 credentials in .env.[/bold green]")
+    console.print("[dim]Note: Restart proxy pool with 'pia-proxy restart' to apply new proxy credentials.[/dim]")
+
+
+@config_group.command("set-port", help="Set the external port for SOCKS5 gateway or backend API.")
+@click.option("--proxy-port", type=int, default=None, help="New SOCKS5 gateway port (e.g. 1087, 1080)")
+@click.option("--api-port", type=int, default=None, help="New Backend API port (e.g. 8007)")
+@click.pass_obj
+def config_set_port(obj: dict[str, Any], proxy_port: int | None, api_port: int | None) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    if proxy_port:
+        config.update_env_value("PROXY_PORT", proxy_port)
+        console.print(f"[bold green]✔ Set PROXY_PORT={proxy_port} in .env.[/bold green]")
+    if api_port:
+        config.update_env_value("API_PORT", api_port)
+        console.print(f"[bold green]✔ Set API_PORT={api_port} in .env.[/bold green]")
+
+    console.print("[dim]Note: Restart proxy pool with 'pia-proxy restart' to apply port changes.[/dim]")

pia_proxy-1.0.0/cli/commands/doctor.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from cli.config import CLIConfig
+
+
+def _is_port_open(port: int, host: str = "127.0.0.1") -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(0.5)
+        return s.connect_ex((host, port)) == 0
+
+
+@click.command("doctor", help="Inspect system readiness, tun device, ports, swap, and Docker requirements.")
+@click.pass_obj
+def doctor_cmd(obj: dict[str, Any]) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    table = Table(title="[bold cyan]System Environment & Health Diagnostics[/bold cyan]", expand=True)
+    table.add_column("Component", style="bold white", width=22)
+    table.add_column("Status", width=16)
+    table.add_column("Details", style="dim")
+
+    # 1. Docker Engine
+    docker_ok = False
+    try:
+        r = subprocess.run(["docker", "info"], capture_output=True, text=True, timeout=3)
+        docker_ok = r.returncode == 0
+    except Exception:
+        pass
+
+    if docker_ok:
+        table.add_row("Docker Engine", Text("✔ OK", style="bold green"), "Daemon is active and reachable")
+    else:
+        table.add_row("Docker Engine", Text("✗ ERROR", style="bold red"), "Docker daemon not running or access denied")
+
+    # 2. Docker Compose
+    compose_ok = False
+    try:
+        r = subprocess.run(["docker", "compose", "version"], capture_output=True, text=True, timeout=3)
+        compose_ok = r.returncode == 0
+        compose_ver = r.stdout.strip()
+    except Exception:
+        compose_ver = "Not installed"
+
+    if compose_ok:
+        table.add_row("Docker Compose", Text("✔ OK", style="bold green"), compose_ver)
+    else:
+        table.add_row("Docker Compose", Text("✗ ERROR", style="bold red"), "docker compose command missing")
+
+    # 3. TUN device
+    tun_path = Path("/dev/net/tun")
+    if tun_path.exists():
+        table.add_row("TUN Device", Text("✔ OK", style="bold green"), "/dev/net/tun is present")
+    else:
+        table.add_row("TUN Device", Text("✗ MISSING", style="bold red"), "Run 'mkdir -p /dev/net && mknod /dev/net/tun c 10 200'")
+
+    # 4. RAM & Swap
+    mem_ok = False
+    mem_info = "Unable to read /proc/meminfo"
+    try:
+        with open("/proc/meminfo") as f:
+            lines = f.readlines()
+            total_ram = 0
+            total_swap = 0
+            for line in lines:
+                if line.startswith("MemTotal:"):
+                    total_ram = int(line.split()[1]) // 1024
+                elif line.startswith("SwapTotal:"):
+                    total_swap = int(line.split()[1]) // 1024
+            mem_info = f"RAM: {total_ram}MB | Swap: {total_swap}MB"
+            mem_ok = total_swap >= 1000 or total_ram >= 3000
+    except Exception:
+        pass
+
+    if mem_ok:
+        table.add_row("Memory & Swap", Text("✔ OK", style="bold green"), mem_info)
+    else:
+        table.add_row("Memory & Swap", Text("⚠ WARN", style="bold yellow"), f"{mem_info} (Recommend adding >= 2GB swap)")
+
+    # 5. PIA Credentials
+    u, p = config.get_pia_account()
+    if u and p:
+        table.add_row("PIA Account", Text("✔ READY", style="bold green"), f"Username: {u}")
+    else:
+        table.add_row("PIA Account", Text("✗ NOT SET", style="bold red"), "Configure with 'pia-proxy config set-credentials'")
+
+    # 6. Gateway Port (1087)
+    gw_in_use = _is_port_open(config.proxy_port)
+    table.add_row(f"Proxy Port ({config.proxy_port})", Text("IN USE" if gw_in_use else "AVAILABLE", style="cyan" if gw_in_use else "green"), "SOCKS5 Proxy Gateway")
+
+    # 7. API Port (8007)
+    api_in_use = _is_port_open(config.api_port)
+    table.add_row(f"API Port ({config.api_port})", Text("IN USE" if api_in_use else "AVAILABLE", style="cyan" if api_in_use else "green"), "FastAPI Backend")
+
+    console.print(table)

pia_proxy-1.0.0/cli/commands/export.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+from rich.console import Console
+
+from cli.config import CLIConfig
+
+
+@click.command("export", help="Export proxy connection strings formatted for bots, antidetect browsers, or crawlers.")
+@click.option(
+    "--format",
+    "-f",
+    type=click.Choice(["url", "standard", "curl", "json", "env"]),
+    default="standard",
+    help="Output format (standard = IP:PORT:USER:PASS).",
+    show_default=True,
+)
+@click.option("--host", "-H", default=None, help="Custom server IP or hostname override.")
+@click.pass_obj
+def export_cmd(obj: dict[str, Any], format: str, host: str | None) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    server_ip = host or config.get_public_ip()
+    port = config.proxy_port
+    user = config.socks5_user
+    pwd = config.socks5_pass
+
+    if format == "standard":
+        # IP:PORT:USER:PASS format commonly accepted by antidetect tools
+        click.echo(f"{server_ip}:{port}:{user}:{pwd}")
+    elif format == "url":
+        click.echo(f"socks5h://{user}:{pwd}@{server_ip}:{port}")
+    elif format == "curl":
+        click.echo(f"curl -x socks5h://{user}:{pwd}@{server_ip}:{port} https://api.ipify.org")
+    elif format == "json":
+        data = {
+            "type": "socks5",
+            "host": server_ip,
+            "port": port,
+            "username": user,
+            "password": pwd,
+            "url": f"socks5h://{user}:{pwd}@{server_ip}:{port}",
+            "standard": f"{server_ip}:{port}:{user}:{pwd}",
+        }
+        click.echo(json.dumps(data, indent=2))
+    elif format == "env":
+        click.echo(f'export ALL_PROXY="socks5h://{user}:{pwd}@{server_ip}:{port}"')
+        click.echo(f'export HTTP_PROXY="socks5h://{user}:{pwd}@{server_ip}:{port}"')
+        click.echo(f'export HTTPS_PROXY="socks5h://{user}:{pwd}@{server_ip}:{port}"')