1. 项目概述：一个为Ollama模型服务量身打造的代理网关

如果你正在本地或内网环境中部署和使用Ollama来运行各种开源大语言模型，并且遇到了需要统一管理、权限控制、负载均衡或者只是想给API调用加一层“缓冲”的需求，那么 kesor/ollama-proxy 这个项目很可能就是你正在寻找的解决方案。简单来说，它是一个专门为Ollama设计的HTTP反向代理服务器。它的核心价值在于，让你能够在不修改Ollama服务本身的情况下，为它增加一层代理层，从而实现对模型服务调用的集中管控、安全增强和运维便利。

想象一下这个场景：你的团队有多个成员需要访问部署在内网服务器上的Ollama服务，每个人可能使用不同的客户端工具（如OpenAI SDK兼容的库、curl命令、或者自己写的脚本）。直接暴露Ollama的原生API端口（默认11434）会带来几个问题：缺乏统一的认证机制、难以记录和审计所有的请求、无法对特定模型或用户的调用频率进行限制，更不用说当你想在多个Ollama实例前做负载均衡时的复杂情况了。 ollama-proxy 就是为了解决这些问题而生的。它扮演了一个“守门人”和“调度员”的角色，所有外部请求先到达代理，由代理进行必要的处理（如鉴权、日志记录、路由转发）后，再转发给后端的Ollama服务，并将响应原路返回。

这个项目由开发者 kesor 维护，采用Go语言编写，以其轻量、高效和易于部署的特性，成为了Ollama生态中一个非常实用的增强组件。它不是要替代Ollama，而是作为Ollama的一个强大“伴侣”，让个人开发者或小团队也能以更企业级、更安全的方式来管理和使用自己的私有模型服务。

2. 核心架构与设计思路拆解

2.1 为什么需要为Ollama加个代理？

Ollama本身的设计哲学是极简和开箱即用，它提供了一个非常干净的RESTful API，主要面向单用户或可信环境下的本地开发。然而，一旦我们将使用场景扩展到小型团队协作、轻度生产环境或需要对API访问进行管控时，原生API的局限性就显现出来了。

首先， 安全性 是首要考量。Ollama原生API默认没有身份验证。任何知道服务器地址和端口的人都可以调用模型、拉取或删除模型文件。虽然可以通过防火墙规则限制IP，但这在动态IP或移动办公场景下并不灵活。 ollama-proxy 可以集成基础的HTTP认证（如Basic Auth）或更复杂的JWT令牌验证，为API访问设立第一道防线。

其次， 可观测性与审计 。原生Ollama的日志相对简单，主要集中在服务运行状态和模型加载过程。对于“谁在什么时候调用了哪个模型、输入是什么、消耗了多少Token”这类业务层面的审计需求，原生服务无法满足。代理层可以完整地记录每一条请求和响应的元数据，甚至可以对敏感信息进行脱敏，为问题排查和用量分析提供数据基础。

再者， 路由与负载均衡 。如果你部署了多个Ollama实例（可能在不同机器上，或者在同一机器上运行不同版本的Ollama以隔离环境），客户端需要知道每个实例的地址。通过代理，你可以提供一个统一的入口地址。代理可以根据策略（如轮询、基于模型名称的路由）将请求分发到不同的后端实例，实现简单的负载均衡和高可用。

最后， 请求预处理与后处理 。代理层可以在请求到达Ollama之前对其进行修改，例如，统一为所有请求添加特定的系统提示词（system prompt），或者修改采样参数（temperature, top_p）。同样，在响应返回给客户端之前，也可以对响应内容进行格式化、过滤或添加自定义的响应头。这为定制化需求提供了极大的灵活性。

ollama-proxy 的设计正是围绕这些需求展开的。它没有试图做一个功能大而全的API网关，而是聚焦于Ollama API的核心流程，通过中间件（Middleware）的架构，以插件化的方式支持上述功能，保持了自身的简洁和高效。

2.2 项目架构与核心组件

