SSH 隧道配置指南

概述

由于安全考虑，平台不开放公网直接访问容器内的服务端口。若需从本地电脑访问容器内运行的 API 服务（如 vLLM、FastAPI 等），需通过 SSH 隧道进行本地代理映射。

本指南适用于所有需要本地访问容器服务的场景，包括但不限于：

• 文本生成 API
• 图像生成 API
• 语音识别 API
• 语音合成 API
• OCR 识别 API

---

步骤一：设置实例密码

1. 进入工作台，找到对应的实例卡片
2. 点击"设置密码"按钮
3. 输入并确认密码，牢记该密码（后续 SSH 连接需要）

---

步骤二：获取连接信息

1. 在工作台找到对应实例
2. 点击实例卡片上的"SSH 连接"或"连接信息"按钮
3. 复制完整的登录指令，格式通常为：

   ssh root+vm-xxxxx@xxx.xx.xxx.xxx -p xxxxx

4. 记下以下信息：
   • 用户名：root+vm-xxxxx
   • 主机地址：xxx.xx.xxx.xxx
   • SSH 端口：xxxxx

---

步骤三：打开本地终端

Windows 用户

1. 打开"我的电脑"或"此电脑"
2. 在地址栏输入 cmd 或 powershell 并按回车
3. 终端窗口会弹出

macOS / Linux 用户

打开系统自带的"终端"应用即可

---

步骤四：执行 SSH 映射指令

在本地终端中执行以下命令（注意替换为您实例的实际信息）：

# 格式：ssh -CNg -L 本地端口:127.0.0.1:容器端口 用户名@主机地址 -p SSH端口
ssh -CNg -L 8188:127.0.0.1:8188 root+vm-xxxxx@xxx.xx.xxx.xxx -p xxxxx

参数说明：

• -CNg：组合选项
  • -C：启用压缩
  • -N：不执行远程命令（仅转发）
  • -g：允许远程主机连接到本地转发端口
• -L 8188:127.0.0.1:8188：端口转发映射
  • 第一个 8188：本地访问端口（可自定义）
  • 127.0.0.1:8188：容器内的服务地址和端口（与容器内服务保持一致）
• 用户名@主机地址 -p SSH端口：远程主机连接信息

示例：

# 将容器内 8188 端口映射到本地 8188
ssh -CNg -L 8188:127.0.0.1:8188 root+vm-k9hCcD0ufznGq16b@140.207.205.81 -p 50821

# 将容器内 8188 端口映射到本地 9000
ssh -CNg -L 9000:127.0.0.1:8188 root+vm-k9hCcD0ufznGq16b@140.207.205.81 -p 50821

---

步骤五：输入密码并保持连接

1. 执行上述命令后，终端会提示输入密码
2. 输入您在步骤一中设置的密码
3. 按回车确认
4. 终端会进入静止状态，这是正常现象——表示 SSH 隧道已建立成功
5. 保持该终端窗口始终打开，隧道才能持续有效

---

步骤六：在本地验证服务

隧道建立后，打开新的终端窗口（不要关闭步骤五的隧道终端），使用 curl 或其他工具验证 API 服务：

验证文本生成 API（vLLM）

curl http://localhost:8188/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "/mnt/moark-models/Qwen3-8B",
        "messages": [
            {"role": "user", "content": "你好"}
        ],
        "temperature": 0.7,
        "max_tokens": 256
    }'

验证图像生成 API（FastAPI）

curl http://localhost:8080/v1/images/generations \
    -H "Content-Type: application/json" \
    -d '{
        "prompt": "一只猫",
        "size": "1024x1024"
    }'

验证语音识别 API（FastAPI）

curl http://localhost:8080/v1/audio/transcriptions \
    -F "file=@test_audio.wav"

验证语音合成 API（FastAPI）

curl http://localhost:8080/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{
        "input": "你好",
        "voice": "default"
    }'

验证 OCR API（FastAPI）

curl http://localhost:8080/v1/vision/ocr \
    -F "file=@test_image.jpg"

预期结果：

• 如果返回 JSON 数据或数据流，说明隧道工作正常
• 如果收到连接拒绝错误，请检查：
  1. SSH 隧道终端是否仍然打开
  2. 本地端口号是否与映射配置一致
  3. 容器内服务是否已正确启动

---

常见问题

Q1：SSH 连接失败，提示"Permission denied"

A：密码输入错误或不存在。请重新检查在工作台中设置的密码。

Q2：隧道建立后，本地 curl 仍然连接拒绝

A：可能原因：

1. 容器内的 API 服务未启动（需提前在 Notebook 或终端中启动）
2. 容器内服务监听的端口与映射配置不一致
3. SSH 隧道终端意外关闭

Q3：可以映射多个端口吗？

A：可以。新建多条 SSH 隧道或在一条隧道中指定多个 -L 参数：

ssh -CNg -L 8188:127.0.0.1:8188 -L 8080:127.0.0.1:8080 \
    root+vm-xxxxx@xxx.xx.xxx.xxx -p xxxxx

Q4：隧道需要一直保持打开吗？

A：是的。SSH 隧道在后台提供端口转发服务，关闭终端后隧道立即断开，本地无法再访问容器内服务。

Q5：可以自定义本地端口吗？

A：可以。-L 参数中的第一个端口号可自定义，例如将容器 8080 映射到本地 9000：

ssh -CNg -L 9000:127.0.0.1:8080 root+vm-xxxxx@xxx.xx.xxx.xxx -p xxxxx

然后通过 http://localhost:9000 访问。

Q6：Windows 的 PowerShell 中执行 SSH 命令出现问题？

A：确保安装了 OpenSSH（Windows 10 1803+ 自带）。如不可用，推荐使用 cmd.exe 或安装 Git Bash。

---

第三方应用集成

一旦通过 SSH 隧道将服务映射到本地，即可无缝集成到第三方应用：

• IDE 编程助手：Claude Code、Cursor
• 知识库与 Agent：Dify、FastGPT、Cherry Studio
• 自动化流程：N8N
• API 客户端：Postman、Insomnia、REST Client 等

配置方式：将 API 端点指向 http://localhost:<本地端口>/v1/... 即可。