feat: add Tailscale exit node support for school system requests

- Add tailscale sidecar container in docker-compose.yml (profile: tailscale)
- Add get_school_http_session() with SOCKS5 proxy support in http_client.py
- Switch fetcher.py to use school-specific HTTP session
- Add PySocks dependency to requirements.txt
- Add TS_AUTHKEY, TS_EXIT_NODE, TS_HOSTNAME env vars to .env.example
- Only school system requests route through proxy; Turnstile etc. unaffected
- Feature is opt-in: requires --profile tailscale and env vars to activate

Author: alvin000009238

.env.example

@@ -17,3 +17,8 @@ TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
 
 # 其他選填參數
 # SHARE_TTL=7200
+
+# Tailscale Exit Node (選填，啟用後學校系統請求會透過指定的 exit node 轉發)
+# TS_AUTHKEY=tskey-auth-xxxxx
+# TS_EXIT_NODE=100.x.x.x
+# TS_HOSTNAME=grades-docker

app/services/http_client.py

@@ -68,6 +68,7 @@ def get_http_session() -> TimeoutSession:
     """
     Returns a requests.Session customized with default timeouts and automatic retries.
     Configurable via environment variables.
+    This session does NOT use any proxy — suitable for Turnstile, internal services, etc.
     """
     try:
         total_retries = int(os.environ.get("HTTP_RETRY_TOTAL", 3))
@@ -106,3 +107,29 @@ def get_http_session() -> TimeoutSession:
     session.mount("https://", adapter)
 
     return session
+
+
+def get_school_http_session() -> TimeoutSession:
+    """
+    Returns a requests.Session for school system requests.
+    If SCHOOL_SOCKS_PROXY is set (e.g. socks5://tailscale:1055), routes traffic
+    through a Tailscale exit node. Otherwise behaves identically to get_http_session().
+    """
+    session = get_http_session()
+
+    socks_proxy = os.environ.get("SCHOOL_SOCKS_PROXY", "").strip()
+    if socks_proxy:
+        session.proxies = {
+            "http": socks_proxy,
+            "https": socks_proxy,
+        }
+        # 只記錄 proxy host:port，不記錄任何 auth 資訊
+        try:
+            from urllib.parse import urlparse
+            parsed = urlparse(socks_proxy)
+            safe_addr = f"{parsed.hostname}:{parsed.port}"
+        except Exception:
+            safe_addr = "(parse error)"
+        logger.info(f"School HTTP session using SOCKS proxy: {safe_addr}")
+
+    return session

docker-compose.yml

@@ -8,6 +8,7 @@ services:
       - PYTHONUNBUFFERED=1
       - REDIS_URL=redis://redis:6379/0
       - TZ=Asia/Taipei
+      - SCHOOL_SOCKS_PROXY=${TS_EXIT_NODE:+socks5://tailscale:1055}
     ports:
       - "5000:5000"
 
@@ -27,6 +28,23 @@ services:
       retries: 3
       start_period: 10s
 
+  tailscale:
+    image: tailscale/tailscale:latest
+    hostname: ${TS_HOSTNAME:-grades-docker}
+    environment:
+      - TS_AUTHKEY=${TS_AUTHKEY:-}
+      - TS_EXTRA_ARGS=--exit-node=${TS_EXIT_NODE:-}
+      - TS_TAILSCALED_EXTRA_ARGS=--socks5-server=0.0.0.0:1055
+      - TS_STATE_DIR=/var/lib/tailscale
+      - TS_USERSPACE=true
+    volumes:
+      - tailscale_state:/var/lib/tailscale
+    deploy:
+      restart_policy:
+        condition: any
+    profiles:
+      - tailscale
+
   tunnel:
     image: cloudflare/cloudflared:latest
     command: tunnel run
@@ -46,3 +64,4 @@ services:
 
 volumes:
   redis_data:
+  tailscale_state:

fetcher.py

@@ -52,9 +52,9 @@ class GradeFetcher:
 
     def __init__(self, session_factory=None):
         if session_factory is None:
-            # Delay import to avoid circular dependency if any, or just use the injected one
-            from app.services.http_client import get_http_session
-            self.session_factory = get_http_session
+            # 使用學校系統專用的 HTTP session，當環境設定 SOCKS proxy 時會走 Tailscale exit node
+            from app.services.http_client import get_school_http_session
+            self.session_factory = get_school_http_session
         else:
             self.session_factory = session_factory
 

requirements.txt

@@ -8,6 +8,7 @@ Flask-Session==0.8.0
 
 # HTTP & Scraping
 requests==2.32.5
+PySocks==1.7.1
 urllib3==2.6.3
 beautifulsoup4==4.14.3
 certifi==2026.2.25