Skip to main content

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

Metadata

Release files for ollaguard 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ollaguard 1.2.0
File Size Uploaded Provenance Actions
ollaguard-1.2.0.tar.gz 7.6 kB Without provenance Details for ollaguard-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ollaguard 1.2.0
File Interpreter ABI Platform Actions
ollaguard-1.2.0-py3-none-any.whl Python 3 none any Details for ollaguard-1.2.0-py3-none-any.whl

Total release size: 14.9 kB

Release files / ollaguard-1.2.0.tar.gz

Download URL ollaguard-1.2.0.tar.gz
Size 7.6 kB
Tags Source
SHA-256 checksum
How to use checksums
b051582930fc9c8ddfc80d51705c0e0ac7593ab7e5d5cd29937c294d24921978
BLAKE2b-256 checksum
How to use checksums
26317749bbb0b6e94e79a1499293fc8c80c29f7ec67a03a7557a43a7d27ea1d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / ollaguard-1.2.0-py3-none-any.whl

Download URL ollaguard-1.2.0-py3-none-any.whl
Size 7.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
27d34b997795ef3dde168a1600d3dc56c63e560dc115c5084febd2b208537164
BLAKE2b-256 checksum
How to use checksums
bc2c960e2acb09e577d58639b9557ed4f35ea88ea3b07a2a546f721c4829d8e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for ollaguard 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page