签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,194 @@
+# 代理配置
+
+:::tip 说明
+开发环境通过 Vite 代理转发 API 请求到后端，生产环境通过 Nginx 代理。代理配置由 `VITE_PROXY` 环境变量控制。
+:::
+
+## 开发环境代理
+
+### Vite 配置
+
+`vite.config.ts` 中通过 `createProxy` 工具函数解析 `VITE_PROXY` 环境变量生成代理配置：
+
+```typescript
+// vite.config.ts
+import { createProxy } from './build/vite/proxy';
+
+export default ({ command, mode }: ConfigEnv): UserConfig => {
+    let VITE_PROXY: any = viteEnv.VITE_PROXY;
+    if (!VITE_PROXY) VITE_PROXY = '[[]]';
+    try {
+        if (typeof VITE_PROXY === 'string') VITE_PROXY = JSON.parse(VITE_PROXY);
+    } catch (e) {
+        VITE_PROXY = [[]];
+    }
+
+    return {
+        server: {
+            host: true,
+            port: VITE_PORT,
+            proxy: createProxy(VITE_PROXY),
+        },
+    };
+};
+```
+
+### 环境变量配置
+
+`.env` 文件中配置代理规则（JSON 数组格式）：
+
+```bash
+# 格式：[["前缀","目标地址"]]
+VITE_PROXY=[["/api","http://127.0.0.1:8021/api/v1"]]
+```
+
+`createProxy` 函数将此配置转换为 Vite 的 `server.proxy` 格式，自动添加 `changeOrigin: true` 等选项。
+
+### 代理规则
+
+```
+前端请求: http://localhost:8001/api/v1/position/page
+代理转发: http://127.0.0.1:8021/api/v1/position/page
+```
+
+`/api` 前缀的请求被代理到后端 `http://127.0.0.1:8021`，`changeOrigin: true` 修改请求头的 Host 为目标地址。
+
+### 开发流程
+
+```
+1. 启动后端: python app.py (127.0.0.1:8021)
+2. 启动前端: pnpm dev (localhost:8001)
+3. 浏览器访问 localhost:8001
+4. API 请求自动代理到 127.0.0.1:8021
+```
+
+### 前端请求路径
+
+前端 API 函数中的 URL 不含 `/api/v1` 前缀：
+
+```typescript
+// src/api/system/position.ts
+export function getPositionList(params?) {
+  return http.request({
+    url: '/position/page', // 实际请求：/api/v1/position/page
+    method: 'GET',
+    params,
+  });
+}
+```
+
+`VAxios` 创建时配置了 `prefixUrl` 和 `urlPrefix`，`beforeRequestHook` 自动拼接：
+
+```typescript
+// src/utils/http/axios/index.ts
+const urlPrefix = globSetting.urlPrefix || '/v1';
+
+createAxios({
+  prefixUrl: urlPrefix, // '/v1'
+  requestOptions: {
+    joinPrefix: true,
+    apiUrl: globSetting.apiUrl, // '/api'
+    urlPrefix: urlPrefix, // '/v1'
+  },
+});
+```
+
+最终请求路径：`/api` + `/v1` + `/position/page` = `/api/v1/position/page`
+
+## 生产环境代理
+
+### Nginx 配置
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # 前端静态文件
+    location / {
+        root /path/to/dist;
+        index index.html;
+        try_files $uri $uri/ /index.html; # SPA 路由回退
+    }
+
+    # API 代理
+    location /api/ {
+        proxy_pass http://127.0.0.1:8021/api/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # 超时配置
+        proxy_connect_timeout 30s;
+        proxy_read_timeout 60s;
+        proxy_send_timeout 60s;
+    }
+}
+```
+
+### Nginx 代理说明
+
+| 配置项 | 说明 |
+|--------|------|
+| `proxy_pass` | 转发目标地址 |
+| `proxy_set_header Host` | 传递原始 Host |
+| `proxy_set_header X-Real-IP` | 传递客户端真实 IP |
+| `proxy_set_header X-Forwarded-For` | 传递代理链 IP |
+| `proxy_set_header X-Forwarded-Proto` | 传递原始协议 |
+| `proxy_connect_timeout` | 连接超时 |
+| `proxy_read_timeout` | 读取超时 |
+
+## 文件访问代理
+
+上传文件的访问也需要代理：
+
+```nginx
+# 文件访问
+location /api/file/ {
+    proxy_pass http://127.0.0.1:8021/api/file/;
+    proxy_set_header Host $host;
+
+    # 静态文件缓存
+    expires 7d;
+    add_header Cache-Control "public, immutable";
+}
+```
+
+:::tip 温馨提示
+后端的文件访问地址需要与前端一致。开发环境为 `http://127.0.0.1:8021/api/file`，生产环境需要在 `.env.production` 中配置 `VITE_GLOB_FILE_URL` 为实际域名。
+:::
+
+## Docker 代理
+
+Docker 环境中通过 docker-compose 网络通信：
+
+```yaml
+services:
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/conf.d/default.conf
+      - ./dist:/usr/share/nginx/html
+    depends_on:
+      - backend
+
+  backend:
+    build: ./backend
+    expose:
+      - "8021"
+```
+
+Nginx 配置中 `proxy_pass` 指向 Docker 服务名：
+
+```nginx
+location /api/ {
+    proxy_pass http://backend:8021/api/;
+}
+```
+
+## 总结
+
+开发环境通过 `VITE_PROXY` 环境变量配置 Vite 代理，`createProxy` 函数解析 JSON 格式的代理规则。前端 API 路径不含 `/api/v1` 前缀，由 `VAxios` 的 `beforeRequestHook` 自动拼接。生产环境通过 Nginx 代理并配置超时、缓存等参数，Docker 环境通过 docker-compose 网络实现服务间通信。