386 lines
11 KiB
Markdown
386 lines
11 KiB
Markdown
# Yggdrasil协议API
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [Yggdrasil路由结构](#yggdrasil路由结构)
|
||
3. [认证服务API](#认证服务api)
|
||
4. [会话服务API](#会话服务api)
|
||
5. [档案服务API](#档案服务api)
|
||
6. [与Minecraft客户端交互流程](#与minecraft客户端交互流程)
|
||
7. [内部用户系统集成](#内部用户系统集成)
|
||
8. [错误处理](#错误处理)
|
||
9. [元数据与证书](#元数据与证书)
|
||
|
||
## 简介
|
||
Yggdrasil协议是Minecraft客户端认证的核心接口，本系统实现了完整的Yggdrasil协议集成，为Minecraft玩家提供认证、会话管理和档案查询服务。该实现通过`/yggdrasil`路由组暴露标准API端点，与Minecraft客户端无缝对接，同时将Yggdrasil请求映射到系统的内部用户体系。
|
||
|
||
**Section sources**
|
||
- [routes.go](file://internal/handler/routes.go#L87-L111)
|
||
|
||
## Yggdrasil路由结构
|
||
系统在`/api/v1/yggdrasil`路径下提供了完整的Yggdrasil协议支持，包含三个主要子路由组：`authserver`、`sessionserver`和`profiles`，分别处理认证、会话和档案相关请求。
|
||
|
||
```mermaid
|
||
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](file://internal/handler/routes.go#L87-L111)
|
||
|
||
**Section sources**
|
||
- [routes.go](file://internal/handler/routes.go#L87-L111)
|
||
|
||
## 认证服务API
|
||
认证服务API位于`/yggdrasil/authserver`路径下，提供用户认证和令牌管理功能。
|
||
|
||
### authenticate
|
||
用户认证端点，用于验证用户凭据并获取访问令牌。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/authserver/authenticate`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"username": "用户邮箱或用户名",
|
||
"password": "密码",
|
||
"clientToken": "客户端令牌"
|
||
}
|
||
```
|
||
- **响应**:
|
||
- 200: 返回包含`accessToken`、`availableProfiles`和`selectedProfile`的认证响应
|
||
- 403: 认证失败
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L156-L246)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L204-L209)
|
||
|
||
### validate
|
||
验证访问令牌的有效性。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/authserver/validate`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"accessToken": "访问令牌"
|
||
}
|
||
```
|
||
- **响应**:
|
||
- 204: 令牌有效
|
||
- 403: 令牌无效
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L248-L267)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L260-L261)
|
||
|
||
### refresh
|
||
刷新访问令牌，延长会话有效期。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/authserver/refresh`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"accessToken": "当前访问令牌",
|
||
"clientToken": "客户端令牌",
|
||
"selectedProfile": "选定的档案"
|
||
}
|
||
```
|
||
- **响应**:
|
||
- 200: 返回新的`accessToken`和`selectedProfile`
|
||
- 400: 刷新失败
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L269-L361)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L341-L351)
|
||
|
||
### invalidate
|
||
使访问令牌失效。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/authserver/invalidate`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"accessToken": "要使失效的令牌"
|
||
}
|
||
```
|
||
- **响应**:
|
||
- 204: 成功使令牌失效
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L363-L378)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L375)
|
||
|
||
### signout
|
||
用户登出，使该用户的所有令牌失效。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/authserver/signout`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"username": "用户邮箱",
|
||
"password": "密码"
|
||
}
|
||
```
|
||
- **响应**:
|
||
- 204: 登出成功
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L380-L425)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L422)
|
||
|
||
## 会话服务API
|
||
会话服务API位于`/yggdrasil/sessionserver`路径下，管理玩家与服务器的会话。
|
||
|
||
### JoinServer
|
||
记录玩家加入服务器的会话信息。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/sessionserver/session/minecraft/join`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"accessToken": "访问令牌",
|
||
"selectedProfile": "选定的档案UUID",
|
||
"serverId": "服务器ID"
|
||
}
|
||
```
|
||
- **响应**:
|
||
- 204: 加入成功
|
||
- 500: 加入失败
|
||
|
||
```mermaid
|
||
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](file://internal/handler/yggdrasil_handler.go#L449-L496)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L81-L163)
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L449-L496)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L81-L163)
|
||
|
||
### HasJoinedServer
|
||
验证玩家是否已加入指定服务器。
|
||
|
||
- **方法**: GET
|
||
- **路径**: `/yggdrasil/sessionserver/session/minecraft/hasJoined`
|
||
- **查询参数**:
|
||
- `serverId`: 服务器ID
|
||
- `username`: 用户名
|
||
- `ip`: IP地址（可选）
|
||
- **响应**:
|
||
- 200: 返回玩家档案信息
|
||
- 204: 未加入或验证失败
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L498-L552)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L165-L201)
|
||
|
||
## 档案服务API
|
||
档案服务API提供玩家档案查询功能。
|
||
|
||
### GetProfileByUUID
|
||
根据UUID获取玩家档案。
|
||
|
||
- **方法**: GET
|
||
- **路径**: `/yggdrasil/sessionserver/session/minecraft/profile/:uuid`
|
||
- **响应**:
|
||
- 200: 返回玩家档案信息
|
||
- 500: 获取失败
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L427-L447)
|
||
- [profile_service.go](file://internal/service/profile_service.go#L71-L80)
|
||
|
||
### GetProfilesByName
|
||
根据用户名批量获取玩家档案。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/api/profiles/minecraft`
|
||
- **请求体**: 用户名数组
|
||
```json
|
||
["player1", "player2"]
|
||
```
|
||
- **响应**: 返回匹配的档案列表
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L554-L587)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L129-L137)
|
||
|
||
## 与Minecraft客户端交互流程
|
||
Minecraft客户端与Yggdrasil服务的完整交互流程如下：
|
||
|
||
```mermaid
|
||
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](file://internal/handler/yggdrasil_handler.go)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go)
|
||
|
||
## 内部用户系统集成
|
||
Yggdrasil实现与系统内部用户体系的集成通过以下方式完成：
|
||
|
||
### 用户映射
|
||
系统通过`Yggdrasil`模型将Yggdrasil协议的密码认证与内部用户ID关联。当用户注册时，系统自动生成一个16位随机密码与用户ID绑定。
|
||
|
||
```mermaid
|
||
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](file://internal/model/yggdrasil.go)
|
||
- [user_service.go](file://internal/service/user_service.go#L13-L67)
|
||
|
||
**Section sources**
|
||
- [yggdrasil.go](file://internal/model/yggdrasil.go#L13-L38)
|
||
- [user_service.go](file://internal/service/user_service.go#L13-L67)
|
||
|
||
### 令牌管理
|
||
系统使用`Token`模型管理访问令牌，将`accessToken`与`userID`、`profileId`关联，实现会话状态管理。
|
||
|
||
```mermaid
|
||
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](file://internal/model/token.go)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L211-L216)
|
||
|
||
**Section sources**
|
||
- [token.go](file://internal/model/token.go)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L211-L216)
|
||
|
||
## 错误处理
|
||
系统实现了标准化的错误处理机制，所有Yggdrasil端点返回一致的错误响应格式。
|
||
|
||
### 常见错误代码
|
||
| HTTP状态码 | 错误类型 | 描述 |
|
||
|-----------|---------|------|
|
||
| 400 | Bad Request | 请求格式无效 |
|
||
| 403 | Forbidden | 认证失败或权限不足 |
|
||
| 404 | Not Found | 资源未找到 |
|
||
| 500 | Internal Server Error | 服务器内部错误 |
|
||
|
||
### 错误响应示例
|
||
```json
|
||
{
|
||
"error": "密码错误"
|
||
}
|
||
```
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L19-L57)
|
||
|
||
## 元数据与证书
|
||
系统提供元数据和玩家证书服务，支持Minecraft客户端的高级功能。
|
||
|
||
### GetMetaData
|
||
获取服务元数据。
|
||
|
||
- **方法**: GET
|
||
- **路径**: `/yggdrasil`
|
||
- **响应**: 包含实现信息、链接和功能标志
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L589-L615)
|
||
|
||
### GetPlayerCertificates
|
||
获取玩家证书。
|
||
|
||
- **方法**: POST
|
||
- **路径**: `/yggdrasil/minecraftservices/player/certificates`
|
||
- **认证**: Bearer Token
|
||
- **响应**: 包含玩家公钥证书
|
||
|
||
**Section sources**
|
||
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L618-L667)
|
||
- [profile_service.go](file://internal/service/profile_service.go#L44-L48) |