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. 克隆项目**
```bash
# 克隆项目到本地
git clone <your-repository-url>
cd wwjcloud-nestjs

# 检查项目结构
ls -la
```

### **2. 安装依赖**
```bash
# 使用 npm 安装
npm install

# 或使用 pnpm (推荐)
pnpm install

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

### **3. 环境配置**
```bash
# 复制环境配置文件
cp .env.example .env

# 编辑环境配置
nano .env
```

**环境配置示例**:
```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. 数据库准备**
```bash
# 启动 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. 启动服务**
```bash
# 开发模式启动
npm run start:dev

# 或使用 pnpm
pnpm start:dev
```

---

## ✅ **验证安装**

### **健康检查**
```bash
# 检查服务状态
curl http://localhost:3001/health

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

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

### **服务状态**
```bash
# 检查端口占用
netstat -tulpn | grep :3001

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

---

## 🔧 **基础配置**

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

### **中间件配置**
```typescript
// 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);
}
```

### **环境变量配置**
```typescript
// 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. 基础路由测试**
```bash
# 测试用户注册
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. 认证测试**
```bash
# 获取 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. 负载均衡测试**
```bash
# 模拟并发请求
for i in {1..10}; do
  curl -s http://localhost:3001/api/member/profile \
    -H "Authorization: Bearer $TOKEN" &
done
wait
```

---

## 📊 **监控和日志**

### **日志查看**
```bash
# 查看应用日志
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
```

### **性能监控**
```bash
# 检查内存使用
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. 端口被占用**
```bash
# 查找占用端口的进程
lsof -i :3001

# 杀死进程
kill -9 <PID>

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

### **2. 数据库连接失败**
```bash
# 检查 MySQL 服务状态
sudo systemctl status mysql

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

# 检查防火墙设置
sudo ufw status
```

### **3. 依赖安装失败**
```bash
# 清理缓存
npm cache clean --force

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

# 重新安装
npm install
```

---

## 🔄 **下一步操作**

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

### **生产部署**
- [ ] 配置生产环境变量
- [ ] 设置数据库和缓存
- [ ] 配置负载均衡和反向代理
- [ ] 设置监控和告警

### **高级功能**
- [ ] 实现微服务网关功能
- [ ] 集成服务网格技术
- [ ] 添加分布式追踪
- [ ] 优化性能和可靠性

---

## 📚 **相关文档**

- [网关系统概览](./overview.md) - 了解系统架构和特性
- [技术架构详解](./architecture.md) - 深入理解技术实现
- [开发计划](./development-plan.md) - 查看开发路线图
- [API 参考](./api-reference.md) - 完整的 API 文档

---

## 💡 **提示和建议**

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

---

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