Decode 项目

这是一个基于 pnpm 工作空间的 monorepo 项目，包含前端和后端应用。项目采用现代化的全栈开发架构，支持多环境部署和容器化运行。

技术栈

前端

React: 用于构建用户界面的 JavaScript 库
Vite: 现代前端构建工具，提供极速的开发体验
TypeScript: 类型安全的 JavaScript 超集
React Router: 前端路由管理
Axios: HTTP 客户端

后端

NestJS: 基于 Node.js 的渐进式服务端框架
MongoDB: NoSQL 数据库
TypeScript: 类型安全的 JavaScript 超集
JWT: 用户认证和授权
Docker: 容器化部署

目录结构

decode/
├── apps/                   # 应用程序目录
│   ├── app-mobile/          # 移动端应用
│   ├── app-pc/              # PC 端 Nuxt 应用
│   ├── admin/               # 管理后台 React 应用
│   │   ├── Dockerfile      # 开发环境 Docker 配置
│   │   ├── Dockerfile.prod # 生产环境 Docker 配置
│   │   ├── tsconfig.json   # TypeScript 配置文件
│   │   ├── tsconfig.node.json # Vite 构建工具 TypeScript 配置
│   │   ├── vite.config.ts  # Vite 配置文件
│   │   └── src/            # 前端源代码
│   │       ├── assets/     # 静态资源
│   │       ├── vite-env.d.ts # Vite 环境类型声明文件
│   │       ├── App.tsx     # 主应用组件
│   │       ├── App.css     # 应用样式
│   │       ├── main.tsx    # 应用入口文件
│   │       └── index.css   # 全局样式
│   └── server/             # 后端 NestJS 服务
│       ├── Dockerfile      # 开发环境 Docker 配置
│       ├── Dockerfile.prod # 生产环境 Docker 配置
│       ├── tsconfig.json   # TypeScript 配置文件
│       ├── tsconfig.build.json # 构建用 TypeScript 配置
│       └── src/            # 后端源代码
├── packages/               # 共享包目录
│   ├── config/             # 共享配置
│   │   └── src/            # 配置源代码
│   ├── shared/             # 共享代码
│   │   ├── decodeToEn/     # 业务相关
│   │   ├── lib/            # 工具库
│   │   └── src/            # 源代码
│   └── ui/                 # 共享 UI 组件
│       └── src/            # UI 组件源代码
├── deployments/            # 部署相关配置
│   ├── docker-compose.prod.yml # 生产环境 Docker Compose 配置
│   └── nginx.conf          # Nginx 配置
├── scripts/                # 脚本文件
│   └── deploy.mjs          # 部署脚本（ES 模块）
├── tsconfig.json           # 根级 TypeScript 配置文件（共享配置）
├── docker-compose.yml      # 开发环境 Docker Compose 配置
├── document/               # 项目文档
├── .env.development        # 开发环境配置文件
├── .env.production         # 生产环境配置文件
├── .env.example            # 环境变量示例文件
└── .github/                # GitHub 相关配置
    └── workflows/          # GitHub Actions 工作流
        ├── ci.yml          # 持续集成配置
        └── cd.yml          # 持续部署配置

安装依赖

本项目使用 pnpm 作为包管理器。请确保已安装 Node.js (推荐 v18+) 和 pnpm。

安装 pnpm (如果尚未安装):

npm install -g pnpm

安装项目依赖:

# 在项目根目录执行
pnpm install

启动项目

开发环境

方法一：启动所有服务

# 在项目根目录执行
pnpm dev

这将启动所有工作空间中的开发服务器。

方法二：启动特定服务

# 启动后端服务
cd apps/server
pnpm dev

# 启动 PC 端前端
cd apps/admin
pnpm dev

# 启动 PC 端 Nuxt 应用
cd apps/app-pc
pnpm dev

# 启动移动端 H5
cd apps/app-mobile
pnpm dev

方法三：使用 Docker Compose

# 在项目根目录执行
docker-compose up

访问应用

PC 端前端: http://localhost:5173
后端 API: http://localhost:4000
MongoDB 数据库: mongodb://localhost:27018

构建项目

# 构建所有应用
pnpm build

# 构建特定应用
cd apps/admin
pnpm build

环境变量配置

项目支持多环境配置，可以为开发和生产环境使用不同的环境变量。

环境文件优先级

系统会按以下优先级加载环境变量文件：

.env.{NODE_ENV} - 环境特定文件（如 .env.production、.env.development）
.env.local - 本地覆盖文件（通常不提交到版本控制）
.env - 默认环境文件

配置步骤

