falkwolsky/runpod-ollama-openwebui

BotBoy RunPod容器

容器功能

本容器提供GPU加速的AI工作空间，内置六项服务：

Ollama仅处理嵌入任务（bge-m3、qwen3-embedding等），所有LLM推理通过vLLM路由。

---

设计目标

1. 快速可靠启动

所有组件均在构建时内置到镜像，启动时无需pip安装、git克隆或下载。镜像包含：

• Ollama二进制文件
• Open WebUI
• Docling + GPU PyTorch
• PDF辅助包
• vLLM（仅amd64）
• Kokoro TTS引擎 + ONNX模型（约80MB）

启动仅创建目录、加载配置和启动服务。

2. 持久化状态与镜像分离

仅数据和配置在重启后保留，存储于/workspace目录。软件在镜像内保持不可变。

3. 保护公网API

Ollama运行于内部端口，Nginx通过令牌认证前置公网端口。vLLM有独立API密钥，无未受保护的暴露服务。

---

运行时布局

镜像内置（不可变）

/workspace下持久化

vLLM模型权重（如Qwen3.5-35B-A3B-FP8约18GB）通过HF_HOME缓存于/workspace/cache/huggingface，若/workspace为持久化挂载（如RunPod网络卷），重启无需重新下载。

---

SSH访问与公钥设置

容器启动时运行SSH守护进程，用于：

1. 直接shell访问RunPod实例调试
2. 通过SSH隧道从VPS连接实例内部服务

公钥注入方式

启动脚本start.sh按优先级检查两个环境变量：

PUBLIC_KEY    (RunPod原生变量名)
SSH_PUBLIC_KEY  (备选变量名)

若设置，值将写入/root/.ssh/authorized_keys，仅支持密钥认证，禁用密码登录。

RunPod设置公钥

选项A：实例环境变量
在RunPod控制台创建/编辑实例时添加：

PUBLIC_KEY = ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... your-email@example.com

粘贴完整公钥（~/.ssh/id_ed25519.pub或~/.ssh/id_rsa.pub内容）。

选项B：账户级SSH密钥
在RunPod账户设置>SSH密钥中添加，系统自动将密钥注入所有实例作为PUBLIC_KEY。

生成密钥对（若未拥有）

本地机器（Mac/Linux/VPS）执行：

bash
ssh-keygen -t ed25519 -C "botboy-runpod" -f ~/.ssh/botboy_runpod

生成：

• ~/.ssh/botboy_runpod：私钥（本地保存，勿分享）
• ~/.ssh/botboy_runpod.pub：公钥（粘贴到RunPod PUBLIC_KEY）

连接实例

实例运行且公钥设置后：

bash
ssh root@<实例IP> -p <实例SSH端口> -i ~/.ssh/botboy_runpod

实例IP和SSH端口可在RunPod控制台"Connect"部分查看。

---

SSH隧道

SSH隧道允许远程主机（如运行OpenClaw的VPS）访问RunPod实例内部服务，如同本地服务。

架构

VPS（OpenClaw）                          RunPod实例
─────────────────                            ──────────
localhost:11434  ── SSH隧道 ──────────►  127.0.0.1:11435 （Ollama内部端口）
localhost:8000   ── SSH隧道 ──────────►  127.0.0.1:8000   （vLLM）
localhost:8100   ── SSH隧道 ──────────►  127.0.0.1:8100   （音频网关）

VPS设置隧道

步骤1：VPS生成密钥对

bash
ssh-keygen -t ed25519 -C "vps-to-runpod" -f ~/.ssh/botboy_runpod

步骤2：将公钥添加到RunPod
复制~/.ssh/botboy_runpod.pub内容到RunPod实例PUBLIC_KEY变量。

步骤3：VPS创建隧道脚本

bash
#!/bin/bash
set -euo pipefail

RUNPOD_HOST="<实例IP>"
RUNPOD_PORT="<实例SSH端口>"
KEY="~/.ssh/botboy_runpod"

