快速上手

本页带你从零跑通第一个经过 Redact 保护的请求：安装 Secret Guard，写好 1 个上游 Provider + 1 个要保护的 Secret 的最小配置，启动网关并发请求，然后把 Agent 工具的 base_url 指过来进入日常使用。

1. 安装

最简单的方式是下载 二进制归档 (Linux x86_64 / ARM64, musl 全静态)，解压即用。也可以从源码仓库 (GitHub, MIT) 安装：

# Nix (flake):
nix run github:luochen1990/secret-guard -- --help
# 或将 overlay / nixosModule 接入你的 flake 后直接用 pkgs.secret-guard

# Cargo (从源码构建, 需要 rustc >= 1.96):
cargo install --git https://github.com/luochen1990/secret-guard
# 或克隆仓库后: cargo install --path .

2. 最小配置

在某个目录创建 secret-guard.toml (1 个上游 Provider + 1 个要保护的 Secret 即可跑通)：

[[providers]]
id = "openai-main"
kind = "direct"                         # 直连上游 (路由端点用 "router")
api_key = "sk-your-upstream-key"        # 条目级凭证, 全端点共享 — 必须写在 [[providers.endpoints]] 之前
[[providers.endpoints]]
protocol = "openai"
base_url = "https://api.openai.com"

[[secrets.entries]]
id = "my-github-token"
value = "ghp_0123456789abcdefghijklmnopqrstuvwxyz"   # 要保护的 secret (不会发往上游)

警告

注意层级：Secret 写在 [[secrets.entries]] 下，而 Provider 是平铺的 [[providers]] (两套写法不一致)。误写 [[secrets]] 会导致启动失败。

全部配置段的字段、类型与默认值见 配置参考。

3. 启动并发出第一个请求

secret-guard run --port 18787
curl http://127.0.0.1:18787/o/openai-main/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "My token is ghp_0123456789abcdefghijklmnopqrstuvwxyz, please summarize."
      }
    ]
  }'

请求中的 Secret 已被替换为等长的仿真 Mock Secret 发往上游 — 每笔转发完成日志的 redactions=1 即替换计数，LLM 全程看不到真值。

浏览器打开 http://127.0.0.1:18787/ 可在 WebUI 的 Records 页查看这次请求的 LLM 视角 (Secret 位置以高亮 Mock 呈现)，详见 WebUI 指南。

注意

本文示例统一用端口 18787；不指定 --port 时默认监听 127.0.0.1:8787 (也可用 [server] port 或环境变量 SG_PORT 修改)。

4. SDK 日常使用

日常使用时，把 Agent 工具的 base_url 指过来即可，无需手写 curl：

OpenAI Python SDK

from openai import OpenAI
client = OpenAI(
    base_url="http://127.0.0.1:18787/o/openai-main/v1",
    api_key="ignored",
)

Anthropic Python SDK

from anthropic import Anthropic
client = Anthropic(
    base_url="http://127.0.0.1:18787/a/anthropic-main",
    api_key="ignored",  # 由 provider 配置覆盖
)

注意

SDK 的 base_url 需自带版本路径前缀 (如 /v1)，Secret Guard 只原样透传； Anthropic SDK 的 base_url 同理配到 /a/<provider-id> 即可 (其 SDK 自带 /v1/messages)。

5. 路由约定

URL 形如 /{proto_short}/{provider_id}/*rest，同时编码 入站协议 与 目标 Provider：

proto_short	Protocol	SDK 示例 (base_url)
o	OpenAI	http://127.0.0.1:18787/o/<provider-id>/v1
a	Anthropic	http://127.0.0.1:18787/a/<provider-id>
g	Gemini	http://127.0.0.1:18787/g/<provider-id>
l	oLLama	http://127.0.0.1:18787/l/<provider-id>
r	Responses (OpenAI Responses API)	http://127.0.0.1:18787/r/<provider-id>/v1

注：表中 URL 是 SDK base_url 口径 — OpenAI SDK (Chat Completions 与 Responses 同 SDK) 需自带 /v1 前缀；Anthropic SDK 自行拼 /v1/messages，配到 /a/<provider-id> 即可； curl 直连则写完整路径 (见上方示例)。

6. 日志与排障

每笔转发完成时 stdout 打一行 INFO 摘要 (forward method=... path=... status=... elapsed_ms=... redactions=N provider=...)， 无需打开 WebUI 即可在命令行确认流量经过 Secret Guard；上游故障 (502/504) 的错误 body 也带可读原因 (如 upstream error: http://127.0.0.1:29999 (Connection refused))。量级大时可用 RUST_LOG=secret_guard=warn 调低 (默认 info)。

配置报错的症状与解法速查见 配置参考 — 常见配置错误。