服务器提供者身份验证指南

Author
玄易同志
作者
2026-01-12
发布时间
Hytale
分类

一、先决条件（申请资格）

想开游戏服务器公司？得先找Hytale官方认证：
联系客服：去Hytale支持页面，选"游戏服务器提供商"这个工单主题
必须提供四样东西：

[TABLE]
[TR]
[TH][LEFT]要啥[/LEFT][/TH]
[TH][LEFT]你给啥[/LEFT][/TH]
[TH][LEFT]审核标准[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]Hytale账号[/LEFT][/TD]
[TD][LEFT]邮箱或UUID[/LEFT][/TD]
[TD][LEFT]必须是标准版或更高级的账号[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]域名匹配[/LEFT][/TD]
[TD][LEFT]你的公司商店网址[/LEFT][/TD]
[TD][LEFT]账号邮箱域名要跟商店域名一致（比如[email]support@example.com[/email]对应store.example.com）[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]公司注册[/LEFT][/TD]
[TD][LEFT]政府注册链接（最好）或官方注册文件[/LEFT][/TD]
[TD][LEFT]公司名必须跟网站上显示的法律实体完全一致[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]网站验证[/LEFT][/TD]
[TD][LEFT]直接的公司网站URL[/LEFT][/TD]
[TD][LEFT]显示的公司名必须跟注册名一样，域名要跟邮箱域名匹配[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]联系邮箱[/LEFT][/TD]
[TD][LEFT]滥用/技术/管理三个联系人邮箱[/LEFT][/TD]
[TD][LEFT]全都要用公司域名邮箱，其中滥用联系邮箱必须有24小时响应承诺[/LEFT][/TD]
[/TR]
[/TABLE]
审核通过后会给你三样东西：
  • 带sessions.unlimited_servers权限的账号——能开无限个服务器（默认只能开100个）
  • game.base游戏所有权
  • GSP专属Discord频道——直接跟Hypixel Studios工程师和其他服务器提供商交流技术
⚠️ 警告：24小时内不响应滥用报告，直接撤销权限，所有服务器当场下线！
[HR][/HR]

二、超简流程（想快速上手看这里）

适用对象：需要管理100+服务器，想全自动开服的老板
四步走战略：
  • 获取权限——联系Hytale客服，提交公司资料，拿到无限开服授权
  • 一次性拿令牌——用"设备码流程"（后面会讲）获取refresh_token（这个能管30天）
  • 创建会话——调用API：先/my-account/get-profiles获取账号信息，再/game-session/new获取sessionToken和identityToken
  • 把令牌给服务器——启动服务器时加上：
java -jar HytaleServer.jar \
--session-token "<sessionToken>" \
--identity-token "<identityToken>"

或者设置环境变量：

export HYTALE_SERVER_SESSION_TOKEN="eyJhbGc..."
export HYTALE_SERVER_IDENTITY_TOKEN="eyJhbGc..."
  • 记得刷新——游戏会话1小时过期，到期前用refresh_token换新的access_token，再创建新会话
核心原则：所有令牌由你的系统集中管理，客户永远看不到登录界面
[HR][/HR]

三、认证方法详解（四种方式）

方法A：服务器控制台命令（适合手动操作）

直接在服务器里输命令：

[TABLE]
[TR]
[TH][LEFT]命令[/LEFT][/TH]
[TH][LEFT]干啥的[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]/auth login device[/LEFT][/TD]
[TD][LEFT]启动设备码流程（推荐，适合没桌面的服务器）[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]/auth login browser[/LEFT][/TD]
[TD][LEFT]启动浏览器登录（需要桌面环境）[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]/auth select <数字>[/LEFT][/TD]
[TD][LEFT]账号有多个游戏角色时，选一个[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]/auth status[/LEFT][/TD]
[TD][LEFT]查看当前登录状态[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]/auth cancel[/LEFT][/TD]
[TD][LEFT]取消正在进行的登录[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]/auth logout[/LEFT][/TD]
[TD][LEFT]退出登录，清掉令牌[/LEFT][/TD]
[/TR]
[/TABLE]
示例：

