前后端分离架构下的 CORS 跨域配置与解决方案

本节基于本项目的 Flask 服务，提供一套可直接落地的 CORS 解决方案。

方案一：使用 flask-cors 扩展（推荐）

flask-cors 是最主流的 Flask CORS 扩展，支持细粒度控制，适合生产环境。

1. 安装依赖

pip install flask-cors

确保已锁定兼容版本（避免与 Transformers 冲突）：

# requirements.txt
Flask==2.3.3
flask-cors==4.0.0
transformers==4.35.2
numpy==1.23.5

2. 全局启用 CORS（适用于 API 统一管理）

from flask import Flask, request, jsonify
from flask_cors import CORS
import logging

app = Flask(__name__)

# 配置日志
logging.basicConfig(level=logging.INFO)

# 启用 CORS 并精细化配置
CORS(app, 
     origins=[
         "http://localhost:3000", # 前端开发服务器
         "https://yourdomain.com" # 生产环境域名
     ], 
     methods=["GET", "POST", "OPTIONS"], 
     allow_headers=["Content-Type", "Authorization", "X-API-Key"], 
     supports_credentials=True, # 支持 Cookie 认证
     max_age=86400 # 预检结果缓存一天
)

@app.route('/api/translate', methods=['POST', 'OPTIONS'])
def translate():
    if request.method == 'OPTIONS':
        return '', 200 # 快速响应预检请求
    
    data = request.get_json()
    text = data.get('text', '').strip()
    
    if not text:
        return jsonify({"error": "Missing text"}), 400
    
    try:
        # 模拟调用 CSANMT 模型（真实逻辑略）
        translated_text = f"[Translated] {text}"
        # 实际应调用 model.generate()
        return jsonify({
            "original": text,
            "translated": translated_text,
            "model": "CSANMT-v1.0"
        }), 200
    except Exception as e:
        app.logger.error(f"Translation failed: {str(e)}")
        return jsonify({"error": "Internal server error"}), 500

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)

3. 关键参数说明

方案二：手动添加响应头（轻量级替代）

若不想引入额外依赖，可通过中间件方式手动注入 CORS 头。

from flask import Flask, request, make_response

app = Flask(__name__)

@app.after_request
def add_cors_headers(response):
    origin = request.headers.get('Origin')
    allowed_origins = [
        'http://localhost:3000',
        'https://yourdomain.com'
    ]
    
    if origin in allowed_origins:
        response.headers['Access-Control-Allow-Origin'] = origin
        response.headers['Access-Control-Allow-Credentials'] = 'true'
        response.headers['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS'
        response.headers['Access-Control-Allow-Headers'] = \
            'Content-Type, Authorization, X-API-Key'
        
        # 对 OPTIONS 请求单独处理
        if request.method == 'OPTIONS':
            resp = make_response()
            resp.headers['Access-Control-Allow-Origin'] = origin
            resp.headers['Access-Control-Allow-Methods'] = 'POST, GET, OPTIONS'
            resp.headers['Access-Control-Allow-Headers'] = 'Content-Type, X-API-Key'
            resp.headers['Access-Control-Max-Age'] = '86400'
            return resp
    
    return response

@app.route('/api/translate', methods=['POST'])
def translate():
    # 同上...
    pass

⚠️ 注意事项：

• 必须检查 Origin 是否在白名单内，防止反射攻击
• Access-Control-Allow-Origin 不可设为 * 如果启用了凭据
• OPTIONS 请求应返回空体 +200 状态码

🧪 前端调用示例与调试技巧

前端 JavaScript 调用代码（React 示例）

// components/Translator.js
const handleTranslate = async () => {
    try {
        const response = await fetch('http://localhost:5000/api/translate', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': 'your-secret-key' // 自定义 Header 触发预检
            },
            body: JSON.stringify({ text: inputText }),
            credentials: 'include' // 发送 Cookie（如 session）
        });
        const result = await response.json();
        setTranslatedText(result.translated);
    } catch (err) {
        console.error('Translation failed:', err);
        alert('翻译请求失败，请检查网络或服务状态');
    }
};

浏览器调试要点

1. 打开开发者工具 → Network 标签页
2. 观察是否有 OPTIONS 请求出现
3. 查看响应头是否包含：
   • Access-Control-Allow-Origin
   • Access-Control-Allow-Methods
   • Access-Control-Allow-Headers
4. 若失败，查看 Console 报错信息定位问题

⚙️ Nginx 反向代理方案（生产环境推荐）

在生产环境中，更推荐使用 Nginx 做统一入口，通过同源代理规避 CORS 问题。

Nginx 配置示例

server {
    listen 80;
    server_name yourdomain.com;

    # 前端静态文件
    location / {
        root /var/www/frontend;
        try_files $uri $uri/ /index.html;
    }

    # API 代理到 Flask 后端
    location /api/ {
        proxy_pass http://127.0.0.1:5000/;
        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;

        # 显式添加 CORS 头（可选）
        add_header Access-Control-Allow-Origin $http_origin always;
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-API-Key" always;
        add_header Access-Control-Allow-Credentials "true" always;

        # 处理预检请求
        if ($request_method = OPTIONS) {
            add_header Content-Length 0;
            add_header Content-Type text/plain;
            return 204;
        }
    }
}

✅ 优势：

• 前后端共用同一域名，彻底避免 CORS
• 可集中管理 SSL、负载均衡、缓存等
• 更高的安全性和性能表现

🛠️ 常见问题排查清单

🎯 总结：CORS 最佳实践建议

1. 开发阶段：使用 flask-cors 快速启用，配合明确的源白名单
2. 生产环境：优先采用 Nginx 反向代理，实现同源部署，从根本上规避 CORS 复杂性
3. 安全性原则：
   • 避免使用 * 通配符（尤其涉及凭据时）
   • 严格校验 Origin 头，防止反射攻击
   • 仅开放必要的 HTTP 方法和请求头
4. 性能优化：
   • 设置较长的 max_age 减少预检频率
   • 使用 CDN 或边缘节点缓存 OPTIONS 响应

🔄 下一步学习路径建议

• 学习 MDN CORS 文档 掌握底层机制
• 实践 JWT Token 替代 Cookie 认证，降低 CORS 复杂度
• 探索 GraphQL + Apollo Server 的 CORS 集成方式
• 了解 Preflight 缓存对高并发场景的影响

通过合理配置 CORS 策略，你的 AI 翻译服务不仅能稳定服务于本地 WebUI，还可轻松拓展为对外开放的公共 API 平台，赋能更多应用场景。