🎯 Yggdrasil API Server (Go)

🚀 高性能的 Minecraft Yggdrasil API 服务器实现

使用 Go 语言编写，完全兼容 Minecraft 官方认证协议，支持 BlessingSkin 皮肤站

✨ 核心特性

🚀 高性能架构基于 Gin 框架，支持高并发 JWT 优先验证架构多层缓存优化响应速度对象池减少内存分配 Sonic JSON高性能序列化	🔐 安全可靠完整的 JWT Token 管理 RSA 数字签名支持速率限制防护 CORS 跨域支持用户状态验证
💾 多存储后端 📁 文件存储 - 轻量级部署 🗄️ 数据库存储 - 高可用性 🎨 BlessingSkin - 完全兼容	🗄️ 智能缓存 🧠 内存缓存 - 极速响应 📁 文件缓存 - Laravel 兼容 🔴 Redis 缓存 - 分布式支持 🗃️ 数据库缓存 - 持久化存储

🎯 完全兼容

✅ 100% 兼容 Minecraft 官方 Yggdrasil API
✅ authlib-injector 完全支持
✅ BlessingSkin 数据库兼容
✅ Laravel 缓存格式兼容

📊 监控与运维

📈 实时性能监控 - QPS、响应时间、错误率
🏥 健康检查 - 自动故障检测
📋 结构化日志 - 便于问题排查
🔧 优雅关闭 - 零停机部署

🚀 快速开始

📦 方式一：下载预编译二进制文件（推荐）

前往 Releases 页面
下载适合您系统的二进制文件
解压并运行：

# Linux/macOS
chmod +x yggdrasil-api-server-*
./yggdrasil-api-server-* -version

# Windows
yggdrasil-api-server-*.exe -version

🔨 方式二：从源码编译

# 克隆仓库
git clone https://github.com/NewNanCity/YggdrasilGo.git
cd yggdrasil-api-go

# 安装依赖
go mod download

# 编译
make build
# 或者
go build -o yggdrasil-api-server main.go

🐳 方式三：Docker 部署

# 拉取镜像
docker pull ghcr.io/NewNanCity/YggdrasilGo:latest

# 运行容器
docker run -d \
  --name yggdrasil-api \
  -p 8080:8080 \
  -v $(pwd)/conf:/app/conf:ro \
  -v $(pwd)/keys:/app/keys:ro \
  ghcr.io/NewNanCity/YggdrasilGo:latest

⚙️ 配置服务器

复制配置文件：
```
cp conf/example.yml conf/config.yml
```

生成密钥对：

make keys
# 或者手动生成
mkdir -p keys
openssl genrsa -out keys/private.pem 2048
openssl rsa -in keys/private.pem -pubout -out keys/public.pem

编辑配置文件 conf/config.yml，根据需要修改数据库连接、缓存设置等

启动服务器：

./yggdrasil-api-server -config conf/config.yml

🎉 服务器启动成功！ 访问 http://localhost:8080 查看 API 状态

📋 配置说明

🎛️ 配置概览

配置类型	说明	支持选项
🗄️ 存储	用户数据存储	`file` `blessing_skin` `database`
🗃️ 缓存	Token/Session缓存	`memory` `redis` `file` `database`
🔐 认证	JWT和RSA配置	自定义密钥、过期时间
🌐 网络	服务器和CORS	端口、域名白名单

🔧 基础配置示例

# 服务器配置
server:
  host: "0.0.0.0"
  port: 8080
  debug: false

# 认证配置
auth:
  jwt_secret: "your-super-secret-jwt-key-change-in-production"
  token_expiration: 72h0m0s
  tokens_limit: 10
  require_verification: false

# 速率限制
rate_limit:
  enabled: true
  auth_interval: 1s

# 存储配置
storage:
  type: "file"  # 可选: file, memory, blessing_skin
  file_options:
    data_dir: "data"