[QUOTE] /auth login device[/QUOTE]
===================================================================
DEVICE AUTHORIZATION
===================================================================
访问: https://accounts.hytale.com/device
输入代码: ABCD-1234
或者访问: https://accounts.hytale.com/device?user_code=ABCD-1234
===================================================================
等待授权中（900秒后过期）...

[用户在浏览器里完成授权]

[QUOTE] 登录成功！模式: OAUTH_DEVICE[/QUOTE]

[HR][/HR]

方法B：设备码流程（RFC 8628标准，适合自动化）

第一步：要设备代码

curl -X POST "https://oauth.accounts.hytale.com/oauth2/device/auth" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=hytale-server" \
-d "scope=openid offline auth:server"

返回：

{
"device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
"user_code": "ABCD-1234",
"verification_uri": "https://accounts.hytale.com/device",
"verification_uri_complete": "https://accounts.hytale.com/device?user_code=ABCD-1234",
"expires_in": 900,
"interval": 5
}

第二步：给用户看提示
  • 网址：verification_uri或verification_uri_complete
  • 代码：user_code（如果用第一个网址才需要）
第三步：轮询获取令牌每5秒请求一次：

curl -X POST "https://oauth.accounts.hytale.com/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=hytale-server" \
-d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
-d "device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"

还没授权时返回：

{"error": "authorization_pending"}

成功时返回：

{
"access_token": "eyJhbGc...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "xreEsdDGrfIaQc...",
"scope": "openid offline auth:server"
}

第四步：获取可用账号信息

curl -X GET "https://account-data.hytale.com/my-account/get-profiles" \
-H "Authorization: Bearer <access_token>"

返回：

{
"owner": "550e8400-e29b-41d4-a716-446655440000",
"profiles": [{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"username": "ServerOperator"
}]
}

第五步：创建游戏会话

curl -X POST "https://sessions.hytale.com/game-session/new" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"uuid": "123e4567-e89b-12d3-a456-426614174000"}'

返回：

{
"sessionToken": "eyJhbGc...",
"identityToken": "eyJhbGc...",
"expiresAt": "2026-01-07T15:00:00Z"
}

这两个Token就是服务器要用的！
[HR][/HR]

方法C：令牌透传（适合托管服务商）

启动服务器时直接把令牌塞进去：
环境变量方式：

export HYTALE_SERVER_SESSION_TOKEN="eyJhbGc..."
export HYTALE_SERVER_IDENTITY_TOKEN="eyJhbGc..."
./hytale-server

命令行参数方式：

./hytale-server \
--session-token "eyJhbGc..." \
--identity-token "eyJhbGc..." \
--owner-uuid "123e4567-e89b-12d3-a456-426614174000"

特点：
  • 服务器运行在EXTERNAL_SESSION模式
  • 到期前5分钟自动刷新
  • 适合你把令牌管理外包给其他系统
[HR][/HR]

方法D：凭证存储API（开发中，未来用）

干啥的：让你用插件或程序来存令牌，重启服务器也不丢
接口定义：

public interface IAuthCredentialStore {
record OAuthTokens(
@Nullable String accessToken,
@Nullable String refreshToken,
@Nullable Instant accessTokenExpiresAt
) {}

void setTokens(@Nonnull OAuthTokens tokens);
@Nonnull OAuthTokens getTokens();
void setProfile(@Nullable UUID uuid);
@Nullable UUID getProfile();
void clear();
}

怎么用：
  • 实现这个接口（存数据库、文件都行）
  • 启动前注册：ServerAuthManager.getInstance().registerCredentialStore(store)
  • 服务器自动从你那拿令牌、刷新、存回去
  • 认证模式会变成OAUTH_STORE
关键规则：
  • 必须在任何认证发生前注册
  • 如果getProfile()返回UUID，自动选那个角色
