API 认证

disaster-server 使用 JWT 保护业务 API。生产环境下，/apis 和 /api 路由会启用 JWT 中间件；dev 环境可能关闭认证以便本地调试。

公开端点

端点	说明
GET /healthz	健康检查
GET /readyz	就绪检查
POST /login	登录并获取 access token 和 refresh token
POST /refresh_token	使用 refresh token 换取新的 access token
GET /openapi.yaml	Swagger 启用时提供 OpenAPI YAML
GET /openapi.json	Swagger 启用时提供 OpenAPI JSON
GET /swagger/	Swagger UI

登录

POST /login
Content-Type: application/json

{
  "username": "admin",
  "password": "Softc@1024"
}

该密码只适用于首次创建或补齐管理员账号的全新环境。已有环境的管理员密码保存在 disaster-system/disaster-server-users Secret 中，升级服务不会自动覆盖；部署后应立即通过用户管理接口修改为环境专用密码。

成功响应包含：

{
  "code": 0,
  "data": {
    "accessToken": "<jwt>",
    "refreshToken": "<jwt>",
    "expire": "2026-05-15T12:00:00+08:00",
    "userid": 1,
    "username": "admin"
  }
}

调用业务 API

Authorization: Bearer <accessToken>

示例：

curl -H "Authorization: Bearer ${TOKEN}" \
  http://<server>/apis/disasterinstances.testudo.softcdata.com/v1/instances

刷新 token

POST /refresh_token
Content-Type: application/json

{
  "refreshToken": "<refreshToken>"
}

当前实现返回新的 access token，不轮换 refresh token。

Watch / WebSocket token

Watch 或 WebSocket 客户端可以通过三种方式传 token：

方式	说明
Authorization: Bearer <token>	推荐方式
Sec-WebSocket-Protocol: <token>	WebSocket 客户端受 header 限制时使用
?token=<token>	兼容部分 EventSource/WebSocket 客户端

如果 token 包含不适合放入 Sec-WebSocket-Protocol 的字符，应使用 query 参数或标准 Authorization header。

生产建议

• 替换默认 JWT secret。
• 首次登录后立即修改内置 admin 用户的默认密码。
• 通过 HTTPS 或受控内网访问 API。
• 避免在日志、URL、截图中泄漏 token。
• 对 refresh token 设置合理过期时间。
• 将 OpenAPI/Swagger 页面放在受控网络内。