Starter 配置参考

完整配置参考

所有键位于 patchbridge-agent 下，未知字段在绑定期失败。

Starter 配置总表

配置键	默认值	范围、条件和行为
`enabled`	`true`	false 时不装配整个 Starter
`base-path`	`/ai`	匹配 `/[A-Za-z0-9.~-]+(?:/[A-Za-z0-9.~-]+)*` 或根路径 `/`；相对路径与尾斜杠绑定期失败。该前缀是 Starter 独占命名空间：宿主 Controller 不得映射到该空间内，否则启动失败；`/` 表示全部 MVC 路径归 Starter 所有
`model.base-url`	无	默认 Provider 必填；绝对 HTTP(S)，禁止 user-info、query、fragment
`model.api-key`	无	可空，取决于上游网关
`model.model`	无	默认 Provider 必填、不可空白
`model.connect-timeout-ms`	`10000`	大于等于 0；0 表示无限
`model.read-timeout-ms`	`300000`	大于等于 0；0 表示无限
`conversations.list-limit`	`50`	必须大于 0
`audit.enabled`	`true`	false 才停止审计写入
`audit.payload-mode`	`metadata-only`	仅 full、metadata-only、none
`audit.summary-max-length`	`4000`	必须大于 0
`mcp.enabled`	`true`	false 时不装配默认 MCP Client/Store/Registry/Manager/MCP Admin；不禁止宿主显式自定义 Bean
`mcp.source`	`properties`	仅 properties 或 jdbc；互斥、不合并、不失败切换
`mcp.namespace`	`mcp`	1-128 字符；字母数字、下划线、连字符，可用点分段
`mcp.servers`	空 Map	properties 模式 Server；不可显式为 null
`mcp.jdbc.encryption-key`	无	默认 JDBC Store 需要；标准 Base64 解码后恰好 32 字节
`admin.enabled`	`false`	true 时必须提供 AdminAccessPolicy

audit.payload-mode=full 才组装请求/响应摘要，并仍经过 AuditRedactor。metadata-only 和 none 当前都不保存 payload 摘要，但仍保存调用元数据；完全关闭需使用 audit.enabled=false。

MCP Server 子配置

每个 mcp.servers.<name> 支持：

配置键	默认值	范围和要求
Server name	无	1-64 字符；首字符字母数字，其余可含下划线、连字符
`url`	无	HTTP(S) 绝对地址；禁止 user-info、fragment；允许 query
`transport`	`streamable-http`	当前只支持此值
`enabled`	`true`	是否发布该 Server 的 Tool
`timeout-ms`	`30000`	100..300000
`cache-ttl-ms`	`300000`	1000..86400000
`auth.type`	`none`	none/basic/bearer/api-key-header/static-headers
`auth.username`	无	仅 basic
`auth.password`	无	仅 basic
`auth.token`	无	仅 bearer 或 api-key-header
`auth.header-name`	无	仅 api-key-header
`auth.headers`	空 Map	仅 static-headers；受 Header 白名单规则约束
`tools.include`	null	null/空表示不限制
`tools.exclude`	null	不得与 include 重叠
`tools.permissions`	空 Map	远端 Tool 名到宿主权限标识

auth 类型是严格互斥联合：basic 只接受 username/password；bearer 只接受 token；api-key-header 只接受 header-name/token；static-headers 至少一个 Header；none 不接受任何凭据字段。非当前类型字段、未知嵌套字段、Header 值中的 CR/LF 都明确失败。自定义 Header 名必须是 RFC token，且不能是 host、content-length、transfer-encoding、connection、keep-alive、proxy-connection、proxy-authorization、te、trailer、upgrade、accept、content-type、mcp-session-id、mcp-protocol-version、authorization 或 cookie。

URL 字符校验不是 SSRF 防护。生产环境必须用出站代理、防火墙、DNS/网络策略和管理权限限制可访问目标。

properties 模式示例

patchbridge-agent:
  mcp:
    enabled: true
    source: properties
    namespace: mcp
    servers:
      inventory:
        url: https://mcp.example.com/mcp
        transport: streamable-http
        enabled: true
        timeout-ms: 30000
        cache-ttl-ms: 300000
        auth:
          type: bearer
          token: ${MCP_INVENTORY_TOKEN}
        tools:
          include:
            - query_stock
          permissions:
            query_stock: inventory:read

properties 模式是只读配置源。Admin 可以查看、刷新和测试连接，但 create/update/enable/delete 会返回 409 MCP_CONFIG_READ_ONLY。

JDBC 模式示例

patchbridge-agent:
  admin:
    enabled: true
  mcp:
    enabled: true
    source: jdbc
    jdbc:
      encryption-key: ${PATCHBRIDGE_AGENT_MCP_ENCRYPTION_KEY}

只使用外部密钥系统或环境变量注入密钥。Admin 查询只返回 authType 和 credentialConfigured，不回显 token、密码或静态 Header。

FilesExpand file tree

configuration.md

Latest commit

History