ollama-proxy 的架构非常清晰，是一个典型的分层处理模型。我们可以将其核心工作流程分解为以下几个步骤：

  1. 接收请求 ：代理服务器监听一个指定的HTTP端口（如 8080 ），等待客户端发起的请求。这些请求必须遵循Ollama API的规范（例如， /api/generate 用于文本生成， /api/chat 用于对话， /api/tags 用于列出模型等）。

  2. 中间件处理链 ：这是代理的核心。请求会依次通过一系列配置好的中间件。每个中间件负责一项特定的任务。常见的中间件包括：

    • 认证中间件 ：检查请求头（如 Authorization ）中的凭证是否有效。
    • 日志中间件 ：将请求的URL、方法、客户端IP、时间戳以及可选的请求/响应体（可配置脱敏）记录到文件或标准输出。
    • 限流中间件 ：基于IP、用户或全局维度，限制对特定接口（如 /api/generate ）的请求频率，防止滥用。
    • 路由/负载均衡中间件 ：根据配置，决定将请求转发到哪一个后端的Ollama实例。配置可以是一个简单的静态列表，也可以支持更复杂的健康检查机制。

  3. 请求转发 ：经过所有中间件处理后，代理会将（可能被修改过的）请求转发给预先配置好的后端Ollama服务地址（如 http://localhost:11434 ）。转发过程基本是透明的，但代理可能会添加、删除或修改一些HTTP头。

  4. 接收并返回响应 ：代理接收Ollama后端返回的响应（通常是一个Streaming HTTP Response，用于流式输出）。响应在返回给客户端的途中，可能也会经过响应处理中间件（例如，添加自定义头 X-Processed-By: ollama-proxy ）。

  5. 错误处理 ：在整个链条中，任何中间件或转发过程出错，代理都应能捕获错误，并返回结构化的错误信息给客户端，而不是暴露后端服务的内部细节。

这种中间件架构的优势在于 高内聚、低耦合 。每个功能模块独立，你可以通过配置文件轻松地启用、禁用或调整它们的顺序。例如，你可以先认证，再记录日志；或者先记录日志，再认证失败的请求。项目的配置通常通过一个YAML或JSON文件完成，使得部署和变更非常方便。

3. 部署与配置实操详解

3.1 环境准备与获取代理程序

ollama-proxy 作为Go语言项目，最方便的部署方式是使用其预编译的二进制文件。假设我们在一台Linux服务器上进行部署，Ollama服务已经运行在本地的 11434 端口。

首先，我们需要从项目的GitHub Releases页面下载最新版本的二进制文件。以 v0.1.0 版本为例，我们可以使用 wget 或 curl 命令。

# 假设下载amd64架构的Linux版本
wget https://github.com/kesor/ollama-proxy/releases/download/v0.1.0/ollama-proxy-linux-amd64 -O ollama-proxy

下载完成后，需要赋予二进制文件可执行权限。

chmod +x ollama-proxy

此时，你可以通过运行 ./ollama-proxy --help 来查看所有可用的命令行参数，确认程序可以正常工作。通常，它会显示如何指定配置文件、监听端口等选项。

注意 ：请始终从项目的官方GitHub仓库下载发布版本，以确保安全性和稳定性。自行从源码编译也是可行的，但这要求你的部署环境中已安装Go工具链（Go 1.19+）。

3.2 配置文件解析与核心参数设定

ollama-proxy 的强大和灵活很大程度上体现在其配置文件上。我们创建一个名为 config.yaml 的配置文件来进行详细说明。

# config.yaml
server:
  # 代理服务监听的地址和端口，客户端将向这个地址发送请求
  host: "0.0.0.0"
  port: 8080
  # 读取和写入超时设置，对于流式生成请求，写超时需要设置得足够长
  read_timeout: "300s"
  write_timeout: "300s"

# 后端Ollama服务的配置
ollama:
  # 后端Ollama实例的地址列表。目前通常配置一个，未来可能支持多实例负载均衡。
  hosts:
    - "http://localhost:11434" # 假设Ollama运行在同一台机器的默认端口
  # 转发到后端时的请求超时
  timeout: "60s"

