zzqqzz/gemma4-31b

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

gemma4-31b/README.md

般若提婆

fix: 过滤 Cloudflare 隧道日志中的 api 域名干扰

b021d113

0 commits

PreviewCode viewBlame

Run gemma4 on Ollama via CNB

基于腾讯云 CNB 云原生开发环境，一键启动 Ollama 服务运行 Gemma4 大模型。预置模型文件，GPU 加速，零配置即开即用。

项目结构

/workspace/
├── .bashrc          # 工作区 Shell 配置（环境变量、自动启动、快捷别名）
├── .cnb.yml         # CNB 编排配置（Ollama 镜像、GPU H20、SSH 服务）
├── cloudflared      # Cloudflared 隧道工具（公网穿透）
├── monitor.sh       # 监控面板脚本（GPU / API / 系统）
├── cf.log           # Cloudflare 隧道地址日志
└── models/          # Ollama 模型存储目录
    ├── blobs/       # 模型分片文件
    └── manifests/   # 模型清单注册表

内置模型

模型	大小	说明
`gemma4:31b`	~19 GB	Google Gemma 4 31B 参数，支持多轮对话与推理

快速开始

1. 启动环境

Fork 本仓库到自己的组织下
选择分支，点击 云原生开发 启动远程开发环境
约 5～9 秒 后进入终端，Ollama 已自动就绪

2. 使用模型

ollama run gemma4:31b        # 交互式对话
ollama list                  # 查看已安装模型

3. 快捷别名

终端已预置以下别名，开箱即用：

别名	命令	说明
`ol`	ollama	执行任意 ollama 命令
`ollist`	ollama list	列出已安装模型
`olrun`	ollama run	运行模型交互

查看隧道与 API 信息

方式一：监控脚本（推荐，信息最全）

./monitor.sh --api      # 仅显示 API 地址信息
./monitor.sh             # 显示全部（含 GPU + API + 系统）

输出示例：

═══ 🌐 API 地址信息 ═══

  ☁ Cloudflare 隧道(推荐):
    https://xxx-xxx-xxx.trycloudflare.com
    API Base: https://xxx-xxx-xxx.trycloudflare.com/v1
    优势: 无60秒超时, 无1小时限制

  CNB 代理地址:   https://xxxxx.cnb.run
  Model:           gemma4:31b
  API Key:         (任意值，如 ollama)

方式二：一键启动脚本（自动检测并输出）

./start.sh          # 启动后自动打印完整 API 信息

输出包含：

Cloudflare 隧道 URL 及各端点路径
CNB 代理地址
连接参数表（Model / API Key / 格式）
本地连通性测试结果

方式三：命令行直接查看

需求	命令	说明
获取隧道地址	`grep -oE 'https://[a-zA-Z0-9-]+\.trycloudflare\.com' /workspace/cf.log \| grep -v api \| tail -1`	从日志提取公网 URL
查看隧道进程	`pgrep -a cloudflared`	确认隧道是否运行
查看完整日志	`cat /workspace/cf.log`	包含连接详情和错误记录
查看 Ollama 进程	`pgrep -a ollama`	确认服务是否运行
验证模型可用	`ollama list`	列出已安装模型
检查模型加载状态	`ollama ps`	查看是否已在 GPU 中运行

方式四：环境变量（Shell 内使用）

.bashrc 在启动时自动将隧道地址导出为环境变量：

source ~/.bashrc       # 加载配置
echo $CF_URL          # 输出隧道地址，如 https://xxx.trycloudflare.com

API 地址汇总

获取到隧道地址后，拼接方式如下：

基础 URL:  <CF_URL>

├── API Base:        <CF_URL>/v1
├── 对话补全:        <CF_URL>/v1/chat/completions     POST
├── 模型列表:        <CF_URL>/v1/models               GET
└── 原生端点:         <CF_URL>/api/tags                GET  (Ollama 原生)

