# SSH 访问
<subtitle>通过 WebSocket 代理连接沙箱 SSH，用于远程终端和文件传输。</subtitle>

SSH 访问可以用于远程终端会话、SCP/SFTP 文件传输，以及接入需要 SSH 连接能力的工具。

## 快速开始

### 1. 构建 SSH 模板

定义一个包含 OpenSSH server 和 [websocat](https://github.com/vi/websocat) 的模板：

```python
# template.py
from ucloud_sandbox import Template, wait_for_port

template = (
    Template()
    .from_ubuntu_image("25.04")
    .apt_install(["openssh-server"])
    .run_cmd([
        "curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl",
        "chmod a+x /usr/local/bin/websocat",
    ], user="root")
    .set_start_cmd(
        "sudo websocat -b --exit-on-eof ws-l:0.0.0.0:8081 tcp:127.0.0.1:22",
        wait_for_port(8081),
    )
)
```

构建模板：

```python
# build.py
from ucloud_sandbox import Template, default_build_logger
from template import template as ssh_template

Template.build(
    ssh_template,
    "ssh-ready",
    cpu_count=2,
    memory_mb=2048,
    on_build_logs=default_build_logger(),
)
```

### 2. 使用模板创建沙箱

```python
from ucloud_sandbox import Sandbox

sbx = Sandbox.create("ssh-ready")
print(sbx.sandbox_id)
```

### 3. 从本地机器连接沙箱

macOS：

```bash
# 安装 websocat
brew install websocat

# 连接沙箱
ssh -o 'ProxyCommand=websocat --binary -B 65536 - wss://8081-%h.cn-wlcb.sandbox.ucloudai.com' user@<sandbox-id>
```

Linux：

```bash
# 安装 websocat
sudo curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl
sudo chmod a+x /usr/local/bin/websocat

# 连接沙箱
ssh -o 'ProxyCommand=websocat --binary -B 65536 - wss://8081-%h.cn-wlcb.sandbox.ucloudai.com' user@<sandbox-id>
```

## 工作原理

这种方式使用 [websocat](https://github.com/vi/websocat) 将 SSH 连接通过 WebSocket 代理到沙箱暴露的端口。

```text
┌───────────────────────────────────────────────────────────┐
│  本地机器                                                  │
│  ┌──────────┐    ProxyCommand    ┌──────────────────┐     │
│  │   SSH    │ ────────────────── │    websocat      │     │
│  │  Client  │                    │   (WebSocket)    │     │
│  └──────────┘                    └─────────┬────────┘     │
└────────────────────────────────────────────┼──────────────┘
                                             │
               wss://8081-<sandbox-id>.cn-wlcb.sandbox.ucloudai.com
                                             │
┌────────────────────────────────────────────┼──────────────┐
│  UCloud Sandbox                            ▼              │
│                                  ┌──────────────────┐     │
│                                  │    websocat      │     │
│                                  │  (WS → TCP:22)   │     │
│                                  └─────────┬────────┘     │
│                                            │              │
│                                  ┌─────────▼────────┐     │
│                                  │   SSH Server     │     │
│                                  │   (OpenSSH)      │     │
│                                  └──────────────────┘     │
└───────────────────────────────────────────────────────────┘
```