# 中间件配置，这是功能核心
middlewares:
  # 1. 日志中间件
  - name: logger
    # 日志格式：支持`json`（结构化，便于收集）或`common`（类Apache通用日志格式）
    format: "json"
    # 输出位置：`stdout` 或文件路径
    output: "stdout"
    # 是否记录请求和响应的Body，出于隐私和性能考虑，生产环境建议关闭或只采样记录
    log_body: false

  # 2. 基础认证中间件（示例）
  - name: basic_auth
    # 配置允许的用户名和密码（bcrypt哈希值）
    # 可以使用 `htpasswd` 工具或 `ollama-proxy` 自带的工具生成哈希
    users:
      - username: "admin"
        password_hash: "$2a$10$YourBcryptHashHere..." # 替换为实际生成的哈希

  # 3. 限流中间件（示例）
  - name: rate_limiter
    # 全局速率限制：每秒最多处理10个请求
    global:
      requests_per_second: 10
    # 基于IP的速率限制：每个IP每秒最多5个请求
    per_ip:
      requests_per_second: 5

  # 4. 请求头修改中间件（示例）
  - name: header_modifier
    request:
      # 在转发给Ollama的请求中添加或覆盖头部
      add:
        - "X-Forwarded-By: ollama-proxy/1.0"
    response:
      # 在返回给客户端的响应中添加头部
      add:
        - "X-Processing-Time: {duration}" # {duration} 是一个内置变量，代表处理耗时

关键配置项解读：

  • server.port ：这是最重要的参数之一，决定了你的代理服务对外暴露的端口。确保该端口在服务器的防火墙或安全组中已开放。
  • ollama.hosts ：指向真实的Ollama服务。如果Ollama运行在另一台机器，需将 localhost 替换为对应的IP地址。 务必确认网络可达 。
  • middlewares ：中间件的执行顺序就是它们在配置文件中的声明顺序。例如，上面配置的顺序是：先记录日志 -> 再进行基础认证 -> 然后检查限流 -> 最后修改请求头。这个顺序很重要，比如把认证放在日志后面，那么认证失败的请求也会被记录下来。
  • basic_auth ：这是最简单的认证方式。密码必须以bcrypt哈希值存储，明文密码写在配置文件里是极不安全的。你可以使用命令 echo -n “yourpassword” | htpasswd -i -B -C 10 -n | cut -d: -f2 来生成哈希（需要 apache2-utils 包），或者查看 ollama-proxy 项目是否提供了配套的密码生成工具。
  • rate_limiter ：限流是保护后端Ollama服务不被突发流量打垮的重要手段。 global 限制整个代理的吞吐， per_ip 则防止单个用户/IP滥用。具体的数值需要根据你的服务器性能和业务需求进行调整。

3.3 启动代理服务与验证

配置文件准备就绪后，就可以启动代理服务了。建议使用 nohup 或 systemd 等工具将服务放到后台运行，以实现持久化。

使用nohup简单启动： 

nohup ./ollama-proxy -c config.yaml > proxy.log 2>&1 &

这条命令的意思是：使用 config.yaml 配置文件启动 ollama-proxy ，并将标准输出和错误输出重定向到 proxy.log 文件， & 表示在后台运行。

使用systemd（推荐用于生产环境）： 创建一个systemd服务文件 /etc/systemd/system/ollama-proxy.service ：

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

[Service]
Type=simple
User=root # 建议创建一个专用用户，如`ollama`，并修改此处
WorkingDirectory=/path/to/ollama-proxy
ExecStart=/path/to/ollama-proxy/ollama-proxy -c /path/to/ollama-proxy/config.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

然后执行：

sudo systemctl daemon-reload
sudo systemctl start ollama-proxy
sudo systemctl enable ollama-proxy # 设置开机自启
sudo systemctl status ollama-proxy # 查看状态

服务验证： 代理启动后，首先检查进程是否在运行（ ps aux | grep ollama-proxy ）和端口是否在监听（ netstat -tlnp | grep 8080 ）。