while true; do
  echo "$(date '+%F %T') 启动RunPod SSH隧道"

  ssh -N \
    -L 127.0.0.1:11434:127.0.0.1:11435 \
    -L 127.0.0.1:8000:127.0.0.1:8000 \
    -L 127.0.0.1:8100:127.0.0.1:8100 \
    root@${RUNPOD_HOST} \
    -p ${RUNPOD_PORT} \
    -i ${KEY} \
    -o IdentitiesOnly=yes \
    -o ExitOnForwardFailure=yes \
    -o ServerAliveInterval=30 \
    -o ServerAliveCountMax=3 \
    -o StrictHostKeyChecking=accept-new

  echo "$(date '+%F %T') 隧道关闭，5秒后重试"
  sleep 5
done

步骤4：PM2管理隧道

bash
pm2 start runpod-tunnel.sh --name runpod-tunnel
pm2 save

---

网络模型

Ollama内部端口

Ollama绑定内部地址，容器外无法访问：

env
OLLAMA_HOST=127.0.0.1:11435
OLLAMA_INTERNAL_PORT=11435

Ollama公网保护端口

Nginx暴露带令牌认证的公网端口：

env
OLLAMA_PORT=11434
ENABLE_OLLAMA_PROXY=1
OLLAMA_PROXY_TOKEN=your-secret-token

请求需包含Authorization: Bearer <token>或X-Ollama-Token: <token>。

vLLM

vLLM绑定所有接口，通过RunPod代理URL访问：

env
VLLM_HOST=0.0.0.0
VLLM_PORT=8000
VLLM_API_KEY=your-vllm-secret

公网访问地址：https://<实例ID>-8000.proxy.runpod.net。

---

环境变量参考

核心变量

env
# 工作空间
WORKSPACE_ROOT=/workspace

# Ollama
OLLAMA_INTERNAL_PORT=11435
OLLAMA_PORT=11434
OLLAMA_PROXY_TOKEN=your-secret
ENABLE_OLLAMA_PROXY=1
OLLAMA_BASE_URL=http://127.0.0.1:11435

# Open WebUI
OPEN_WEBUI_HOST=0.0.0.0
OPEN_WEBUI_PORT=8080

# Docling
DOCLING_PORT=5001

vLLM变量

env
ENABLE_VLLM=1
VLLM_HOST=0.0.0.0
VLLM_PORT=8000
VLLM_MODEL=Qwen/Qwen3.5-35B-A3B-FP8
VLLM_API_KEY=your-vllm-secret

音频网关变量

env
ENABLE_AUDIO_GATEWAY=1
AUDIO_GATEWAY_PORT=8100
GROQ_API_KEY=gsk_...

---

启动行为

容器启动时执行：

1. 安装并启动sshd（注入公钥）
2. 创建/workspace目录
3. 复制默认配置到/workspace/config（若缺失）
4. 加载botboy.env（环境变量覆盖文件值）
5. 生成WebUI密钥（若未设置）
6. 启动Ollama（内部端口，等待就绪）
7. 启动Docling（等待就绪）
8. 启动Nginx代理（验证令牌）
9. 启动Open WebUI（等待健康检查）
10. （可选）后台拉取嵌入模型
11. 启动vLLM（若ENABLE_VLLM=1）
12. 启动音频网关（若ENABLE_AUDIO_GATEWAY=1）

---

音频网关端点

端口8100提供TTS/STT服务：

TTS示例

bash
curl -X POST http://127.0.0.1:8100/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "你好，今天我能帮你什么？", "voice": "af_bella", "speed": 1.0}' \
  --output speech.wav

STT示例

bash
curl -X POST http://127.0.0.1:8100/stt \
  -F "file=@recording.wav" \
  -F "language=zh"

---

部署示例

Docker Run命令

bash
docker run -d \
  --name botboy-runpod \
  -p 8080:8080 \
  -p 11434:11434 \
  -v /path/to/your/workspace:/workspace \
  -e PUBLIC_KEY="ssh-ed25519 AAAAC3NzaC1lZDI..." \
  -e ENABLE_VLLM=1 \
  -e VLLM_API_KEY="your-vllm-key" \
  docker.xuanyuan.run/falkwolsky/runpod-ollama-openwebui

---

总结

本容器是预构建运行时镜像，而非启动时引导镜像：

• 镜像较大但启动快速、运行可靠
• 内置六项服务：Ollama、Open WebUI、Docling、Nginx、vLLM、音频网关
• /workspace存储所有可变状态
• 通过PUBLIC_KEY/SSH_PUBLIC_KEY注入SSH公钥
• SSH隧道实现VPS与RunPod服务的透明连接
• vLLM和音频网关通过环境变量启用