docs/SSH_ACCESS.md

本地 SSH 到 HF 上的 Ubuntu（反向 SSH）

HF Spaces 只暴露一个端口（默认 7860），无法从公网直接 SSH 进容器。通过 反向 SSH：容器主动连到你的跳板机，你在本机先 SSH 到跳板机，再通过隧道连到容器。

---

1. 在 Space 里配置 Secrets

在 HuggingRun Space 的 Settings → Repository secrets 中增加：

Secret	说明
SSH_AUTHORIZED_KEYS	你的公钥（一行），用于登录容器里的用户。例如 ssh-rsa AAAA... your@email
SSH_REVERSE_TARGET	跳板机连接串，容器会用 ssh -R ... $SSH_REVERSE_TARGET -N 连出去。HF 出站只允许 80/443/8080，所以跳板机须在 443 或 8080 提供 SSH。示例：user@你的跳板机公网IP -p 443

---

2. 跳板机准备（你本机或一台有公网 IP 的机器）

• 跳板机需要 公网 IP 或域名，且从 HF 能访问（出站 443 或 8080）。

• 在跳板机上用 443 或 8080 跑 SSH（HF 不允许出站 22）：

  # 例如在 443 上跑 sshd（与现有 443 服务二选一）
  sudo sshd -p 443 -d  # 调试时
  # 或 /etc/ssh/sshd_config 里加 Port 443，然后 systemctl restart sshd
  

• 确保你的公钥已加入跳板机的 ~/.ssh/authorized_keys（容器连跳板机用），并且本机私钥对应 SSH_AUTHORIZED_KEYS 里的公钥（用于从跳板机进容器）。

---

3. 容器内行为

• 启动时若存在 SSH_AUTHORIZED_KEYS，会在 $HOME/.ssh 下起一个 非 root sshd，监听 127.0.0.1:2222。
• 若设置了 SSH_REVERSE_TARGET，会执行： ssh -R 0.0.0.0:2222:127.0.0.1:2222 $SSH_REVERSE_TARGET -N
• 这样跳板机的 2222 端口会转发到容器内的 2222（sshd）。

---

4. 本机如何 SSH 进容器

1. 先 SSH 到跳板机（如 443 端口）：

   ssh -p 443 user@跳板机公网IP
   

2. 在跳板机上连到容器（本机已通过反向隧道把容器 2222 映射到跳板机 2222）：

   ssh -p 2222 -o StrictHostKeyChecking=no localhost
   

   登录用户为容器内运行桌面时的用户（与 $HOME 一致）。

也可以本机一步到位（ProxyJump）：

ssh -J "ssh -p 443 user@跳板机公网IP" -p 2222 -o StrictHostKeyChecking=no localhost

（需跳板机允许 2222 的转发或本机用 LocalForward 等，通常更简单的是先登跳板机再 ssh -p 2222 localhost。）

---

5. 验收「本地能成功 SSH」

• 在 Space 已 RUNNING、且上述 Secrets 与跳板机都配置好后，在跳板机上执行： ssh -p 2222 localhost
• 能拿到容器内的 shell，即表示 本地能成功 SSH（经跳板机到 HF 上的 Ubuntu）。