快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• package.json
• .env.development
• docker-compose.yml
• back/index.ts
• back/procedures/index.ts
• Dockerfile
• vite.config.ts
• eslint.config.js
• back/init.ts

Monoproject 是一个单体全栈脚手架项目，采用 Vite 作为统一构建工具，后端使用 Fastify + tRPC + MongoDB + Redis，前端使用 React + TailwindCSS。该架构适合中小型团队快速启动项目，无需复杂的微服务拆分，同时保留了良好的扩展性。

环境准备与依赖安装

技术栈概览

该项目采用单体仓库架构，前后端共享同一套依赖体系。核心技术组件包括：

根据 README.md:1-25 的说明，项目采用全依赖模式，不区分 dependencies 与 devDependencies，简化了依赖管理复杂度。

依赖安装步骤

项目使用 pnpm 作为包管理器。安装前需确保系统已安装 Node.js 22.x 及 pnpm。

bash
1# 克隆仓库（示例命令，需替换为实际仓库地址）
2git clone <repository-url>
3cd monoproject
4
5# 安装依赖
6pnpm install

根据 package.json:1-49 的依赖清单，安装过程会自动下载所有必需的运行时和构建依赖，包括 TypeScript 编译器、ESLint、Vite 插件等。

环境变量配置

项目使用 .env 文件管理环境变量。开发环境需创建 .env.development 文件，参考 .env.development:1-5 的配置模板：

bash
1# .env.development 示例
2NODE_ENV=development
3MONGO_URI=mongodb://admin:1234@localhost:5552
4MONGO_NAME=template
5REDIS_URI=redis://:1234@localhost:5553
6DEFAULT_USER_ID=template-default-user

关键配置项说明：

本地开发环境启动

端口分配规划

根据 README.md:7-13 的说明，项目需要预留 4-5 个端口：

数据库服务启动

项目提供 docker-compose.yml 用于本地数据库服务部署。根据 docker-compose.yml:1-49 的配置，执行以下命令启动数据库：

bash
1# 启动 MongoDB 和 Redis 容器
2docker compose up -d mongo redis

该命令会启动两个容器：

• template-mongo：MongoDB 实例，映射端口 5552
• template-redis：Redis 实例，映射端口 5553，启用 AOF 持久化

后端服务启动

根据 package.json:9 的脚本定义，后端开发服务启动命令为：

bash
1pnpm back

该命令执行 tsx watch 启动后端服务，具有热重载功能。根据 back/index.ts:97-98，服务启动后会输出：

服务器运行在内网： http://0.0.0.0:5550
数据库迁移完成，当前版本：v.x.x
定时任务启动完成

前端开发服务器启动

根据 package.json:7 的脚本定义，前端开发服务启动命令为：

bash
1pnpm dev

根据 vite.config.ts:39-42 的配置，Vite 开发服务器监听 0.0.0.0:5551，支持局域网访问。

最短可运行路径（推荐）

完整的本地开发环境启动流程如下：

bash
1# 1. 安装依赖
2pnpm install
3
4# 2. 启动数据库服务
5docker compose up -d mongo redis
6
7# 3. 启动后端服务（终端 1）
8pnpm back
9
10# 4. 启动前端服务（终端 2）
11pnpm dev

启动完成后可访问：

• 前端应用：http://localhost:5551
• 后端 API 文档：http://localhost:5550/doc（仅开发环境可用，参考 README.md:25）

后端服务架构

Fastify 实例初始化

后端服务基于 Fastify 框架构建。根据 back/init.ts:1-36，初始化流程注册了以下核心插件：

typescript
1// 核心插件注册顺序
21. CORS（仅开发环境启用，允许所有来源）
32. JWT（用于身份认证）
43. Redis（缓存服务）
54. MongoDB（数据库连接）

关键配置项：

• logger: false：禁用 Fastify 默认日志
• maxParamLength: 5000：路由参数最大长度

tRPC 路由配置

根据 back/index.ts:17-61，tRPC 插件配置包含：

上下文创建逻辑（back/index.ts:21-56）：

1. 检查请求路径是否在白名单中
2. 白名单路径直接返回基础上下文
3. 非白名单路径验证 Authorization 头
4. 开发环境支持使用 DEFAULT_USER_ID 绕过认证

定时任务调度

项目使用 node-cron 实现定时任务。根据 back/procedures/index.ts:1-11，开发环境下会启动示例定时任务：

typescript
1// 每 10 秒执行一次（仅开发环境）
2cron.schedule("*/10 * * * * *", testService, {
3  timezone: "Asia/Shanghai",
4})

API 文档生成

开发环境下，项目使用 trpc-to-openapi 和 @scalar/fastify-api-reference 生成 API 文档。根据 back/index.ts:63-94，文档配置包括：

• 文档路径：/doc
• 认证方式：Bearer Token
• 默认 Token：process.env.DEFAULT_USER_ID

生产环境部署

Docker 镜像构建

根据 Dockerfile:1-9，生产环境镜像构建流程：

dockerfile
1# 基础镜像
2FROM node:22-alpine
3
4# 构建步骤
51. 复制 package.json 和 pnpm-lock.yaml
62. 全局安装 pnpm
73. 安装依赖（使用 npmmirror 镜像源）
84. 复制源代码
95. 执行构建命令（pnpm build）

容器编排配置

根据 docker-compose.yml:1-49，生产环境包含四个服务：

正在加载图表渲染器...

服务依赖关系：

1. backend 依赖 mongo 和 redis
2. nginx 依赖 backend

部署脚本执行