开发环境配置

复制开发环境模板：

cp .env.development .env.local
# 或直接使用
NODE_ENV=development pnpm dev

开发环境特点：
- 使用本地数据库
- 详细的调试日志
- 宽松的安全配置
- 较高的请求限制

生产环境配置

复制生产环境模板：

cp .env.production .env
# 或设置环境变量
NODE_ENV=production pnpm deploy

生产环境特点：
- 使用 Docker 容器数据库
- 简洁的日志输出
- 严格的安全配置
- 合理的请求限制

使用方法

开发环境启动

# 使用开发环境配置
pnpm dev
# 或明确指定
NODE_ENV=development pnpm dev

# 使用生产环境配置进行开发
pnpm dev:prod

生产环境部署

# 生产环境部署（默认）
pnpm deploy

# 开发环境部署
pnpm deploy:dev

环境变量文件说明

.env.development - 开发环境专用配置
.env.production - 生产环境专用配置
.env.local - 本地覆盖配置（不会被提交）
.env.example - 配置模板文件

# 应用环境
NODE_ENV=production

# 服务端口配置
BACKEND_PORT=4000
FRONTEND_PORT=80

# 数据库配置
MONGODB_VERSION=6.0
MONGODB_PORT=27017
MONGODB_USERNAME=admin
MONGODB_PASSWORD=your-secure-password
MONGODB_DATABASE=decode
DATABASE_URL=mongodb://mongodb:27017/decode

# API 配置
API_PREFIX=api
REACT_APP_API_URL=http://localhost:4000

# 日志配置
LOG_LEVEL=info

# JWT 配置
JWT_SECRET=your-jwt-secret-key

# 其他配置
CORS_ORIGIN=http://localhost:3000
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW_MS=900000

环境变量说明

NODE_ENV: 应用运行环境 (development/production)
BACKEND_PORT: 后端服务端口
FRONTEND_PORT: 前端服务端口
MONGODB_*: MongoDB 数据库相关配置
JWT_SECRET: JWT 令牌加密密钥
API_PREFIX: API 路径前缀
LOG_LEVEL: 日志级别

注意: 生产环境中请务必修改默认密码和密钥！

部署项目

使用 Docker Compose 部署

开发环境

docker-compose -f deployments/docker-compose.yml up -d

生产环境

docker-compose -f deployments/docker-compose.prod.yml up -d

使用脚本部署

# 构建所有应用
./scripts/build-all.sh

# 部署应用
node scripts/deploy.mjs
# 或使用开发环境部署
NODE_ENV=development node scripts/deploy.mjs

脚本文件说明

deploy.mjs

这是一个使用 ES 模块语法编写的部署脚本，主要功能包括：

根据环境变量加载不同的 .env 文件
自动构建应用
检查 Docker 和 Docker Compose 可用性
执行 Docker Compose 部署
检查部署状态

使用 .mjs 扩展名的优势：

明确标识为 ES 模块，支持 import/export 语法
不需要在 package.json 中设置 "type": "module"
可以与 CommonJS 模块在同一项目中共存
支持顶级 await 和动态导入

项目结构说明

apps/: 包含所有独立应用
- server/: NestJS 后端服务
- admin/: React 管理后台应用
- app-mobile/: 移动端应用
packages/: 包含所有共享代码包
- shared/: 共享业务逻辑、API 和工具函数
- ui/: 共享 UI 组件库
- config/: 共享配置
deployments/: 包含部署相关配置文件
- docker-compose.yml: 开发环境 Docker 配置
- docker-compose.prod.yml: 生产环境 Docker 配置
- nginx.conf: Nginx 配置文件
scripts/: 包含自动化脚本
- build-all.sh: 构建所有应用的脚本
- deploy.sh: 部署脚本
.github/workflows/: GitHub Actions 工作流配置
- ci.yml: 持续集成配置
- cd.yml: 持续部署配置
- pr-check.yml: Pull Request 检查配置

CI/CD 流水线

本项目配置了完整的 CI/CD 流水线，使用 GitHub Actions 实现自动化构建、测试和部署。

🔄 持续集成 (CI)

触发条件

推送到 main 或 develop 分支
创建或更新 Pull Request

CI 流程包括

代码检查
- ESLint 代码规范检查
- TypeScript 类型检查
- 代码格式检查
自动化测试
- 单元测试 (pnpm test)
- 端到端测试 (pnpm test:e2e)
- 测试覆盖率报告
构建验证
- 前端应用构建 (pnpm build)
- 后端应用构建 (pnpm build)
- 构建产物上传
安全扫描
- 依赖漏洞扫描 (npm audit)
- 代码安全扫描 (Trivy)
- SARIF 报告上传

