Documentation
¶
Index ¶
- Constants
- type APIOpen
- type APIResponseEvent
- type APIResponseEventKind
- type AgentAddress
- type AgentApplication
- type AgentCache
- type AgentRuntime
- type AgentSelector
- type AgentServer
- type Application
- type AttemptStream
- type AttemptStreamOpener
- type AttemptStreamRequest
- type BodyLimits
- type BodyStore
- type Context
- type DatabaseLayoutMode
- type EventBus
- type HTTPAPIProtocolError
- type HTTPAPIStream
- type HTTPAPIStreamOpener
- type Hub
- type MasterServer
- type MasterSettingsSnapshot
- type NotificationHandler
- type ProbePolicy
- type ProbeStream
- type ProbeStreamOpener
- type ProbeStreamRequest
- type Publisher
- type QuotaChecker
- type RelayHandler
- type RelayLink
- type ReplayBody
- type Reporter
- type ResourceCounts
- type RoutePath
- type Settler
- type Store
- type Syncer
- type TransportPool
- type UserInfo
- type WSBridge
- type WSClient
- type WSConn
- type WebSocketAPIStream
- type WebSocketAPIStreamOpener
- type WebSocketAccepted
- type WebSocketEvent
- type WebSocketEventKind
- type WebSocketExecutionError
- type WebSocketOpen
- type WebSocketRejection
Constants ¶
const ( ProbeRespectBusinessPolicy = tunnel.ProbeRespectBusinessPolicy ProbeBypassBusinessPolicy = tunnel.ProbeBypassBusinessPolicy )
const ( WebSocketMessageStartEvent = tunnel.WebSocketMessageStartEvent WebSocketMessageDataEvent = tunnel.WebSocketMessageDataEvent WebSocketMessageEndEvent = tunnel.WebSocketMessageEndEvent WebSocketPingEvent = tunnel.WebSocketPingEvent WebSocketPongEvent = tunnel.WebSocketPongEvent WebSocketCloseEvent = tunnel.WebSocketCloseEvent WebSocketTextMessage = tunnel.WebSocketTextMessage WebSocketBinaryMessage = tunnel.WebSocketBinaryMessage WebSocketCloseProtocolError = tunnel.WebSocketCloseProtocolError )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIResponseEvent ¶ added in v0.0.16
type APIResponseEvent struct {
Kind APIResponseEventKind
Headers *tunnel.Headers
Data []byte
Trailers *tunnel.Trailers
Result *apiattempt.APIExecutionResult
}
type APIResponseEventKind ¶ added in v0.0.16
type APIResponseEventKind uint8
const ( APIResponseHeaders APIResponseEventKind = iota + 1 APIResponseData APIResponseEnd APIResponseResult )
type AgentAddress ¶ added in v0.0.13
AgentAddress is the shared address value used at application boundaries.
type AgentApplication ¶
type AgentApplication interface {
GetCache() AgentCache
GetBodyStore() BodyStore
GetLogger() *zap.Logger
GetConfig() *config.AgentRuntimeConfig
GetTransportPool() TransportPool
RelayTimeout() time.Duration // 非流式请求的总超时;0 表示不限
}
AgentApplication 是 agent 端专用服务容器,跟 Application 并列存在于 RelayContext。 Relay pipeline 通过此接口拿到 cache / logger / config / transport pool, 避免把整个 *Handler 当参数到处传,方便测试时 stub 单个依赖。
type AgentCache ¶
type AgentCache interface {
Store
FindTokenRoute(tokenID uint, realModel string) *models.AgentRoute
FindAdminChannelRoute(channelID uint, realModel string) *models.AgentRoute
EffectiveRequestLimiters(userID, groupID uint) []*models.RequestLimiter
EffectiveAttemptLimiters(userID, groupID uint, src string, channelID uint) []*models.RequestLimiter
}
AgentCache 在 Store 基础上加 relay 需要的 route 查询能力。 嵌入 Store 是为了让 relay 路径既能查 Token / Channel / ModelConfig, 也能查 AgentRoute,不必持有两个对象。
type AgentRuntime ¶
type AgentRuntime struct {
Uptime int64 `json:"uptime"`
CachedTokens int `json:"cached_tokens"`
CachedChannels int `json:"cached_channels"`
CachedModels int `json:"cached_models"`
ActiveConnections int `json:"active_connections"`
Version int64 `json:"version"`
MasterVersion int64 `json:"master_version"`
}
AgentRuntime Agent 运行时信息 包含 Agent 的缓存状态、连接数、版本等运行时数据
type AgentSelector ¶ added in v0.0.13
AgentSelector identifies exactly one agent or one agent tag.
type AgentServer ¶
type AgentServer interface {
Run() error
RunBackground(ctx context.Context)
Shutdown(ctx context.Context) error
MountRoutes(router *gin.Engine)
GetRelayLink() RelayLink
}
AgentServer Agent 数据面服务器 负责请求中继、配置缓存同步、指标上报等数据面功能
type Application ¶
type Application interface {
GetCoreDB() *gorm.DB
SetCoreDB(*gorm.DB)
GetLogDB() *gorm.DB
SetLogDB(*gorm.DB)
GetDatabaseLayoutMode() DatabaseLayoutMode
SetDatabaseLayoutMode(DatabaseLayoutMode)
GetMasterSettings() *MasterSettingsSnapshot
GetMasterServer() MasterServer
SetMasterServer(MasterServer)
GetHub() Hub
SetHub(Hub)
GetPublisher() Publisher
SetPublisher(Publisher)
GetSettler() Settler
SetSettler(Settler)
GetQuotaChecker() QuotaChecker
SetQuotaChecker(QuotaChecker)
GetAgentServer() AgentServer
SetAgentServer(AgentServer)
GetStore() Store
SetStore(Store)
GetSyncer() Syncer
SetSyncer(Syncer)
GetWSBridge() WSBridge
SetWSBridge(WSBridge)
GetRelayHandler() RelayHandler
SetRelayHandler(RelayHandler)
GetReporter() Reporter
SetReporter(Reporter)
GetEventBus() EventBus
SetEventBus(EventBus)
GetWSClient() WSClient
SetWSClient(WSClient)
}
Application 是整个应用的顶层容器接口 统一管理 Master 和 Agent 侧的所有组件,通过 Get/Set 方法实现依赖注入 LogDB 支持后台 connector 原子替换,MasterSettings 支持运行期原子发布; 其余依赖仅在初始化阶段 Set。
func NewApplication ¶
func NewApplication() Application
type AttemptStream ¶ added in v0.0.14
type AttemptStream interface {
Commit(ctx context.Context) error
Upload(ctx context.Context, src io.Reader) error
CopyAttemptResponse(ctx context.Context, dst http.ResponseWriter) (attemptwire.AttemptProxyResult, error)
CommitState() tunnel.CommitState
Cancel(cause error)
Close() error
}
type AttemptStreamOpener ¶ added in v0.0.14
type AttemptStreamOpener interface {
OpenAttemptStream(context.Context, AttemptStreamRequest) (AttemptStream, error)
}
type AttemptStreamRequest ¶ added in v0.0.14
type BodyLimits ¶ added in v0.0.13
type BodyStore ¶ added in v0.0.13
type BodyStore interface {
Capture(ctx context.Context, src io.Reader, limits BodyLimits) (ReplayBody, error)
}
type Context ¶
type Context struct {
*gin.Context
App Application
UserInfo *UserInfo
Logger *zap.Logger
Settings *config.MasterRuntimeConfig
OwnerContext context.Context
}
Context 承载请求级别的数据和全局共享服务。
func NewContext ¶
func NewContext(c *gin.Context, settings *config.MasterRuntimeConfig, logger *zap.Logger, application Application) *Context
func (*Context) RequestContext ¶ added in v0.0.13
type DatabaseLayoutMode ¶ added in v0.0.14
type DatabaseLayoutMode uint32
DatabaseLayoutMode controls database routing explicitly during the split rollout. The zero value preserves the legacy single-database deployment.
const ( DatabaseLayoutLegacySingle DatabaseLayoutMode = iota DatabaseLayoutSplit )
func (DatabaseLayoutMode) Validate ¶ added in v0.0.14
func (m DatabaseLayoutMode) Validate() error
type EventBus ¶
type EventBus interface {
Publish(ctx context.Context, event eventbus.Event) error
Subscribe(topic string, handler eventbus.EventHandler) (eventbus.Subscription, error)
SubscribePattern(pattern string, handler eventbus.EventHandler) (eventbus.Subscription, error)
Close() error
}
EventBus 事件总线接口 — 所有核心接口的规范定义位于 app 包。
type HTTPAPIProtocolError ¶ added in v0.0.16
func (*HTTPAPIProtocolError) Error ¶ added in v0.0.16
func (e *HTTPAPIProtocolError) Error() string
type HTTPAPIStream ¶ added in v0.0.16
type HTTPAPIStream interface {
Open(context.Context, APIOpen) error
SendRequestData(context.Context, []byte) error
EndRequest(context.Context, tunnel.Trailers) error
Receive(context.Context) (APIResponseEvent, error)
Cancel(cause error)
Close() error
}
HTTPAPIStream is the Source-side consumer contract for one Generic API attempt. Open completes the Tunnel Ready/Commit handshake before request data may be sent. Receive preserves Headers/Data/End/Result wire order.
type HTTPAPIStreamOpener ¶ added in v0.0.16
type HTTPAPIStreamOpener interface {
OpenHTTPAPIStream(context.Context, APIOpen) (HTTPAPIStream, error)
}
type Hub ¶
type Hub interface {
// HandleWS 处理 Agent 的 WebSocket 连接请求
HandleWS(c *gin.Context)
// Call 向指定 Agent 发起 RPC 调用并等待响应
Call(agentID string, method string, params any, timeout time.Duration) (json.RawMessage, error)
// Broadcast 向所有在线 Agent 广播通知
Broadcast(method string, params any)
// GetOnlineAgentIDs 获取所有在线 Agent 的 ID 列表
GetOnlineAgentIDs() []string
// GetRuntime 获取指定 Agent 的运行时信息(心跳、延迟等)
GetRuntime(agentID string) *AgentRuntime
// IsOnline 检查指定 Agent 是否在线
IsOnline(agentID string) bool
// GetAgentAddresses 获取 Agent 的合并地址列表(配置地址 + 自动探测地址)
GetAgentAddresses(agentID string, dbHTTPAddrs string) []AgentAddress
// ConnectedAgents 返回当前在线的 Agent 数量
ConnectedAgents() int
}
Hub WebSocket 连接管理中心 Master 端用于管理所有 Agent 的 WebSocket 连接,支持 RPC 调用、广播和在线状态查询
type MasterServer ¶
type MasterServer interface {
Run() error
Shutdown(ctx context.Context) error
InitAdminUser(username, password string) error
}
MasterServer Master 控制面服务器 负责管理 API、WebSocket Hub、计费结算等控制面功能
type MasterSettingsSnapshot ¶ added in v0.0.15
type MasterSettingsSnapshot struct {
// contains filtered or unexported fields
}
MasterSettingsSnapshot stores master-only settings for request hot paths. Published maps are immutable; readers load one pointer without taking a lock.
func NewMasterSettingsSnapshot ¶ added in v0.0.15
func NewMasterSettingsSnapshot() *MasterSettingsSnapshot
func (*MasterSettingsSnapshot) Lookup ¶ added in v0.0.15
func (s *MasterSettingsSnapshot) Lookup(key string) (string, bool)
func (*MasterSettingsSnapshot) LookupBool ¶ added in v0.0.15
func (s *MasterSettingsSnapshot) LookupBool(key string, fallback bool) bool
func (*MasterSettingsSnapshot) Replace ¶ added in v0.0.15
func (s *MasterSettingsSnapshot) Replace(values map[string]string)
Replace atomically publishes a complete clone of values.
func (*MasterSettingsSnapshot) Update ¶ added in v0.0.15
func (s *MasterSettingsSnapshot) Update(values map[string]string)
Update atomically merges values into the current snapshot. CAS preserves disjoint updates when multiple writers publish concurrently.
type NotificationHandler ¶
NotificationHandler 处理 JSON-RPC 通知的回调函数。
type ProbePolicy ¶ added in v0.0.14
type ProbePolicy = tunnel.ProbePolicy
type ProbeStream ¶ added in v0.0.14
type ProbeStreamOpener ¶ added in v0.0.14
type ProbeStreamOpener interface {
OpenProbeStream(context.Context, ProbeStreamRequest) (ProbeStream, error)
}
type ProbeStreamRequest ¶ added in v0.0.14
type ProbeStreamRequest struct {
TargetAgentID string
RequestID string
Remaining time.Duration
Policy ProbePolicy
}
type Publisher ¶
type Publisher interface {
// Start 启动推送监听
Start()
}
Publisher 配置变更推送器 监听事件总线上的配置变更事件,通过 Hub 将增量更新推送给所有在线 Agent
type QuotaChecker ¶
type QuotaChecker interface {
Start()
}
QuotaChecker 额度检查器 定期检查用户额度使用情况,对超额用户进行处理
type RelayHandler ¶
RelayHandler 请求中继处理器 Agent 端的核心组件,负责接收客户端 API 请求,通过 Codec 转换协议后转发到上游服务商
type RelayLink ¶ added in v0.0.13
type RelayLink interface {
AttemptStreamOpener
ProbeStreamOpener
HTTPAPIStreamOpener
}
type ReplayBody ¶ added in v0.0.13
type Reporter ¶
type Reporter interface {
Start(ctx context.Context) error
Stop()
SetClient(client WSClient)
PendingCount() int
}
Reporter 使用量指标上报器 Agent 端组件,收集 API 请求的使用量数据(token 消耗、模型、耗时等), 批量聚合后通过 WebSocket 上报给 Master
type ResourceCounts ¶ added in v0.0.13
type ResourceCounts struct {
LifecycleWorkers int64
HTTPHandlers int64
AcceptedSockets int64
ControlSessions int64
ControlHandlers int64
ControlSockets int64
RelayCandidates int64
RelayActive int64
RelayDraining int64
RelayStreams int64
CacheLoads int64
CacheRefreshes int64
ReporterWorkers int64
Inflight int64
Timers int64
Transports int64
RelaySockets int64
DirectOutgoingActive int64
DirectOutgoingCandidates int64
DirectOutgoingDraining int64
DirectIncomingActive int64
DirectIncomingCandidates int64
DirectIncomingDraining int64
DirectStreams int64
DirectSockets int64
}
type Settler ¶
type Settler interface {
Start()
Settle(ctx context.Context, agentID string, logs []protocol.UsageLogEntry)
}
Settler 计费结算器 监听 Agent 上报的使用量数据,计算费用并更新用户额度
type Store ¶
type Store interface {
// --- Token 操作 ---
GetToken(ctx context.Context, key string) *models.Token
SetToken(token *models.Token)
DeleteToken(key string)
GetTokenByID(ctx context.Context, id uint) *models.Token
DeleteTokenByID(id uint)
LoadTokens(tokens []models.Token)
TokenCount() int
// --- Channel 操作 ---
GetChannel(id uint) *models.Channel
SetChannel(ch *models.Channel)
DeleteChannel(id uint)
LoadChannels(channels []models.Channel)
ChannelCount() int
// --- ModelConfig 操作 ---
GetModelConfig(modelName string) *models.ModelConfig
SetModelConfig(mc *models.ModelConfig)
DeleteModelConfig(modelName string)
LoadModelConfigs(configs []models.ModelConfig)
ModelConfigCount() int
// --- 模型路由 ---
GetChannelsForModel(model string) []*models.Channel
RebuildModelIndex()
GetAllModelNames() []string
// --- User 操作 ---
GetUser(ctx context.Context, id uint) *protocol.SyncedUser
SetUserQuota(id uint, quota int64) // 更新已缓存 user 的 Quota;不在缓存则忽略
// --- BYOK 私有 channel ---
GetVisiblePrivateChannelsForUser(userID uint, model string) []*protocol.SyncedPrivateChannel
ListVisibleBYOKModelNamesForUser(userID uint) []string // 列举 user 全部 enabled BYOK channel 的 Models 并集(去重)
// --- Agent 操作 ---
GetAgent(agentID string) *models.Agent
SetAgent(agent *models.Agent)
UpdateAgentAutoAddresses(agentID string, addrs []AgentAddress)
DeleteAgent(agentID string)
GetAgentsByTag(tag string) []*models.Agent
GetAllAgents() []*models.Agent
LoadAgents(agents []models.Agent)
AgentCount() int
// --- 版本与设置 ---
Version() int64
SetVersion(v int64)
LoadSettings(s []models.Setting)
Settings() settings.AgentSettings
TraceMaxBodySize() int
FallbackSleepMs() int
// --- 系统 Token ---
GetSystemTestToken() *models.Token
// --- 事件处理 ---
HandleSyncEvent(entity, action string, data []byte)
}
Store 本地配置缓存 Agent 端用于缓存从 Master 同步的 Token、Channel、Model 等配置数据, 支持增量更新和全量加载
type Syncer ¶
type Syncer interface {
SetClient(client WSClient)
FullSync(ctx context.Context) error
SubscribeEvents() error
StartPeriodicCheck(ctx context.Context)
}
Syncer 缓存同步器 负责与 Master 建立连接,拉取全量配置并订阅增量事件,保持本地缓存与 Master 一致
type TransportPool ¶
type TransportPool interface {
Get(ch *models.Channel) *http.Transport
Invalidate(channelID uint, oldProxyURL string)
CloseIdleConnections()
}
TransportPool 抽象 channel → *http.Transport 缓存能力。 让 relay 在多次 upstream 请求间共享连接池,避免每次 new(http.Transport)。
Invalidate 用于 channel.ProxyURL 变更时让旧 transport 失效; server.go 在装配阶段通过 Store.OnChannelChange 回调调用。
type UserInfo ¶
type UserInfo struct {
UserID uint
Username string
DisplayName string // JWT claim ClaimDisplayName,SSO 注册时由 IdP 同步,可空
AvatarURL string // JWT claim ClaimAvatarURL,SSO 注册时由 IdP 同步,可空
Role int
TokenID uint // API Token 认证时填充,JWT 登录时为 0
TokenName string
TraceEnabled bool // Agent 侧:Token 是否开启 trace
TraceMode models.TokenTraceMode // Agent 侧:Token 成功请求的 trace 捕获范围
BYOKOnly bool // Agent 侧:Token 是否限定只用 BYOK/私有渠道
APIRoleMode models.APIRoleMode // Agent 侧:Generic API 权限事实取 Token 还是 User effective RoleSet
TokenModels []string // Agent 侧:Token 允许的模型列表(空表示不限)
AllowedChannelIDs []uint // Agent 侧:Token 允许的频道列表(空表示不限)
// 新增:来自该用户所在 Group
GroupID uint
GroupModels []string
GroupAllowedChannelIDs []uint
}
UserInfo 承载认证用户身份信息,在应用内流转。
type WSBridge ¶
type WSBridge interface {
Start()
}
WSBridge WebSocket 同步桥 监听 WebSocket 连接上的消息,将 Master 推送的增量更新转发给 Store 处理
type WSClient ¶
type WSClient interface {
// OnNotification 注册指定方法的通知回调处理器
OnNotification(method string, handler NotificationHandler)
// Call 发起 RPC 调用并等待响应
Call(ctx context.Context, method string, params any) (json.RawMessage, error)
// Notify 发送单向通知(不等待响应)
Notify(method string, params any) error
// Close 关闭 WebSocket 连接
Close() error
// ReadLoop 启动消息读取循环(通常在 goroutine 中运行)
ReadLoop()
}
WSClient WebSocket 客户端 封装 WebSocket 连接,提供 JSON-RPC 风格的 Call(请求-响应)和 Notify(单向通知)能力
type WSConn ¶
type WSConn interface {
// SendNotification 向客户端发送 JSON-RPC 通知
SendNotification(method string, params any) error
// SendResponse 向客户端发送 JSON-RPC 响应
SendResponse(resp *jsonrpc.Response) error
// ReadMessage 读取一条消息,区分请求和响应
ReadMessage() (*jsonrpc.Request, *jsonrpc.Response, error)
// WriteJSON 发送任意 JSON 数据
WriteJSON(v any) error
// Close 关闭连接
Close() error
// Done 返回连接关闭的通知 channel
Done() <-chan struct{}
}
WSConn WebSocket 服务端连接 封装单个 WebSocket 连接的服务端视角,提供消息读写和生命周期管理
type WebSocketAPIStream ¶ added in v0.0.16
type WebSocketAPIStream interface {
Open(context.Context, WebSocketOpen) (WebSocketAccepted, error)
ProviderAcceptance() WebSocketAccepted
SendEvent(context.Context, WebSocketEvent) error
ReceiveEvent(context.Context) (WebSocketEvent, error)
ReceiveResult(context.Context) (apiattempt.APIExecutionResult, error)
Close() error
}
WebSocketAPIStream is the source-side transport contract for one Generic API WebSocket. Events preserve message boundaries; data events may be fragmented at the negotiated tunnel data limit.
type WebSocketAPIStreamOpener ¶ added in v0.0.16
type WebSocketAPIStreamOpener interface {
OpenWebSocketAPIStream(context.Context, WebSocketOpen) (WebSocketAPIStream, error)
}
type WebSocketAccepted ¶ added in v0.0.16
type WebSocketAccepted = tunnel.WebSocketAccepted
type WebSocketEvent ¶ added in v0.0.16
type WebSocketEvent = tunnel.WebSocketEvent
type WebSocketEventKind ¶ added in v0.0.16
type WebSocketEventKind = tunnel.WebSocketEventKind
type WebSocketExecutionError ¶ added in v0.0.16
type WebSocketExecutionError struct {
Result apiattempt.APIExecutionResult
Err error
}
func (*WebSocketExecutionError) Error ¶ added in v0.0.16
func (e *WebSocketExecutionError) Error() string
func (*WebSocketExecutionError) Unwrap ¶ added in v0.0.16
func (e *WebSocketExecutionError) Unwrap() error
type WebSocketOpen ¶ added in v0.0.16
type WebSocketRejection ¶ added in v0.0.16
type WebSocketRejection = tunnel.WebSocketRejection