CarrotSkin/backend
4
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a4b6c5011e1c196b6b1095b6f9e0bcd9fe15722b
backend/.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/Yggdrasil协议API.md

386 lines
11 KiB
Markdown
Raw Normal View History

chore(git): 更新.gitignore以忽略新的本地文件
2025-11-30 08:33:17 +08:00
# 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)
Reference in New Issue Copy Permalink