termix 搭配 tailscale

本文記錄如何透過 Docker 部署 Web-based 終端機 Termix，並結合 Tailscale 網狀網路，解決跨實體區域網路的 SSH/SFTP 連線管理問題。

1. Termix 簡介與 Docker Compose 部署

1.1 Termix 功能概述與網路需求

Termix 是一款輕量化的網頁終端機面板。部署完成後，可直接透過桌面或行動裝置的瀏覽器存取伺服器，無需額外安裝 SSH App 或匯入金鑰。

• GitHub 專案位址：https://github.com/lukegus/termix

跨網段痛點：若 Termix 部署於 A 區網，而目標伺服器位於 B 區網（如 192.168.yy.x），預設無法連線。此處選用 Tailscale 作為底層 VPN，將 Termix 與目標內網橋接。

1.2 取得 Tailscale Auth Key

部署 Docker 前，需先申請 API 金鑰供容器自動登入 Tailscale 網路。

1. 登入 Tailscale 管理控制台：https://login.tailscale.com/admin

2. 進入 Settings -> Keys -> Auth keys。

3. 點擊 Generate auth key。

4. 勾選 Reusable（容器重啟可重複使用）與 Ephemeral（容器刪除時自動清除節點）。

5. 複製產生的 tskey-auth-... 字串。

1.3 Docker Compose 設定檔

於工作目錄建立 .env 檔案存放金鑰：

TS_AUTHKEY=tskey-auth-你的金鑰字串...

建立 docker-compose.yaml。此處採用 Sidecar 模式，將 Termix 的網路綁定至 Tailscale 容器。設定檔中需特別注意特權模式（privileged）與 TUN 設備掛載，以確保底層網卡正常運作。

YAML

services:
  # 1. Tailscale 網狀網路節點 (Sidecar 核心)
  tailscaled:
    image: tailscale/tailscale:latest
    container_name: termix-tailscale
    hostname: markliou-termix
    
    # 【關鍵】賦予特權模式，突破系統底層硬體限制
    privileged: true 
    
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_STATE_DIR=/var/lib/tailscale
      # 【關鍵】指示該節點主動接收遠端 Subnet Router 廣播的內網路由
      - TS_EXTRA_ARGS=--accept-routes
      # 【關鍵】強制關閉降級機制，指定使用 Kernel 網卡模式修改路由表
      - TS_USERSPACE=false
      
    volumes:
      - tailscale-data:/var/lib/tailscale
      
    # 【關鍵】宣告實體 TUN 設備掛載
    devices:
      - /dev/net/tun:/dev/net/tun
      
    cap_add:
      - NET_ADMIN
      - NET_RAW
    ports:
      - "8000:8080"
    networks:
      - termix-net
    restart: unless-stopped

  # 2. Termix 服務
  termix:
    image: ghcr.io/lukegus/termix:latest
    container_name: termix
    restart: unless-stopped
    # 網路層強制綁定至 tailscaled 容器，統一由 VPN 隧道出入
    network_mode: "service:tailscaled"  
    volumes:
      - termix-data:/app/data
    depends_on:
      - guacd
      - tailscaled

  # 3. Guacamole 代理服務
  guacd:
    image: guacamole/guacd:latest
    container_name: guacd
    restart: unless-stopped
    networks:
      - termix-net

volumes:
  termix-data:
    driver: local
  tailscale-data:
    driver: local

networks:
  termix-net:
    driver: bridge

上面幾個要點筆記:

1. 網路部分就是全權交給tailscale了，所以連port的設定都要從原本是termix的container移轉到tailscale路由器container上面

2. enviroment的封包轉發頗重要，要可以廣播到整個docker-compose的網路上

執行啟動指令：

Bash

sudo docker-compose up -d

---

2. Tailscale 路由概念與遠端伺服器 (Subnet Router) 設定

2.1 跨網段路由概念

要讓 Termix 容器存取遠端內網，需在遠端內網配置一台實體主機作為「子網路由器 (Subnet Router)」。

運作邏輯如下：

1. 遠端主機向 Tailscale 網路廣播目標網段（如 192.168.yy.x）。

2. Termix 容器因帶有 --accept-routes 參數，會接收該廣播。

3. 當 Termix 發出前往 192.168.yy.x 的封包時，系統會查詢 Tailscale 建立的隱藏路由表（Table 52），並將封包封裝後送往遠端主機進行解封與轉發。因為涉及到封包轉發出去，所以就有下面2.2的ubuntu核心參數修改

2.2 遠端主機 IP 轉發設定

於目標內網的遠端主機（如 Ubuntu）執行以下指令，修改 Linux 核心參數以允許封包轉發：

Bash

echo 'net.ipv4.ip_forward = 1' | sudo tee -a /etc/sysctl.d/99-tailscale.conf
echo 'net.ipv6.conf.all.forwarding = 1' | sudo tee -a /etc/sysctl.d/99-tailscale.conf
sudo sysctl -p /etc/sysctl.d/99-tailscale.conf

2.3 廣播目標路由指令

執行 tailscale up 指令並指定要放行的內網網段。若需同時打通多個網段（例如增加 10.2.0.0/16），需以半形逗號分隔，不可包含空格：

Bash

sudo tailscale up --advertise-routes=192.168.yy.0/24,10.2.y.y/16

上面的直觀的意思就是: 碰到192.168.yy.xx跟10.2.yy.yy就是要進入到這個路由，往對面的區往丟。這樣設計很巧妙，因為如果兩邊內網有可能又碰到ip相衝，例如我串接AB兩個網段，A跟B上面又有其他網段一樣都是192.168.4.x，那這邊的設定就可以人為操作那些封包要阻擋下來不要往遠方網段丟，以免丟錯機器

另外一個值得提的，就是tailscale up是一個系統等級的指令，所以那台機器上面的所有使用者都會依循這路由規則，同時如果機器有重開，tailscale是會自動起來，不用寫到run level當中

2.4 管理控制台核准路由

基於安全性，廣播的路由不會自動生效，需手動放行：

1. 回到 Tailscale 管理控制台：https://login.tailscale.com/admin/machines

2. 找到該台遠端 Ubuntu 節點，點擊右側 ⋮ 選單，選擇 Edit route settings。

3. 在 Subnet routes 區塊中，將 192.168.yy./24 與 10.2.0.0/16 旁邊的開關設為 Enable。位置就是上面的那張圖，有個"Edit route setting"，點進去就知道要在哪邊打勾了。

---

3. 路由建立驗證

Tailscale 會將跨網段路由寫入隱藏的第 52 號路由表 (Table 52) 以避免與系統主路由衝突。回到部署 Termix 的宿主機，執行以下指令驗證：

Bash

sudo docker exec -it termix-tailscale ip route show table 52

若輸出顯示對應的網段由 tailscale0 設備接管，即代表底層網路對接完成：

10.2.0.0/16 dev tailscale0
192.168.71.0/24 dev tailscale0

至此，已可直接開啟 Termix 網頁介面，輸入遠端內網 IP 進行無縫連線操作。