本文档提供在 Linux 服务器上通过 Docker Compose 部署 Ollama 的完整指南。

适用场景: Java/Spring Boot 开发者需要在服务器部署本地 LLM，用于 RAG、Agent 等 AI 应用开发。

---

📋 目录

1. 环境准备
2. 快速部署
3. 模型管理
4. API 测试
5. Spring Boot 集成
6. 常见问题
7. 性能优化

---

环境准备

1.1 上传部署文件到服务器

将以下文件上传到服务器的 ~/ollama-deployment/ 目录：

# 在本地执行（你的电脑）
scp -r ollama-deployment/ user@your-server:~/ollama-deployment/

# 或者直接在服务器上创建
ssh user@your-server
mkdir -p ~/ollama-deployment
cd ~/ollama-deployment

1.2 运行环境检测脚本

# 在服务器上执行
cd ~/ollama-deployment
chmod +x check-env.sh
./check-env.sh

预期输出示例：

==========================================
   Ollama 部署环境检测脚本
==========================================

1. 系统信息检测
----------------------------------------
✓ PASS: 操作系统: Ubuntu 22.04
✓ PASS: 系统架构: x86_64
✓ PASS: 内核版本: 5.15.0-91-generic

2. Docker 环境检测
----------------------------------------
✓ PASS: Docker 已安装，版本: 24.0.7
✓ PASS: Docker 服务正在运行
✓ PASS: Docker Compose 已安装，版本: 2.21.0
✓ PASS: 当前用户有 Docker 执行权限

3. GPU 检测
----------------------------------------
⚠ WARN: 未检测到 NVIDIA GPU 或驱动未安装 (nvidia-smi 不可用)
⚠ WARN: 未检测到 GPU，将使用 CPU 模式运行（速度较慢）

4. 系统资源检测
----------------------------------------
✓ PASS: 总内存: 16GB, 可用内存: 12GB
✓ PASS: 内存充足，可以运行 7B 模型
✓ PASS: 根分区总空间: 100G, 可用空间: 60G
✓ PASS: 磁盘空间充足

5. 网络检测
----------------------------------------
✓ PASS: 可以访问 Docker Hub
✓ PASS: 端口 11434 可用

==========================================
   检测完成
==========================================

检测结果统计:
通过: 12
失败: 0
警告: 2

环境检测通过，可以开始部署！

1.3 安装 Docker（如未安装）

Ubuntu/Debian:

# 一键安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 安装 Docker Compose 插件
sudo apt-get update
sudo apt-get install -y docker-compose-plugin

# 验证安装
docker --version
docker compose version

# 将当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
newgrp docker

CentOS/RHEL:

# 安装 Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version
docker compose version

---

快速部署

2.1 选择部署方案

根据环境检测结果，选择合适的 docker-compose.yml 文件：

方案	文件	适用场景
基础版（推荐）	docker-compose.yml	CPU 模式，无 GPU 或测试环境
GPU 加速版	docker-compose.gpu.yml	有 NVIDIA GPU，需要加速推理
生产环境版	docker-compose.prod.yml	需要 Web UI 界面和持久化配置

2.2 部署基础版（CPU 模式）

cd ~/ollama-deployment

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f

# 检查服务状态
docker compose ps

预期输出：

[+] Running 2/2
 ✔ Network ollama-deployment_default  Created
 ✔ Container ollama                   Started

NAME      IMAGE                  COMMAND   SERVICE   CREATED         STATUS         PORTS
ollama    ollama/ollama:latest  "/bin/ollama serve"   ollama    10 seconds ago  Up 9 seconds   0.0.0.0:11434->11434/tcp

2.3 部署 GPU 加速版

前置条件： 已安装 NVIDIA 驱动和 NVIDIA Container Toolkit

# 安装 NVIDIA Container Toolkit (Ubuntu/Debian)
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# 验证 GPU 可用
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

# 启动 Ollama (GPU 版)
cd ~/ollama-deployment
docker compose -f docker-compose.gpu.yml up -d