# 缓存配置
cache:
  token:
    type: "memory"  # 可选: memory, redis, file, database
    options: {}
  session:
    type: "memory"
    options: {}

  # 响应缓存（提升性能）
  response:
    enabled: true
    api_metadata: true
    error_responses: true
    cache_duration: 5m

  # 用户信息缓存
  user:
    enabled: true
    duration: 5m
    max_users: 500

# 材质配置
texture:
  base_url: "https://your-domain.com"
  upload_enabled: false
  max_file_size: 2097152  # 2MB
  allowed_types: ["image/png", "image/jpeg"]

# Yggdrasil API 配置
yggdrasil:
  meta:
    server_name: "Yggdrasil API Server (Go)"
    implementation_name: "yggdrasil-api-go"
    implementation_version: "1.0.0"
    links:
      homepage: ""  # 留空则自动根据请求Host生成
      register: ""

  # 皮肤域名白名单
  skin_domains:
    - "localhost"
    - ".localhost"        # 通配符域名
    - "127.0.0.1"
    - "192.168.0.0/16"    # CIDR网段
    - "10.0.0.0/8"

  # 密钥文件路径
  keys:
    private_key_path: "keys/private.pem"
    public_key_path: "keys/public.pem"

  # 功能开关
  feature_non_email_login: true
  feature_legacy_skin_api: true
  feature_username_check: true
  feature_profile_key: true

# 性能监控
monitoring:
  enabled: true
  metrics_endpoint: "/metrics"
  cache_stats: true

# 安全配置
security:
  cors:
    enabled: true
    allowed_origins: ["*"]
    allowed_methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allowed_headers: ["*"]
  max_request_size: "1MB"
  read_timeout: "30s"
  write_timeout: "30s"

🗄️ 存储配置

文件存储（推荐用于小型部署）

storage:
  type: "file"
  file_options:
    data_dir: "data"

特点：

✅ 简单易用，无需数据库
✅ 适合小型服务器
❌ 不支持集群部署
❌ 密钥需要从配置文件读取

BlessingSkin 存储（推荐用于现有BlessingSkin站点）

storage:
  type: "blessing_skin"
  blessingskin_options:
    database_dsn: "user:password@tcp(localhost:3306)/blessingskin?charset=utf8mb4&parseTime=True&loc=Local"
    texture_base_url_override: false # false=从options读取site_url, true=使用配置文件的texture.base_url
    debug: false # 开启调试模式查看SQL查询

    # 安全配置 - 与BlessingSkin环境变量保持一致
    security:
      salt: "" # BlessingSkin通常不使用额外的salt，密码直接使用bcrypt
      pwd_method: "BCRYPT" # 与环境变量PWD_METHOD一致
      app_key: "base64:your_app_key_here" # 与环境变量APP_KEY一致

特点：

✅ 与BlessingSkin完全兼容
✅ 支持现有用户和角色
✅ 密钥从数据库options表读取
✅ 支持集群部署
❌ 需要MySQL数据库

数据库存储（暂未实现）

storage:
  type: "database"
  database_options:
    dsn: "user:password@tcp(localhost:3306)/yggdrasil?charset=utf8mb4&parseTime=True&loc=Local"

🗄️ 缓存配置

Redis 缓存（推荐用于生产环境）

cache:
  token:
    type: "redis"
    options:
      redis_url: "redis://localhost:6379"
  session:
    type: "redis"
    options:
      redis_url: "redis://localhost:6379"

特点：

✅ 高性能，支持集群
✅ JWT优先验证架构
✅ 自动过期清理
✅ 支持持久化
❌ 需要Redis服务

数据库缓存（推荐用于中型部署）

cache:
  token:
    type: "database"
    options:
      dsn: "user:password@tcp(localhost:3306)/cache?charset=utf8mb4&parseTime=True&loc=Local"
      table_prefix: "ygg_cache_"
      cleanup_interval: "5m"
      debug: false # 设置为true可以打印SQL调试日志
  session:
    type: "database"
    options:
      dsn: "user:password@tcp(localhost:3306)/cache?charset=utf8mb4&parseTime=True&loc=Local"
      table_prefix: "ygg_cache_"
      cleanup_interval: "5m"
      debug: false

