---
url: /handbook.md
---
# 知识手册（架构与模块）

> 本手册由 Qoder 知识中心的 Repo Wiki 生成后**整册迁入**（快照 2026-11-15，源码引用钉在
> `797ae1a`），迁移时做过隐私与措辞扫描、链接体检。深度逐条校对随增量同步节奏进行——
> 发现与代码不符之处请开 Issue。
>
> 三条使用约定：
>
> 1. **契约与部署以主目录为准**：环境变量表见 [`../deploy.md`](../deploy.md)，
>    迁移步骤见 [`../migration.md`](../migration.md)，插件/主题规范见
>    [`../plugin-spec.md`](../plugin-spec.md) / [`../theme-spec.md`](../theme-spec.md)。
>    本手册讲「实现是怎么长的」，主目录讲「对外承诺什么」。
> 2. **mermaid 图**：仓库页面直接渲染；文档站需主题支持（换 just-the-docs 后可视化）。
> 3. 页首「本文引用的文件」链接钉在快照 commit 上，长期有效但行号以快照为准。

## 入门

[项目概览与快速开始](项目概览与快速开始.md) · [快速开始](快速开始.md) · [开发指南](开发指南.md) · [故障排除与常见问题](故障排除与常见问题.md)

## 总体架构

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

## 存储与迁移

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

## 账号、协议与接入

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

## 材质与皮肤库

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

## 插件与主题

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

## API 参考

[API-参考](API-参考.md) · [API-客户端封装](API-客户端封装.md) · [Web-API（-api-v1）](Web-API（-api-v1）.md) · [管理-API（-api-admin）](管理-API（-api-admin）.md) · [公开只读-API（-api-public-v1）](公开只读-API（-api-public-v1）.md)

## 前端

[前端架构](前端架构.md) · [组件体系](组件体系.md) · [页面与路由](页面与路由.md) · [国际化](国际化.md)

## 管理面板

[面板概览与导航](面板概览与导航.md) · [仪表盘](仪表盘.md) · [站点设置](站点设置.md) · [举报、通知与任务](举报、通知与任务.md)

## 运维与安全

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

## 功能专题

[UGC-文本过滤与审核举报](UGC-文本过滤与审核举报.md) · [后台任务模块](后台任务模块.md) · [邮件服务集成](邮件服务集成.md)