feat: sshd + reverse SSH for local SSH into HF Ubuntu; docs/SSH_ACCESS.md

Dockerfile

@@ -9,7 +9,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && pip3 install --no-cache-dir --break-system-packages huggingface_hub \
     && rm -rf /var/lib/apt/lists/*
 
-# Desktop stack: Xvfb, XFCE, dbus, x11vnc, Firefox
+# Desktop stack: Xvfb, XFCE, dbus, x11vnc, Firefox; OpenSSH for reverse SSH
 RUN apt-get update && apt-get install -y --no-install-recommends \
     xvfb \
     xfce4 xfce4-goodies \
@@ -17,6 +17,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     x11vnc \
     firefox \
     procps \
+    openssh-server openssh-client \
     && rm -rf /var/lib/apt/lists/*
 
 # noVNC (web client on 7860)

README.md

@@ -46,7 +46,7 @@ HuggingRun 是面向 Hugging Face Spaces 的**通用部署接口**：用同一
 - **统一入口**：同一 entrypoint 先做恢复与同步，再 `exec` 你的 `RUN_CMD`，便于任意镜像复用。
 
 详见 [docs/HF_LIMITATIONS.md](docs/HF_LIMITATIONS.md)。  
-远端构建/运行日志：[docs/REMOTE_LOGS.md](docs/REMOTE_LOGS.md)。**Push → 部署 → 监控 → 测试** 循环：[docs/PUSH_DEBUG.md](docs/PUSH_DEBUG.md)。
+远端构建/运行日志：[docs/REMOTE_LOGS.md](docs/REMOTE_LOGS.md)。**Push → 部署 → 监控 → 测试** 循环：[docs/PUSH_DEBUG.md](docs/PUSH_DEBUG.md)。**本地 SSH 进 HF Ubuntu**（反向 SSH）：[docs/SSH_ACCESS.md](docs/SSH_ACCESS.md)。
 
 ## 示例（最小用法）
 

docs/SSH_ACCESS.md

@@ -0,0 +1,67 @@
+# 本地 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）。

ubuntu-desktop/Dockerfile

@@ -9,7 +9,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && pip3 install --no-cache-dir --break-system-packages huggingface_hub \
     && rm -rf /var/lib/apt/lists/*
 
-# Desktop stack: Xvfb, XFCE, dbus, x11vnc, Firefox
+# Desktop stack: Xvfb, XFCE, dbus, x11vnc, Firefox; OpenSSH for reverse SSH (本地 SSH 进容器)
 RUN apt-get update && apt-get install -y --no-install-recommends \
     xvfb \
     xfce4 xfce4-goodies \
@@ -17,6 +17,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     x11vnc \
     firefox \
     procps \
+    openssh-server openssh-client \
     && rm -rf /var/lib/apt/lists/*
 
 # noVNC (web client on 7860)

ubuntu-desktop/start-desktop.sh

@@ -31,5 +31,32 @@ sleep 3
 # x11vnc: share display :99 on port 5901
 x11vnc -display "$DISPLAY" -rfbport "$VNC_PORT" -forever -shared -noxdamage -bg
 
+# SSH: non-root sshd on 2222, then reverse tunnel 以便本地 SSH 进容器（HF 不暴露 22）
+SSHD_PORT="${SSH_PORT:-2222}"
+mkdir -p "$HOME/.ssh"
+if [ -n "${SSH_AUTHORIZED_KEYS-}" ]; then
+  echo "$SSH_AUTHORIZED_KEYS" > "$HOME/.ssh/authorized_keys"
+  chmod 600 "$HOME/.ssh/authorized_keys"
+fi
+if [ ! -f "$HOME/.ssh/ssh_host_ed25519_key" ]; then
+  ssh-keygen -t ed25519 -f "$HOME/.ssh/ssh_host_ed25519_key" -N "" -C "" 2>/dev/null || true
+fi
+if [ -f "$HOME/.ssh/authorized_keys" ] && [ -f "$HOME/.ssh/ssh_host_ed25519_key" ]; then
+  sshd -o "Port=$SSHD_PORT" \
+       -o "HostKey=$HOME/.ssh/ssh_host_ed25519_key" \
+       -o "AuthorizedKeysFile=$HOME/.ssh/authorized_keys" \
+       -o "PermitEmptyPasswords=no" -o "PasswordAuthentication=no" \
+       -o "ListenAddress=127.0.0.1" -o "PidFile=$HOME/.ssh/sshd.pid" \
+       -o "UsePAM=no" -o "PermitUserEnvironment=yes" \
+       -D -e &
+  sleep 1
+  if [ -n "${SSH_REVERSE_TARGET-}" ]; then
+    # HF 出站仅 80/443/8080，跳板机需在 443 或 8080 接 SSH
+    ssh -o StrictHostKeyChecking=no -o ServerAliveInterval=60 \
+        -R "0.0.0.0:${SSHD_PORT}:127.0.0.1:${SSHD_PORT}" \
+        $SSH_REVERSE_TARGET -N &
+  fi
+fi
+
 # noVNC: must run in foreground; listen on 0.0.0.0 so HF proxy can reach it
 exec /bin/bash -c "cd /opt/noVNC && exec ./utils/novnc_proxy --listen 0.0.0.0:$NOVNC_PORT --vnc localhost:$VNC_PORT --web /opt/noVNC"