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)

# API基础URL - 直接指向客户端应用（端口8081）
baseURL: 'http://127.0.0.1:8081'
enableMock: false

测试环境 (.env.test)

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

生产环境 (.env.prod)

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

本地环境 (.env.local)

# API基础URL - 本地客户端应用（端口8081）
baseURL: 'http://127.0.0.1:8081'
enableMock: false

Admin环境配置

开发环境 (.env.development)

NODE_ENV=development
VITE_APP_ENV=development
VITE_API_BASE_URL=http://127.0.0.1:8082
VITE_MOCK_ENABLED=false

本地开发环境 (.env.development-local)

NODE_ENV=development
VITE_APP_ENV=development-local
VITE_API_BASE_URL=http://127.0.0.1:8082
VITE_MOCK_ENABLED=false

测试环境 (.env.test)

NODE_ENV=test
VITE_APP_ENV=test
VITE_API_BASE_URL=https://test.api.ziweidoushu.com
VITE_MOCK_ENABLED=false

生产环境 (.env.production)

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/ 前缀：

// 正确示例
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/ 前缀：

// 正确示例
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

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

启动admin-app

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

Docker部署

# 启动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部署

开发环境启动

cd everything-is-suitable-uniapp
npm run dev:h5

生产环境构建

cd everything-is-suitable-uniapp
npm run build:h5
# 构建产物在 dist/build/h5 目录

小程序构建

# 微信小程序
npm run build:mp-weixin

# H5
npm run build:h5

Admin部署

开发环境启动

cd everything-is-suitable-admin
npm run dev

生产环境构建

cd everything-is-suitable-admin
npm run build
# 构建产物在 dist 目录

Docker部署

# 构建镜像
docker build -t admin-frontend:latest .

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

3. 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;
    }
}

集成测试

运行集成测试脚本

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

# 确保后端服务已启动
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健康检查

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

预期响应：

{
  "status": "UP",
  "application": "client-app"
}

admin-app健康检查

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

预期响应：

{
  "status": "UP",
  "application": "admin-app"
}

故障排查

常见问题

1. Uniapp无法连接到API

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

检查项:

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

解决方案:

# 检查端口占用
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 是否正确

解决方案:

# 检查端口占用
lsof -i :8082

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

3. CORS错误

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

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

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

4. 网关路由错误

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

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

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

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

监控和日志

应用监控

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

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

访问Grafana: http://localhost:3000

日志查看

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

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

回滚方案

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

回滚前端配置

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

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

回滚后端配置

# 回滚到之前的版本
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架构调整文档
• 前端双应用架构适配计划
• 集成测试脚本