2.4 验证部署

# 测试健康检查
curl http://localhost:11434/api/health

# 预期输出
{"status":"ok"}

---

模型管理

3.1 拉取模型

进入容器拉取模型：

# 进入 Ollama 容器
docker exec -it ollama bash

# 拉取推荐的小模型（3B-7B）
ollama pull qwen2:7b      # 推荐：中文效果好
ollama pull llama3.2:3b   # 轻量级，速度快
ollama pull mistral:7b     # 英文效果好

# 查看已安装的模型
ollama list

# 测试运行模型
ollama run qwen2:7b "你好，请介绍一下自己"

# 退出容器
exit

推荐模型（适合 3B-7B）：

模型	大小	推荐场景	拉取命令
qwen2:7b	4.5GB	中文对话、RAG	ollama pull qwen2:7b
llama3.2:3b	2GB	轻量级、快速推理	ollama pull llama3.2:3b
mistral:7b	4.1GB	英文、代码生成	ollama pull mistral:7b
qwen2:1.5b	1GB	超轻量、极速	ollama pull qwen2:1.5b

3.2 模型资源需求

模型	最低内存	推荐内存	磁盘空间	推理速度 (CPU)
llama3.2:3b	4GB	8GB	2GB	~10 tok/s
qwen2:7b	8GB	16GB	4.5GB	~5 tok/s
mistral:7b	8GB	16GB	4.1GB	~5 tok/s

注意： CPU 模式推理速度较慢，建议用于开发和测试。生产环境建议使用 GPU 加速。

3.3 删除模型

# 进入容器
docker exec -it ollama bash

# 删除模型
ollama rm qwen2:7b

# 退出容器
exit

---

API 测试

4.1 生成文本（/api/generate）

# 测试模型推理
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2:7b",
  "prompt": "用 Java 写一个单例模式",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "max_tokens": 2048
  }
}'

预期输出：

{
  "model": "qwen2:7b",
  "created_at": "2026-01-15T10:30:00.000Z",
  "response": "```java\npublic class Singleton {\n    private static volatile Singleton instance;\n    \n    private Singleton() {}\n    \n    public static Singleton getInstance() {\n        if (instance == null) {\n            synchronized (Singleton.class) {\n                if (instance == null) {\n                    instance = new Singleton();\n                }\n            }\n        }\n        return instance;\n    }\n}\n```",
  "done": true,
  "total_duration": 1234567890,
  "load_duration": 123456,
  "prompt_eval_count": 15,
  "eval_count": 150,
  "eval_duration": 1234567890
}

4.2 对话模式（/api/chat）

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2:7b",
  "messages": [
    {
      "role": "user",
      "content": "什么是 RAG？"
    }
  ],
  "stream": false,
  "options": {
    "temperature": 0.7
  }
}'

4.3 Python 测试脚本

import requests
import json

# Ollama API 地址
OLLAMA_URL = "http://localhost:11434"

# 测试生成 API
def test_generate():
    response = requests.post(
        f"{OLLAMA_URL}/api/generate",
        json={
            "model": "qwen2:7b",
            "prompt": "用 Java 写一个快速排序",
            "stream": False,
            "options": {
                "temperature": 0.7,
                "max_tokens": 1024
            }
        }
    )
    print("生成结果：")
    print(response.json()["response"])

# 测试对话 API
def test_chat():
    response = requests.post(
        f"{OLLAMA_URL}/api/chat",
        json={
            "model": "qwen2:7b",
            "messages": [
                {"role": "user", "content": "什么是 Spring Boot？"}
            ],
            "stream": False
        }
    )
    print("对话结果：")
    print(response.json()["message"]["content"])

if __name__ == "__main__":
    test_generate()
    # test_chat()

---

Spring Boot 集成

5.1 使用 LangChain4j 集成 Ollama

Maven 依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-ollama</artifactId>
    <version>0.27.1</version>
</dependency>

配置类：

