正式环境与演示环境

截至 2026-09-12，星途已部署正式基础控制台与 SDK 接入服务。H5 账号 SDK 已增加 v0.4.0，原生和引擎工件保留 v0.3.0；服务部署更新不代表安装包重新发行或全部原生设备已验收。先确认环境，再执行各端示例。

入口与域名职责

入口	地址	用途
官网与文档	https://starai.art/ 、https://starai.art/docs/	产品信息、文档及下载，无业务 API
开发者端	https://developer.starai.art/	接入团队账号、应用与密钥；仅 /api/developer/
管理后台	https://admin.starai.art/	授权运营人员开户、审核与管理；仅 /api/admin/
SDK / 游戏服 API	https://api.starai.art	玩家认证、配置、可信交换、角色与履约协议
游戏演示	https://demo.starai.art/	独立演示数据，免环境密码访问
代理合作	https://agent.starai.art/	服务筹备页面，尚无开户、佣金与结算接口

www.starai.art 跳转官网。API 根路径返回 404 是预期行为，健康检查使用 /api/health。SDK 域名拒绝开发者、管理员和演示快捷兑换接口；错误域名不会自动代理到其他端。

开放能力

能力	正式基础环境	独立演示 / 本地
开发者登录、创建应用、审批与密钥管理	已开放；管理员可开户	可验证流程
开发者自助注册	已开放，主动同意当前服务协议与隐私政策后创建账号	本地服务说明，仅限验证
平台玩家密码认证与 PKCE 兑换	已批准应用和已开通玩家账号可用	可用演示玩家账号
玩家短信注册、登录、找回	未接通真实短信，返回 503 SMS_NOT_CONFIGURED	返回演示验证码，无真实短信
区服、可信角色绑定、履约队列协议	可对接；默认 external	local 与 external 可验证
真实支付、退款、平台币收付	未开放，不能用演示支付替代	模拟记账，不收取真实资金
Apple / Steam 身份、商店支付	未验收且未开放	配置偏好不会激活供应商
代理开户、佣金、提现结算	未开放	原型不是正式业务

以 /api/capabilities?appId=实际AppID 的 available、mode、reason 判断可用性。productionReady: false 表示完整商业能力尚未就绪，不表示正式 API 健康检查失败。

首次正式接入

1. 打开开发者端自助注册，阅读并主动同意当前服务协议与隐私政策，成功后进入控制台。管理员也可核验身份后开户；账号开通不代表游戏通过审核。
2. 创建应用并选择客户端，保存一次性服务端密钥，等待批准。正式库不提供演示 App ID、商品、玩家账号或赠送余额。
3. 与平台确认真实玩家账号的开通方式。当前支持独立用户名密码注册，注册后需玩家主动登录；真实短信注册和手机绑定尚未接通，详见玩家账号；开发者账号不能作为玩家登录。开发者可创建限定游戏、短期有效的 test_ 专用账号完成身份、角色与客服验证，见本地游戏联调；该账号不支持真实支付或钱包资产。
4. 游戏后端配置平台 origin https://api.starai.art、实际 App ID 与服务端密钥；客户端 baseUrl 使用同一 origin，不添加 /api。
5. H5 提前向平台提交页面的完整 HTTPS Origin（协议、域名、端口）。当前正式跨域为显式名单；应用审批不会自动添加游戏域名。本地 localhost / 127.0.0.1 带明确非默认端口的来源可按本地联调指南登记，生产域名仍需另行配置。
6. 按各端文档接入 PKCE、可信兑换、刷新恢复、切号和注销。真实角色由游戏服务器绑定，不能把兼容字段中的 unbound_* 当成存档或可发货角色。
7. 查询能力并隐藏未开放入口。支付、短信、商店渠道、真实游戏服消费器及设备验收分别完成，不能以一次密码登录代替全部验收。

curl https://api.starai.art/api/health
# {"status":"ok","mode":"production","deployment":"restricted","paymentsAvailable":false,"smsAvailable":false}

curl https://developer.starai.art/api/developer/registration-terms
# 当前 available=true，协议版本2026-09-12.1；提交时使用接口实时返回的 version。
# 若环境配置异常使 available=false，展示 reason 并停止提交。

如何使用本地示例

各端代码中的 http://127.0.0.1:18787、Android 模拟器 http://10.0.2.2:18787、示例账号和 starlight-h5 均用于本地演示，不能直接拿到正式环境调用。客户端和游戏后端必须一起替换 origin 与 App ID；不要只改网页地址。

正式服务不使用 X-Starlight-Preview-Key。演示访问凭据只向受控联调人员提供，不写进公开客户端。已有 0.3.0 工件没有统一提供环境网关头配置；原生演示联调需要受控网络适配或本地环境。正式与演示的账号、密钥、令牌和数据互不迁移。

常见环境问题

现象	处理
在 api 域调用 developer 登录得到 404	改用 developer 域；不要改后台路由放行
正式 App ID 不存在	使用正式控制台生成的标识，演示应用不会自动迁移
H5 返回 ORIGIN_FORBIDDEN	向平台确认精确 HTTPS 来源配置；不使用通配符绕过
REGISTRATION_UNAVAILABLE	当前环境协议配置不可用或临时暂停；读取实时 reason，停止重复提交并联系平台
SMS_NOT_CONFIGURED / PAYMENT_NOT_CONFIGURED	真实服务未配置，隐藏入口，不循环重试
登录得到 unbound_*、角色数值为 0	兼容投影；通过可信角色接口对接实际游戏角色

继续阅读应用创建、开发者账号和正式支付边界。