🚀 持续部署 (CD)

触发条件

推送到 main 分支（自动部署到 staging）
创建版本标签 v*（如 v1.0.0，部署到 production）
CI 流程成功完成后

CD 流程包括

Docker 镜像构建
- 多平台支持 (linux/amd64, linux/arm64)
- 镜像推送到 GitHub Container Registry
- 镜像缓存优化
环境部署
- Staging 环境: 自动部署 main 分支
- Production 环境: 手动部署版本标签
- 健康检查和状态验证
安全扫描
- Docker 镜像漏洞扫描
- 安全报告生成

📋 Pull Request 检查

自动检查项目

提交信息格式检查
代码类型检查
代码格式验证
快速测试执行
Bundle 大小检查
自动 PR 评论

🔧 CI/CD 配置文件

工作流文件

.github/workflows/ci.yml: 持续集成配置
.github/workflows/cd.yml: 持续部署配置
.github/workflows/pr-check.yml: PR 检查配置

项目管理文件

.github/CODEOWNERS: 代码审查规则
.github/pull_request_template.md: PR 模板

📝 开发工作流规范

分支策略

main: 主分支，用于生产环境部署
develop: 开发分支，用于功能集成
feature/*: 功能分支，用于新功能开发
hotfix/*: 热修复分支，用于紧急修复

提交规范

推荐使用 Conventional Commits 规范：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型说明:

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具的变动

示例:

feat(auth): add user login functionality
fix(api): resolve database connection issue
docs: update README with CI/CD information

Pull Request 流程

从 develop 分支创建功能分支
完成功能开发并提交代码
创建 Pull Request 到 develop 分支
等待 CI 检查通过
代码审查通过后合并
定期将 develop 合并到 main 进行发布

版本发布流程

确保 develop 分支所有功能已完成
将 develop 合并到 main

在 main 分支创建版本标签：

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

GitHub Actions 自动触发生产环境部署

🛡️ 安全和质量保证

代码质量检查

ESLint 规则强制执行
TypeScript 严格模式
代码覆盖率要求
自动化测试必须通过

安全措施

依赖漏洞自动扫描
Docker 镜像安全检查
敏感信息检测
分支保护规则

环境保护

Staging 环境自动部署
Production 环境需要手动批准
部署前健康检查
回滚机制

🔍 监控和日志

部署监控

健康检查端点
服务状态监控
部署成功/失败通知

日志管理

结构化日志输出
不同环境的日志级别
错误日志聚合

📚 相关文档

🚨 故障排除

常见问题

CI 构建失败

检查代码是否通过 ESLint 检查
确认所有测试用例通过
验证 TypeScript 类型检查无误

部署失败

检查 Docker 镜像构建是否成功
验证环境变量配置
确认目标环境资源充足

测试失败

在本地运行测试确认问题
检查测试环境配置
更新测试用例以匹配代码变更

获取帮助

查看 GitHub Actions 运行日志
检查项目 Issues 页面
联系项目维护者

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github		.github
apps		apps
deployments		deployments
document		document
packages		packages
scripts		scripts
.dockerignore		.dockerignore
.env.development		.env.development
.env.example		.env.example
.env.production		.env.production
.gitignore		.gitignore
.npmrc		.npmrc
README.md		README.md
docker-compose.yml		docker-compose.yml
mobile-network-test.html		mobile-network-test.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Decode 项目

技术栈

前端

后端

目录结构

安装依赖

启动项目

开发环境

方法一：启动所有服务

方法二：启动特定服务

方法三：使用 Docker Compose

访问应用

构建项目

环境变量配置

环境文件优先级

配置步骤

开发环境配置

生产环境配置

使用方法

开发环境启动

生产环境部署

环境变量文件说明

环境变量说明

部署项目

使用 Docker Compose 部署

开发环境

生产环境

使用脚本部署

脚本文件说明

deploy.mjs

项目结构说明

CI/CD 流水线

🔄 持续集成 (CI)

触发条件

CI 流程包括

🚀 持续部署 (CD)

触发条件

CD 流程包括

📋 Pull Request 检查

自动检查项目

🔧 CI/CD 配置文件

工作流文件

项目管理文件

📝 开发工作流规范

分支策略

提交规范

Pull Request 流程

版本发布流程

🛡️ 安全和质量保证

代码质量检查

安全措施

环境保护

🔍 监控和日志

部署监控

日志管理

📚 相关文档

🚨 故障排除

常见问题

获取帮助

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages