Clawdbot部署教程：Qwen3:32B网关服务启用HTTPS反向代理与JWT Token校验配置

Clawdbot部署教程：Qwen3:32B网关服务启用HTTPS反向代理与JWT Token校验配置

1. Clawdbot是什么：一个开箱即用的AI代理网关平台

Clawdbot 不是一个需要从零搭建的复杂系统，而是一个已经打包好的AI代理网关与管理平台。它像一个智能“交通指挥中心”，帮你把本地运行的大模型（比如 Qwen3:32B）安全、稳定、可控地暴露给前端应用或外部调用方。

你不需要写一行反向代理配置、不用手搓鉴权逻辑、也不用反复调试 CORS 或 token 透传问题——Clawdbot 把这些工程细节都封装好了。它提供一个直观的 Web 控制台，让你能直接测试对话、切换模型、查看请求日志、管理 API 密钥，甚至一键启停后端服务。

更重要的是，它不是只支持某一个模型的“玩具平台”。通过内置的 OpenAI 兼容接口适配器，Clawdbot 能无缝对接 Ollama、LM Studio、Text Generation WebUI 等主流本地推理服务。本次教程聚焦在Qwen3:32B 模型 + Ollama 后端 + HTTPS 反向代理 + JWT 校验这一完整链路，带你从零跑通生产级部署。

小贴士：很多开发者卡在“模型跑起来了但前端连不上”“能访问但总提示未授权”“本地 HTTP 服务没法被公网域名调用”这几个典型问题上。本教程每一步都对应一个真实痛点，不讲虚的。

2. 环境准备：确认基础依赖与资源条件

在开始配置前，请先确认你的运行环境满足以下最低要求。这不是“建议”，而是实际影响 Qwen3:32B 是否能正常加载和响应的关键前提。

2.1 硬件与系统要求

• GPU 显存：≥24GB（推荐 32GB+），Qwen3:32B 在 FP16 推理下约占用 20–22GB 显存，预留空间用于 KV Cache 和并发请求
• CPU 与内存：≥8 核 CPU，≥32GB RAM（Ollama 和 Clawdbot 主进程需共享内存）
• 操作系统：Ubuntu 22.04 LTS（推荐）或 CentOS 8+；不支持 Windows 原生部署（可使用 WSL2，但性能损耗明显）
• Docker 版本：≥24.0.0（Clawdbot 官方镜像基于 Docker Compose v2 构建）

2.2 软件依赖检查

请在终端中逐条执行并确认输出符合预期：

# 检查 Docker 是否就绪 docker --version # 预期输出：Docker version 24.0.7, build afdd53b # 检查 Docker Compose 是否可用（v2 内置模式） docker compose version # 预期输出：Docker Compose version v2.23.0 # 检查 nvidia-container-toolkit（GPU 加速必需） nvidia-container-cli --version # 预期输出：version: 1.12.0 # 检查 Ollama 是否已安装并可调用 ollama list # 预期输出：空列表或已拉取的模型（如 qwen3:32b）

如果任意一条命令报错或版本过低，请先完成对应组件升级。跳过这步可能导致后续服务启动失败、GPU 不识别、或模型加载超时。

2.3 域名与证书准备（HTTPS 必需）

Clawdbot 的 JWT 校验与反向代理功能默认启用 HTTPS 强制重定向。因此，你需要一个可解析的域名（哪怕只是本地测试用）和一对有效的 TLS 证书。

• 开发测试场景：使用localhost+ 自签名证书（浏览器会提示不安全，但功能完整）
• 生产或演示场景：使用真实域名（如ai.yourcompany.com）+ Let’s Encrypt 免费证书

我们以clawdbot.local为例（需在/etc/hosts中添加127.0.0.1 clawdbot.local），证书生成方式如下：

# 创建证书目录 mkdir -p ./certs # 生成自签名证书（有效期 365 天） openssl req -x509 -nodes -days 365 \ -newkey rsa:2048 \ -keyout ./certs/clawdbot.local.key \ -out ./certs/clawdbot.local.crt \ -subj "/CN=clawdbot.local"

