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）：

  ```bash
  # 例如在 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 端口）：
   ```bash
   ssh -p 443 user@跳板机公网IP
   ```

2. 在跳板机上连到容器（本机已通过反向隧道把容器 2222 映射到跳板机 2222）：
   ```bash
   ssh -p 2222 -o StrictHostKeyChecking=no localhost
   ```
   登录用户为容器内运行桌面时的用户（与 `$HOME` 一致）。

也可以本机一步到位（ProxyJump）：
```bash
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）。