ollaguard 1.2.0

A lightweight transparent proxy for Ollama with API Key authentication.

Ollaguard

Ollaguard 是一个基于 FastAPI 构建的轻量级透明代理服务器。

项目初衷：为 Ollama 提供一个极简的 API Key 鉴权层，在不增加过多系统资源负担的前提下（相比于 LiteLLM 等重型方案），确保本地或私有化部署的服务安全性。

核心功能

• 透明全量代理：拦截所有路径和 HTTP 方法，并将其转发到指定的 TARGET_URL。支持流式响应（StreamingResponse），完美适配 AI 流式输出或大文件传输。
• 安全认证机制：
  • Master Key：通过环境变量或命令行设置，拥有最高权限。
  • 动态 API Key：支持动态生成普通 API Key，并持久化存储在 storage.json 中。
  • Bearer Token 校验：所有经过代理或管理接口的请求均需通过 HTTP Bearer Token 进行身份验证。
• 灵活配置：支持通过命令行参数或环境变量动态调整服务器运行参数。
• 依赖管理：采用现代化的 pyproject.toml 管理依赖，推荐使用 uv 工具进行环境搭建。

快速开始

1. 环境准备

推荐安装 uv 以获得更快的依赖安装体验。

# 克隆项目
git clone https://gitcode.com/Neila/ollaguard.git
cd ollaguard

# 安装依赖并安装本地包
uv sync

2. 启动服务

安装完成后，您可以直接使用 ollaguard 命令：

ollaguard --target-url http://localhost:11434 --master-key my-secret-master-key

或者使用 python main.py 启动：

python main.py --target-url http://localhost:11434 --master-key my-secret-master-key

3. 主要命令行参数

参数	描述	默认值	环境变量
--host	绑定主机地址	0.0.0.0	-
--port	监听端口	4000	-
--target-url	(必须) 代理目标基础 URL	-	TARGET_URL
--master-key	主管理密钥，用于生成普通 Key	-	MASTER_KEY
--prefix	Key 的前缀，用于生成特定的 Key	""	-
--timeout	请求超时时间（秒）	300.0	-

接口说明

代理转发 (所有路径)

任何发送到服务器的请求（除了 /key/generate）都会被转发到 TARGET_URL。

• 认证：请求头需包含 Authorization: Bearer <YOUR_KEY>。
• 注意：如果未设置 MASTER_KEY，则认证机制默认关闭，所有请求将直接转发。
• 前缀说明：如果设置了 --prefix，则验证 Master Key 时可以带上前缀（即 prefix + master-key），也可以仅使用原始 master-key。

生成新 API Key

接口：POST /key/generate

权限：需提供 MASTER_KEY。

请求示例：

curl -X POST http://localhost:8000/key/generate \
  -H "Authorization: Bearer <MASTER_KEY>"

响应：

{
  "key": "prefix-xxxxxxxxxxxx"
}

生成的 Key 将自动包含设置的 --prefix（如果有），并保存到 storage.json 中，并在后续请求中生效。

项目结构

• pyproject.toml: 现代 Python 打包配置。
• ollaguard/: 核心包目录
  • main.py: FastAPI 应用主逻辑，定义路由。
  • cli.py: 命令行工具入口。
  • proxy.py: 核心代理实现，基于 httpx。
  • security.py: 认证逻辑（Master Key & 普通 Key 校验）。
  • gen_key.py: Key 生成逻辑。
  • config.py: 配置解析与持久化存储管理。
• storage.json: 用于存储已生成的 API Key（自动创建）。

许可证

MIT License