backend/.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/Yggdrasil协议API.md

Yggdrasil协议API

**本文档引用的文件** - [routes.go](file://internal/handler/routes.go) - [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go) - [yggdrasil_service.go](file://internal/service/yggdrasil_service.go) - [yggdrasil_repository.go](file://internal/repository/yggdrasil_repository.go) - [yggdrasil.go](file://internal/model/yggdrasil.go) - [token.go](file://internal/model/token.go) - [user_service.go](file://internal/service/user_service.go) - [profile_service.go](file://internal/service/profile_service.go) - [profile_repository.go](file://internal/repository/profile_repository.go) - [jwt.go](file://pkg/auth/jwt.go)

目录

1. 简介
2. Yggdrasil路由结构
3. 认证服务API
4. 会话服务API
5. 档案服务API
6. 与Minecraft客户端交互流程
7. 内部用户系统集成
8. 错误处理
9. 元数据与证书

简介

Yggdrasil协议是Minecraft客户端认证的核心接口，本系统实现了完整的Yggdrasil协议集成，为Minecraft玩家提供认证、会话管理和档案查询服务。该实现通过/yggdrasil路由组暴露标准API端点，与Minecraft客户端无缝对接，同时将Yggdrasil请求映射到系统的内部用户体系。

Section sources

• routes.go

Yggdrasil路由结构

系统在/api/v1/yggdrasil路径下提供了完整的Yggdrasil协议支持，包含三个主要子路由组：authserver、sessionserver和profiles，分别处理认证、会话和档案相关请求。

graph TB
Yggdrasil[Yggdrasil根路由 /yggdrasil]
subgraph AuthServer
Authenticate[POST /authserver/authenticate]
Validate[POST /authserver/validate]
Refresh[POST /authserver/refresh]
Invalidate[POST /authserver/invalidate]
SignOut[POST /authserver/signout]
end
subgraph SessionServer
GetProfile[GET /sessionserver/session/minecraft/profile/:uuid]
JoinServer[POST /sessionserver/session/minecraft/join]
HasJoined[GET /sessionserver/session/minecraft/hasJoined]
end
subgraph Profiles
GetProfilesByName[POST /api/profiles/minecraft]
end
Yggdrasil --> Authenticate
Yggdrasil --> Validate
Yggdrasil --> Refresh
Yggdrasil --> Invalidate
Yggdrasil --> SignOut
Yggdrasil --> GetProfile
Yggdrasil --> JoinServer
Yggdrasil --> HasJoined
Yggdrasil --> GetProfilesByName

**Diagram sources **

• routes.go

Section sources

• routes.go

认证服务API

认证服务API位于/yggdrasil/authserver路径下，提供用户认证和令牌管理功能。

authenticate

用户认证端点，用于验证用户凭据并获取访问令牌。

• 方法: POST
• 路径: /yggdrasil/authserver/authenticate
• 请求体:

  {
    "username": "用户邮箱或用户名",
    "password": "密码",
    "clientToken": "客户端令牌"
  }
  

• 响应:
  • 200: 返回包含accessToken、availableProfiles和selectedProfile的认证响应
  • 403: 认证失败

Section sources

• yggdrasil_handler.go
• yggdrasil_service.go

validate

验证访问令牌的有效性。

• 方法: POST
• 路径: /yggdrasil/authserver/validate
• 请求体:

  {
    "accessToken": "访问令牌"
  }
  

• 响应:
  • 204: 令牌有效
  • 403: 令牌无效

Section sources

• yggdrasil_handler.go
• yggdrasil_service.go

refresh

刷新访问令牌，延长会话有效期。

• 方法: POST
• 路径: /yggdrasil/authserver/refresh
• 请求体:

  {
    "accessToken": "当前访问令牌",
    "clientToken": "客户端令牌",
    "selectedProfile": "选定的档案"
  }
  

• 响应:
  • 200: 返回新的accessToken和selectedProfile
  • 400: 刷新失败

Section sources

• yggdrasil_handler.go
• yggdrasil_service.go

invalidate

使访问令牌失效。

• 方法: POST
• 路径: /yggdrasil/authserver/invalidate
• 请求体:

  {
    "accessToken": "要使失效的令牌"
  }
  

• 响应:
  • 204: 成功使令牌失效

Section sources

• yggdrasil_handler.go
• yggdrasil_service.go

signout

用户登出，使该用户的所有令牌失效。

• 方法: POST
• 路径: /yggdrasil/authserver/signout
• 请求体:

  {
    "username": "用户邮箱",
    "password": "密码"
  }
  

• 响应:
  • 204: 登出成功

Section sources

• yggdrasil_handler.go
• yggdrasil_service.go

会话服务API

会话服务API位于/yggdrasil/sessionserver路径下，管理玩家与服务器的会话。

JoinServer

记录玩家加入服务器的会话信息。

• 方法: POST
• 路径: /yggdrasil/sessionserver/session/minecraft/join
• 请求体:

  {
    "accessToken": "访问令牌",
    "selectedProfile": "选定的档案UUID",
    "serverId": "服务器ID"
  }
  

• 响应:
  • 204: 加入成功
  • 500: 加入失败

sequenceDiagram
participant Client as "Minecraft客户端"
participant SessionServer as "会话服务"
participant Redis as "Redis存储"
Client->>SessionServer : POST /join
SessionServer->>SessionServer : 验证accessToken
SessionServer->>SessionServer : 验证selectedProfile
SessionServer->>Redis : 存储会话数据
Redis-->>SessionServer : 存储成功
SessionServer-->>Client : 204 No Content

**Diagram sources **

• yggdrasil_handler.go
• yggdrasil_service.go

Section sources

• yggdrasil_handler.go
• yggdrasil_service.go

HasJoinedServer

验证玩家是否已加入指定服务器。

• 方法: GET
• 路径: /yggdrasil/sessionserver/session/minecraft/hasJoined
• 查询参数:
  • serverId: 服务器ID
  • username: 用户名
  • ip: IP地址（可选）
• 响应:
  • 200: 返回玩家档案信息
  • 204: 未加入或验证失败

Section sources

• yggdrasil_handler.go
• yggdrasil_service.go

档案服务API

档案服务API提供玩家档案查询功能。

GetProfileByUUID

根据UUID获取玩家档案。

• 方法: GET
• 路径: /yggdrasil/sessionserver/session/minecraft/profile/:uuid
• 响应:
  • 200: 返回玩家档案信息
  • 500: 获取失败

Section sources

• yggdrasil_handler.go
• profile_service.go

GetProfilesByName

根据用户名批量获取玩家档案。

• 方法: POST
• 路径: /yggdrasil/api/profiles/minecraft
• 请求体: 用户名数组

  ["player1", "player2"]
  

• 响应: 返回匹配的档案列表

Section sources

• yggdrasil_handler.go
• profile_repository.go

与Minecraft客户端交互流程

Minecraft客户端与Yggdrasil服务的完整交互流程如下：

sequenceDiagram
participant Client as "Minecraft客户端"
participant AuthServer as "认证服务"
participant SessionServer as "会话服务"
participant ProfileServer as "档案服务"
Client->>AuthServer : authenticate(邮箱/用户名, 密码)
AuthServer-->>Client : accessToken, availableProfiles
Client->>SessionServer : join(serverId, accessToken, selectedProfile)
SessionServer-->>Client : 204
Client->>ProfileServer : hasJoined(serverId, username)
ProfileServer-->>Client : 玩家档案
Client->>ProfileServer : getProfile(uuid)
ProfileServer-->>Client : 档案详情

**Diagram sources **

• yggdrasil_handler.go
• yggdrasil_service.go

内部用户系统集成

Yggdrasil实现与系统内部用户体系的集成通过以下方式完成：

用户映射

系统通过Yggdrasil模型将Yggdrasil协议的密码认证与内部用户ID关联。当用户注册时，系统自动生成一个16位随机密码与用户ID绑定。

classDiagram
class User {
+int64 ID
+string Username
+string Email
+string Password
}
class Yggdrasil {
+int64 ID
+string Password
}
User --> Yggdrasil : "1对1关联"

**Diagram sources **

• yggdrasil.go
• user_service.go

Section sources

• yggdrasil.go
• user_service.go

令牌管理

系统使用Token模型管理访问令牌，将accessToken与userID、profileId关联，实现会话状态管理。

classDiagram
class Token {
+string AccessToken
+int64 UserID
+string ProfileId
+bool Usable
}
class Profile {
+string UUID
+int64 UserID
+string Name
}
Token --> Profile : "关联档案"
Token --> User : "关联用户"

**Diagram sources **

• token.go
• yggdrasil_service.go

Section sources

• token.go
• yggdrasil_service.go

错误处理

系统实现了标准化的错误处理机制，所有Yggdrasil端点返回一致的错误响应格式。

常见错误代码

HTTP状态码	错误类型	描述
400	Bad Request	请求格式无效
403	Forbidden	认证失败或权限不足
404	Not Found	资源未找到
500	Internal Server Error	服务器内部错误

错误响应示例

{
  "error": "密码错误"
}

Section sources

• yggdrasil_handler.go

元数据与证书

系统提供元数据和玩家证书服务，支持Minecraft客户端的高级功能。

GetMetaData

获取服务元数据。

• 方法: GET
• 路径: /yggdrasil
• 响应: 包含实现信息、链接和功能标志

Section sources

• yggdrasil_handler.go

GetPlayerCertificates

获取玩家证书。

• 方法: POST
• 路径: /yggdrasil/minecraftservices/player/certificates
• 认证: Bearer Token
• 响应: 包含玩家公钥证书

Section sources

• yggdrasil_handler.go
• profile_service.go