import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.ollama.OllamaChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OllamaConfig {
    
    @Bean
    public ChatLanguageModel chatModel() {
        return OllamaChatModel.builder()
            .baseUrl("http://localhost:11434")
            .modelName("qwen2:7b")
            .temperature(0.7)
            .build();
    }
}

服务类：

import dev.langchain4j.model.chat.ChatLanguageModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class AIService {
    
    @Autowired
    private ChatLanguageModel chatModel;
    
    public String chat(String message) {
        return chatModel.generate(message);
    }
}

5.2 使用 Spring AI 集成 Ollama

Maven 依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
    <version>0.8.1</version>
</dependency>

配置文件（application.yml）：

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2:7b
          temperature: 0.7

控制器：

import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/ai")
public class AIController {
    
    @Autowired
    private ChatClient chatClient;
    
    @PostMapping("/chat")
    public String chat(@RequestBody String message) {
        return chatClient.call(message);
    }
}

---

常见问题

6.1 端口 11434 被占用

# 查看端口占用
sudo netstat -tulpn | grep 11434

# 解决方案 1：停止占用端口的进程
sudo kill -9 <PID>

# 解决方案 2：修改 docker-compose.yml 中的端口映射
ports:
  - "11435:11434"  # 改为 11435

6.2 模型下载慢

配置代理：

# 编辑 docker-compose.yml
environment:
  - HTTP_PROXY=http://your-proxy:port
  - HTTPS_PROXY=http://your-proxy:port

使用国内镜像：

# 进入容器后设置环境变量
export OLLAMA_HOST=0.0.0.0
export OLLAMA_MODELS=/root/.ollama/models

# 或者使用镜像站（如果可用）

6.3 内存不足

# 查看内存使用
free -h
docker stats

# 解决方案：使用更小的模型
docker exec -it ollama bash
ollama rm qwen2:7b
ollama pull qwen2:1.5b  # 只占用 1GB 内存

6.4 容器无法启动

# 查看详细日志
docker compose logs ollama

# 常见问题：
# 1. 端口被占用（见 6.1）
# 2. 权限问题（见 6.5）
# 3. 磁盘空间不足（清理空间或删除无用镜像）
docker system prune -a

6.5 权限问题

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER
newgrp docker

# 或者每次用 sudo 运行
sudo docker compose up -d

---

性能优化

7.1 保持模型常驻内存

# 编辑 docker-compose.yml
environment:
  - OLLAMA_KEEP_ALIVE=24h  # 模型加载后保持 24 小时

7.2 调整并发设置

# 编辑 docker-compose.yml
environment:
  - OLLAMA_NUM_PARALLEL=2  # 同时处理 2 个请求
  - OLLAMA_MAX_LOADED_MODELS=2  # 最多加载 2 个模型

7.3 使用 GPU 加速

参考 2.3 部署 GPU 加速版

性能对比：

模式	推理速度	适用场景
CPU (无加速)	5-10 tok/s	开发测试
GPU (NVIDIA)	50-100 tok/s	生产环境

---

清理和卸载

# 停止并删除容器
cd ~/ollama-deployment
docker compose down

# 删除容器和数据卷（慎用！会删除所有模型）
docker compose down -v

# 只删除容器，保留数据
docker compose down --remove-orphans

---

总结

✅ 已完成：

1. 环境检测和 Docker 安装
2. Ollama 部署（基础版/GPU 版/生产版）
3. 模型拉取和管理
4. API 测试
5. Spring Boot 集成示例

📌 下一步：

1. 根据自己的需求选择合适的模型
2. 集成到 Spring Boot 项目中（使用 LangChain4j 或 Spring AI）
3. 开发 RAG 或 Agent 应用

💡 推荐阅读：

• Ollama 官方文档
• LangChain4j 文档
• Spring AI 文档

---

部署文件清单：

• docker-compose.yml - 基础版配置
• docker-compose.gpu.yml - GPU 加速版配置
• docker-compose.prod.yml - 生产环境版配置
• check-env.sh - 环境检测脚本
• DEPLOYMENT_GUIDE.md - 本文档