然后，我们可以使用 curl 命令进行一个简单的测试。假设我们配置了基础认证，用户名为 admin ，密码为 password123 。

  1. 测试未认证请求（应返回401） ：

    curl -v http://your-server-ip:8080/api/tags

    你应该看到返回 401 Unauthorized 。

  2. 测试带认证的请求 ：

    curl -u admin:password123 http://your-server-ip:8080/api/tags

    如果一切正常，这个命令应该会返回与直接调用 http://localhost:11434/api/tags 相同的结果，即你本地Ollama中已拉取的模型列表。这证明代理工作正常，它成功认证了你的请求，并将其转发给了后端的Ollama服务。

  3. 测试流式生成请求 ： 这是更复杂的测试，确保代理能正确处理长连接和流式数据。

    curl -u admin:password123 -N \
  http://your-server-ip:8080/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2:1b",
    "prompt": "Hello, how are you?",
    "stream": true
  }'

    如果能看到模型单词接单词地流式输出，说明代理的流式转发功能也完全正常。

4. 高级功能与集成场景探索

4.1 实现基于API密钥（JWT）的认证

基础认证简单，但不够安全（每次请求都传输密码），也不便于管理多个密钥或集成到第三方系统。更常见的做法是使用API密钥，通常以JWT（JSON Web Token）的形式实现。 ollama-proxy 可能通过自定义中间件或社区插件来支持JWT。

其工作流程通常是：

  1. 用户首先向一个独立的“认证服务”（可以是一个简单的端点，甚至是代理内置的一个 /auth 接口）提供凭证（如用户名密码），换取一个短期的JWT令牌。
  2. 用户在后续请求Ollama代理时，在 Authorization 头部携带 Bearer <JWT_TOKEN> 。
  3. 代理配置的JWT验证中间件会：
    • 检查令牌是否存在且格式正确。
    • 验证签名（确保令牌未被篡改）。
    • 检查有效期（ exp 声明）。
    • 可选地，验证令牌中的其他声明（如 role , model_access 等），实现更细粒度的权限控制。

虽然 ollama-proxy 原生可能不直接包含一个完整的JWT签发服务，但它的中间件架构允许你集成一个验证中间件。你需要编写或找到一个Go库（如 github.com/golang-jwt/jwt ）来实现验证逻辑，并将其编译到自定义版本的代理中，或者等待社区提供相关插件。

4.2 与Prometheus/Grafana集成实现监控可视化

对于生产环境，监控代理和后端Ollama服务的健康状态、请求量、响应延迟、错误率等指标至关重要。 ollama-proxy 可以通过暴露Prometheus格式的指标端点来实现这一点。

通常，这需要一个 指标收集中间件 。这个中间件会在每个请求处理前后记录：

  • ollama_proxy_requests_total ：总请求数（按方法、路径、状态码分类）。
  • ollama_proxy_request_duration_seconds ：请求耗时分布直方图。
  • ollama_proxy_request_size_bytes ：请求体大小。
  • ollama_proxy_response_size_bytes ：响应体大小。
  • ollama_proxy_upstream_requests_total ：向上游（Ollama）发起的请求数（按后端主机、状态码分类）。

然后，在配置中启用这个中间件，并配置代理服务暴露一个额外的HTTP端点（如 /metrics ）。Prometheus服务器可以定期从这个端点抓取指标数据。最后，在Grafana中导入或创建仪表盘，将这些指标可视化出来，你就能得到类似“过去一小时QPS”、“95分位响应时间”、“各模型调用占比”等非常有价值的运维视图。

4.3 作为多模型/多版本路由网关

如果你管理着多个不同用途的Ollama实例， ollama-proxy 可以成为一个简单的路由网关。例如：

  • 实例A ：专门运行代码模型（如 codellama ），GPU资源充足。
  • 实例B ：专门运行通用对话模型（如 llama3 ）。
  • 实例C ：运行一个较旧的、但非常稳定的模型版本用于特定历史任务。

你可以在代理的配置中定义多个后端主机，并编写一个自定义的 路由中间件 。这个中间件可以根据请求的某些特征来决定转发目标：

  • 基于请求路径 ：例如，将 /api/generate 且请求体中 model 字段以 codellama 开头的请求，路由到实例A。
  • 基于HTTP头 ：例如，客户端在头中指定 X-Target-Backend: stable-v1 ，则路由到实例C。
  • 基于负载 ：实现简单的轮询或最少连接数算法，将请求均匀分发到多个提供相同模型的后端实例上，实现水平扩展。

