AI AI 工具指南
常见问题解决库

Ollama 启动报 port already in use

执行 ollama serve 时报 address already in use，端口 11434 被占用无法启动。快速定位占用进程、清理僵尸实例、修改默认端口的完整操作步骤。

发布于: 作者: AI Productivity Guide Team 🌐 查看英文版本

执行 ollama serve 或通过系统服务启动 Ollama 时，终端打印 Error: listen tcp 127.0.0.1:11434: bind: address already in use，服务无法启动。最常见的情况是 Ollama 有一个僵尸进程还在运行，或者 macOS 上的 Ollama.app 已经在后台监听了同一端口。少数情况下是另一个完全不相关的程序恰好选了 11434 这个端口。

常见原因

1. Ollama 僵尸进程仍在监听

上一次 ollama serve 通过 Ctrl+C 退出，但子进程没有被正确清理，父进程退出了而 worker 进程还在占用端口。

怎么判断：lsof -i :11434 或 ss -tlnp | grep 11434（Linux），检查输出中是否有 ollama 进程。

2. macOS 上 Ollama.app 后台服务与命令行 serve 冲突

在 macOS 上安装了 Ollama.app 后，应用会注册为 Launch Agent，系统启动时自动在后台运行并监听 11434 端口。此时在终端额外执行 ollama serve 就会端口冲突。

怎么判断：菜单栏查看是否有 Ollama 图标；或 launchctl list | grep ollama 检查是否有活跃的 Launch Agent。

3. systemd 服务在运行，用户又手动启动了第二个实例

Linux 上 Ollama 通过 sudo systemctl start ollama 已在运行，用户又在终端执行了 ollama serve，两个实例争用同一端口。

怎么判断：systemctl status ollama 查看服务状态；若显示 active (running)，说明 systemd 服务已经在运行。

4. 另一个程序占用了 11434 端口

虽然 11434 是 Ollama 的默认端口，但理论上任何程序都可能选用它。某些开发工具、Prometheus exporter 或自定义脚本可能使用了这个端口。

怎么判断：lsof -i :11434 -P -n 查看占用进程名，若不是 ollama 说明是其他程序。

5. 端口处于 TIME_WAIT 状态未释放

在快速重启场景下，之前的 TCP 连接可能进入 TIME_WAIT 状态（通常持续 60-120 秒），操作系统不允许新进程绑定处于此状态的端口。

怎么判断：ss -tan | grep 11434 检查是否有 TIME_WAIT 行；若有，等待 2 分钟后重试。

6. Docker 容器映射了 11434 端口到宿主机

运行了包含 Ollama 的 Docker 容器，并通过 -p 11434:11434 将端口映射到宿主机，导致宿主机上该端口被占用。

怎么判断：docker ps --format "{{.Ports}}" | grep 11434 检查是否有容器映射了该端口。

最短修复路径

Step 1：找出占用端口的进程

# macOS / Linux 通用
lsof -i :11434 -P -n

# Linux（更快速）
ss -tlnp | grep :11434

# 示例输出：
# COMMAND   PID     USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# ollama   1234  liziang   12u  IPv4  12345      0t0  TCP 127.0.0.1:11434 (LISTEN)

Step 2A：如果是 Ollama 自身进程，直接终止

# 获取 PID（从上面的 lsof 输出）
kill -15 $(lsof -ti :11434)

# 等待 2 秒后确认端口已释放
sleep 2
lsof -i :11434
# 应该无输出

# 重新启动
ollama serve

Step 2B：macOS 上停止 Ollama.app 后台服务

# 方法 1：通过菜单栏点击 Ollama 图标 → Quit Ollama
# 方法 2：命令行停止 Launch Agent
launchctl stop com.ollama.ollama

# 之后可以正常运行 ollama serve
# 或者让 Launch Agent 管理它（不要手动 serve）

Step 2C：Linux systemd 服务管理

# 查看服务状态
systemctl status ollama

# 如果已在运行，通过 systemctl 操作而不是手动 serve
sudo systemctl restart ollama   # 重启服务
sudo systemctl stop ollama      # 停止服务

# 需要前台调试时，先停止 systemd 服务再手动 serve
sudo systemctl stop ollama
OLLAMA_DEBUG=1 ollama serve

Step 3：修改 Ollama 监听端口（永久方案）

# 如果 11434 确实被其他程序长期占用，修改 Ollama 端口
export OLLAMA_HOST=0.0.0.0:11435

# 或写入 shell 配置
echo 'export OLLAMA_HOST=0.0.0.0:11435' >> ~/.bashrc
source ~/.bashrc

# 之后客户端调用时指定新端口
curl http://localhost:11435/api/generate -d '{"model":"llama3","prompt":"hello"}'

Step 4：处理 TIME_WAIT 状态（Linux）

# 查看 TIME_WAIT 连接
ss -tan | grep 11434

# 临时开启端口复用（不推荐长期使用）
sudo sysctl -w net.ipv4.tcp_tw_reuse=1

# 或等待 60 秒让 TIME_WAIT 自然过期

预防建议

  • macOS 上选择一种管理方式（Ollama.app 或命令行 ollama serve），不要混用，避免双实例冲突。
  • Linux 上统一通过 systemd 管理 Ollama 服务，用 systemctl 命令操作而非手动执行 ollama serve。
  • 写脚本启动 Ollama 前先检查端口是否空闲：! lsof -i :11434 -P -n -t >/dev/null 2>&1 && ollama serve。
  • 在 .env 或环境配置中固定 OLLAMA_HOST，避免依赖隐式默认端口导致迁移时出问题。
  • 系统重启后不要手动 ollama serve，而是依赖 systemd 或 Launch Agent 自动启动，避免重复实例。
  • 开发环境和生产环境使用不同端口（如 11434 和 11435），互不干扰。

常见问答 (FAQ)

Q: kill 之后重启 Ollama 还是报端口占用，怎么办？ A: 可能 kill 信号没有立即生效，或者有多个 ollama 进程。使用 pkill -9 ollama 强制终止所有 ollama 进程，然后等待 5 秒再重试。也检查 lsof -i :11434 是否有非 ollama 进程。

Q: 修改了 OLLAMA_HOST 端口后，Open WebUI 或其他客户端连不上了怎么办？ A: 需要同步修改客户端的 API base URL。Open WebUI 在设置里修改 Ollama URL 为新端口；直接调用 API 的脚本修改 base_url 变量。

Q: Docker 中运行的 Ollama 也会出现这个问题吗？ A: Docker 内部的 11434 端口不影响宿主机，但如果容器通过 -p 11434:11434 映射到宿主机，宿主机上就会有进程占用 11434。用 docker stop <container> 停止容器即可释放。

Q: 能不能让 Ollama 监听 0.0.0.0 而不是 127.0.0.1？ A: 可以，设置 OLLAMA_HOST=0.0.0.0:11434 后 Ollama 会接受所有网卡的连接。注意这意味着局域网内其他设备也能访问，在公网环境下要加防火墙规则。

相关阅读

标签: #local-llm #ollama #排查

相关文章

常见问题解决库

本地 LLM 服务在多 GPU 机器上启动后，所有计算只在第一张卡上进行，其他卡显存占用为零。从 tensor parallel 配置、NVLink、环境变量三个层面给出强制分布的修复方案。

#local-llm #vllm