跳到主要内容

tophant.aidy.gateway.entity

Messages & Enums​

message GlobalPluginConfig​

插件全局配置

message GlobalPluginConfig {
    // 日志插件配置
    optional LogPluginGlobalConfig log = 1;
    // 安全检测插件配置
    optional GuardPluginGlobalConfig guard = 2;
    // 限速插件配置
    optional RateLimitPluginGlobalConfig rate_limit = 3;
    // 上游限速插件配置
    optional UpstreamRateLimitPluginGlobalConfig upstream_rate_limit = 4;
}

message GuardPluginConfig​

安全检测插件路由级配置

message GuardPluginConfig {
    // 对于 chat 的请求进行检测
    optional GuardPluginConfig.DetectConfig detect_chat_request = 31;
    // 对于 chat 的响应进行检测
    optional GuardPluginConfig.DetectConfig detect_chat_response = 32;
    // 对于 embeddings 的请求进行检测
    optional GuardPluginConfig.DetectConfig detect_embeddings_request = 33;
}

enum GuardPluginConfig.CheckMode​

enum CheckMode {
    CHECK_MODE_UNSPECIFIED = 0;
    // 关闭检测
    CHECK_MODE_DISABLED = 1;
    // 阻断
    CHECK_MODE_BLOCK = 2;
    // 仅记录检测结果（不阻断）
    CHECK_MODE_LOG_ONLY = 3;
}

message GuardPluginConfig.DetectConfig​

message DetectConfig {
    // 检测模式：disabled / block / log_only
    optional GuardPluginConfig.CheckMode mode = 1;
    // CyberGuard JSON 配置（使用 guardpb.v3.PolicyChain 的 JSON 表达）
    optional string policy_chain_json = 3;
    // CyberGuard JSON 兼容版本（用于后续管理 JSON 版本）
    optional int32 policy_chain_json_compatibility_version = 4;
}

message GuardPluginGlobalConfig​

安全检测插件全局配置

message GuardPluginGlobalConfig {
    // 检查服务 URL
    optional string check_service_url = 2;
    // 检测服务请求超时时间（默认 30s）
    optional google.protobuf.Duration timeout = 3;
}

message HeaderBucket​

基于请求 Header 的限速桶

message HeaderBucket {
    // header 名称，例如 "X-Tenant-ID"
    optional string name = 1;
}

message HeaderCondition​

基于请求 Header 的条件

message HeaderCondition {
    // header 名称
    optional string name = 1;
    // 等于指定值
    optional string equals = 11;
    // 前缀匹配
    optional string starts_with = 12;
    // 包含指定值
    optional string contains = 13;
    // 正则匹配
    optional string regex = 14;
    // 检查 header 是否存在（设为 true）
    optional bool exists = 15;
}

message LogPluginGlobalConfig​

请求日志记录插件配置

message LogPluginGlobalConfig {
    // 是否禁用请求日志上报
    optional bool disabled = 1;
    // 是否记录未知路由的日志
    optional bool log_unknown_routes = 21;
    // 是否记录未认证请求的日志
    optional bool log_unauthenticated_routes = 22;
    // 利用 HTTP 进行上报
    optional LogPluginGlobalConfig.Http http = 11;
    // 利用 Kafka 进行上报
    optional LogPluginGlobalConfig.Kafka kafka = 12;
}

message LogPluginGlobalConfig.Http​

message Http {
    // 请求方法
    optional string method = 1;
    // 日志上报上游 URL
    optional string url = 2;
    optional LogPluginGlobalConfig.Http.BasicAuth basic_auth = 11;
}

message LogPluginGlobalConfig.Http.BasicAuth​

message BasicAuth {
    optional string username = 1;
    optional string password = 2;
}

message LogPluginGlobalConfig.Kafka​

message Kafka {
    // Kafka broker 地址列表
    repeated string brokers = 1;
    // Kafka topic 名称
    optional string topic = 2;
    // TLS 配置
}

message LogPluginGlobalConfig.Kafka.TlsConfig​

message TlsConfig {
    // 是否启用 TLS
    optional bool enable = 1;
    // CA 证书文件路径
    optional string ca_file_path = 2;
    // 客户端证书文件路径
    optional string cert_file_path = 3;
    // 客户端私钥文件路径
    optional string key_file_path = 4;
    // 是否跳过服务器证书验证
    optional bool insecure_skip_verify = 5;
}

message Pair​

message Pair {
    optional string name = 1;
    optional string value = 2;
}

message PluginConfig​

插件路由级配置

message PluginConfig {
    // 安全检测插件配置
    optional GuardPluginConfig guard = 2;
    // 限速插件配置
    optional RateLimitPluginConfig rate_limit = 3;
    // 上游限速插件配置
    optional UpstreamRateLimitPluginConfig upstream_rate_limit = 4;
}

message RateLimitBucket​

限速桶：用于确定限速的维度/key

message RateLimitBucket {
    // 基于请求 header
    optional HeaderBucket header = 1;
    // 基于客户端 IP
    optional SourceAddrBucket source_addr = 2;
}

message RateLimitCondition​

限速条件：满足条件才触发限速检查

message RateLimitCondition {
    // 基于请求 header 的条件
    optional HeaderCondition header = 1;
    // 基于客户端 IP 的条件
    optional SourceAddrCondition source_addr = 2;
}

message RateLimitPluginConfig​

限速插件路由级配置

message RateLimitPluginConfig {
    // 响应头模式：控制限速相关响应头的返回策略
    optional RateLimitPluginHeadersMode headers_mode = 1;
}

message RateLimitPluginGlobalConfig​

限速插件全局配置

