csansoon/hostel-rooms

新增與管理房間

機器設定於伺服器上的設定文件中。您必須是管理員（hostel-users）。每次變更會立即生效。

hostel config providers        # 名稱, 種類, 機器
hostel config rooms            # 機器, 種類, 作業系統, 平台, 標籤, 房間
hostel config edit             # 在 $EDITOR 中編輯 TOML 檔案

機器命名為 <provider>/<machine>，或僅以 <machine> 命名（當名稱唯一時）。名稱必須符合 ^[a-z][a-z0-9-]*$。平台需求（Xcode、Android SDK、KVM、桌面環境）位於 hostel-platforms。

位於 NAT 後方的機器（機器連接到伺服器）

這適用於大多數自有機器：家中的 Mac mini、Windows PC、Linux 電腦。機器會與伺服器保持出站連線，不需要來自網際網路的入站 SSH。

1. 在您的電腦上，建立一個機器代碼（24 小時有效，僅能使用一次）：

   hostel config rooms add mac-mini --platform ios --label xcode-26.5 --label desktop
   hostel config rooms add win-pc --label desktop
   

   --platform 和 --label 可以重複。--provider 選擇靜態提供者（預設為 home；若不存在，伺服器會自動新增）。在應用程式中：櫃檯 › 新增房間。

2. 在新機器上以管理員身分執行列印出的命令：macOS 和 Linux 使用 sudo，Windows 使用管理員 PowerShell。該命令會從您的伺服器下載 hostel 並執行 hostel machine join <code>。

hostel machine join 會建立使用者 hostel（無管理員權限）、安裝伺服器的金鑰、將機器新增至設定檔（connect = true，作業系統由機器自動偵測），並安裝執行 hostel machine connect 的服務：

作業系統	服務	紀錄檔
Linux	systemd 單元 hostel-machine-connect.service（使用者 hostel-connect）	journalctl -u hostel-machine-connect
macOS	LaunchDaemon so.hostel.machine-connect	/var/log/hostel-machine-connect.log
Windows	排程工作 Hostel machine connect（LOCAL SERVICE）	C:\ProgramData\hostel\machine-connect.log

Token 位於 /etc/hostel 或 C:\ProgramData\hostel；房間使用者無法讀取。如果某個步驟失敗，請修正問題後再次執行相同命令：它會從中斷處繼續。--no-service 會跳過服務安裝，並印出 hostel machine connect 命令供您自行執行（--server <url> --token-file <file> [--server-key k] [--ssh 127.0.0.1:22]）。

3. 執行 join 印出的、僅能由人來完成的步驟：

   • macOS：系統設定 › 一般 › 共享 › 開啟「遠端登入」，對象為 hostel；iOS 需要 Xcode；若需要 desktop，請設定 hostel 自動登入，且螢幕保護程式啟動後不需密碼。
   • Windows：OpenSSH 伺服器必須執行並設為自動啟動（Get-Service sshd）；若需要 desktop，請設定「Hostel desktop」工作。
   • Linux：SSH 伺服器在連接埠 22 執行，並允許 hostel 使用者使用金鑰登入。

4. 檢查：hostel status 會在一分鐘內顯示該房間。

伺服器可透過 SSH 連線的靜態機器

當您的伺服器可以開啟 TCP 連線到該機器（相同區域網路或 VPN）時使用此方式。在機器上建立標準使用者 hostel，並安裝伺服器的 SSH 公鑰。該公鑰是 hostel admin pubkey（在管理員的電腦上執行）的輸出，hostel server init 也會印出它（「伺服器公鑰」）。在 Linux 上：

sudo useradd -m -s /bin/bash hostel
sudo install -d -m 700 -o hostel -g hostel ~hostel/.ssh
echo 'ssh-ed25519 AAAA... hostel-server' | sudo tee ~hostel/.ssh/authorized_keys
sudo chown hostel:hostel ~hostel/.ssh/authorized_keys && sudo chmod 600 ~hostel/.ssh/authorized_keys

允許該使用者使用 SSH 金鑰登入。請保持 sshd 中的 TCP 轉送功能開啟（OpenSSH 預設開啟；通道需要此功能）。然後使用 hostel config edit 新增：

[providers.home]
kind = "static"

[providers.home.machines.mac-mini]
address = "[email protected]"    # user@host[:port]；預設使用者為 hostel，連接埠 22
os = "macos"                         # 必要：linux、macos 或 windows
platforms = ["ios", "android"]       # 裝置平台；作業系統平台為自動偵測
labels = ["xcode-26.5", "desktop"]
tools = { java = "21" }              # 機器層級的 mise 工具
env = { HOSTEL_IOS_RUNTIME = "26.5" }
# slots = [{ name = "a" }, { name = "b" }]   # 一次兩個租約（預設為一個 slot "a"）

• slots：每個 slot n 會取得用於通道的連接埠 7500 + 10n 到 7509 + 10n。Slot 可以設定 ports、env 及其自己的 OS user。
• 提供者層級的 env 和 tools 會套用到其所有機器；機器層級的金鑰會取代相同名稱的金鑰。
• 伺服器會在第一次連線時鎖定該機器的 SSH 主機金鑰。
• Windows 手動設定：請參考 docs/static-room-setup.md 中的「Windows」章節（使用者以及 OpenSSH 要求的 authorized_keys 存取規則）。
• 對於公開位址：僅允許來自伺服器的入站 SSH，或使用 connect = true（加入流程）並關閉入站 SSH。

在不使用編輯器的情況下變更某個金鑰（platforms 和 labels 是逗號分隔的清單）：

hostel config rooms set mac-mini labels=xcode-26.5,desktop
hostel config rooms set mac-mini platforms=ios

Namespace（隨需雲端機器）

Namespace (namespace.so) 會在需要租用時建立房間：devbox（macOS 或 Linux），instance（Linux）。兩個 CLI 都必須安裝在伺服器使用者之下，並將 ~/.local/bin 加入服務的 PATH：

curl -fsSL https://get.namespace.so/cloud/install.sh | sh        # nsc
curl -fsSL get.namespace.so/devbox/install.sh | bash             # devbox
sudo mkdir -p /etc/systemd/system/hostel.service.d
printf '[Service]\nEnvironment=PATH=%s/.local/bin:/usr/local/bin:/usr/bin:/bin\n' "$HOME" \
  | sudo tee /etc/systemd/system/hostel.service.d/path.conf
sudo systemctl daemon-reload && sudo systemctl restart hostel

在您的電腦上執行（它會印出一個 URL；開啟它並選擇工作區）：

hostel config providers login namespace        # --cli devbox 或 --cli nsc 用於其中一個 CLI
hostel config providers add ns --kind namespace

然後使用 hostel config edit 新增機器範本：

[providers.ns]
kind = "namespace"
max_rooms = 3                        # 此提供者的所有機器總和
# limits = [{ machines = ["mac"], max_rooms = 1 }]

[providers.ns.machines.mac]
spec = { product = "devbox", platform = "macos", size = "m", image = "tahoe-slim" }
platforms = ["ios"]
labels = ["xcode-26.5", "desktop"]
env = { DEVELOPER_DIR = "/Applications/Xcode_26.5.app/Contents/Developer", HOSTEL_IOS_RUNTIME = "26.5" }
max_rooms = 1
max_lifetime = "3h"                  # devbox 必要：方案的最大持續時間

[providers.ns.machines.linux]
spec = { product = "instance", machine_type = "linux/amd64:8x16" }   # 可選：image（預設 ubuntu:24.04）
platforms = ["android"]
labels = ["kvm"]
tools = { java = "21" }
max_rooms = 2

成本與限制（請在 Namespace 查看目前方案）：

• Hostel 僅對名稱前綴為 hostel-<server_id>- 的房間進行操作。
• Devbox 是短暫的：在大約 15 分鐘閒置後，以及在達到 max_lifetime 時會被刪除。Instance 有固定的截止時間，伺服器會延長它。
• macOS devbox 每分鐘的成本遠高於 Linux devbox。
• 方案限制會一併套用至所有租用（它們共用同一個登入）。在 Developer 方案上：每個使用者一個 devbox、最長 3 小時、無 Windows。出現「已達限制」錯誤時，機器會在 limit_retry（2 分鐘）內被標記為已滿。
• 僅支援 linux instance 類型。Namespace 上的 Android 使用 Linux。
• 一次登入可持續數天。當登入失效時，提供者呼叫會失敗：請重新登入。

外部提供者（您自己的命令）

kind = "external" 會針對每個操作（capabilities、provision、resume、stop、extend、destroy、list、access）執行您的命令，並透過 stdin/stdout 傳遞 JSON。docs/design.md 第 7 節「外部提供者合約」提供了完整合約。此儲存庫中的 test/fakeprovider（Docker 容器）是一個測試工具，而非受支援的提供者。

[providers.docker]
kind = "external"
command = ["/usr/local/bin/my-provider"]
command_env = { DOCKER_HOST = "unix:///var/run/docker.sock" }
timeouts = { provision = "5m", default = "1m" }

[providers.docker.machines.small]
os = "linux"                         # 必要
spec = { image = "debian:13" }       # 原樣傳遞給您的命令
max_rooms = 2

限制與暖啟動機器（隨需機器）

金鑰	位置	預設值
max_rooms	提供者（其所有機器）/ 機器	無 / 1
limits	提供者：[{ machines = [...], max_rooms = N }]	[]
max_lease	提供者, 機器	2h
max_lifetime	提供者, 機器	無
warm_running	提供者, 機器：讓一個空閒房間保持執行狀態的時長	5m
warm_stopped	提供者, 機器：保留一個已停止房間的時長	24h

卸載、修復、移除、銷毀

hostel config rooms drain mac-mini        # 不允許新租約；現有租約繼續
hostel config rooms undrain mac-mini
hostel config rooms repair mac-mini       # 重新檢查故障的房間
hostel config rooms repair mac-mini --accept-host-key
hostel config rooms destroy ns/mac        # 一個沒有租約的隨需房間（若有多個，請指定房間名稱）
hostel config rooms remove mac-mini       # 移除機器；其房間 token 將被撤銷
hostel config providers remove ns         # 僅在沒有隨需房間時才能移除

• 具有有效租約的機器無法被移除：請先將其卸載並等待。
• 具有房間的隨需機器無法被移除：請先將其銷毀。
• hostel admin room drain|undrain|repair|destroy <room name or ID> 可以按房間執行相同操作。

離線機器

每 intervals.presence（30 秒）伺服器會檢查每個靜態的閒置房間。沒有回應的房間會進入離線狀態，且不會接受新的租約。當它再次回應時，伺服器會自行重新準備它，無需任何命令。hostel status 會顯示 offline (last seen ...)。請參閱 hostel-troubleshoot。