everything-is-suitable/docs/plans/2026-02-25-frontend-deployment-config.md

# 前端双应用架构部署配置文档

## 概述

本文档描述了前端项目（Uniapp和Admin）在API双应用架构下的部署配置。后端已分离为两个独立应用：
- **client-app**: 端口8081，路由前缀 `/client/**`
- **admin-app**: 端口8082，路由前缀 `/admin/**`

## 架构说明

### 网关路由

```
                    ┌─────────────────┐
                    │   API Gateway  │
                    │   (Nginx)     │
                    └────────┬────────┘
                             │
                    ┌────────┴────────┐
                    │                 │
           ┌────────▼────┐  ┌─────▼────────┐
           │ client-app   │  │  admin-app   │
           │  (Port 8081)│  │  (Port 8082) │
           └─────────────┘  └──────────────┘
                    │                 │
           ┌────────▼────┐  ┌─────▼────────┐
           │  Uniapp     │  │    Admin      │
           │  (Client)    │  │  (Backend)   │
           └─────────────┘  └──────────────┘
```

### API端点分配

| 应用 | 端口 | 路由前缀 | 用途 |
|------|--------|-----------|------|
| client-app | 8081 | `/client/**` | 客户端API（黄历、算命等） |
| admin-app | 8082 | `/admin/**` | 管理后台API（用户、角色、菜单等） |

## 环境配置

### Uniapp环境配置

#### 开发环境 (.env.development)
```bash
# API基础URL - 直接指向客户端应用（端口8081）
baseURL: 'http://127.0.0.1:8081'
enableMock: false
```

#### 测试环境 (.env.test)
```bash
# API基础URL - 测试环境网关地址
baseURL: 'https://test.api.ziweidoushu.com'
enableMock: false
```

#### 生产环境 (.env.prod)
```bash
# API基础URL - 生产环境网关地址
baseURL: 'https://api.ziweidoushu.com'
enableMock: false
```

#### 本地环境 (.env.local)
```bash
# API基础URL - 本地客户端应用（端口8081）
baseURL: 'http://127.0.0.1:8081'
enableMock: false
```

### Admin环境配置

#### 开发环境 (.env.development)
```bash
NODE_ENV=development
VITE_APP_ENV=development
VITE_API_BASE_URL=http://127.0.0.1:8082
VITE_MOCK_ENABLED=false
```

#### 本地开发环境 (.env.development-local)
```bash
NODE_ENV=development
VITE_APP_ENV=development-local
VITE_API_BASE_URL=http://127.0.0.1:8082
VITE_MOCK_ENABLED=false
```

#### 测试环境 (.env.test)
```bash
NODE_ENV=test
VITE_APP_ENV=test
VITE_API_BASE_URL=https://test.api.ziweidoushu.com
VITE_MOCK_ENABLED=false
```

#### 生产环境 (.env.production)
```bash
NODE_ENV=production
VITE_APP_ENV=production
VITE_API_BASE_URL=https://api.ziweidoushu.com
VITE_MOCK_ENABLED=false
```

## API路径前缀规范

### Uniapp API路径

所有Uniapp的API调用必须使用 `/client/` 前缀：

```typescript
// 正确示例
httpClient.post('/client/calendar/convert', request)
httpClient.post('/client/lunar-calendar/convert', request)
httpClient.post('/client/fortune/daily', request)
httpClient.post('/client/ziwei/analyze', request)

// 错误示例
httpClient.post('/calendar/convert', request)  // 缺少 /client/ 前缀
```

### Admin API路径

所有Admin的API调用必须使用 `/admin/` 前缀：

```typescript
// 正确示例
httpClient.post('/admin/auth/login', credentials)
httpClient.get('/admin/user/list')
httpClient.get('/admin/role/list')
httpClient.get('/admin/menu/list')

// 错误示例
httpClient.post('/auth/login', credentials)  // 缺少 /admin/ 前缀
```

## 部署流程

### 1. 后端部署

#### 启动client-app
```bash
cd everything-is-suitable-api
# 启动客户端应用（端口8081）
./gradlew :client-app:bootRun
```

#### 启动admin-app
```bash
cd everything-is-suitable-api
# 启动管理应用（端口8082）
./gradlew :admin-app:bootRun
```

#### Docker部署
```bash
# 启动client-app
docker run -d -p 8081:8081 --name client-app client-app:latest

# 启动admin-app
docker run -d -p 8082:8082 --name admin-app admin-app:latest
```

### 2. 前端部署

#### Uniapp部署

**开发环境启动**
```bash
cd everything-is-suitable-uniapp
npm run dev:h5
```

**生产环境构建**
```bash
cd everything-is-suitable-uniapp
npm run build:h5
# 构建产物在 dist/build/h5 目录
```

**小程序构建**
```bash
# 微信小程序
npm run build:mp-weixin

# H5
npm run build:h5
```

#### Admin部署

**开发环境启动**
```bash
cd everything-is-suitable-admin
npm run dev
```

**生产环境构建**
```bash
cd everything-is-suitable-admin
npm run build
# 构建产物在 dist 目录
```

**Docker部署**
```bash
# 构建镜像
docker build -t admin-frontend:latest .

# 运行容器
docker run -d -p 5174:80 --name admin-frontend admin-frontend:latest
```