这种架构将模型部署的复杂性对客户端隐藏起来，客户端只需要知道代理的地址，由代理来智能地分配请求，极大地提升了系统的可管理性和弹性。

5. 生产环境部署的注意事项与排错指南

5.1 安全加固 checklist

将 ollama-proxy 暴露在公网或内部生产网络前，务必检查以下安全项：

  1. 强密码与密钥管理 ：

    • 绝对禁止在配置文件中使用明文密码。
    • 用于Basic Auth的密码应使用强bcrypt哈希（高cost factor，如12）。
    • 如果使用JWT，确保使用强密钥（HS256至少32字节随机字符串，RS256使用足够长的私钥），并定期轮换。
    • 考虑使用外部密钥管理服务（如HashiCorp Vault、云厂商的KMS）来管理密钥，而不是写在配置文件中。

  2. 网络层隔离 ：

    • 代理服务器本身应该部署在防火墙或安全组之后，仅开放必要的代理端口（如8080）和管理端口（如SSH）。
    • 后端Ollama服务（11434端口） 不应该 直接暴露给外部网络，只允许来自代理服务器IP的流量访问。这可以通过主机的本地防火墙（如 ufw ）或云安全组规则实现。
    • 示例 ufw 规则： sudo ufw allow from <proxy_server_ip> to any port 11434 。

  3. TLS/HTTPS加密 ：

    • ollama-proxy 默认使用HTTP。在公网或传输敏感信息的内部网络， 必须启用HTTPS 。
    • 你可以使用反向代理（如Nginx, Caddy）放在 ollama-proxy 前面，由它们处理TLS终止。这是更常见和专业的做法。
    • 也可以寻找或开发支持直接加载SSL证书的 ollama-proxy 版本。
    • 使用Let‘s Encrypt等服务获取免费且受信任的证书。

  4. 最小权限原则 ：

    • 不要以 root 用户身份运行 ollama-proxy 进程。创建一个专用的系统用户（如 ollamaproxy ），并确保它只拥有运行所需的最小文件和目录权限。
    • 在 systemd 服务文件中指定 User 和 Group 。

  5. 日志与审计 ：

    • 确保日志中间件已开启，并将日志输出到安全的、有权限控制的文件中。
    • 定期归档和审查日志，关注异常访问模式（如大量认证失败、来自异常IP的请求）。
    • 对日志中的敏感信息（如请求中的完整prompt、生成的文本）进行脱敏处理，可以在日志中间件配置中设置 log_body: false 或使用脱敏规则。

5.2 性能调优与高可用考量

  1. 资源限制 ：

    • Go程序本身内存管理较好，但仍需关注。可以使用 systemd 的 MemoryMax 等指令限制服务可用的最大内存，防止内存泄漏导致系统崩溃。
    • 根据预期并发连接数，调整操作系统的文件描述符限制（ ulimit -n ）。

  2. 超时设置 ：

    • server.read_timeout / server.write_timeout ：对于流式生成，这个值必须设置得足够大，以容纳长时间的模型推理。可以设置为 0 表示禁用（不推荐），或设置为一个非常大的值（如 3600s ）。需要权衡的是，过长的超时可能挂起连接，消耗资源。
    • ollama.timeout ：这是代理等待后端Ollama响应的最长时间。如果后端模型“卡住”或响应极慢，这个超时可以防止代理线程被无限期占用。建议根据模型通常的响应时间设置，例如 300s 。

  3. 高可用部署 ：

    • 代理层高可用 ：可以部署多个 ollama-proxy 实例，前端使用负载均衡器（如Nginx, HAProxy）进行流量分发。负载均衡器需要配置健康检查，自动剔除故障的代理实例。
    • 后端层高可用 ：如前所述，通过代理的路由功能，将请求分发到多个Ollama后端实例。关键在于，这些后端实例需要加载相同的模型，并且模型文件需要保持同步（可以通过共享存储或部署脚本解决）。
    • 状态管理 ： ollama-proxy 本身通常是无状态的（除了可能的限流计数器，如果存储在内存中）。对于内存中的限流器，在多个代理实例间无法共享状态，可能导致限流不准确。此时可以考虑使用基于Redis等外部存储的分布式限流中间件，或者直接在前端负载均衡器或API网关层面做限流。

