AstrBot + Ollama 本地部署完整指南

环境：Windows + Docker Desktop + WSL2 Ubuntu
显卡：RTX 5080（16GB 显存）
目标：搭建带 Agent 沙盒的 AstrBot，对接本地 Ollama 大模型

---

一、环境准备

1.1 已安装组件

• Windows 10/11
• Docker Desktop（WSL2 后端）
• WSL2 Ubuntu 子系统

1.2 确认 Docker 可用

（需要你预先准备好Docker，可以参考我的另一篇 Windows10安装部署Docker的一次记录）

docker --version
docker compose version

（返回版本信息即正常可用）

二、部署 AstrBot（带 Agent 沙盒）

可以查阅官方wiki---- AstrBot的Docker部署

2.1 下载 AstrBot 源码

由于网络问题（国内常态）可能无法直接 git clone，我选择使用 ZIP 下载方式：

mkdir astrbot && cd astrbot

# 下载源码
wget https://github.com/AstrBotDevs/AstrBot/archive/refs/heads/master.zip

# 解压
unzip master.zip
cd AstrBot-master

如果提示 unzip: command not found，先安装：sudo apt install unzip

2.2 修改沙盒配置（可选）

nano compose-with-shipyard.yml

根据需要修改 Shipyard 的 access token 等环境变量。

2.3 启动 AstrBot + Agent 沙盒

# 启动服务
docker compose -f compose-with-shipyard.yml up -d

# 拉取沙盒镜像
docker pull soulter/shipyard-ship:latest

2.4 验证 AstrBot 运行状态

# 查看容器
docker ps | grep astrbot

# 查看日志（确认管理面板地址）
docker logs -f astrbot

日志中出现 🌈 管理面板已启动，可访问 即表示成功。
打开浏览器访问对应的链接（如 http://172.25.187.6:6185）。

注意：Docker 隔离网络，不能使用 localhost 访问，需使用日志中提供的实际 IP。

---

三、安装 Ollama

3.1 下载 Ollama 安装包

由于 curl | sh 安装方式网络太慢，选择手动下载：

cd ~

# 使用 ghproxy 镜像加速下载（通用 amd64 版本）
wget https://github.com/ollama/ollama/releases/download/v0.30.6/ollama-linux-amd64.tar.zst

# 解压（注意：实际可能是普通 tar 归档，非 gzip 压缩）
tar -xvf ollama-linux-amd64.tgz

# 移动到系统目录
sudo mv ollama /usr/local/

# 创建软链接
sudo ln -sf /usr/local/ollama /usr/local/bin/ollama

# 验证安装
ollama --version

注意：如果 tar -xzf 报错 not in gzip format，说明文件实际是未压缩的 tar 归档，改用 tar -xvf。
特别注意这里有个大坑，就是Ollama的发行版在本身打包成tar文件的情况下（文件后缀名为tar），通过运行指令 file ollama-linux-amd64.tar 发现，它其实是gz的压缩格式，所以在把zst格式解压后，需要用 tar -xvf 解压 tar 包而不是 tar -zxvf

3.2 配置 Ollama 允许外部访问（关键步骤）

AstrBot 运行在 Docker 容器内，需要访问宿主机 Ollama。默认 Ollama 只监听 127.0.0.1，必须改为监听所有网卡：

# 启动 Ollama 并绑定到所有网卡
OLLAMA_HOST=0.0.0.0:11434 ollama serve

验证端口绑定：

ss -tlnp | grep 11434

预期输出：

LISTEN 0  4096  *:11434  *:*  users:(("ollama",pid=xxxx,fd=x))

必须是 *:11434 或 0.0.0.0:11434，不能是 127.0.0.1:11434。

3.3 配置开机自启（可选）

创建 systemd 服务：

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

写入：

[Unit]
Description=Ollama Service
After=network.target

[Service]
Type=simple
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/usr/local/bin/ollama serve
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable ollama
sudo systemctl start ollama

---

四、下载大模型

4.1 拉取模型

根据显存和场景选择模型。这里我是RTX 5080（16GB），推荐 qwen2.5:14b，根据你自己的显卡配置来选择，较低的配置可以选择7b的模型

# 拉取模型
ollama pull qwen2.5:14b

# 查看已安装模型
ollama list

4.2 模型选择参考

模型	参数	显存需求	适用场景
qwen2.5:7b	7B	~8GB	快速响应、低配置
qwen2.5:14b	14B	~12GB	平衡选择，推荐
qwen2.5-vl:7b	7B	~8GB	需要图像理解能力
deepseek-r1:14b	14B	~12GB	复杂推理、代码生成

qwen2.5:14b 能力：文本对话 ✅ | 代码生成 ✅ | 工具调用 ✅ | 图像理解 ❌ | 音频 ❌
（一句话概括：纯文本）