### 3. Nginx网关配置

```nginx
# API网关配置
upstream client_app {
    server 127.0.0.1:8081;
}

upstream admin_app {
    server 127.0.0.1:8082;
}

server {
    listen 80;
    server_name api.ziweidoushu.com;

    # 客户端API路由
    location /client/ {
        proxy_pass http://client_app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 管理后台API路由
    location /admin/ {
        proxy_pass http://admin_app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

## 集成测试

### 运行集成测试脚本

在部署后，运行集成测试脚本验证前后端连接：

```bash
# 确保后端服务已启动
cd everything-is-suitable-api
./gradlew :client-app:bootRun &
./gradlew :admin-app:bootRun &

# 运行集成测试
node scripts/integration-test.js
```

### 测试结果

集成测试脚本会检查以下端点：

**Uniapp端点**
- `GET /client/health`
- `POST /client/calendar/convert`
- `POST /client/lunar-calendar/convert`
- `POST /client/fortune/daily`
- `POST /client/ziwei/analyze`

**Admin端点**
- `GET /admin/health`
- `POST /admin/auth/login`
- `GET /admin/user/list`
- `GET /admin/role/list`
- `GET /admin/menu/list`

## 健康检查

### client-app健康检查

```bash
curl http://127.0.0.1:8081/client/health
```

预期响应：
```json
{
  "status": "UP",
  "application": "client-app"
}
```

### admin-app健康检查

```bash
curl http://127.0.0.1:8082/admin/health
```

预期响应：
```json
{
  "status": "UP",
  "application": "admin-app"
}
```

## 故障排查

### 常见问题

#### 1. Uniapp无法连接到API

**症状**: Uniapp前端显示网络错误

**检查项**:
1. 确认client-app是否在8081端口运行
2. 检查API路径是否包含 `/client/` 前缀
3. 验证环境配置中的baseURL是否正确

**解决方案**:
```bash
# 检查端口占用
lsof -i :8081

# 重启client-app
./gradlew :client-app:bootRun
```

#### 2. Admin无法连接到API

**症状**: Admin登录失败或API调用错误

**检查项**:
1. 确认admin-app是否在8082端口运行
2. 检查API路径是否包含 `/admin/` 前缀
3. 验证环境变量 `VITE_API_BASE_URL` 是否正确

**解决方案**:
```bash
# 检查端口占用
lsof -i :8082

# 重启admin-app
./gradlew :admin-app:bootRun
```

#### 3. CORS错误

**症状**: 浏览器控制台显示CORS错误

**解决方案**:
在后端应用中配置CORS允许前端域名：

```java
@CrossOrigin(origins = {
    "http://localhost:5173",  // Uniapp开发服务器
    "http://localhost:5174",  // Admin开发服务器
    "https://*.ziweidoushu.com"  // 生产域名
})
```

#### 4. 网关路由错误

**症状**: 请求被路由到错误的应用

**解决方案**:
检查Nginx配置中的location路径是否正确：

```nginx
# 确保路径以斜杠结尾
location /client/ {
    proxy_pass http://client_app;
}

location /admin/ {
    proxy_pass http://admin_app;
}
```

## 监控和日志

### 应用监控

使用Prometheus和Grafana监控应用状态：

```bash
# 启动监控服务
docker-compose -f docker-compose.monitoring.yml up -d
```

访问Grafana: http://localhost:3000

### 日志查看

```bash
# 查看client-app日志
docker logs -f client-app

# 查看admin-app日志
docker logs -f admin-app
```

## 回滚方案

如果部署后出现问题，可以快速回滚：

### 回滚前端配置

```bash
# Uniapp
cd everything-is-suitable-uniapp
git revert <commit-hash>

# Admin
cd everything-is-suitable-admin
git revert <commit-hash>
```

### 回滚后端配置

```bash
# 回滚到之前的版本
cd everything-is-suitable-api
git checkout <previous-tag>
./gradlew :client-app:bootRun
./gradlew :admin-app:bootRun
```

## 安全注意事项

1. **HTTPS配置**: 生产环境必须使用HTTPS
2. **API密钥管理**: 不要在前端代码中硬编码敏感信息
3. **CORS配置**: 严格限制允许的域名
4. **认证授权**: 所有Admin API必须经过认证
5. **日志脱敏**: 确保日志中不包含敏感信息

## 性能优化

1. **CDN加速**: 静态资源使用CDN分发
2. **Gzip压缩**: 启用Nginx的Gzip压缩
3. **缓存策略**: 合理设置HTTP缓存头
4. **负载均衡**: 多实例部署时使用负载均衡

## 附录

### 端口分配

| 服务 | 端口 | 用途 |
|------|------|------|
| client-app | 8081 | 客户端API |
| admin-app | 8082 | 管理后台API |
| Uniapp H5 | 8080 | Uniapp开发服务器 |
| Admin | 5174 | Admin开发服务器 |
| Nginx | 80/443 | API网关 |

### 相关文档

- [API架构调整文档](../everything-is-suitable-api/docs/plans/2025-02-24-dual-app-architecture-refactor.md)
- [前端双应用架构适配计划](./2026-02-25-frontend-dual-app-architecture-adaptation.md)
- [集成测试脚本](../scripts/integration-test.js)