Natayark Skin Server

一个自托管的 Minecraft 皮肤站，使用 Node.js、TypeScript 和 MySQL。管理皮肤、披风和游戏角色，提供 Yggdrasil 外置登录与 Yggdrasil Connect，也可以通过第三方账号登录网站。

这是一个基于 Blessing Skin Server 设计理念独立开发的Minecraft皮肤站系统。

Warning

Natayark Skin Server is currently in a rapidly iterating development phase and cannot guarantee full compliance with production environment requirements. Please make sure to backup the data when making any modifications.

开始使用

需要 Node.js 22 或更新版本，以及一个 MySQL 数据库。现有数据库兼容测试使用 MySQL 5.7.26，其他版本的实测情况见兼容说明。

npm ci
npm run setup

setup 会生成带随机 APP_KEY 的 .env，已有文件不会覆盖。填写数据库连接信息后，为新站创建表：

npm run db:init -- --apply
npm run build
npm run dev

打开 http://localhost:3000 注册自己的账户，再用本地命令将其设为管理员：

npm run admin:promote -- --email you@example.com --apply

站点名称、配色、圆角、首页样式、版权和备案信息可以在后台调整。邮箱确认、找回密码需要配置 SMTP；第三方登录需要配置客户端凭据和回调地址。

已有 Blessing Skin 站点请先读从 Blessing Skin 迁移，保留原账户、材质和第三方登录，不要运行新站初始化命令。生产环境的 HTTPS、反向代理、持久化与备份见部署说明。

目前已实现的功能

以下按当前代码中的功能整理。第三方登录、邮件、正版验证和部分兼容接口需要先配置凭据或启用对应选项；实际验证范围见本节末尾的说明。

账户与登录

• 邮箱或角色名加密码登录、注册、记住登录、退出登录和会话吊销。
• 邮箱绑定与验证、修改邮箱、设置或修改密码、邮件找回密码；密码变更后撤销已有会话和令牌。
• Natayark ID、Microsoft Live 及可配置的 OAuth 提供方登录，支持第三方账号绑定、解绑和可用登录方式检查。
• 原 Blessing Skin 第三方账户归属确认：通过原密码或原邮箱确认后绑定稳定身份，保留原 UID、角色、UUID、材质和积分。
• 本站图片验证码、reCAPTCHA v2 复选框与 invisible 模式，覆盖注册、找回密码和多次失败后的登录验证。
• 个人昵称与头像设置；头像可以使用指定皮肤或跟随已装备的角色皮肤，兼容原 Gravatar 入口。

配置及迁移规则见账户认证说明。

皮肤、披风与衣柜

• PNG 皮肤和披风上传、拖放选择、上传预览、尺寸与格式校验，支持 Steve、Alex 和高清材质。
• 公开与私有材质、名称及模型修改、删除、下载，以及经过 HTML 净化的 Markdown 材质描述。
• 皮肤库按名称、类型、上传者筛选，支持上传时间、收藏数等排序和分页。
• 衣柜收藏、搜索、分类、别名修改与移除，可将收藏的皮肤和披风应用到角色。
• 2D 头像、等距 3D 头像、皮肤前后视图和披风静态渲染，支持 PNG、无损 WebP、自定义尺寸及缓存。
• 可操作的 3D 预览，支持旋转、缩放、行走、奔跑、暂停、重置、2D/3D 切换、皮肤模型、披风和背景设置。
• 命令行批量导入皮肤或披风，支持预演、重复文件检测和逐文件校验；沿用原批量导入不扣积分、不自动加入衣柜的行为。

角色与正版验证

• 多角色创建、重命名、删除，独立应用或清除皮肤和披风。
• 可配置角色命名规则、数量上限、单角色模式和新增角色积分消耗，注册时创建免费初始角色。
• 保留已有角色 UUID；网页默认遮蔽 UUID，由角色所有者主动查看或复制。
• Minecraft Java 正版所有权验证，支持 Microsoft → Xbox → Minecraft 授权链路、绑定冲突检查和一次性积分奖励。
• 正版 UUID 显式同步；单角色模式下可保留原角色，或在确认后更名并同步，保留 PID、皮肤和披风。

Microsoft 网站登录与游戏正版验证分别配置，具体规则见正版验证说明。

积分、签到与用户互动

• 每日签到和可配置积分奖励；上传、存储、收藏、新增角色等操作使用站点积分规则，并按规则处理返还及奖励。
• 仪表盘展示积分、角色及材质用量，以及当前规则下的剩余容量。
• 注册分享链接管理、链接停用和邀请奖励，处理重复领取与并发发奖。
• 材质举报、本人举报记录及处理状态查询。
• 站内通知、未读提示、单条阅读和全部已读；用户页支持可配置来源、缓存与失败回退的一言。

Yggdrasil 外置登录与材质接口

• 内置 Yggdrasil 认证服务，支持 authenticate、refresh、validate、invalidate、signout，以及邮箱或角色名登录、多角色选择和令牌吊销。
• join/hasJoined 联机认证、角色与权限校验；认证状态存储在数据库中，支持共享数据库的多进程和多实例部署。
• 单个或批量角色档案查询、RSA 材质签名、公开材质公钥和 authlib-injector 服务元数据。
• 持有有效授权的客户端可上传、替换或清除角色材质，沿用站内所有权校验和积分规则。
• CustomSkinLoader、USM 和旧版皮肤/披风接口，以及不存在角色返回 204 的兼容选项。
• 启动器认证地址、拖入启动器入口、复制配置与配置文件下载。

