GoWind Admin｜风行 — 开箱即用的企业级全栈中后台框架：AK/SK 机器凭证

GoWind Admin｜风行 --- 开箱即用的企业级全栈中后台框架：AK/SK 机器凭证

管理系统的账号是人用的。但当监控平台要拉数据、CI 流水线要触发任务、第三方系统要对接时，团队最常见的做法是把管理员账号密码写进对方的配置文件------这是一次凭据泄漏事故的预约：密码改一轮就得通知所有对接方、那个人还有正常登录和会话、泄漏了都不知道从哪漏的。风行（GoWind Admin）提供 AK/SK 机器凭证体系：给"系统对系统"的调用发独立身份，人机分治、各自设防。

一、模型：机器是机器，人是人

AK/SK（Access Key / Secret Key）与云厂商开放 API 的凭证同构，任何对接过 AWS/阿里云 API 的开发者零学习成本：

要素	设计
AK	公开标识，`ak-` 前缀 + 16 字符随机 hex，列表页明文可见（用来认身份，不用来证明身份）
SK	私密密钥，`sk-` 前缀 + 64 字符高熵 hex，只在创建/重置的响应里出现一次，服务端只存 SHA-256 摘要
归属	凭证归属于创建者的租户------机器令牌继承该租户的隔离与闸门
生命周期	状态启停（立即生效）、过期时间（到期自动拒）、最近使用时间（闲置凭证一眼可见）

机器凭证据此换取租户作用域的机器 JWT，随后与人用令牌走同一套鉴权中间件访问业务 API。三条人机分治的硬边界：

机器令牌 userId=0------没有用户行、不进会话管理、不出现在在线用户列表；
机器令牌只签 access、不签 refresh------凭证按需重新交换，没有"长期续命"的会话，泄漏影响面被压缩到单个 access 的 TTL 之内；
机器令牌照常受租户隔离、Api 表闸门、登录/API 审计的完整约束------它不是绕过体系的后门，而是体系内的另一种主体。

管理面「系统管理 → OpenAPI 凭证」：AK 列表、启停开关、过期时间、最近使用、一键重置密钥------云厂商控制台那套凭证管理体验，平移进你的系统。

二、交换协议：把"校验一个密钥"做对

令牌交换端点免登录态（AK/SK 本身即凭据），防护链五步：

text 复制代码

POST /admin/v1/access-keys/token
  1 限流预检    IP + AK 双维度 Redis 计数（复用登录限流器），锁定中直接 400
  2 查 AK 行    SystemViewer 通道跨租户读；不存在与密钥错误返回统一文案（防枚举）
  3 状态闸      停用 → 拒；过期 → 拒
  4 密钥比对    请求方经 HTTPS 传 SK 明文，服务端计算 SHA-256 后
               subtle.ConstantTimeCompare 恒定时间比对------响应时间不随匹配程度变化，
               时序侧信道无从下手；比对失败计入限流
  5 签发        清限流计数 → 签发机器 JWT（userId=0、tid=AK 归属租户、
               roles=["machine"]）入缓存 → best-effort 刷新最近使用时间
               （不阻塞响应）

完整对接只要两步：

bash 复制代码

# 1. 交换令牌
curl -X POST https://api.example.com/admin/v1/access-keys/token \
  -H "Content-Type: application/json" \
  -d '{ "accessKey": "ak-3f9c2b81a4d5e670", "secret": "sk-8f14e45fceea167a5a36dedd4bea2543" }'
# => { "accessToken": "eyJhbGci...", "tokenType": "bearer", "expiresIn": 5400 }

# 2. 携带机器 JWT 调用业务 API（租户闸门、权限、审计照常生效）
curl https://api.example.com/admin/v1/users \
  -H "Authorization: Bearer eyJhbGci..."

三、安全设计背后的五个决策

**1. SK 明文不落库。**库里只有 SHA-256 摘要。拖库者拿不到可用密钥；SK 只在创建/重置那一刻存在，之后谁也找不回来------丢了就重置，这是云凭证世界的标准契约。

**2. 恒定时间比对。**普通字符串比较在第一个不匹配字节处返回，攻击者可以靠测量响应时间逐字节猜出摘要。subtle.ConstantTimeCompare 无论几位匹配耗时恒定，这条侧信道从根上关死。

3. 统一文案 + 双维限流。"AK 不存在"与"密钥错误"同文案------攻击者无法批量探测有效 AK；IP + AK 双维计数让"分布式爆破单个 AK"与"单机扫库"都被同一道闸拦住。

**4. AK 与摘要不可变，密钥只能整体轮换。**更新接口的黑名单里，AK 与摘要两个路径不可写------凭据的核心标识不可篡改，轮换走重置密钥：生成新 SK、替换摘要，旧 SK 的交换立即被阻断（摘要已变），已签出的机器令牌在各自过期前自然消亡------轮换语义清晰：立刻断新令牌，存量短窗自然收敛。

**5. 机器身份默认没有权限。**机器令牌的角色是 machine，授权语义随引擎配置：默认 noop 引擎放行（开发期）；切换 Casbin/OPA 后，机器身份无显式策略 = fail-closed 拒绝------要给某个 AK 开接口面，须逐条审阅后显式配策略。机器凭据面向自动化调用方，权限面不该继承"管理员能用的它都能用"。

四、纵深：凭证表本身也在隔离体系内

AK 管理数据自身并不特殊：sys_access_keys 挂着与全部 33 张租户表相同的双防线（数据层租户谓词 + 仓内变更守卫），跨租户的凭证篡改 0 行命中，且有单测钉住防线不回退。管理凭证的能力本身受 RBAC 权限点控制------"谁能发凭证"与"凭证能干什么"是两个独立的权限面。

结语

系统对接的成熟度，是企业级产品的隐形分水岭。共享管理员账号是野路子，自研临时 token 是欠账，AK/SK + 租户作用域机器 JWT + 恒定时间比对 + fail-closed 授权，才是能写进安全问卷的答案。风行把它做成了开箱能力：管理页发凭证、两步完成对接、授权逐条审阅。

项目地址 ：github.com/tx7do/go-wi... / gitee.com/tx7do/go-wi...

在线演示 ：demo.admin.gowind.cloud（前端）/ api.demo.admin.gowind.cloud/docs/（后端 Swagger）