接入客户端时填写：

字段	值
API Base URL	`<CF_URL>/v1`
Model	`gemma4:31b`
API Key	`ollama`（任意非空值即可）

公网访问

本项目提供两种公网接入方式：

方式一：Cloudflare 隧道（推荐）

环境启动后自动创建 Cloudflare 隧道，无超时限制：

./monitor.sh --api   # 查看隧道地址

或直接读取日志：

cat /workspace/cf.log | grep trycloudflare

方式二：CNB 代理端口

在 CNB 的 PORTS 配置中添加 11434 并开启公网访问即可。

接入 AI 客户端

Ollama 兼容 OpenAI API 格式，可直接接入各类 LLM 客户端：

参数	值
API Base URL	`<公网地址>/v1`
Model	`gemma4:31b`
API Key	任意值（如 `ollama`）

支持端点：

POST /v1/chat/completions — 对话补全
GET /v1/models — 模型列表

兼容客户端举例：OpenClaw、Workbuddy、ChatGPT-Next-Web 等。

SSH 远程连接

环境自动启动 SSH 服务，可用于远程连接或端口转发：

参数	值
主机	CNB 分配的公网 IP
用户	root
密码	cnb_ollama2026

ssh root@<cnb-host>

监控面板

内置 monitor.sh 一键查看系统状态：

./monitor.sh          # 全部信息（GPU + API + 系统）
./monitor.sh --gpu    # 仅显示 GPU / 显存状态
./monitor.sh --api    # 仅显示 API 地址信息
./monitor.sh --watch  # 持续刷新模式（每 3 秒，Ctrl+C 退出）

监控内容：

模块	信息
🎮 GPU / 显存	显卡型号、显存使用/总量/空闲、利用率、功耗、温度、活跃进程
🌐 API 地址	Cloudflare 隧道地址、CNB 代理地址、Model 名称、API Key
💻 系统资源	CPU 使用率、内存占用、磁盘用量

技术规格

基础镜像：ollama/ollama:latest
GPU：NVIDIA H20 (CNB gpu:H20 标签)
架构：amd64
Ollama 监听：0.0.0.0:11434
模型目录：/workspace/models

一键启动脚本

环境内置 start.sh 自动化脚本，可一键完成全部初始化：

./start.sh              # 正常启动（跳过已运行的服务）
./start.sh --restart    # 强制重启所有服务（Ollama + 隧道）
./start.sh --no-tunnel  # 仅启动 Ollama，不创建隧道

脚本自动执行以下步骤：

设置环境变量 (OLLAMA_MODELS, OLLAMA_HOST, OLLAMA_ORIGINS)
启动 Ollama 服务并等待就绪
验证 gemma4:31b 模型可用性
创建 Cloudflare 公网隧道
输出完整 API 连接信息
执行本地连通性测试

常见问题处理

Q1: 执行 ollama 命令报错 `ollama: not found`

原因：当前 Shell 未加载工作区配置，PATH 或别名未生效。

解决方案：

# 方式一：手动加载配置（推荐）
source ~/.bashrc   # 或 . ~/.bashrc

# 方式二：使用绝对路径
/usr/bin/ollama list

# 方式三：使用预置别名
ollist             # 等同于 ollama list
olrun gemma4:31b   # 等同于 ollama run gemma4:31b

说明：.bashrc 中包含 OLLAMA_MODELS=/workspace/models 和 OLLAMA_HOST=0.0.0.0 等关键环境变量。如果未加载，Ollama 将找不到模型目录或无法绑定端口。

Q2: Ollama 服务未运行或端口 11434 未监听

原因：Ollama 进程未启动或已崩溃。

排查步骤：

# 1. 检查进程是否存在
pgrep -a ollama

# 2. 检查日志
tail -20 /tmp/ollama.log

# 3. 手动重启服务
export OLLAMA_MODELS=/workspace/models OLLAMA_HOST=0.0.0.0
nohup ollama serve > /tmp/ollama.log 2>&1 &
sleep 3
ollama list          # 验证是否正常