特点：

✅ 可靠性高，支持事务
✅ JWT优先验证架构
✅ 定期清理过期数据
✅ 支持调试模式
❌ 性能略低于Redis

文件缓存（推荐用于小型部署）

cache:
  token:
    type: "file"
    options:
      cache_dir: "storage/framework/cache/tokens"
  session:
    type: "file"
    options:
      cache_dir: "storage/framework/cache/sessions"

特点：

✅ 无需额外服务
✅ Laravel兼容格式
✅ JWT优先验证架构
❌ 不支持集群部署
❌ 性能相对较低

🏗️ JWT优先验证架构

本项目采用创新的JWT优先验证架构，大幅提升性能：

传统架构 vs JWT优先架构

传统架构：
客户端请求 → 查询缓存/数据库 → 验证Token → 返回结果
每次请求都需要查询存储

JWT优先架构：
客户端请求 → JWT本地验证（极快） → 按需查询缓存 → 返回结果
大部分请求无需查询存储，性能提升10倍以上

性能优势

Token验证: JWT本地验证，无需查询数据库
缓存优化: 只存储JWT中没有的信息（如ClientToken）
存储键优化: 使用userID:tokenID作为键，提高查询效率
内存占用: 大幅减少缓存内存占用

🐳 Docker 部署

🚀 快速部署（推荐）

使用 Docker Compose 一键部署完整环境：

# 克隆仓库
git clone https://github.com/NewNanCity/YggdrasilGo.git
cd yggdrasil-api-go

# 准备环境
cp .env.example .env
cp conf/example.yml conf/config.yml

# 编辑配置文件
nano .env
nano conf/config.yml

# 启动服务
make deploy
# 或者
docker-compose up -d

🔧 自定义部署

# 仅启动 API 服务器
docker run -d \
  --name yggdrasil-api \
  -p 8080:8080 \
  -v $(pwd)/conf:/app/conf:ro \
  -v $(pwd)/keys:/app/keys:ro \
  -v yggdrasil_storage:/app/storage \
  ghcr.io/NewNanCity/YggdrasilGo:latest

# 启动完整环境（包含监控）
docker-compose --profile monitoring up -d

# 启动带 Nginx 的环境
docker-compose --profile with-nginx up -d

🏥 健康检查

# 检查服务状态
curl http://localhost:8080/

# 查看性能指标
curl http://localhost:8080/metrics

# 查看容器状态
docker-compose ps

# 查看日志
docker-compose logs -f yggdrasil-api

🌐 API 文档

📋 API 端点概览

类别	端点	方法	说明
🔐 认证	`/authserver/authenticate`	POST	用户登录
🔐 认证	`/authserver/refresh`	POST	刷新令牌
🔐 认证	`/authserver/validate`	POST	验证令牌
🔐 认证	`/authserver/invalidate`	POST	撤销令牌
🔐 认证	`/authserver/signout`	POST	登出
🎮 会话	`/sessionserver/session/minecraft/join`	POST	客户端加入服务器
🎮 会话	`/sessionserver/session/minecraft/hasJoined`	GET	服务端验证客户端
👤 角色	`/api/profiles/minecraft`	POST	批量查询角色
👤 角色	`/sessionserver/session/minecraft/profile/{uuid}`	GET	获取角色档案
📊 监控	`/`	GET	API 元数据
📊 监控	`/metrics`	GET	性能指标

📖 详细 API 文档

🔐 用户认证

POST /authserver/authenticate

用户登录认证

// 请求
{
  "username": "user@example.com",
  "password": "password123",
  "agent": {
    "name": "Minecraft",
    "version": 1
  }
}

