Metadata-Version: 2.4
Name: ollaguard
Version: 1.2.0
Summary: A lightweight transparent proxy for Ollama with API Key authentication.
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.135.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: uvicorn>=0.42.0
Description-Content-Type: text/markdown

# 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](https://github.com/astral-sh/uv) 以获得更快的依赖安装体验。

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

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

### 2. 启动服务

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

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

或者使用 `python main.py` 启动：

```bash
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`。

**请求示例**：
```bash
curl -X POST http://localhost:8000/key/generate \
  -H "Authorization: Bearer <MASTER_KEY>"
```

**响应**：
```json
{
  "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](LICENSE)