生成后，./certs/clawdbot.local.crt和./certs/clawdbot.local.key将在后续 Nginx 配置中被引用。

3. 部署 Qwen3:32B 与 Ollama 后端服务

Clawdbot 本身不运行模型，它只是一个“调度员”。真正的推理工作由 Ollama 承担。因此，第一步是确保 Qwen3:32B 已正确加载并可通过本地 API 访问。

3.1 拉取并验证 Qwen3:32B 模型

Qwen3:32B 是通义千问系列最新发布的开源大语言模型，对中文理解、长上下文和代码能力有显著提升。注意：它不是qwen2:7b或qwen2.5:14b，必须明确指定 tag。

# 拉取模型（首次需约 15–25 分钟，取决于网络） ollama pull qwen3:32b # 查看已安装模型 ollama list # 输出应包含： # NAME ID SIZE MODIFIED # qwen3:32b 8a9c7f... 20.3GB 3 minutes ago # 测试本地 API 是否响应（无需等待完整响应，看到流式 chunk 即可） curl -X POST http://127.0.0.1:11434/api/chat \ -H "Content-Type: application/json" \ -d '{ "model": "qwen3:32b", "messages": [{"role": "user", "content": "你好，请用一句话介绍你自己"}], "stream": false }' | jq '.message.content'

如果返回类似"我是通义千问Qwen3，一个超大规模语言模型..."，说明 Ollama 后端已就绪。

3.2 配置 Ollama 监听地址（关键！）

默认情况下，Ollama 只监听127.0.0.1:11434，这意味着只有本机进程能访问。但 Clawdbot 的网关容器运行在独立网络中，必须让 Ollama 接受来自 Docker 网络的请求。

编辑 Ollama 配置文件（Linux）：

sudo nano /etc/systemd/system/ollama.service

找到ExecStart=行，在末尾添加--host=0.0.0.0:11434：

ExecStart=/usr/bin/ollama serve --host=0.0.0.0:11434

然后重载并重启：

sudo systemctl daemon-reload sudo systemctl restart ollama sudo systemctl status ollama # 确认状态为 active (running)

最后验证跨网络可达性（从宿主机 ping 容器网络）：

# 运行一个临时 alpine 容器测试连通性 docker run --rm -it alpine sh -c "apk add curl && curl -s http://host.docker.internal:11434/api/tags | jq '.models | length'" # 应返回 1（表示成功获取到 1 个模型）

常见错误：忘记修改--host导致 Clawdbot 启动时报connection refused；或防火墙拦截11434端口。请务必验证此步。

4. 配置 Clawdbot 网关：启用 HTTPS 与 JWT 校验

Clawdbot 默认以 HTTP 启动，且不强制鉴权。要达到“生产可用”标准，需通过其配置系统开启 HTTPS 反向代理和 JWT Token 校验。这不是插件，而是内建能力，只需修改config.yaml。

4.1 初始化 Clawdbot 配置目录

# 创建配置目录（推荐放在项目根目录下） mkdir -p ./clawdbot-config # 下载官方默认配置模板 curl -o ./clawdbot-config/config.yaml https://raw.githubusercontent.com/clawdbot/clawdbot/main/config.example.yaml

打开./clawdbot-config/config.yaml，按以下顺序修改关键字段：

4.2 启用 HTTPS 反向代理（Nginx 前置）

Clawdbot 本身不内置 HTTPS 服务，而是依赖前置反向代理（如 Nginx）。我们在config.yaml中声明代理行为：

# ./clawdbot-config/config.yaml server: port: 3000 # Clawdbot 内部 HTTP 端口（仅容器内访问） host: "0.0.0.0" # 绑定所有接口（Docker 网络可见） https: false # 关键：设为 false，交由 Nginx 处理 TLS # 添加反向代理规则（Clawdbot 会自动识别并注入 X-Forwarded-* 头） proxy: enabled: true trustProxy: true # 允许信任 X-Forwarded-* 头（Nginx 必须设置） secure: true # 启用安全头（HSTS、X-Content-Type-Options 等）

4.3 配置 JWT Token 校验策略

这是本次教程的核心安全机制。Clawdbot 支持两种 Token 模式：Dashboard Token（前端登录用）和API Token（程序调用用）。我们统一使用csdn作为示例密钥（生产环境请替换为 32 位随机字符串）。

在config.yaml中添加：

auth: jwt: enabled: true secret: "csdn" # 生产环境务必更换为 openssl rand -hex 32 issuer: "clawdbot-gateway" audience: "clawdbot-api" expiresIn: "24h" cookieName: "clawdbot_token" headerName: "Authorization" # 允许 Dashboard 页面通过 URL 参数传 token（兼容你提供的访问方式） allowUrlParam: true urlParamName: "token" # 设置默认 dashboard token（用于 ?token=xxx 场景） dashboard: defaultToken: "csdn"

保存后，Clawdbot 将在启动时自动加载该策略：所有/api/*请求必须携带有效 JWT，而/chat等前端路径则接受?token=xxx或 Cookie 方式。

4.4 关联 Ollama 后端模型

在config.yaml的providers区域，替换或新增my-ollama配置（与你提供的 JSON 结构一致，但转为 YAML）：

providers: - id: "my-ollama" name: "Local Qwen3 32B" type: "openai-completions" baseUrl: "http://host.docker.internal:11434/v1" # Docker 内部访问 Ollama apiKey: "ollama" models: - id: "qwen3:32b" name: "Qwen3 32B" reasoning: false input: ["text"] contextWindow: 32000 maxTokens: 4096 cost: input: 0 output: 0 cacheRead: 0 cacheWrite: 0

注意baseUrl使用了host.docker.internal—— 这是 Docker Desktop 和新版 Docker Engine 提供的宿主机别名，比127.0.0.1更可靠。

5. 启动全栈服务：Nginx + Clawdbot + Ollama

现在所有组件配置完毕，我们用一个docker-compose.yml文件统一编排。

5.1 编写 docker-compose.yml

创建docker-compose.yml文件，内容如下：

version: '3.8' services: nginx: image: nginx:alpine ports: - "443:443" - "80:80" volumes: - ./certs:/etc/nginx/certs:ro - ./nginx.conf:/etc/nginx/nginx.conf:ro depends_on: - clawdbot clawdbot: image: ghcr.io/clawdbot/clawdbot:latest ports: - "3000:3000" # 仅内部暴露，不映射到宿主机 volumes: - ./clawdbot-config:/app/config:ro - /var/run/docker.sock:/var/run/docker.sock:ro environment: - NODE_ENV=production - CLAWDBOT_CONFIG_PATH=/app/config/config.yaml depends_on: - ollama ollama: image: ollama/ollama:latest volumes: - ./ollama-data:/root/.ollama ports: - "11434:11434" deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

5.2 编写 Nginx 配置文件

创建nginx.conf，启用 HTTPS、反向代理、JWT 透传和安全头：

events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"'; access_log /var/log/nginx/access.log main; error_log /var/log/nginx/error.log warn; sendfile on; keepalive_timeout 65; # SSL 配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_prefer_server_ciphers off; # 启用 HSTS（仅 HTTPS 有效） add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; server { listen 80; server_name clawdbot.local; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name clawdbot.local; ssl_certificate /etc/nginx/certs/clawdbot.local.crt; ssl_certificate_key /etc/nginx/certs/clawdbot.local.key; # 反向代理到 Clawdbot location / { proxy_pass http://clawdbot:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port; proxy_cache_bypass $http_upgrade; proxy_redirect off; } # API 路径显式透传 Authorization 头（JWT 必需） location /api/ { proxy_pass http://clawdbot:3000; proxy_set_header Authorization $http_authorization; proxy_pass_request_headers on; include /etc/nginx/proxy_params; } } }

5.3 一键启动与验证

# 启动全部服务（后台运行） docker compose up -d # 查看日志确认启动状态 docker compose logs -f clawdbot | grep -i "ready\|listening" # 预期看到： # info: Server listening on http://0.0.0.0:3000 # info: JWT auth enabled with issuer "clawdbot-gateway"

等待约 30 秒，打开浏览器访问：

https://clawdbot.local/?token=csdn

你应该看到 Clawdbot 控制台首页，右上角显示 “Authenticated”；点击左侧 “Chat” 进入对话界面，选择 “Qwen3 32B” 模型，输入问题即可获得响应。

验证成功标志：

• 页面通过 HTTPS 加载（地址栏有锁图标）
• 无 “unauthorized” 报错
• 对话响应来自 Qwen3:32B（可提问“你是哪个模型？”验证）
• curl -H "Authorization: Bearer <valid-jwt>" https://clawdbot.local/api/models返回模型列表

6. 常见问题排查与实用技巧

部署过程中最常遇到的问题往往集中在网络、权限和配置拼写上。以下是高频问题的快速定位方法。

6.1 “disconnected (1008): unauthorized: gateway token missing”

这不是 Clawdbot 故障，而是 JWT 校验失败的明确提示。按顺序检查：

• URL 中?token=csdn是否拼写正确（区分大小写，无空格）
• config.yaml中auth.jwt.secret与 URL token 是否完全一致
• Nginx 是否透传了Authorization头（检查nginx.conf中location /api/块）
• Clawdbot 日志是否打印JWT verification failed（若有，说明密钥不匹配）

6.2 “Failed to load model qwen3:32b” 或响应超时

• ollama list是否显示该模型？若无，重新ollama pull qwen3:32b
• ollama serve是否监听0.0.0.0:11434？用ss -tuln | grep 11434确认
• docker compose logs ollama是否有 CUDA out of memory 错误？降低num_ctx参数或升级显存
• docker compose exec clawdbot curl http://ollama:11434/api/tags是否返回模型列表？若失败，检查docker network inspect网络连通性

6.3 HTTPS 访问提示证书不受信任

这是自签名证书的正常现象。开发阶段可：

• Chrome 中输入thisisunsafe（页面空白时敲击）临时绕过
• 或将clawdbot.local.crt导入系统钥匙串（macOS）/ 证书管理器（Windows）

生产环境请务必使用 Let’s Encrypt 证书，Clawdbot 官方文档提供certbot自动续签集成方案。

6.4 提升 Qwen3:32B 实际体验的三个小技巧

1. 启用动态上下文裁剪
   在config.yaml的模型配置中添加：

   qwen3:32b: contextWindow: 32000 trimStrategy: "oldest" # 自动丢弃最早消息，避免超限

2. 设置默认系统提示词
   在providers.my-ollama.models[0]下添加：

   systemPrompt: "你是一个专业、严谨、乐于助人的AI助手，回答需简洁准确，不虚构信息。"

3. 限制单次最大输出长度
   防止长文本阻塞队列：

   maxTokens: 2048 # 从 4096 降至 2048，响应更快，显存压力更小

7. 总结：你已掌握生产级 AI 网关的核心能力

到此为止，你已完成一套完整的、具备工业级安全标准的 AI 代理网关部署：

• 用 Ollama 成功加载并运行 Qwen3:32B 这一前沿大模型
• 通过 Nginx 实现 HTTPS 全站加密与反向代理，屏蔽内部端口暴露
• 启用 JWT Token 校验，支持 URL 参数、Cookie、Header 三种鉴权方式
• 所有服务通过 Docker Compose 统一编排，启动、停止、日志一目了然

这不再是一个“能跑就行”的 demo，而是一个可立即接入企业内部系统的 AI 基础设施模块。你可以将它作为：

• 内部知识库问答入口（对接 RAG 插件）
• 客服机器人后端（集成企业微信/钉钉 Bot）
• 开发者 API 平台（为前端团队提供/v1/chat/completions兼容接口）

下一步，你可以探索 Clawdbot 的扩展能力：添加自定义工具函数、配置多模型路由策略、接入 Prometheus 监控指标，或将其嵌入现有 SSO 体系实现统一身份认证。

真正的 AI 工程化，始于一个稳定、安全、可运维的网关层。而你，已经迈出了最关键的一步。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。