GoWVP 开发者鉴权方案指南本文档面向系统集成开发者与前端开发者详细介绍 GoWVPOWL提供的三种接口鉴权机制、设计原理、配置方式及调用示例。1. 鉴权方案概览GoWVP 支持以下三种鉴权模式三种模式在网关中间件中无缝协同、层层兜底鉴权方案凭据形态时效性权限等级核心适用场景APISecret 静态秘钥固定字符串永久有效直至配置变更默认管理员admin外部系统集成、自动化脚本、后台监控、长期微服务通信JWT 动态令牌三段式 Base64 签名串动态过期默认3天按登录身份签发Web 前端用户登录、管理控制台、交互式客户端第三方 AuthURL透传原始 Header/Body由第三方服务判定由第三方服务控制企业已有 SSO 单点登录、统一认证中心、集中权限网关2. 鉴权流程与决策链路当客户端向受保护接口发起请求时中间件遵循**“静态优先、动态验签、远程兜底”**的过滤机制客户端请求 (Header: Authorization / Query: token) │ ▼ 提取 tokenStr (剥离可选 Bearer 前缀) │ ▼ [配置了 APISecret 且凭据完全匹配?] ├── 是 ──► 注入管理员上下文 (usernameadmin, roleadmin) ──► 放行 (200) └── 否 │ ▼ [凭据为 Bearer 前缀且 JWT 解析成功?] ├── 成功 ──► 注入 JWT Claims ──► 放行 (200) ├── 过期 ──► 直接拦截 (401 Token Expired, 要求重新登录) └── 失败 │ ▼ [是否配置了第三方 AuthURL?] ├── 是 ──► 原样透传 Header 与 Body 至远程鉴权服务 │ ├── 远程返回 200 ──► 放行 │ └── 远程返回非 200 ──► 原样透传远程响应状态与内容 └── 否 ──► 拦截 (401 身份验证失败)关键设计优势零性能损耗APISecret 采用crypto/subtle.ConstantTimeCompare常数时间比对既规避了时序侧信道攻击又无需执行耗时的 Base64 解码与数字验签高频 API 调用耗时仅纳秒级。长短互补日常开发管理使用 JWT 保证会话时效安全性后端脚本或跨节点同步使用 APISecret避免定时轮询刷新 Token 的复杂心跳逻辑。接口调用一致性无论使用哪种鉴权方式均支持标准的 HTTPAuthorization: Bearer token头部调用方无须更改请求头封装。3. 方案详解与调用示例方案一APISecret 永久秘钥鉴权适用于自动化巡检、Prometheus 指标拉取、流媒体节点纳管、外部业务系统服务端调用。1. 规约与格式密钥仅允许由数字、大小写字母、下划线组成。长度限制1 ~ 32 位。系统在每次启动时会自动校验此配置项若配置为空系统将自动生成 32 位无连字符 UUID并持久化回写至config.toml若配置了非法字符或超长系统会打印 WARN 警告日志并自动重新生成合规的 32 位秘钥覆盖持久化。2. 配置文件 (configs/config.toml)[Server.HTTP] # 永久 API 秘钥替代 JWT 鉴权 APISecret my_secure_api_secret_20263. 调用方式支持两种传参途径Header 方式推荐curl-HAuthorization: Bearer my_secure_api_secret_2026http://127.0.0.1:15123/debug/sip/memoryURL Query 方式适合浏览器直连、播放器拉流或轻量 Webhookcurlhttp://127.0.0.1:15123/debug/sip/memory?tokenmy_secure_api_secret_2026方案二JWT 动态令牌鉴权适用于 Web 管理控制台、App 客户端等需要用户登录交互的场景。1. 获取令牌调用系统登录接口获取 JWT Tokencurl-XPOST http://127.0.0.1:15123/api/v1/user/login\-HContent-Type: application/json\-d{username: admin, password: your_password}响应体示例{reason:OK,msg:success,details:[],trace_id:0191e4b3-a123-74b8-8c12-3456789abcde,data:{token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...,user:admin}}2. 调用受保护接口在请求头中携带 Tokencurl-HAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...http://127.0.0.1:15123/app/network/subnets3. 过期与鉴权失败处理当 Token 超过签发有效期默认 3 天时接口会直接返回 401 统一错误响应{reason:ErrUnauthorizedToken,msg:请重新登录,details:[],trace_id:0191e4b3-a123-74b8-8c12-3456789abcde}若未传递凭证或凭据非法且无第三方鉴权服务兜底时接口返回{reason:ErrUnauthorizedToken,msg:身份验证失败,details:[],trace_id:0191e4b3-a123-74b8-8c12-3456789abcde}此时客户端需重新发起登录换取新 Token。方案三第三方 AuthURL 转发鉴权适用于企业内部已有统一账号与权限体系如 OAuth2、CAS、统一网关服务希望将 GoWVP 的鉴权委托给自研鉴权服务。1. 配置文件 (configs/config.toml)[Server.HTTP] # 填写第三方鉴权服务的 HTTP 地址留空表示不启用 AuthURL http://auth.internal.company.com/verify2. 工作原理当客户端发起的请求未命中 APISecret且未通过系统原生 JWT 验签时中间件将原始 HTTP 请求的所有 Header 与 Body 原样 POST 转发给AuthURL。规则裁决若第三方鉴权服务返回 HTTP 状态码200 OKGoWVP 判定鉴权通过继续执行接口逻辑若第三方服务返回其他状态码如 401、403、500 等GoWVP 直接将该响应状态码和响应体原样输出给客户端。4. 多语言代码集成示例Pythonimportrequests# 方式一使用 APISecretheaders{Authorization:Bearer my_secure_api_secret_2026}resprequests.get(http://127.0.0.1:15123/app/network/subnets,headersheaders)print(resp.json())# 方式二URL Query 传参resp_queryrequests.get(http://127.0.0.1:15123/app/network/subnets?tokenmy_secure_api_secret_2026)print(resp_query.json())Gopackagemainimport(fmtionet/http)funcmain(){client:http.Client{}req,_:http.NewRequest(GET,http://127.0.0.1:15123/app/network/subnets,nil)req.Header.Set(Authorization,Bearer my_secure_api_secret_2026)resp,err:client.Do(req)iferr!nil{panic(err)}deferresp.Body.Close()body,_:io.ReadAll(resp.Body)fmt.Println(string(body))}JavaScript / TypeScript (Fetch)constAPI_URLhttp://127.0.0.1:15123/app/network/subnets;constAPI_SECRETmy_secure_api_secret_2026;asyncfunctionfetchSubnets(){constresponseawaitfetch(API_URL,{method:GET,headers:{Authorization:Bearer${API_SECRET}}});constdataawaitresponse.json();console.log(data);}5. 安全最佳实践生产环境秘钥保护APISecret 具备全站最高管理员权限且永不过期严禁提交到开源仓库或前端代码中。结合 HTTPS / 反向代理建议在生产环境中通过 Nginx 启用 HTTPS避免明文 HTTP 传输导致网络窃听。内外网隔离若对外暴露接口建议限制 APISecret 仅在受信任的内网 IP 段使用或在反向代理层限制特定路径。