知识手册（架构与模块）

本手册由 Qoder 知识中心的 Repo Wiki 生成后整册迁入（快照 2026-11-15，源码引用钉在 797ae1a），迁移时做过隐私与措辞扫描、链接体检。深度逐条校对随增量同步节奏进行—— 发现与代码不符之处请开 Issue。

三条使用约定：

1. 契约与部署以主目录为准：环境变量表见 ../deploy.md， 迁移步骤见 ../migration.md，插件/主题规范见 ../plugin-spec.md / ../theme-spec.md。 本手册讲「实现是怎么长的」，主目录讲「对外承诺什么」。
2. mermaid 图：仓库页面直接渲染；文档站需主题支持（换 just-the-docs 后可视化）。
3. 页首「本文引用的文件」链接钉在快照 commit 上，长期有效但行号以快照为准。

入门

项目概览与快速开始 · 快速开始 · 开发指南 · 故障排除与常见问题

总体架构

系统架构总览 · 后端核心模块 · 应用入口与外壳 · 路由系统与-API-暴露 · 数据模型 · 状态管理与领域模型

存储与迁移

多引擎存储抽象模块 · 方言适配与-dbx-抽象层 · 数据库与迁移 · 数据库选型与迁移 · 迁移系统

账号、协议与接入

认证与账户系统 · 本地账号与密码认证 · 密码与认证模块 · 账户与角色模块 · 用户管理 · 玩家与角色管理 · 邀请码与注册门禁 · 邮箱验证门禁与通知 · Yggdrasil-协议实现 · Yggdrasil-协议-API · 内置-OIDC-提供者 · OIDC-提供者模块 · OIDC-第三方登录集成 · 启动器-Bearer-API · 协议与外部集成

材质与皮肤库

纹理上传与处理管线 · 纹理处理与材质模块 · 皮肤与材质管理 · 材质管理 · 皮肤库浏览与筛选 · 头像生成与材质元数据

插件与主题

插件系统 · 插件架构与生命周期 · 插件管理 · 插件开发指南 · 插件-API（-api-plugins---v1） · Manifest-v2-规范 · 事件总线与钩子 · UI-插槽与-iframe-集成 · 主题系统 · 主题市场

API 参考

API-参考 · API-客户端封装 · Web-API（-api-v1） · 管理-API（-api-admin） · 公开只读-API（-api-public-v1）

前端

前端架构 · 组件体系 · 页面与路由 · 国际化

管理面板

面板概览与导航 · 仪表盘 · 站点设置 · 举报、通知与任务

运维与安全

部署与运维 · Docker-部署 · 构建与开发环境 · 二进制与源码构建 · 环境变量参考 · 反向代理配置 · 备份与恢复 · 备份与灾难恢复 · 监控与健康检查 · 性能与可扩展性 · 安全与合规 · 安全模型与沙箱限制 · 审计与访问日志 · 访问日志与审计模块 · 出站请求安全封装 · 测试与质量保障

功能专题

UGC-文本过滤与审核举报 · 后台任务模块 · 邮件服务集成