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

【免费下载链接】QuestarrQuestarr is an *Arr-inspired game manager that helps you discover, track, and automatically download the games you want.项目地址https://gitcode.com/gh_mirrors/qu/Questarr点击查看免费下载Questarr 是一款 *Arr 风格的自托管游戏管理器帮你发现、追踪并自动下载想玩的游戏。本文带你快速拆解 Questarr 系统架构前端 React 19 单页应用、后端 Express REST API、底层 Drizzle ORM 数据层三块如何在一个 TypeScript 代码库里协作新手也能一次看懂 一、三层架构总览一个仓库三种职责Questarr 最特别的一点它不是 monorepo而是单一package.json下的三层 TypeScript 应用见 docs/ARCHITECTURE.md目录职责核心技术client/前端展示层React 19 SPAReact 19、Wouter 路由、TanStack Query、Tailwind CSSserver/后端业务层REST WebSocketExpress、Socket.io、Zod 校验shared/共享数据契约层Drizzle ORM schema、Zod 校验 schema这个设计有一个关键规则浏览器从不直接接触数据库、外部服务或下载客户端所有动作都必须经过服务端中转。服务端因此成为整个系统的中心信任边界。浏览器 (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携带 JWTTanStack Query 缓存结果并渲染列表——整个过程前端不关心数据来自哪个索引器、经过多少次去重这些都是服务端的职责。三、后端层Express 如何编排所有业务3.1 统一请求路径服务端每个 REST 请求都走同一条链路Client → 路由server/routes.ts等经 express-validator/Zod 校验→storage.tsDrizzle 查询→ JSON 响应路由从不直接碰数据库——所有读写都收敛到 server/storage.ts 这一个模块它是应用数据层唯一导入 Drizzledb客户端的地方。这种漏斗式设计让数据访问点集中便于维护与审计。3.2 中间件与安全配置应用工厂 server/app.ts 负责装配中间件顺序经过精心考量最早注册安全响应头X-Robots-Tag: noindex防止自托管面板被搜索引擎收录CORS 白名单、JSON 请求体 5MB 上限express-rate-limit限流尤其保护登录接口每个/api请求记录方法、路径、状态码与耗时日志认证中间件authenticateTokenserver/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自动下载游戏的核心引擎任务间隔作用checkDownloadStatus1 分钟轮询下载客户端状态变化即经 Socket.io 推送downloadUpdatecheckAutoSearch1 小时按用户配置间隔向索引器自动搜索可触发自动下载checkGameUpdates24 小时从 IGDB 批量拉取游戏资料更新checkXrelReleases6 小时监控 xREL.to 场景发布checkSteamWishlist1 小时可选同步 Steam 愿望单并匹配 IGDBRSS 刷新1 小时拉取用户配置的 RSS 订阅源配合下载器抽象层 server/downloaders/DownloaderManagerQuestarr 以统一接口对接 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_DIALECTpostgresDATABASE_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。五、值得借鉴的架构决策单仓三层而非 monorepo小团队项目少一层工具链开销shared/用一个目录就解决了前后端契约问题数据访问单点收口所有 DB 读写只走storage.ts测试与审计都有明确抓手schema 即校验Drizzle drizzle-zod 让数据库定义和输入校验永不漂移出站流量统一护栏safeFetch一处收口所有第三方调用SSRF 防护不会被新集成遗漏REST WebSocket 分工明确命令式操作用 REST状态变化下载进度、扫描进度、日志流用 Socket.io 推送Questarr 目前定位为一个实例一个受信操作者的自托管应用详见 docs/ARCHITECTURE.md 多用户章节架构设计也围绕这一信任模型做了取舍。六、快速上手从仓库到运行想要亲手验证这套架构推荐路径克隆仓库git clone https://gitcode.com/gh_mirrors/qu/Questarr阅读 docs/ARCHITECTURE.md 中的 actor 表与数据流图本地开发npm install后执行npm run devVite 以中间件模式挂载在 Express 上热更新与 API 同源见 server/vite.ts部署可选 DockerDockerfile / docker-compose.yml、Helm Chartcharts/questarr/、Proxmox LXC 或 Unraid 社区应用七、总结Questarr 系统架构的三层 TypeScript 设计可以一句话概括React 19 SPA 负责看Express 负责做Drizzle ORM 负责存shared/目录负责让三者说同一种语言。对想学习自托管应用架构的开发者来说这套代码库从 SSRF 防护、限流到双数据库方言切换都有清晰的工程示范是一个值得通读的小型完整项目。赞分享【免费下载链接】QuestarrQuestarr is an *Arr-inspired game manager that helps you discover, track, and automatically download the games you want.项目地址https://gitcode.com/gh_mirrors/qu/Questarr点击查看免费下载相关推荐如何看懂这个开源电商系统Next.js Express MySQL 三层架构完整拆解如何看懂这个开源电商系统Next.js Express MySQL 三层架构完整拆解 SingitronicElectronics eCommerc电商后端前端如何快速看懂 Native Shell 三层架构nsh-core、nsh-base 与你的组件库如何分工完整指南如何快速看懂 Native Shell 三层架构nsh core、nsh base 与你的组件库如何分工完整指南 Native ShellNSH是一个10分钟上手Grounded-SAM文本驱动图像分割入门指南10分钟上手Grounded SAM文本驱动图像分割入门指南 手工标注一批图片动辄折腾好几天。Grounded SAM把目标检测和图像分割拼成一条流水线你计算机视觉人工智能示例工程多模态上一篇突破分割边界Segment Anything如何用动态IoU预测重构损失函数设计下一篇3种Layui表单布局技巧让界面瞬间专业起来创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考