一键修复：

./start.sh --restart

Q3: Cloudflare 隧道创建失败

常见错误信息：

failed to request quick Tunnel: ... EOF — 网络连接中断
tunnel address is empty — 隧道地址未成功获取

解决方案：

# 1. 重启隧道即可（最常用）
pkill -f cloudflared
sleep 2
rm -f /workspace/cf.log
nohup /workspace/cloudflared tunnel --url http://127.0.0.1:11434 > /workspace/cf.log 2>&1 &
sleep 10
grep "trycloudflare" /workspace/cf.log | tail -3

# 2. 使用一键脚本（推荐）
./start.sh --restart

验证隧道状态：

# 查看进程
pgrep -a cloudflared

# 获取地址（过滤掉 api.trycloudflare.com 的干扰匹配）
grep -oE 'https://[a-zA-Z0-9-]+\.trycloudflare\.com' /workspace/cf.log | grep -v api | tail -1

Q4: API 调用超时或无响应

症状	原因	解决方案
本地调用慢	模型首次加载到 GPU 显存	等待 30～60 秒，首次加载后后续请求会很快
外部调用超时	CNB 代理有 60s/1h 限制	切换到 Cloudflare 隧道地址
隧道访问不通	隧道未建立或已断开	运行 `./start.sh --restart`
报 404 错误	URL 路径错误	确认使用 `/v1/chat/completions`（非 `/api/chat`）

快速诊断命令：

# 检查模型是否已加载到 GPU（有输出表示已加载）
ollama ps

# 测试本地 API（需要 python3）
python3 -c "
import urllib.request, json
req = urllib.request.Request('http://127.0.0.1:11434/v1/chat/completions',
    data=json.dumps({'model':'gemma4:31b','messages':[{'role':'user','content':'hi'}],'stream':False}).encode(),
    headers={'Content-Type':'application/json'})
resp = urllib.request.urlopen(req, timeout=120)
print(resp.read().decode())
"

Q5: GPU 显存不足或模型无法加载

现象	说明
`gemma4:31b` 占用 ~72GB 显存	正常现象，H20 有 96GB 显存
`ollama ps` 无输出	模型未加载，首次请求会触发自动加载

查看显存状态：

./monitor.sh --gpu        # 可视化显存占用
nvidia-smi                # NVIDIA 官方工具

如果显存被其他进程占满：

# 查看 GPU 进程占用
nvidia-smi pmon

# 重启 Ollama 释放显存
./start.sh --restart

Q6: Shell 提示 `shopt: not found` 或语法错误

原因：当前终端使用的是 sh 而非 bash，部分 bash 特有语法不支持。

解决：切换到 bash 环境：

bash           # 进入 bash Shell
source ~/.bashrc   # 加载配置
ollist              # 使用别名

此问题不影响 Ollama 核心功能，仅影响 .bashrc 中的个别高级特性。

Q7: 环境重启后所有服务丢失

原因：容器重启后后台进程不会自动恢复。

解决方案 — 在每次进入终端后执行：

./start.sh --restart    # 一键恢复全部服务

如需完全自动化，可将以下内容追加到 /root/.bashrc（末尾）：

# 每次登录时自动启动全部服务
if [ -f /workspace/start.sh ]; then
    /workspace/start.sh >/dev/null 2>&1 &
fi

问题速查表

命令	用途
`./start.sh --restart`	一键重启全部服务（首选方案）
`pgrep -a ollama \| pgrep -a cloudflared`	检查服务进程状态
`ollama list`	验证模型可用性
`ollama ps`	查看模型是否已加载到 GPU
`tail -20 /tmp/ollama.log`	查看 Ollama 日志
`tail -10 /workspace/cf.log`	查看隧道日志和地址
`./monitor.sh --watch`	实时监控系统状态