跳到主要内容

架构

一张图​

浏览器 / 游戏 / 启动器
│ :17546(唯一对外端口)
▼
┌──────────────── skinloom(Go,一个程序)────────────────┐
│ gateway 后端路径 → httpapi;/_next/static → 磁盘;其余 → Next.js │
│ httpapi /api/v1(Huma)· 游戏协议 · OAuth · BS 兼容接口 · /events │
│ modules 账号 · 材质 · 角色 · 积分 · 举报 · 通知 · 外置登录 …… │
│ plugin 双层插件与主题引擎(QuickJS 沙箱 + Native gRPC + 签名市场) │
│ hook 领域事件与前置拦截(随事务写入任务队列,提交后投递) │
│ platform 数据库 · 任务队列 · 存储 · 日志 · 发布订阅 …… │
└──────────────────────────┬─────────────────────────────┘
▲ 服务端渲染时调用内部 API │
┌───────┴────────┐ ▼
│ Next.js 前端 │ SQLite / MySQL / PostgreSQL · 本地盘 / S3
│(子进程或独立部署)│ + Tier 2 Native 插件子进程(双向 gRPC + 隔离 SQL)
└────────────────┘
  • 一个程序、一个端口:skinloom up 启动后端,再拉起并看管 Next.js 子进程。大站可以把前端单独部署、多开(web.mode = external)。
  • 模块化单体:业务按模块分包,模块之间直接调用对方的 Service;没有微服务,没有消息中间件。
  • 热加载:站点设置、主题、配置文件改了立即生效。设置保存后递增配置版本号,各节点通过 /events(SSE)通知浏览器刷新。

目录​

cmd/skinloom/ main:只调用 internal/cli
internal/
cli/ 命令行(cobra),每组命令一个文件
app/ 装配:创建各个服务、启动 HTTP 与后台任务(core.go、run.go)
config/ config.toml 与环境变量
gateway/ 唯一入口:按路径分给后端或前端
launcher/ 启动、看管 Next.js 子进程
daemon/ 注册为系统服务(systemd / launchd / Windows 服务)
backup/ 备份与恢复
httpapi/ HTTP 层:把请求翻译成 Service 调用(doc.go 有文件索引)
hook/ 扩展总线:领域事件与前置 Filter,供内置模块与插件接入
plugin/ 双层插件与主题运行时(Tier 1 QuickJS + Tier 2 Native gRPC)、.slp 签名与官方市场客户端
jsrt/ QuickJS/WASM 沙箱实例池(指令燃料上限与内存配额)
modules/ 业务模块,每个包拥有自己的表和规则
account/ 用户、会话、安装、注册登录、审计入口
texture/ 上传、皮肤库、衣柜、材质管理与文件清理
player/ score/ report/ notify/ render/ theme/ settings/ ……
oauth/ yggdrasil/ social/ cdn/ captcha/ mail/
platform/ 与业务无关的基础设施
db/ dbtest/ migrate/ jobs/ storage/ pubsub/ logging/ ……
importer/bs/ 从 Blessing Skin 导入
contract/ 游戏接口的契约测试工具
tools/ 开发工具:migdiff(生成迁移)、plugingen(插件契约生成)、protogen(gRPC 生成)、benchseed(压测数据)
sdk/go/ Go 原生插件 SDK(Host API、plugindb 隔离 SQL 迁移器、plugintest 内存宿主测试套件)
ent/schema/ 数据模型(ent),生成代码在 ent/ 下
migrations/ SQLite、MySQL、PostgreSQL 各一套迁移(生成后提交)
api/
openapi.json 由代码生成的 OpenAPI 3.1 文档
proto/plugin/v1/ 宿主 ↔ Native 插件子进程双向 gRPC 契约(plugin.proto)
themes/ 内置主题包
web/ 前端与插件工具链:apps/web(Next.js)、packages/{ui,api-client,plugin-sdk,cli,create-plugin}
website/ 本文档站与开发日志
deploy/ Dockerfile、Compose、Kubernetes、Helm、打包脚本
docs/design/ docs/adr/ 设计文档与架构决策记录

依赖方向:cli → app → httpapi → modules → platform。platform 不认识任何业务;modules 之间可以互相调用,但不依赖 httpapi。

一个请求怎么走​

以"收藏材质"为例:

  1. gateway 看到 /api/v1/me/closet 属于后端,交给 httpapi。
  2. 中间件解析客户端地址(只信任配置过的代理)、会话 Cookie,并检查 CSRF 头。
  3. httpapi/manage.go 的处理函数校验参数,调用 texture.Service.Favorite。
  4. Favorite 在一个事务里按固定顺序加锁(材质 → 用户),重新读取要依据的数据,写衣柜、扣积分、记积分流水,并把领域事件写进同一个事务。
  5. 提交后,任务队列把事件投递给订阅者(如 CDN 刷新)。

写代码时要遵守的规则​

这些规则都来自真实的 bug,详见 ADR:

规则为什么ADR
不变量写进数据库(唯一、外键、CHECK),积分和计数用原子更新应用层检查挡不住并发0019
事务先加锁、再判断:按"材质 → 用户(id 升序)→ 角色 → 其它"加锁,加锁后重新读取决定结果的数据否则并发时会重复扣费或死锁0026、0027
审计记录和领域事件写在同一个事务里事务回滚时不会留下假记录或发出假事件0028
事务一律用 db.WithTx统一提交、回滚,panic 时也会回滚、释放锁0040
每个新事务都要有并发测试(dbtest.ForEach),在 PostgreSQL 上跑SQLite 单写者,很多竞态在它上面测不出来0026
请求路径上不做运维动作(迁移、清缓存、写配置)请求可能并发、可能被取消0003
后端保留路径(/api/、/csl/ 等,见 internal/gateway)前端不得占用网关按路径分流0001
注释写"为什么",不写"做了什么"代码已经说明了做了什么—

深入阅读​