[HR][/HR]

四、API参考（技术细节）

1. 创建游戏会话

POST /game-session/new
Host: sessions.hytale.com
Authorization: Bearer <oauth_access_token>
Content-Type: application/json

{"uuid": "<profile_uuid>"}

2. 获取账号信息


GET /my-account/get-profiles
Host: account-data.hytale.com
Authorization: Bearer <oauth_access_token>

3. 刷新会话

POST /game-session/refresh
Host: sessions.hytale.com
Authorization: Bearer <session_token>

4. 结束会话（服务器关的时候调用）

DELETE /game-session
Host: sessions.hytale.com
Authorization: Bearer <session_token>

5. 刷新OAuth令牌

curl -X POST "https://oauth.accounts.hytale.com/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=hytale-server" \
-d "grant_type=refresh_token" \
-d "refresh_token=<refresh_token>"

[HR][/HR]

五、令牌生命周期（多久过期）


[TABLE]
[TR]
[TH][LEFT]令牌类型[/LEFT][/TH]
[TH][LEFT]存活时间[/LEFT][/TH]
[TH][LEFT]备注[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]OAuth Access Token[/LEFT][/TD]
[TD][LEFT]1小时[/LEFT][/TD]
[TD][LEFT]用来创建游戏会话[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]OAuth Refresh Token[/LEFT][/TD]
[TD][LEFT]30天[/LEFT][/TD]
[TD][LEFT]用来换新的Access Token[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]Game Session[/LEFT][/TD]
[TD][LEFT]1小时[/LEFT][/TD]
[TD][LEFT]服务器到期前5分钟自动刷新[/LEFT][/TD]
[/TR]
[/TABLE]
刷新策略：
  • 服务器会在令牌过期前5分钟自动刷新
  • 如果游戏会话刷新失败，会退回去刷新OAuth令牌
[HR][/HR]

六、错误处理

常见HTTP错误

  • 400 Bad Request：请求格式错了或缺参数
  • 401 Unauthorized：没登录或登录信息不对
  • 403 Forbidden：登录了但权限不够（没授权、超过会话限制）
  • 404 Not Found：资源不存在（比如UUID错了）

会话限制错误

没sessions.unlimited_servers权限的账号最多100个并发会话，超了返回403 Forbidden

令牌验证失败

启动时如果令牌不对，会提示：
复制
Token validation failed. Server starting unauthenticated.
Use /auth login to authenticate.

常见原因：
  • 令牌过期了
  • 签名无效
  • 缺少必要权限范围（hytale:server）
[HR][/HR]

七、JWKS终端（验证玩家用）

服务器用公钥验证玩家的JWT令牌：
请求：

GET /.well-known/jwks.json
Host: sessions.hytale.com

返回：

{
"keys": [{
"kty": "OKP",
"alg": "EdDSA",
"use": "sig",
"kid": "key-id-1",
"crv": "Ed25519",
"x": "base64url-encoded-public-key"
}]
}

[HR][/HR]

八、其他工具

Hytale下载器CLI

作用：自动下载和更新服务器文件，集成到你的配置系统里
下载：hytale-downloader.zip（含快速启动脚本，支持Linux和Windows）
文档：看官方服务器手册里的《Hytale下载器CLI》章节
[HR][/HR]

九、核心信息总结

OAuth客户端信息：
  • Client ID: hytale-server
  • 权限范围（Scopes）: openid, offline, auth:server
OAuth端点： 测试环境：把hytale.com换成arcanitegames.ca
[HR][/HR]

十、规划中的功能

官方正在开发CLI工具来自动化令牌获取和刷新，但现在还没好。想了解进度，去GSP专属Discord频道看公告。
[HR][/HR]
最后提醒：整个流程的核心是——拿到30天有效的refresh_token → 每小时用它换access_token → 用access_token创建游戏会话 → 把sessionToken和identityToken给服务器。记住这个链条，其他的都是细节！
返回上一页