csansoon/hostel-server-setup

設定 Hostel 伺服器

伺服器負責維護佇列、使用者、配置和 SSH 閘道。 為團隊執行一台伺服器。代理程式和人員從他們自己的電腦 連線 (hostel-install)。

1. 選擇機器與 TLS 模式

• 一台搭載 systemd 的 Linux 機器（amd64 或 arm64；2 顆 CPU 和 4 GB 記憶體即足夠），或 一台保持開機的家用機器。此儲存庫僅記錄 systemd 服務； 在其他作業系統上，請使用您自己的服務管理器執行 hostel server run。
• 一個客戶端可存取的 HTTPS 地址。API 與閘道共用此地址： 閘道在 /v1/gateway 上接受 WebSocket 內的 SSH 連線。

TLS 模式	使用時機	客戶端驗證
self-signed（預設）	沒有網域或沒有代理：IP 地址、LAN 名稱、VPN 名稱。伺服器使用自己的憑證提供 HTTPS。	邀請碼中的釘選金鑰。
off	代理伺服器（Caddy、雲端負載平衡器）位於伺服器前方，並負責 TLS。	正常驗證代理的憑證。

2. 安裝

以伺服器機器上的管理員身份執行：

curl -fsSL -o install.sh https://raw.githubusercontent.com/csansoon/hostel/main/install.sh
sudo sh install.sh --dir /usr/local/bin --server /opt/hostel

/opt/hostel/helpers 會取得所有房間的二進位檔（hostel-<os>-<arch>、 mise-<os>-<arch>）。/opt/hostel/platforms 會取得平台腳本（僅 舊版伺服器會匯入它們；二進位檔已包含預設平台）。

3. 初始化

以執行服務的使用者（非 root）身份執行 hostel server init。 在終端機中，若未透過旗標提供，它會詢問伺服器名稱、地址和您的姓名。旗標：

旗標	意義
--server-id	伺服器名稱，[a-z0-9]{1,20}（預設：從主機名稱取得）。它會成為伺服器所建立房間名稱的一部分。
--listen	API 地址（預設 127.0.0.1:7410）。
--tls	self-signed（預設）或 off。
--url	客戶端使用的地址。可重複使用以設定多個地址。邀請碼會包含它們。
--user	您的姓名，用於建立第一個管理員。
--helper-dir	房間的二進位檔目錄：install.sh --server /opt/hostel 後的 /opt/hostel/helpers（預設：data_dir/helpers）。
--config	要寫入的檔案（預設 ~/.config/hostel/server.toml）。

使用自簽憑證，在自己的連接埠上執行（在防火牆中開啟 TCP 7410）：

hostel server init --server-id demo --listen 0.0.0.0:7410 \
  --url https://hostel.example.com:7410 --user "Alice Example" \
  --helper-dir /opt/hostel/helpers

位於有 TLS 的代理後方：

hostel server init --server-id demo --tls off --listen 127.0.0.1:8000 \
  --url https://hostel.example.com --user "Alice Example" \
  --helper-dir /opt/hostel/helpers

使用 --tls off 和 https:// 地址時，init 也會寫入 gateway_public = "wss://hostel.example.com/v1/gateway"：訪客和已加入的機器 會透過代理連線到 SSH 閘道。代理必須將 /v1/gateway（一個 WebSocket）轉發到伺服器。

init 會寫入 server.toml、hostel.schema.json、資料目錄 （~/.local/share/hostel：資料庫、server_ed25519、gateway_host_ed25519 和 TLS 憑證），並列印伺服器的 SSH 公鑰和第一個管理員邀請碼：

Connect your computer as the first admin. Run this on your computer:

  hostel connect hostel1-...

請在 24 小時內於您自己的電腦上執行該命令（hostel-install）。

4. 編輯 server.toml

server.toml 僅包含伺服器在開啟資料庫前所需的金鑰：server_id、listen、 gateway_listen、gateway_public、tls、public_urls、data_dir、helper_dir、 platforms_dir。init 會寫入 helper_dir（使用 --helper-dir）以及（位於代理後方時） gateway_public。請檢查它們：