Yggdrasil Connect 与应用授权

• 内置 Yggdrasil Connect 和 OAuth/OIDC 服务，无需另外运行 Janus；保留常用 Janus 路径及 OAuth 接口别名。
• OpenID discovery、JWKS、授权码、S256 PKCE、设备授权、UserInfo、离线刷新和令牌吊销。
• 明确的应用授权确认、角色选择、授权范围控制，以及用户查看和撤销已有授权。
• 开发者应用创建、编辑、删除，配置回调地址、客户端类型和密钥；管理员可管理客户端。
• 个人访问令牌创建、权限范围选择及吊销，令牌内容只在创建时展示。

接口及协议边界见协议兼容说明。

Minecraft 游戏内好友

• 支持 Minecraft Java 26.2、26.3 的游戏内好友列表，本站角色可按名字或 UUID 发送、接受、拒绝、撤回好友申请及删除好友。
• 好友关系与隐私偏好按角色保存，同账号的不同角色独立管理。
• 游戏「在线选项」可控制好友列表及是否接收申请；关闭好友列表后隐藏在线状态并保留已有关系。
• 好友在线及游戏中状态、心跳过期离线和条件轮询，仅向已确认的好友提供状态。

该功能用于本站角色之间，不包含跨认证站好友同步、P2P 世界邀请或 Realms。升级启用方式与客户端测试见好友列表说明。

管理后台

• 用户资料、积分、权限、封禁和验证状态管理，支持删除用户及管理指定用户的衣柜。
• 角色名称、所属用户、皮肤和披风管理；材质管理和举报处理。
• 向全部用户、普通用户、指定 UID 或邮箱发送站内通知，正文支持经过净化的 Markdown。
• 用户、角色及举报的高级搜索：字段条件、比较、列表、括号、and/or/not、日期、排序和 API 字段选择，见搜索语法。
• 站点基础信息、注册与角色规则、积分规则、验证码、第三方登录、资源与缓存、外观及自定义 CSS/JS 配置。
• 应用客户端管理、多语言条目查询与编辑、Yggdrasil 日志查询。
• 站点统计与趋势图；系统状态页展示程序版本、运行时间、资源用量、数据库、材质目录及邮件配置状态。

外观、响应式与交互

• 浅色、深色和跟随系统模式，可配置站点配色、圆角与默认主题。
• 分栏、经典大图、皮肤库优先和简洁四种首页，支持首页图片、最近上传、使用介绍、固定背景和透明导航配置。
• 站点名称、介绍、公告、版权与备案信息定制。
• 手机及桌面布局，适配导航、工具栏、表格、弹窗和材质网格。
• 页面切换的方向位移与内容分批入场，支持后退方向、滚动恢复和减少动态效果偏好。
• 中英文切换保留当前路径、查询参数与锚点；提供加载骨架、操作反馈和确认弹窗。

旧站迁移与部署支持

• 读取已有 Blessing Skin 账户、角色、UUID、材质、衣柜、积分、配置和客户端数据；兼容原密码算法、盐及签名密钥。
• 新站数据库初始化、管理员提升、配置生成，以及已有站点扩展表迁移；默认保留原表字段，长描述列扩容需显式启用。
• 复现已列明的原插件能力及兼容开关，包括注册分享、单角色限制、旧材质接口和开发者菜单隐藏等，详见原站兼容核验。
• 可配置 SMTP、受信任代理、独立材质存储和多实例共享状态；配置阿里云 CDN 后可在角色或材质变更提交后刷新相关地址。
• 提供隔离数据库集成测试、协议 HTTP 测试和官方 authlib 好友协议测试，便于升级时验证行为。

新站与旧站使用不同的初始化流程，操作前请阅读迁移说明或部署说明。

实现与验证范围

以上为已实现的能力，不代表所有外部环境均已验收。真实第三方授权回调、SMTP 投递、CDN 刷新，以及 HMCL/PCL/Prism 和完整 Minecraft 图形客户端联机仍需实测；官方 authlib HTTP 测试不能代替完整游戏客户端验收。

目前未提供玩家聊天证书、PHP 插件运行时或插件市场；旧浏览器会话和部分旧授权需要重新登录或授权，多语言文案也仍在补充。完整范围见兼容说明。上传奖励上限、私有及删除语义、并发限制和自动文件回收见资源与安全说明。

开发与贡献

npm run typecheck
npm test
npm run build

数据库集成测试使用独立表命名空间，准备方法见开发说明。修复问题或提交新功能前，可以先开 issue 说明实际场景；界面修改请附截图。具体约定见 CONTRIBUTING.md。安全问题请按 SECURITY.md 的方式报告。

许可证

项目采用 MIT License，允许使用、修改和商业使用，分发时须保留版权及许可文本。页面默认保留 Powered by Natayark Skin Server，感谢使用者保留这处署名。

依赖和随附资源的许可单独列在第三方说明。

特别鸣谢

感谢 Blessing Skin 对 Minecraft 皮肤站生态的贡献。它的功能设计与接口行为为本项目的独立复现和兼容性验证提供了参考。