5.3 常见问题排查实录

在实际运维中，你可能会遇到以下问题。这里提供一个快速排查的思路：

问题现象 可能原因 排查步骤
客户端连接代理超时 1. 代理进程未运行。
2. 代理监听端口被防火墙阻止。
3. 网络路由问题。		 1. systemctl status ollama-proxy 或 ps aux | grep proxy 检查进程。
2. sudo netstat -tlnp | grep :8080 检查端口监听。
3. 在服务器本地 curl http://localhost:8080/api/tags 测试。
返回 401 Unauthorized 1. 未提供认证信息。
2. 认证信息错误（密码/令牌错误）。
3. 认证中间件配置错误或顺序有误。		 1. 确认请求头包含正确的 Authorization 。
2. 检查配置中的密码哈希或JWT密钥是否正确。
3. 检查中间件顺序，认证是否在日志等中间件之后被绕过？
返回 502 Bad Gateway 或 503 Service Unavailable 1. 后端Ollama服务未运行或不可达。
2. 后端Ollama服务崩溃或端口不对。
3. 代理到后端的网络不通。		 1. 检查后端Ollama服务状态 ( ollama serve 是否在运行)。
2. 在代理服务器上 curl http://后端IP:11434/api/tags 测试连通性。
3. 检查代理配置中 ollama.hosts 地址是否正确。
流式响应中断或连接被重置 1. 代理或客户端的读写超时设置过短。
2. 网络不稳定。
3. 后端Ollama模型推理过程中出错。		 1. 检查代理配置的 read_timeout 和 write_timeout ，适当调大。
2. 查看代理和后端Ollama的日志，寻找错误信息。
3. 尝试一个非常简单的prompt，看是否稳定。
请求非常慢 1. 后端Ollama模型加载或推理本身慢。
2. 代理服务器资源（CPU/内存）不足。
3. 限流中间件配置过于严格。		 1. 直接请求后端Ollama，对比速度，排除代理问题。
2. 监控代理服务器资源使用情况 ( top , htop )。
3. 检查限流中间件配置，临时调高或禁用限流测试。
日志文件增长过快 1. 配置了 log_body: true ，记录了完整的请求/响应体。
2. 访问量巨大。		 1. 生产环境建议关闭 log_body 或仅对特定路径开启。
2. 配置日志轮转（logrotate），定期压缩和清理旧日志。

一个实用的调试技巧 ：在测试或排查问题时，可以先使用一个极简的配置文件，只保留最基本的路由功能，禁用所有中间件。确认基础转发正常后，再逐一启用中间件，并观察行为变化，这样可以快速定位是哪个环节引入了问题。

部署和运维 ollama-proxy 的过程，本质上是在“简单易用”和“可控可靠”之间寻找平衡点。它可能引入了一些额外的复杂性，但为你的Ollama服务带来的管理能力、安全性和可观测性的提升，对于超越个人开发的任何使用场景来说，都是非常值得的投入。随着你对它的熟悉，你可以根据自己团队的具体需求，定制或集成更多的中间件，让它真正成为你私有AI基础设施中坚实而灵活的一环。

# Ollama
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

百万Token不是数字游戏：Kimi K3完整吞下10万行代码库后，我测出了它的真实理解力

avatar 亚马逊云科技技术品牌专区
cover

【2026最新版】Codex换肤助手下载和使用教程：一键美化 Codex 客户端，支持自定义主题

avatar 亚马逊云科技技术品牌专区

FastAPI + OpenAI 兼容协议 + DeepSeek 实战：大模型 Function Calling 工具调用全拆解

模型本身不能直接查天气、查数据库。我们告诉模型"你有这些函数可用"，模型在觉得需要时返回"我想调用某个函数、参数是这样"，真正的函数由我们本地执行，再把结果交还给模型整理成话。这就是"模型决策 + 本地执行"的混合模式。

avatar 亚马逊云科技技术品牌专区