4.3 测试模型

ollama run qwen2.5:14b

输入 /bye 退出。

---

五、AstrBot 对接 Ollama

5.1 获取 WSL2 IP 地址

ip addr show eth0 | grep 'inet ' | awk '{print $2}' | cut -d/ -f1

示例输出：172.25.187.6（你的实际 IP 应当不同于这个）

5.2 在 AstrBot 管理面板配置

1. 打开浏览器访问 AstrBot 管理面板（如 http://172.25.187.6:6185）
2. 左侧菜单 → 提供商管理 → 添加提供商
3. 选择 Ollama

填写配置：

配置项	填写内容
提供商源唯一 ID	自定义，如 ollama-local
API Key	任意填写，如 sk-ollama（Ollama 本地不验证）
API Base URL	http://<WSL2_IP>:11434/v1（如 http://172.25.187.6:11434/v1）
模型	手动输入 qwen2.5:14b（不要点"获取模型列表"）
代理地址	留空

关键：Base URL 末尾必须加 /v1，使用 API 路径。

注意：如果点击"获取模型列表"按钮，可能因 API 路径问题报错 404。直接手动输入模型名保存即可。

4. 保存配置，测试对话

5.3 验证连通性

# 从 Docker 容器内测试 Ollama API
docker exec -it astrbot sh
curl http://172.25.187.6:11434/v1/models

# 测试完整对话 API
curl -X POST http://172.25.187.6:11434/v1/chat/completions   -H "Content-Type: application/json"   -H "Authorization: Bearer sk-ollama"   -d '{
    "model": "qwen2.5:14b",
    "messages": [{"role": "user", "content": "你好"}]
  }'

---

六、常见问题排查

6.1 git clone 失败（TLS 错误）

fatal: unable to access 'https://github.com/...': GnuTLS recv error (-110)

解决：使用 ZIP 下载代替 git clone，或使用 ghproxy 镜像加速。

6.2 Ollama 安装包解压失败

gzip: stdin: not in gzip format
tar: Child returned status 1

解决：文件实际是未压缩的 tar 归档，使用 tar -xvf 而非 tar -xzf。

6.3 Docker 容器无法访问 Ollama

现象：AstrBot 测试连接失败，或提示 Connection error。

解决：

1. 检查 Ollama 端口绑定：ss -tlnp | grep 11434
2. 确保是 *:11434 而非 127.0.0.1:11434
3. 使用 WSL2 实际 IP 而非 host.docker.internal（Linux Docker 可能不识别）

6.4 AstrBot 获取模型列表 404

现象：获取模型列表失败: 404 page not found

解决：

• Base URL 加 /v1 后缀
• 手动输入模型名（我这里是qwen2.5:14b），不点击"获取模型列表"按钮

6.5 模型下载慢

解决：挂代理，或更换下载时段。Ollama 模型库在国内访问较慢。

---

七、后续开发方向

基于当前搭建的环境，可开展以下项目：

项目	技术要点
超仿真聊天机器人	调整温度参数（0.8-1.0）、设计详细 System Prompt、开发表情包插入插件
微信远控 Agent	配置微信消息平台适配器、开发工具调用插件、启用 Agent 沙盒执行本地代码
电商智能客服	接入知识库（RAG）、配置商品 FAQ、对接店铺 API
视频脚本生成	设计脚本生成 Prompt、接入视频素材库、自动化剪辑工具调用

---

八、关键配置速查

# Ollama 常用命令
ollama serve                    # 启动服务
ollama pull qwen2.5:14b        # 下载模型
ollama list                     # 查看已安装模型
ollama run qwen2.5:14b         # 运行模型
ollama rm qwen2.5:14b          # 删除模型

# Docker 常用命令
docker ps                       # 查看运行容器
docker logs -f astrbot          # 查看 AstrBot 日志
docker exec -it astrbot sh      # 进入 AstrBot 容器
docker compose -f compose-with-shipyard.yml up -d   # 启动 AstrBot + 沙盒

# 网络诊断
curl http://localhost:11434/api/tags                # 测试 Ollama 原生 API
curl http://localhost:11434/v1/models               
ip addr show eth0 | grep 'inet ' | awk '{print $2}' | cut -d/ -f1   # 获取 WSL2 IP

---

核心经验：Ollama 本地部署无 API Key 验证，AstrBot 对接时手动填模型名 + Base URL 加 /v1，可绕过兼容性问题。
AstrBot只是一个让你可以通过微信或QQ等平台与Agent远程通信的框架，但有了这个框架，就有了本地部署和远程通信的通道，本地部署的意义绝不仅仅是省那点儿Token（实际上国内Token费用已经相当便宜），更多的是对于数据安全和隐私防护具有重要的意义，也具有了更广阔的可能性。