Documentation
¶
Index ¶
- Constants
- func AgentAuth(agentSvc *service.AgentTokenService) gin.HandlerFunc
- func AgentCallLatencyMs(c *gin.Context) uint
- func Audit(cfg AuditConfig) gin.HandlerFunc
- func ClientDistGuard(guard ClientDistGuardChecker, ratePerSecond, burst, maxConcurrent int) gin.HandlerFunc
- func ErrorLog() gin.HandlerFunc
- func GetAgentClient(c *gin.Context) string
- func GetAgentPrincipal(c *gin.Context) *service.AgentPrincipal
- func JWTAuth(secret string) gin.HandlerFunc
- func LoadAccess(authz *service.AuthzService) gin.HandlerFunc
- func RateLimit(ratePerSecond, capacity int) gin.HandlerFunc
- func RequireAnyPerm(nodes ...string) gin.HandlerFunc
- func RequireGroupAccess() gin.HandlerFunc
- func RequireGroupManage() gin.HandlerFunc
- func RequireInstanceAccess(authz *service.AuthzService) gin.HandlerFunc
- func RequireInstanceManage(authz *service.AuthzService) gin.HandlerFunc
- func RequirePerm(node string) gin.HandlerFunc
- func RequirePermission(node service.PermissionNode) gin.HandlerFunc
- func RequireRole(minRole model.UserRole) gin.HandlerFunc
- type AuditConfig
- type ClientDistGuardChecker
- type RateLimiter
Constants ¶
const ( CtxAgentPrincipal = "agentPrincipal" CtxActorKind = "actorKind" // "user" | "agent" // CtxAgentClient 解析后的调用方（mcp|jmagent|curl|unknown），FR-390。 CtxAgentClient = "agentClient" // CtxAgentCallStart 请求开始时间，供流水 latency_ms。 CtxAgentCallStart = "agentCallStart" )
Context keys for agent principal。
const ( CtxUserID = "userId" CtxUsername = "username" CtxRole = "role" CtxAuthVersion = "authVersion" CtxAccess = "access" )
Context keys。
const HeaderAgentClient = "X-JM-Agent-Client"
HeaderAgentClient 客户端自报标识头（FR-390 约定）。
Variables ¶
This section is empty.
Functions ¶
func AgentAuth ¶ added in v0.20.0
func AgentAuth(agentSvc *service.AgentTokenService) gin.HandlerFunc
AgentAuth 可选：若 Bearer 以 jmat_ 开头则走 Agent Token 鉴权，成功后注入 principal 并跳过 JWT。 与 JWTAuth 组合使用：先 AgentAuth（成功则 c.Next 且已 abort 跳过后续 JWT 的写法见 AgentOrJWT）。 鉴权成功后解析 X-JM-Agent-Client 写入上下文（401 不写库，由 Ops 层 Record）。
func AgentCallLatencyMs ¶ added in v0.20.0
AgentCallLatencyMs 自鉴权成功起的耗时毫秒；无起点返回 0。
func ClientDistGuard ¶
func ClientDistGuard(guard ClientDistGuardChecker, ratePerSecond, burst, maxConcurrent int) gin.HandlerFunc
ClientDistGuard 面向玩家分发端点的 L7 防护中间件（FR-096，见 ADR-023）： ① IP 黑白名单（命中拒 → 403）② per-IP 令牌桶限流（超频 → 429）③ 全局并发信号量（满 → 429）。 限流以 **IP 为主键**（机器码不可信，ADR-023）；命中拦截累加计数器（可观测、不写库）。 L3/L4 容量型 DDoS 不在此（靠 CDN/云清洗）。
func ErrorLog ¶
func ErrorLog() gin.HandlerFunc
ErrorLog API 错误统一落平台日志（FR-320）：4xx 业务拒绝记 warn、5xx 记 error， 附路径/状态码/响应体/用户/IP——经 log_slog 桥自动进日志中心 platform 源， 用户在 /logs 页即可追查「某个操作为什么报错」（此前错误只回 HTTP 响应，平台日志恒空）。 401（token 过期常态）/404（探路噪音）/429（限流自身会刷）跳过，避免淹没真问题。
func GetAgentClient ¶ added in v0.20.0
GetAgentClient 取解析后的 client 标识；缺省 unknown。
func GetAgentPrincipal ¶ added in v0.20.0
func GetAgentPrincipal(c *gin.Context) *service.AgentPrincipal
GetAgentPrincipal 从上下文取 agent 主体。
func LoadAccess ¶
func LoadAccess(authz *service.AuthzService) gin.HandlerFunc
LoadAccess 加载当前用户的授权上下文并写入 gin.Context(CtxAccess)。 必须在 JWTAuth 之后执行。参见 ADR-004: 用户组替代多租户。
func RateLimit ¶
func RateLimit(ratePerSecond, capacity int) gin.HandlerFunc
RateLimit 限流中间件。 按 IP 限流，默认 60 请求/分钟，桶容量 10。
func RequireAnyPerm ¶ added in v0.22.0
func RequireAnyPerm(nodes ...string) gin.HandlerFunc
RequireAnyPerm 要求命中任一权限节点；平台管理员始终放行。
func RequireGroupAccess ¶
func RequireGroupAccess() gin.HandlerFunc
RequireGroupAccess 要求当前用户能访问路径参数 :id 指定的用户组。 平台管理员全量放行；否则必须属于该组（成员或组管理员）。
func RequireGroupManage ¶
func RequireGroupManage() gin.HandlerFunc
RequireGroupManage 要求当前用户能管理路径参数 :id 指定的用户组（组管理员或平台管理员）。
func RequireInstanceAccess ¶
func RequireInstanceAccess(authz *service.AuthzService) gin.HandlerFunc
RequireInstanceAccess 要求当前用户能访问路径参数 :id 指定的实例。 平台管理员全量放行；否则实例必须归属于其可访问的组。
func RequireInstanceManage ¶
func RequireInstanceManage(authz *service.AuthzService) gin.HandlerFunc
RequireInstanceManage 要求当前用户能管理（写/删除）路径参数 :id 指定的实例。
func RequirePerm ¶ added in v0.22.0
func RequirePerm(node string) gin.HandlerFunc
RequirePerm 要求权限树节点（FR-432 / ADR-089）。 平台管理员始终放行；其余用户按 UserAccess.Nodes 判断。
func RequirePermission ¶
func RequirePermission(node service.PermissionNode) gin.HandlerFunc
RequirePermission 要求当前用户拥有指定权限节点。 平台管理员拥有全部权限；其余角色按 HasPermission 判断，资源级隔离由后续中间件收敛。
func RequireRole ¶
func RequireRole(minRole model.UserRole) gin.HandlerFunc
RequireRole 要求最低角色等级的中间件。
Types ¶
type AuditConfig ¶
type AuditConfig struct {
// RecordFunc 记录审计日志的回调函数。
// success/errMsg：操作结果（FR-321）——失败操作也留痕并带错误内容（响应 error body 截断）。
RecordFunc func(userID uint, action, targetType, targetID, detail, ip string, success bool, errMsg string)
}
AuditConfig 审计中间件配置。
type ClientDistGuardChecker ¶
type ClientDistGuardChecker interface {
// Allowed 报告 IP 是否放行（黑白名单）。
Allowed(ip string) bool
// MarkDeny / MarkRate / MarkConcurrency 累加防护拦截计数（可观测）。
MarkDeny()
MarkRate()
MarkConcurrency()
}
ClientDistGuardChecker 客户端分发端点 IP 防护检查（FR-096，由 service.ClientIPGuardService 实现）。 以接口注入避免 middleware → service 依赖。
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter 令牌桶限流器。
func NewRateLimiter ¶
func NewRateLimiter(ratePerSecond, capacity int) *RateLimiter
NewRateLimiter 创建限流器。
Source Files