skinloom

module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT

README

云织 SkinLoom

开源、自托管的 Minecraft 皮肤站

文档 · 下载 · 更新日志 · English


玩家在云织上传、分享皮肤和披风,给游戏角色换装;启动器和游戏通过 authlib-injector 外置登录或 CustomSkinLoader 等 Mod 显示这些皮肤。

云织以 Blessing Skin 为蓝本重新实现,对外协议保持兼容:老站可以一键迁移,玩家和服务器不用改配置。

1.0 正在收尾,目前是 0.x 预览版。

功能

  • 玩家:皮肤库、上传与收藏、衣柜、多角色、3D 预览、签到积分、举报、站内通知,GitHub / Microsoft / OpenID Connect 登录
  • 游戏:authlib-injector 外置登录、CustomSkinLoader、UniSkinMod、头像与预览图
  • 站长:后台管理与审计日志;设置、主题、首页在线修改,不用重启;插件与主题官方签名市场一键安装;SQLite / MySQL / PostgreSQL;本地或 S3 存储;CDN 刷新;备份恢复
  • 开发者:OAuth 2.0、个人访问令牌、与 Blessing Skin 相同的资源接口、REST API(OpenAPI 3.1),以及双层插件与主题平台(QuickJS/WASM TypeScript 沙箱 + Go 原生 gRPC 独立进程、@skinloom/plugin-sdk、sdk/go、create-skinloom-plugin)
  • 部署:Docker、Kubernetes / Helm,或 Windows / macOS / Linux 发行包(自带运行环境,可注册为系统服务)

快速开始

Docker:

mkdir skinloom && cd skinloom
curl -fsSLO https://raw.githubusercontent.com/Entropy-Increase-Team/skinloom/main/deploy/compose/minimal/compose.yaml
docker compose up -d
docker compose logs skinloom | grep setup     # 一次性安装链接

发行包: 从 Releases 下载解压,Windows 双击 start.bat,macOS 双击 start.command,Linux 运行 ./start.sh。