// 响应
{
  "accessToken": "jwt-token-here",
  "clientToken": "client-token-here",
  "availableProfiles": [
    {
      "id": "uuid-here",
      "name": "PlayerName"
    }
  ],
  "selectedProfile": {
    "id": "uuid-here",
    "name": "PlayerName"
  }
}

POST /authserver/refresh

刷新访问令牌

// 请求
{
  "accessToken": "old-jwt-token",
  "clientToken": "client-token"
}

// 响应
{
  "accessToken": "new-jwt-token",
  "clientToken": "client-token"
}

🎮 游戏会话

POST /sessionserver/session/minecraft/join

客户端加入服务器

// 请求
{
  "accessToken": "jwt-token",
  "selectedProfile": {
    "id": "player-uuid",
    "name": "PlayerName"
  },
  "serverId": "server-hash"
}

// 响应: 204 No Content

GET /sessionserver/session/minecraft/hasJoined

服务端验证客户端

GET /sessionserver/session/minecraft/hasJoined?username=PlayerName&serverId=server-hash

// 响应
{
  "id": "player-uuid",
  "name": "PlayerName",
  "properties": [
    {
      "name": "textures",
      "value": "base64-encoded-texture-data",
      "signature": "rsa-signature"
    }
  ]
}

🔧 密钥管理

BlessingSkin存储

对于BlessingSkin存储，密钥从数据库的options表读取：

私钥: 从ygg_private_key字段读取
公钥: 从私钥自动提取
配置: 密钥文件路径可以留空

yggdrasil:
  keys:
    private_key_path: "" # 留空，从BlessingSkin数据库读取
    public_key_path: ""  # 留空，从BlessingSkin数据库读取

其他存储类型

对于文件存储等其他类型，密钥从配置文件指定的路径读取：

yggdrasil:
  keys:
    private_key_path: "keys/private.pem" # 必填
    public_key_path: "keys/public.pem"   # 必填

如果密钥文件不存在，服务器会自动生成新的密钥对。

📊 性能监控

🎯 实时监控指标

指标类型	监控内容	访问方式
🚀 性能	QPS、响应时间、错误率	`/metrics`
🗃️ 缓存	命中率、内存使用	`/metrics`
🗄️ 数据库	查询次数、平均时间	`/metrics`
💾 系统	内存、GC、协程数	`/metrics`

📈 监控数据示例

访问 /metrics 端点获取详细的性能统计：

{
  "performance": {
    "qps": 322.5,
    "avg_response_time_ms": 21.82,
    "error_rate": 0.0,
    "total_requests": 12847,
    "uptime_seconds": 3600
  },
  "cache_stats": {
    "token_cache": {
      "type": "redis",
      "hit_rate": 95.2,
      "total_requests": 10000,
      "cache_hits": 9520,
      "memory_usage_mb": 12.5
    },
    "session_cache": {
      "type": "redis",
      "active_sessions": 150,
      "hit_rate": 88.7
    },
    "uuid_cache": {
      "size": 500,
      "max_size": 1000,
      "hit_rate": 99.1
    }
  },
  "database": {
    "total_queries": 1250,
    "avg_query_time_ms": 5.2,
    "active_connections": 5,
    "max_connections": 100
  },
  "memory": {
    "heap_mb": 45.2,
    "system_mb": 67.8,
    "gc_count": 23,
    "goroutines": 15
  }
}

🔧 监控配置

启用详细监控和调试：

# 性能监控配置
monitoring:
  enabled: true
  metrics_endpoint: "/metrics"
  cache_stats: true

# 数据库调试
storage:
  blessingskin_options:
    debug: true # 打印SQL调试日志

# 缓存调试
cache:
  token:
    type: "database"
    options:
      debug: true # 打印缓存操作日志

🎛️ Grafana 仪表板

使用 Docker Compose 启动完整监控环境：

# 启动监控环境
docker-compose --profile monitoring up -d

# 访问 Grafana
open http://localhost:3000
# 默认账号: admin / admin