根据 README.md:23，生产环境通过 Jenkins 执行 deploy.sh 脚本进行部署。部署前需确保脚本具有执行权限：

bash
1# 赋予脚本执行权限（建议/常见做法，未在仓库证据中出现）
2chmod +x deploy.sh
3
4# 执行部署
5./deploy.sh

生产环境启动命令（package.json:10）：

bash
1pnpm back:prod

该命令使用 .env.production 环境变量文件，不启用热重载功能。

代码规范与开发工具

ESLint 配置

项目使用 ESLint 9.x 扁平化配置。根据 eslint.config.js:1-27，配置包含：

自定义规则调整：

• react-refresh/only-export-components: off：允许非组件导出
• @typescript-eslint/no-explicit-any: off：允许 any 类型

全局忽略配置：dist 目录被排除在检查范围外。

TypeScript 配置

根据 package.json:24，项目使用 @tsconfig/node22 预设配置，适配 Node.js 22.x 运行时。构建命令（package.json:8）：

bash
1pnpm build

该命令执行 tsc -b 进行类型检查，随后运行 vite build 构建前端资源。

React Compiler 优化

项目集成了 React 19 的编译器优化。根据 vite.config.ts:8-12，Vite 配置启用了 babel-plugin-react-compiler：

typescript
1react({
2  babel: {
3    plugins: [["babel-plugin-react-compiler"]],
4  },
5})

该插件可自动优化 React 组件的渲染性能，减少不必要的重渲染。

多页面应用支持

根据 vite.config.ts:31-37，项目配置为多页面应用：

开发服务器通过中间件实现路由重写（vite.config.ts:14-27），确保刷新页面时正确加载对应入口文件。

运行验证

后端服务健康检查

后端服务启动后，可通过以下方式验证：

1. 控制台输出检查：确认输出包含以下关键信息（back/index.ts:97-102）：

   服务器运行在内网： http://0.0.0.0:5550
   数据库迁移完成，当前版本：v.x.x
   定时任务启动完成
   

2. API 文档访问：开发环境下访问 http://localhost:5550/doc，应显示 Scalar API 文档界面（back/index.ts:80-81）。

3. tRPC 端点测试：访问 http://localhost:5550/rpc 应返回 tRPC 响应（back/index.ts:18）。

前端服务验证

前端开发服务器启动后：

1. 访问 http://localhost:5551 应显示应用首页
2. 访问 http://localhost:5551/admin 应加载 admin 入口
3. 访问 http://localhost:5551/pc 应加载 pc 入口

数据库连接验证

MongoDB 连接可通过以下方式验证（建议/常见做法，未在仓库证据中出现）：

bash
1# 使用 mongosh 连接
2mongosh "mongodb://admin:1234@localhost:5552/template"

Redis 连接验证：

bash
1# 使用 redis-cli 连接
2redis-cli -p 5553 -a 1234 ping
3# 预期输出：PONG

常见问题与排错

问题 1：端口冲突

症状：启动服务时报 EADDRINUSE 错误。

原因：5550-5553 端口范围内有其他进程占用。

解决方案：

1. 检查端口占用情况：

   bash
   1# macOS/Linux
   2lsof -i :5550 -i :5551 -i :5552 -i :5553

2. 终止占用进程或修改项目端口配置（需同步修改 .env.development、vite.config.ts、docker-compose.yml 中的端口设置）。

问题 2：数据库连接失败

症状：后端启动时报 MongoDB 或 Redis 连接错误。

原因：数据库容器未启动或连接字符串配置错误。

解决方案：

1. 确认容器运行状态：

   bash
   1docker compose ps

2. 检查 .env.development 中的连接字符串与 docker-compose.yml 配置是否一致（.env.development:2-4，docker-compose.yml:6-7）。

问题 3：API 文档无法访问

症状：访问 /doc 路径返回 404。

原因：非开发环境运行，或环境变量 NODE_ENV 未正确设置。

解决方案：

1. 确认 NODE_ENV=development（.env.development:1）
2. 确认使用 pnpm back 命令启动（而非 pnpm back:prod）
3. API 文档仅在开发环境启用（back/index.ts:63）

问题 4：前端热更新不生效

症状：修改代码后浏览器未自动刷新。

原因：Vite HMR WebSocket 连接失败。

解决方案：

1. 检查 vite.config.ts 中 server.host 配置为 0.0.0.0（vite.config.ts:40）
2. 如果通过局域网访问，需确保防火墙允许 5551 端口通信
3. 检查浏览器控制台是否有 WebSocket 连接错误

问题 5：Docker 构建失败

症状：执行 docker compose build 时报错。

原因：依赖安装失败或构建上下文问题。

解决方案：

1. 检查 pnpm-lock.yaml 文件是否存在（Dockerfile:5）
2. 确认 Dockerfile 位于项目根目录（Dockerfile:3）
3. 清理 Docker 构建缓存后重试：

   bash
   1docker compose build --no-cache

下一步建议

完成快速上手后，建议按以下路径深入学习：

1. API 开发指南：查阅 tRPC 路由定义与 OpenAPI 集成方式，了解如何添加新的 API 端点
2. 数据库模型设计：学习 MongoDB Schema 设计最佳实践及迁移脚本编写
3. 前端架构详解：深入了解多页面应用路由配置与状态管理方案
4. 生产部署流程：研究 CI/CD 流水线配置与容器化部署策略

项目采用单体架构设计，适合快速迭代开发。随着业务复杂度增长，可考虑将后端服务拆分为独立微服务，或引入消息队列处理异步任务。