如何快速看懂 Questarr 系统架构：React + Express + Drizzle 三层 TypeScript 设计完整指南

Questarr 是一款 *Arr 风格的自托管游戏管理器，帮你发现、追踪并自动下载想玩的游戏。本文带你快速拆解 Questarr 系统架构：前端 React 19 单页应用、后端 Express REST API、底层 Drizzle ORM 数据层，三块如何在一个 TypeScript 代码库里协作，新手也能一次看懂 🎮

一、三层架构总览：一个仓库，三种职责

Questarr 最特别的一点：它不是 monorepo，而是单一package.json下的三层 TypeScript 应用（见 docs/ARCHITECTURE.md）：

这个设计有一个关键规则：浏览器从不直接接触数据库、外部服务或下载客户端，所有动作都必须经过服务端中转。服务端因此成为整个系统的"中心信任边界"。

浏览器 (React SPA) │ HTTP REST (JWT) + Socket.io ▼ Express 服务端 ── 路由 / 认证 / 定时任务 / 搜索编排 │ ├─ Drizzle ORM (storage.ts) ──▶ SQLite / PostgreSQL ├─ safeFetch (SSRF 防护) ──▶ 索引器 / 下载客户端 / IGDB └─ 定时任务 (cron.ts) ──▶ 状态轮询与自动下载

下面逐层拆解。

二、前端层：React 19 单页应用如何组织

前端入口是 client/src/App.tsx，核心选型只有几个，但每个都切中"自托管管理面板"的痛点：

• 路由：使用轻量级 wouter 而非重型路由库，SPA 体积更小
• 服务端状态：用 TanStack Query 统一管理所有 API 请求的缓存与刷新
• 按需加载：所有页面通过React.lazy做代码分割，首屏只加载当前路由
• 实时通道：通过 client/src/lib/socket.ts 建立 Socket.io 连接，接收下载进度、通知推送等事件
• 主题：next-themes提供明暗主题切换

一个直观的例子：你在游戏中点击"搜索资源"，页面发起GET /api/indexers/search（携带 JWT），TanStack Query 缓存结果并渲染列表——整个过程前端不关心数据来自哪个索引器、经过多少次去重，这些都是服务端的职责。

三、后端层：Express 如何编排所有业务

3.1 统一请求路径

服务端每个 REST 请求都走同一条链路：

Client → 路由（server/routes.ts等，经 express-validator/Zod 校验）→storage.ts（Drizzle 查询）→ JSON 响应

路由从不直接碰数据库——所有读写都收敛到 server/storage.ts 这一个模块，它是应用数据层唯一导入 Drizzledb客户端的地方。这种"漏斗式"设计让数据访问点集中，便于维护与审计。

3.2 中间件与安全配置

应用工厂 server/app.ts 负责装配中间件，顺序经过精心考量：

• 最早注册安全响应头（X-Robots-Tag: noindex防止自托管面板被搜索引擎收录）
• CORS 白名单、JSON 请求体 5MB 上限
• express-rate-limit限流（尤其保护登录接口）
• 每个/api请求记录方法、路径、状态码与耗时日志
• 认证中间件authenticateToken（server/auth.ts）基于 JWT 放行受保护路由

3.3 出站请求：safeFetch 的 SSRF 防线

所有对外调用（索引器、下载客户端、HowLongToBeat、NexusMods、Steam、IGDB）都强制经过 server/ssrf.ts 中的safeFetch：无条件屏蔽链路本地/云元数据/广播网段，并对每个解析出的 IP 二次校验，防止 DNS 重绑定攻击。allowPrivate默认开启是有意为之——Questarr 本来就部署在与下载器同一条内网里。

3.4 后台定时任务：无人值守的自动下载

server/cron.ts 是 Questarr"自动下载游戏"的核心引擎：

配合下载器抽象层 server/downloaders/（DownloaderManager），Questarr 以统一接口对接 qBittorrent、Transmission、rTorrent、SABnzbd、NZBGet 五种下载客户端，你只需在设置页配置，底层差异全部被屏蔽。

四、数据层：Drizzle ORM 一份 schema 喂饱两端

数据层的精髓在shared/目录：shared/schema.ts 用 Drizzle 定义全部表结构（games、user_settings、indexers、downloaders等），并通过drizzle-zod的createInsertSchema直接生成 Zod 校验 schema——数据库结构与请求校验共用一份定义，前后端天然类型一致。

4.1 SQLite 默认，PostgreSQL 可选

数据库驱动选择在 server/db.ts：

• 默认SQLite，零配置开箱即用
• 显式设置DB_DIALECT=postgres+DATABASE_URL才切换 PostgreSQL（注意：仅设置DATABASE_URL不会自动切换，避免升级时误换库造成数据丢失）
• 上层存储门面 server/storage.ts 对两种方言暴露完全相同的 API，业务代码无感知

4.2 迁移管理

两套迁移目录与方言一一对应：

• migrations/ — SQLite 迁移，由 drizzle.config.ts 基于shared/schema.ts生成
• migrations-pg/ — PostgreSQL 迁移，对应 drizzle.config.pg.ts

服务启动时 server/migrate.ts 的ensureDatabase()会先确保迁移完成再启动，开发者本地则可用npm run db:generate/npm run db:migrate管理（详见 docs/DATABASE.md）。

五、值得借鉴的架构决策

1. 单仓三层而非 monorepo：小团队项目少一层工具链开销，shared/用一个目录就解决了前后端契约问题
2. 数据访问单点收口：所有 DB 读写只走storage.ts，测试与审计都有明确抓手
3. schema 即校验：Drizzle + drizzle-zod 让"数据库定义"和"输入校验"永不漂移
4. 出站流量统一护栏：safeFetch一处收口所有第三方调用，SSRF 防护不会被新集成遗漏
5. REST + WebSocket 分工明确：命令式操作用 REST，状态变化（下载进度、扫描进度、日志流）用 Socket.io 推送

Questarr 目前定位为"一个实例一个受信操作者"的自托管应用（详见 docs/ARCHITECTURE.md 多用户章节），架构设计也围绕这一信任模型做了取舍。

六、快速上手：从仓库到运行

想要亲手验证这套架构，推荐路径：

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/qu/Questarr
2. 阅读 docs/ARCHITECTURE.md 中的 actor 表与数据流图
3. 本地开发：npm install后执行npm run dev（Vite 以中间件模式挂载在 Express 上，热更新与 API 同源，见 server/vite.ts）
4. 部署可选 Docker（Dockerfile / docker-compose.yml）、Helm Chart（charts/questarr/）、Proxmox LXC 或 Unraid 社区应用

七、总结

Questarr 系统架构的三层 TypeScript 设计可以一句话概括：React 19 SPA 负责"看"，Express 负责"做"，Drizzle ORM 负责"存"，shared/目录负责让三者说同一种语言。对想学习自托管应用架构的开发者来说，这套代码库从 SSRF 防护、限流到双数据库方言切换都有清晰的工程示范，是一个值得通读的小型完整项目。