wwjcloud-nest-v1/admin/docs/src/wwjcloud/gateway/quick-start.md

快速开始指南

快速上手 WWJCloud 网关系统，从零开始搭建完整的网关环境

🚀 环境准备

系统要求

• 操作系统: Windows 10+, macOS 10.15+, Ubuntu 18.04+
• Node.js: >= 18.0.0
• npm: >= 8.0.0 或 pnpm >= 7.0.0
• Docker: >= 20.0.0 (可选)
• Kubernetes: >= 1.20.0 (可选)

开发工具

• 代码编辑器: VS Code (推荐)
• API 测试: Postman 或 Apifox
• 数据库管理: MySQL Workbench 或 phpMyAdmin
• 容器管理: Docker Desktop

---

📦 安装步骤

1. 克隆项目

# 克隆项目到本地
git clone <your-repository-url>
cd wwjcloud-nestjs

# 检查项目结构
ls -la

2. 安装依赖

# 使用 npm 安装
npm install

# 或使用 pnpm (推荐)
pnpm install

# 检查安装结果
npm list --depth=0

3. 环境配置

# 复制环境配置文件
cp .env.example .env

# 编辑环境配置
nano .env

环境配置示例:

# 应用配置
NODE_ENV=development
PORT=3001

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=wwjcloud

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=7d

# 日志配置
LOG_LEVEL=info

4. 数据库准备

# 启动 MySQL 服务
sudo systemctl start mysql

# 创建数据库
mysql -u root -p
CREATE DATABASE wwjcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;

# 导入数据库结构
mysql -u root -p wwjcloud < sql/wwjcloud.sql

5. 启动服务

# 开发模式启动
npm run start:dev

# 或使用 pnpm
pnpm start:dev

---

✅ 验证安装

健康检查

# 检查服务状态
curl http://localhost:3001/health

# 预期响应
{
  "status": "ok",
  "timestamp": "2025-08-25T02:36:55.746Z",
  "uptime": 123.456
}

API 文档

• 访问地址: http://localhost:3001/docs
• 功能: 查看所有可用的 API 接口
• 测试: 在线测试 API 功能

服务状态

# 检查端口占用
netstat -tulpn | grep :3001

# 检查进程状态
ps aux | grep node

---

🔧 基础配置

路由配置

// src/app.module.ts
@Module({
  imports: [
    // 基础模块
    ConfigModule.forRoot({
      isGlobal: true,
      load: [configuration],
    }),
    
    // 网关模块
    GatewayModule,
    
    // 业务模块
    UserModule,
    AuthModule,
  ],
})
export class AppModule {}

中间件配置

// src/main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // 全局中间件
  app.useGlobalPipes(new ValidationPipe());
  app.useGlobalInterceptors(new TransformInterceptor());
  
  // CORS 配置
  app.enableCors({
    origin: ['http://localhost:3000', 'http://localhost:8080'],
    credentials: true,
  });
  
  // 启动服务
  await app.listen(3001);
}

环境变量配置

// src/config/index.ts
export default () => ({
  nodeEnv: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT || '3000', 10),
  
  // 网关配置
  gateway: {
    enabled: process.env.GATEWAY_ENABLED === 'true',
    timeout: parseInt(process.env.GATEWAY_TIMEOUT || '30000', 10),
    retries: parseInt(process.env.GATEWAY_RETRIES || '3', 10),
  },
  
  // 负载均衡配置
  loadBalancer: {
    algorithm: process.env.LB_ALGORITHM || 'round-robin',
    healthCheck: process.env.LB_HEALTH_CHECK === 'true',
  },
});

---

🧪 测试网关功能

1. 基础路由测试

# 测试用户注册
curl -X POST http://localhost:3001/api/member/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'

# 测试用户登录
curl -X POST http://localhost:3001/api/member/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "password123"
  }'

2. 认证测试

# 获取 JWT Token
TOKEN=$(curl -s -X POST http://localhost:3001/api/member/login \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "password123"}' \
  | jq -r '.access_token')

# 使用 Token 访问受保护的接口
curl -X GET http://localhost:3001/api/member/profile \
  -H "Authorization: Bearer $TOKEN"

3. 负载均衡测试

# 模拟并发请求
for i in {1..10}; do
  curl -s http://localhost:3001/api/member/profile \
    -H "Authorization: Bearer $TOKEN" &
done
wait

---

📊 监控和日志

日志查看

# 查看应用日志
tail -f logs/app-$(date +%Y-%m-%d).log

# 查看错误日志
grep "ERROR" logs/app-$(date +%Y-%m-%d).log

# 查看性能日志
grep "PERFORMANCE" logs/app-$(date +%Y-%m-%d).log

性能监控

# 检查内存使用
ps -o pid,ppid,%mem,%cpu,cmd -p $(pgrep node)

# 检查网络连接
netstat -an | grep :3001 | wc -l

# 检查响应时间
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3001/health

curl-format.txt 内容:

     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n

---

🚨 常见问题

1. 端口被占用

# 查找占用端口的进程
lsof -i :3001

# 杀死进程
kill -9 <PID>

# 或者修改端口
export PORT=3002
npm run start:dev

2. 数据库连接失败

# 检查 MySQL 服务状态
sudo systemctl status mysql

# 检查数据库连接
mysql -u root -p -h localhost

# 检查防火墙设置
sudo ufw status

3. 依赖安装失败

# 清理缓存
npm cache clean --force

# 删除 node_modules
rm -rf node_modules package-lock.json

# 重新安装
npm install

---

🔄 下一步操作

开发模式

• 熟悉项目结构和代码组织
• 了解各个模块的功能和接口
• 开始开发新的功能模块
• 编写单元测试和集成测试

生产部署

• 配置生产环境变量
• 设置数据库和缓存
• 配置负载均衡和反向代理
• 设置监控和告警

高级功能

• 实现微服务网关功能
• 集成服务网格技术
• 添加分布式追踪
• 优化性能和可靠性

---

📚 相关文档

• 网关系统概览 - 了解系统架构和特性
• 技术架构详解 - 深入理解技术实现
• 开发计划 - 查看开发路线图
• API 参考 - 完整的 API 文档

---

💡 提示和建议

1. 开发环境: 建议使用 VS Code 和相关的 NestJS 插件
2. 版本控制: 定期提交代码，保持良好的版本管理习惯
3. 测试驱动: 先写测试，再写代码，确保代码质量
4. 文档更新: 及时更新文档，保持文档与代码同步
5. 性能优化: 关注性能指标，持续优化系统性能

---

注意: 如果遇到问题，请查看日志文件或提交 Issue 到项目仓库。