grep -E 'helper_dir|gateway_public' ~/.config/hostel/server.toml
hostel admin config check

沒有 helper_dir，伺服器就無法為房間提供助手，且 hostel machine join 也無法下載二進位檔。位於代理後方時如果沒有 gateway_public， 每個訪客 SSH 工作階段和每個已加入的機器都會失敗。

一個 Caddy 範例（Caddy 會傳遞 WebSocket 升級，無需額外設定）：

hostel.example.com {
	reverse_proxy 127.0.0.1:8000
}

使用 tls = "self-signed" 時，預設的 gateway_public 為同一地址上的 /v1/gateway； 請勿設定它。檢查檔案（它會列印每個問題和有效值）：

hostel admin config check

變更 server.toml 後需要重新啟動伺服器。

5. systemd 服務

/etc/systemd/system/hostel.service（將 alice 替換為執行 init 的使用者）：

[Unit]
Description=Hostel server
After=network-online.target
Wants=network-online.target

[Service]
User=alice
ExecStart=/usr/local/bin/hostel server run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now hostel
journalctl -u hostel -f

hostel server run --config <file> 可選用另一個 server.toml。日誌為 stderr 上的 JSON 格式。如果配置無效，伺服器將無法啟動，且日誌會說明原因。

對於命名空間房間，devbox 和 nsc CLI 必須位於服務的 PATH 中（請參閱 hostel-rooms 中的「命名空間」章節）。

6. 資料庫中的配置

所有其他設定（提供者、機器、平台和設定）都儲存在資料庫的 配置文件中。管理員可以從任何已連線的電腦變更它。 有效的變更會立即生效，無需重新啟動。

hostel config                    # 顯示文件（成員會看到機密顯示為 ***）
hostel config edit               # 在 $VISUAL / $EDITOR 中編輯
hostel config apply file.toml    # 用檔案取代（或使用 - 從 stdin 讀取）
hostel config history            # 修訂紀錄，包含使用者和時間
hostel config settings           # 非預設值的設定
hostel config settings set idle_timeout=20m

設定：idle_timeout（10m）、poll_timeout（5m）、limit_retry（2m）、 port_process_offline（10m）、intervals.scheduler（10s）、 intervals.reconcile（5m）、intervals.tunnel_check（30s）、 intervals.presence（30s）、mise.idiomatic_tools（["node", "python"]）、 mise.github_token、mise.agent_device（true）。

如果另一個修訂版本先寫入（需再次編輯）或配置無效（錯誤會指出金鑰路徑）， 伺服器將拒絕變更。機器與提供者：請參閱 hostel-rooms。 平台：請參閱 hostel-platforms。使用者：請參閱 hostel-users。

7. 在伺服器機器上產生邀請碼

如果沒有人能以管理員身份登入，請直接在伺服器機器上產生邀請碼（它不使用 API）：

hostel server invite                     # 管理員邀請
hostel server invite --role member --name "Bob Example"

8. 備份

狀態位於資料目錄中（~/.local/share/hostel）。備份金鑰一次 （server_ed25519、gateway_host_ed25519、tls_cert.pem、tls_key.pem）。 使用 SQLite 備份資料庫，而不是直接複製檔案：

sqlite3 ~/.local/share/hostel/hostel.db ".backup /var/backups/hostel.db"

• 資料庫遺失：使用者必須重新連線；具有此 server_id 的隨需房間將在 下一次協調時被銷毀。
• server_ed25519 遺失：將新的公鑰（hostel admin pubkey）放置到每個 靜態機器上。
• TLS 金鑰遺失（自簽憑證）：每個客戶端必須使用新的邀請碼重新連線。

9. 更新

curl -fsSL -o install.sh https://raw.githubusercontent.com/csansoon/hostel/main/install.sh
sudo sh install.sh --dir /usr/local/bin --server /opt/hostel
sudo systemctl restart hostel

伺服器會在下一次租約到期前將新的助手發送給每個房間。

下一步

• 新增房間：請參閱 hostel-rooms。
• 邀請人員：請參閱 hostel-users。