监控面板包含：

📈 QPS 和响应时间趋势
🗃️ 缓存命中率统计
🗄️ 数据库性能监控
💾 系统资源使用情况

🧪 测试

运行完整测试

cd test
go run perfect_client.go

测试覆盖所有API端点：

✅ API元数据获取
✅ 角色查询（单个和批量）
✅ 用户认证（邮箱和角色名登录）
✅ 令牌管理（验证、刷新、撤销）
✅ 会话管理（Join/HasJoined）
✅ 角色档案获取
✅ 性能监控

测试结果示例

🎯 最终测试结果: 12/12 通过 (100.0%)
🎉 所有测试通过！Yggdrasil API服务器完全可用！

✨ 测试完成的功能:
  ✅ 用户认证（邮箱和角色名登录）
  ✅ 令牌管理（验证、刷新、撤销）
  ✅ 角色查询（单个和批量）
  ✅ 角色档案获取
  ✅ API元数据获取
  ✅ 性能监控
  ✅ 会话管理（Join/HasJoined）

🚀 部署建议

小型部署（< 100用户）

storage:
  type: "file"

cache:
  token:
    type: "file"
  session:
    type: "file"

中型部署（100-1000用户）

storage:
  type: "blessing_skin"

cache:
  token:
    type: "database"
  session:
    type: "database"

大型部署（> 1000用户）

storage:
  type: "blessing_skin"

cache:
  token:
    type: "redis"
  session:
    type: "redis"

🔍 故障排除

常见问题

密钥文件不存在
- 确保 keys/ 目录存在
- 服务器会自动生成密钥对
数据库连接失败
- 检查数据库连接字符串
- 确保数据库服务正在运行
Redis连接失败
- 检查Redis连接配置
- 确保Redis服务正在运行
BlessingSkin兼容问题
- 检查安全配置是否与BlessingSkin一致
- 确认密码加密方法正确

调试模式

启用调试模式获取详细日志：

server:
  debug: true

storage:
  blessingskin_options:
    debug: true

cache:
  token:
    options:
      debug: true

🤝 贡献

💝 感谢所有贡献者

我们欢迎各种形式的贡献！无论是 Bug 报告、功能建议、代码贡献 还是 文档改进。

🚀 如何贡献

1. 🐛 报告 Bug

使用 Bug Report 模板
提供详细的复现步骤
包含系统信息和日志

2. 💡 功能建议

使用 Feature Request 模板
描述使用场景和预期效果
考虑向后兼容性

3. 🔧 代码贡献

# 1. Fork 仓库
git clone https://github.com/your-username/yggdrasil-api-go.git
cd yggdrasil-api-go

# 2. 创建功能分支
git checkout -b feature/amazing-feature

# 3. 进行开发
make deps
make test
make build

# 4. 提交更改
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

# 5. 创建 Pull Request

4. 📚 文档贡献

改进 README 和 Wiki
添加代码注释
编写使用示例

🎯 贡献领域

领域	描述	难度
🐛 Bug 修复	修复已知问题	⭐⭐
📊 性能优化	提升响应速度	⭐⭐⭐
🔐 安全增强	加强安全防护	⭐⭐⭐⭐
🌐 国际化	多语言支持	⭐⭐
📚 文档完善	改进文档质量	⭐
🧪 测试覆盖	增加测试用例	⭐⭐

📊 项目统计

📄 许可证

MIT License - 详见 LICENSE 文件

Copyright (c) 2025 Gk0Wk

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🙏 致谢

🌟 特别感谢

Minecraft - 游戏本体
Yggdrasil - 认证协议规范
BlessingSkin - 皮肤站参考实现
Gin - 高性能 HTTP 框架
GORM - 优秀的 Go ORM 库

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
conf		conf
docs		docs
src		src
test		test
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

License

NewNanCity/YggdrasilGo

Folders and files

Latest commit

History

Repository files navigation