打开日志里的安装链接(http://服务器地址:17546/setup?token=…),设置站点名称和管理员账号即可。更多部署方式见文档。

文档

我是…… 去看
玩家 玩家指南:账号、上传皮肤、角色、在游戏里使用
站长 站长指南:部署、配置、后台、从 Blessing Skin 迁移
开发者 开发环境、架构、接口

设计取舍见设计文档和架构决策记录。

参与开发

需要 Go 1.26+、Node.js 24 和 bun(或 pnpm / npm),不需要 Docker:

git clone https://github.com/Entropy-Increase-Team/skinloom && cd skinloom
cd web && bun install && cd ..
go run ./cmd/skinloom up --dev     # http://localhost:17546

命令与约定见 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告。

鸣谢

感谢 Blessing Skin 团队与社区多年的工作;部分翻译文本与渲染算法思路源自 Blessing Skin(MIT),版权声明见 NOTICE。也感谢 skinview3d、authlib-injector、CustomSkinLoader 等项目。

许可

MIT。云织与 Mojang Studios、Microsoft 无关。

Directories

Path Synopsis
api
Package api holds the generated OpenAPI document of the REST API.
Package api holds the generated OpenAPI document of the REST API.
proto/plugin/v1
Package pluginv1 holds the bidirectional gRPC contract between SkinLoom host and Tier 2 native Go plugins.
Package pluginv1 holds the bidirectional gRPC contract between SkinLoom host and Tier 2 native Go plugins.
cmd
skinloom command
Command skinloom runs the SkinLoom (云织) skin site.
Command skinloom runs the SkinLoom (云织) skin site.
ent
Package ent holds the generated data access layer.
Package ent holds the generated data access layer.
job
internal
app
Package app wires the services together.
Package app wires the services together.
backup
Package backup writes and restores a whole SkinLoom install as one .tar.gz (docs/design/02 F78): the SQLite database (an online snapshot, the site may keep running), the config file, the secrets and the texture files.
Package backup writes and restores a whole SkinLoom install as one .tar.gz (docs/design/02 F78): the SQLite database (an online snapshot, the site may keep running), the config file, the secrets and the texture files.
cli
Package cli implements the skinloom command line.
Package cli implements the skinloom command line.
config
Package config loads the static (file + environment) configuration.
Package config loads the static (file + environment) configuration.
contract
Package contract turns responses of the game-facing APIs (CustomSkinLoader, USM, Legacy, texture files, Yggdrasil) into stable text: the status, the headers that are part of the contract, and the body with what changes from run to run (times, tokens, signatures) replaced by markers.
Package contract turns responses of the game-facing APIs (CustomSkinLoader, USM, Legacy, texture files, Yggdrasil) into stable text: the status, the headers that are part of the contract, and the body with what changes from run to run (times, tokens, signatures) replaced by markers.
daemon
Package daemon installs SkinLoom as a background service of the operating system (docs/design/04 §9.1, 02 F76): a systemd unit on Linux, a launchd daemon on macOS, a Windows service.
Package daemon installs SkinLoom as a background service of the operating system (docs/design/04 §9.1, 02 F76): a systemd unit on Linux, a launchd daemon on macOS, a Windows service.
gateway
Package gateway is the single public entry point.
Package gateway is the single public entry point.
hook
Package hook is the extension bus every module — and later every plugin — uses.
Package hook is the extension bus every module — and later every plugin — uses.
httpapi
Package httpapi is the backend's HTTP surface.
Package httpapi is the backend's HTTP surface.
importer/bs
Package bs imports a Blessing Skin site (design 02 §4, §5, 04 §10): accounts with their passwords, players with their UUIDs, textures with their files, closets, reports, unread notifications, OAuth applications, settings, reworded terms and the Yggdrasil signing key.
Package bs imports a Blessing Skin site (design 02 §4, §5, 04 §10): accounts with their passwords, players with their UUIDs, textures with their files, closets, reports, unread notifications, OAuth applications, settings, reworded terms and the Yggdrasil signing key.
jsrt
Package jsrt isolates the embedded JavaScript runtime behind an engine-agnostic sandbox abstraction so plugins run in pooled, memory-capped, preemptively time-bounded ES2023 isolates without CGo.
Package jsrt isolates the embedded JavaScript runtime behind an engine-agnostic sandbox abstraction so plugins run in pooled, memory-capped, preemptively time-bounded ES2023 isolates without CGo.
launcher
Package launcher runs and supervises the Next.js frontend as a child process, so one `skinloom up` starts the whole site on Windows, macOS and Linux.
Package launcher runs and supervises the Next.js frontend as a child process, so one `skinloom up` starts the whole site on Windows, macOS and Linux.
modules/account
Package account owns users, browser sessions, one-time tokens, the first-run setup and the audit log.
Package account owns users, browser sessions, one-time tokens, the first-run setup and the audit log.
modules/audit
Package audit writes the audit log (audit_logs): who did what to what, from where.
Package audit writes the audit log (audit_logs): who did what to what, from where.
modules/captcha
Package captcha verifies that a form was filled in by a person.
Package captcha verifies that a form was filled in by a person.
modules/cdn
Package cdn tells a CDN to drop its copies of a player's profile and avatar when the player changes (docs/design/02 F72), so game clients behind the CDN see a new skin without waiting for delivery.profile_cache_seconds.
Package cdn tells a CDN to drop its copies of a player's profile and avatar when the player changes (docs/design/02 F72), so game clients behind the CDN see a new skin without waiting for delivery.profile_cache_seconds.
modules/mail
Package mail sends email: an SMTP driver, a log driver for development, MIME building and the localized templates.
Package mail sends email: an SMTP driver, a log driver for development, MIME building and the localized templates.
modules/notify
Package notify keeps each user's inbox: notifications sent to them, and their copies of announcements sent to many.
Package notify keeps each user's inbox: notifications sent to them, and their copies of announcements sent to many.
modules/oauth
Package oauth is the site's OAuth 2.0 authorization server and personal access tokens (contract docs/design/02 §2.6): applications registered by users sign people in with the authorization code flow (PKCE, refresh tokens), and the tokens they get, or personal access tokens, call the Blessing Skin compatible resource API.
Package oauth is the site's OAuth 2.0 authorization server and personal access tokens (contract docs/design/02 §2.6): applications registered by users sign people in with the authorization code flow (PKCE, refresh tokens), and the tokens they get, or personal access tokens, call the Blessing Skin compatible resource API.
modules/player
Package player owns players (in-game characters): names, UUIDs, the skin and cape each one wears, and the profiles game clients fetch.
Package player owns players (in-game characters): names, UUIDs, the skin and cape each one wears, and the profiles game clients fetch.
modules/render
Package render draws avatars (a skin's head, flat or as a cube) and previews (the skin seen from the front and the back, or a cape) for /avatar and /preview.
Package render draws avatars (a skin's head, flat or as a cube) and previews (the skin seen from the front and the back, or a cape) for /avatar and /preview.
modules/report
Package report handles complaints about textures.
Package report handles complaints about textures.
modules/score
Package score changes users' scores.
Package score changes users' scores.
modules/settings
Package settings holds runtime settings that admins edit: typed definitions, a database store, and an atomically swapped snapshot that changes are hot-applied from.
Package settings holds runtime settings that admins edit: typed definitions, a database store, and an atomically swapped snapshot that changes are hot-applied from.
modules/sitesettings
Package sitesettings assembles the definitions of every module's settings into one registry, so the server and the Blessing Skin importer check settings alike.
Package sitesettings assembles the definitions of every module's settings into one registry, so the server and the Blessing Skin importer check settings alike.
modules/social
Package social signs people in with accounts they have elsewhere (contract docs/design/02 F07, F08): GitHub, Microsoft and any OpenID Connect provider, set up in auth.social.providers.
Package social signs people in with accounts they have elsewhere (contract docs/design/02 F07, F08): GitHub, Microsoft and any OpenID Connect provider, set up in auth.social.providers.
modules/stats
Package stats computes the figures of the admin overview and the home page's totals.
Package stats computes the figures of the admin overview and the home page's totals.
modules/texture
Package texture owns uploaded skins and capes: the upload pipeline, the files (blobs, reference counted), the skin library and closets.
Package texture owns uploaded skins and capes: the upload pipeline, the files (blobs, reference counted), the skin library and closets.
modules/theme
Package theme loads theme packages and resolves the active theme for a request.
Package theme loads theme packages and resolves the active theme for a request.
modules/yggdrasil
Package yggdrasil implements the Yggdrasil API that authlib-injector launchers and game servers use for external login (contract docs/design/02 §2.4): launcher tokens (authserver), joining servers (sessionserver), profile lookups and texture uploads, compatible with Blessing Skin's yggdrasil-api plugin.
Package yggdrasil implements the Yggdrasil API that authlib-injector launchers and game servers use for external login (contract docs/design/02 §2.4): launcher tokens (authserver), joining servers (sessionserver), profile lookups and texture uploads, compatible with Blessing Skin's yggdrasil-api plugin.
platform/buildinfo
Package buildinfo carries version metadata injected at build time via -ldflags.
Package buildinfo carries version metadata injected at build time via -ldflags.
platform/clip
Package clip shortens text to fit a column or a log line without cutting a UTF-8 character in half.
Package clip shortens text to fit a column or a log line without cutting a UTF-8 character in half.
platform/datalock
Package datalock marks a data directory as in use (ADR 0039).
Package datalock marks a data directory as in use (ADR 0039).
platform/db
Package db opens the database connection shared by ent and raw SQL users.
Package db opens the database connection shared by ent and raw SQL users.
platform/dbtest
Package dbtest opens migrated databases for tests: SQLite always, plus MySQL and PostgreSQL when SKINLOOM_TEST_MYSQL / SKINLOOM_TEST_POSTGRES name a test database (CI's integration job sets them).
Package dbtest opens migrated databases for tests: SQLite always, plus MySQL and PostgreSQL when SKINLOOM_TEST_MYSQL / SKINLOOM_TEST_POSTGRES name a test database (CI's integration job sets them).
platform/fsperm
Package fsperm keeps files that hold secrets private where Unix mode bits do not: on Windows a new file takes its folder's permissions, which in a data directory under C:\ or a shared folder let every local user read it (ADR 0039).
Package fsperm keeps files that hold secrets private where Unix mode bits do not: on Windows a new file takes its folder's permissions, which in a data directory under C:\ or a shared folder let every local user read it (ADR 0039).
platform/httpx
Package httpx holds small HTTP helpers shared by the API and the gateway.
Package httpx holds small HTTP helpers shared by the API and the gateway.
platform/jobs
Package jobs runs background work stored in the jobs table.
Package jobs runs background work stored in the jobs table.
platform/logging
Package logging builds the process logger; level and format can change at runtime.
Package logging builds the process logger; level and format can change at runtime.
platform/migrate
Package migrate applies the embedded versioned migrations with goose.
Package migrate applies the embedded versioned migrations with goose.
platform/pubsub
Package pubsub is the in-process fan-out used for change notifications (settings, themes, plugins) and the browser SSE stream.
Package pubsub is the in-process fan-out used for change notifications (settings, themes, plugins) and the browser SSE stream.
platform/realip
Package realip derives the real client address, scheme and host of a request.
Package realip derives the real client address, scheme and host of a request.
platform/registry
Package registry provides copy-on-write tables that can be swapped atomically while requests are being served.
Package registry provides copy-on-write tables that can be swapped atomically while requests are being served.
platform/secrets
Package secrets creates and reads the per-install secrets under <data>/secrets.
Package secrets creates and reads the per-install secrets under <data>/secrets.
platform/storage
Package storage keeps texture files.
Package storage keeps texture files.
platform/validate
Package validate holds the error types services use to reject input, so the HTTP layer can map them the same way for every module: a FieldError per bad field (422) and RateLimitError (429).
Package validate holds the error types services use to reject input, so the HTTP layer can map them the same way for every module: a FieldError per bad field (422) and RateLimitError (429).
tools/benchseed command
Command benchseed fills an empty SkinLoom database with a large site for the load tests in bench/k6 (design 04 §5.4, ADR 0038): users, a skin library of a million textures, players wearing real skin files, and the setup marker.
Command benchseed fills an empty SkinLoom database with a large site for the load tests in bench/k6 (design 04 §5.4, ADR 0038): users, a skin library of a million textures, players wearing real skin files, and the setup marker.
tools/migdiff command
Command migdiff writes a new versioned migration (goose format) for one dialect by diffing ent/schema against the replayed migration directory on a dev database.
Command migdiff writes a new versioned migration (goose format) for one dialect by diffing ent/schema against the replayed migration directory on a dev database.
tools/plugingen command
Command plugingen generates website/static/schema/plugin.v1.json and web/packages/plugin-sdk/src/gen/catalog.ts from the Go hook catalog, plugin permission table, UI slot registry, and built-in theme block definitions.
Command plugingen generates website/static/schema/plugin.v1.json and web/packages/plugin-sdk/src/gen/catalog.ts from the Go hook catalog, plugin permission table, UI slot registry, and built-in theme block definitions.
tools/protogen command
Command protogen compiles api/proto/plugin/v1/plugin.proto into Go protobuf and gRPC stubs without requiring an external C++ protoc binary.
Command protogen compiles api/proto/plugin/v1/plugin.proto into Go protobuf and gRPC stubs without requiring an external C++ protoc binary.
Package migrations embeds the versioned SQL migrations, one directory per dialect.
Package migrations embeds the versioned SQL migrations, one directory per dialect.
sdk
go
Package plugin is the official Go SDK for building Tier 2 SkinLoom native plugins.
Package plugin is the official Go SDK for building Tier 2 SkinLoom native plugins.
go/plugindb
Package plugindb provides three-dialect isolated SQL database access and goose-powered schema migrations for Tier 2 SkinLoom native Go plugins.
Package plugindb provides three-dialect isolated SQL database access and goose-powered schema migrations for Tier 2 SkinLoom native Go plugins.
go/plugintest
Package plugintest provides an in-memory mock SkinLoom host and isolated SQLite database harness so Tier 2 native Go plugins can be unit-tested with standard `go test` without launching subprocesses.
Package plugintest provides an in-memory mock SkinLoom host and isolated SQLite database harness so Tier 2 native Go plugins can be unit-tested with standard `go test` without launching subprocesses.
Package themes embeds the built-in themes.
Package themes embeds the built-in themes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL