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 地址、局域网名称、VPN 名称。服务器使用自己的证书提供 HTTPS。	来自邀请码的固定密钥。
off	服务器前端有带 TLS 的代理（Caddy、云负载均衡器）。	代理的证书，以正常方式校验。

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。日志以 JSON 格式输出到 stderr。如果配置无效，服务器将无法启动，日志会说明原因。

对于命名空间房间，devbox 和 nsc CLI 必须位于服务的 PATH 中（hostel-rooms，章节“Namespace”）。

6. 数据库中的配置

其他所有内容（提供者、机器、平台和设置）都存储在数据库的配置文档中。管理员可以从任何连接的计算机更改它。有效的更改会立即生效，无需重启。

hostel config                    # 显示文档（成员会将密钥显示为 ***）
hostel config edit               # 在 $VISUAL / $EDITOR 中更改
hostel config apply file.toml    # 用文件替换（或使用 - 从标准输入读取）
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 的按需房间将在下一次 reconciled 时被销毁。
• 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。