message RateLimitPluginGlobalConfig {
    // 响应头模式：控制限速相关响应头的返回策略
    optional RateLimitPluginHeadersMode headers_mode = 1;
}

enum RateLimitPluginHeadersMode​

限速插件响应头模式

enum RateLimitPluginHeadersMode {
    // 未指定，使用默认行为
    RATE_LIMIT_PLUGIN_HEADERS_MODE_UNSPECIFIED = 0;
    // 始终返回限速相关响应头
    RATE_LIMIT_PLUGIN_HEADERS_MODE_ALWAYS = 1;
    // 仅在触发限速时返回响应头
    RATE_LIMIT_PLUGIN_HEADERS_MODE_ON_LIMIT = 2;
    // 从不返回限速相关响应头
    RATE_LIMIT_PLUGIN_HEADERS_MODE_NEVER = 3;
}

message RateLimitQuota​

限速配额配置

message RateLimitQuota {
    // 限速数量
    optional int64 limit = 1;
    // 时间窗口（滑动窗口），例如 1s、1m、1h、24h
    optional google.protobuf.Duration window = 2;
    // 计量单位
    optional RateLimitUnit unit = 3;
}

enum RateLimitUnit​

限速计量单位

enum RateLimitUnit {
    RATE_LIMIT_UNIT_UNSPECIFIED = 0;
    // token 数
    RATE_LIMIT_UNIT_TOKENS = 1;
    // 字符数
    RATE_LIMIT_UNIT_CHARACTERS = 2;
}

message Route​

message Route {
    // 路由 ID，后续日志等会包含
    optional string id = 1;
    // 路由名称，后续日志等会包含
    optional string name = 2;
    // 路由前缀，用于匹配请求路径，必须以 / 开头，不可以使用特殊符号
    optional string prefix = 3;
    // 租户 ID，用于多租户隔离
    optional string tenant_id = 4;
    optional Upstream upstream = 11;
    // 访问该路由本身的认证（注意不是访问上游时的认证 —— 上游认证在 upstream 中配置）
    optional RouteAuth auth = 21;
    // passthrough_auth_token 控制是否透传请求中的 Token（Authorization 头）到上游
    // - true：透传原始请求的 Authorization 头到上游（无论是否配置了 upstream.token）
    // - false（默认）：仅当未配置 upstream.token 时保留原始 Authorization 头，否则使用 upstream.token
    // 注意：如果配置了 auth（RouteAuth），则不能开启 passthrough_auth_token，因为 RouteAuth 会消费掉 Authorization 头
    optional bool passthrough_auth_token = 24;
    // capabilities 用于控制路由启用的能力
    // 可选值：
    // - "openai-models"：允许访问 /v1/models
    // - "openai-chat"：允许访问 /v1/chat/completions
    // - "openai-embeddings"：允许访问 /v1/embeddings
    // - "forward-unknown"：对未显式支持的路径原样向上游转发（否则直接返回 404）
    repeated string capabilities = 23;
    optional PluginConfig plugin_config = 31;
    // 自定义标签，用于上报时携带，最多10个
    optional google.protobuf.Struct labels = 41;
}

message RouteAuth​

message RouteAuth {
    // Bearer Token 认证
    optional RouteAuth.BearerAuth bearer = 1;
}

message RouteAuth.BearerAuth​

message BearerAuth {
    repeated string tokens = 1;
}

message SourceAddrBucket​

基于客户端 IP 的限速桶 空消息，表示使用客户端 IP 作为桶 key

message SourceAddrBucket {
    // no fields
}

message SourceAddrCondition​

基于客户端 IP 的条件

message SourceAddrCondition {
    // 等于指定 IP
    optional string equals = 1;
    // 前缀匹配，如 "192.168.1."
    optional string starts_with = 2;
    // CIDR 匹配，如 "192.168.0.0/16"
    optional string cidr = 3;
    // 是否存在可用的客户端 IP（true 表示必须存在且合法）
    optional bool exists = 4;
}

message Tenant​

message Tenant {
    // 租户 ID
    optional string id = 1;
    optional string name = 2;
    // requests per second
    optional uint32 inbound_rate_limit_qps = 21;
    // characters per minute
    optional uint32 detect_rate_limit_cpm = 31;
}

message Upstream​

message Upstream {
    optional UpstreamType type = 1;
    optional string url = 2;
    optional string token = 3;
    optional uint32 max_idle_conns_per_host = 4;
    repeated Pair extra_headers = 11;
}

message UpstreamRateLimitPluginConfig​

上游限速插件路由级配置

message UpstreamRateLimitPluginConfig {
    // 限速规则列表（为空则插件不生效）
    repeated UpstreamRateLimitRule rules = 1;
}

message UpstreamRateLimitPluginGlobalConfig​

上游限速插件全局配置 预留字段，暂无全局配置

message UpstreamRateLimitPluginGlobalConfig {
    // no fields
}

message UpstreamRateLimitRule​

上游限速规则

message UpstreamRateLimitRule {
    // 限速桶配置（用于确定限速的维度/key）
    // 隐含：每个规则的限速桶会自动添加 "route:{RouteID}:rule:{RuleIndex}" 作为前缀
    optional RateLimitBucket bucket = 1;
    // 限速条件（满足所有条件才触发限速检查，为空则始终触发）
    repeated RateLimitCondition conditions = 2;
    // 限速配额配置
    optional RateLimitQuota quota = 3;
}

message UpstreamType​

message UpstreamType {
    optional UpstreamType.OpenAICompatible openai_compatible = 1;
    optional UpstreamType.AzureOpenAI azure_openai = 2;
}

message UpstreamType.AzureOpenAI​

message AzureOpenAI {
    // no fields
}

message UpstreamType.OpenAICompatible​

message OpenAICompatible {
    // no fields
}