leaudit-platform-frontend/DYNAMIC-CLIENT-CONFIG.md

动态客户端配置使用指南

🎯 概述

本项目支持通过Nginx代理自动识别客户端，无需手动设置环境变量。Nginx会在请求头中传递 X-Client-ID，前端应用会自动读取并使用对应的配置。

🔧 工作原理

用户访问 → Nginx代理 → 添加X-Client-ID头部 → 前端应用 → 动态获取配置

端口映射

端口	客户端ID	说明
5174	client-a	客户端A
5175	client-b	客户端B
5176	client-c	客户端C
5177	client-d	客户端D

📁 相关文件

核心配置文件

• app/config/api-config.ts - API配置管理（已更新支持动态配置）
• nginx-ubuntu-optimized.conf - Nginx配置文件

新增工具文件

• app/utils/client-detection.ts - 客户端检测工具函数
• app/examples/dynamic-config-usage.ts - 使用示例
• app/routes/test.client-config.tsx - 配置测试页面

🚀 使用方法

1. 在Remix Loader中使用

import type { LoaderFunctionArgs } from '@remix-run/node';
import { getApiConfig, getApiBaseUrl } from '~/config/api-config';

export async function loader({ request }: LoaderFunctionArgs) {
  // 方法1: 获取完整配置
  const config = getApiConfig(request);
  
  // 方法2: 获取特定配置项
  const baseUrl = getApiBaseUrl(request);
  
  // 使用动态配置进行API调用
  const response = await fetch(`${baseUrl}/api/data`);
  const data = await response.json();
  
  return { data };
}

2. 在Action中使用

import type { ActionFunctionArgs } from '@remix-run/node';
import { getUploadUrl } from '~/config/api-config';

export async function action({ request }: ActionFunctionArgs) {
  const uploadUrl = getUploadUrl(request);
  const formData = await request.formData();
  
  const response = await fetch(uploadUrl, {
    method: 'POST',
    body: formData
  });
  
  return await response.json();
}

3. OAuth重定向URL生成

import { getOAuthConfig } from '~/config/api-config';

export function generateOAuthUrl(request: Request): string {
  const oauthConfig = getOAuthConfig(request);
  
  const params = new URLSearchParams({
    client_id: oauthConfig.clientId,
    redirect_uri: oauthConfig.redirectUri,
    response_type: 'code'
  });
  
  return `${oauthConfig.serverUrl}/oauth/authorize?${params.toString()}`;
}

🧪 测试验证

1. 访问测试页面

通过不同端口访问测试页面来验证配置：

# 客户端A
http://localhost:5174/test/client-config

# 客户端B  
http://localhost:5175/test/client-config

# 客户端C
http://localhost:5176/test/client-config

# 客户端D
http://localhost:5177/test/client-config

2. 检查配置状态

测试页面会显示：

• ✅ Nginx代理是否正常工作
• ✅ 客户端识别是否成功
• ✅ 配置匹配是否正确

3. 验证请求头

在浏览器开发者工具中检查网络请求，确认包含：

• X-Client-ID: 对应的客户端标识
• X-Original-Port: 原始端口号
• X-Forwarded-Port: 转发端口号

🔍 调试信息

查看Nginx日志

# 查看客户端A的访问日志
sudo tail -f /var/log/nginx/client-a-access.log

# 查看客户端D的访问日志
sudo tail -f /var/log/nginx/client-d-access.log

使用调试工具

import { detectClientFromRequest, getRequestDebugInfo } from '~/utils/client-detection';

export async function loader({ request }: LoaderFunctionArgs) {
  const clientId = detectClientFromRequest(request);
  const debugInfo = getRequestDebugInfo(request);
  
  console.log('🔧 调试信息:', { clientId, debugInfo });
  
  // ... 其他逻辑
}

⚠️ 注意事项

1. 兼容性

• 保持了原有的静态配置导出，确保现有代码不受影响
• 新的动态配置函数是可选的，可以逐步迁移

2. 环境要求

• 需要Nginx正确配置并运行
• 确保 nginx-ubuntu-optimized.conf 配置文件已应用

3. 错误处理

• 如果无法检测到客户端ID，会回退到默认值 'main'
• 如果Nginx未正确配置，仍可通过环境变量设置客户端ID

🔄 迁移指南

从环境变量迁移到动态配置

之前（需要设置环境变量）：

# .env文件
NEXT_PUBLIC_CLIENT_ID=client-d

现在（自动检测）：

// 在loader中
const config = getApiConfig(request); // 自动从请求头获取客户端ID

更新现有代码

1. 替换静态配置调用：

   // 旧方式
   import { API_BASE_URL } from '~/config/api-config';
   
   // 新方式
   import { getApiBaseUrl } from '~/config/api-config';
   const baseUrl = getApiBaseUrl(request);
   

2. 在loader/action中传递request：

   // 确保所有需要配置的地方都能访问到request对象
   export async function loader({ request }: LoaderFunctionArgs) {
     const config = getApiConfig(request);
     // ...
   }
   

🎉 优势

1. 无需手动配置 - 不再需要为每个客户端设置环境变量
2. 自动识别 - 通过访问端口自动识别客户端
3. 动态切换 - 同一个应用实例支持多个客户端
4. 向后兼容 - 现有代码无需修改即可继续工作
5. 易于调试 - 提供完整的调试信息和测试页面

现在你可以直接通过 http://localhost:5177 访问应用，系统会自动识别为 client-d 并使用对应的配置！