DP/tempdocs/必须修改清单.md

✅ 必须修改清单（上线前）

🎯 修改目标

解决 5 个架构问题：

1. ✅ CORS 支持 CEP 环境（Origin: null）
2. ✅ 生产环境 API 地址配置
3. ✅ 静态文件由 Caddy 处理（性能优化）
4. ✅ Token 通过 Header 传递（已经正确，确认即可）
5. ✅ 使用 Caddy 自动 HTTPS

---

📝 需要修改的文件

1. 后端 CORS 配置 ⭐ 重要

文件: Server/app/main.py

修改前 (第 16-28 行):

# CORS configuration
origins = [
    "http://localhost:5173", # Vite default
    "http://localhost:3000",
    "*" # For development convenience
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

修改后:

# ========== CORS 配置 ==========
import os

IS_DEV = os.getenv("ENV", "development") == "development"

if IS_DEV:
    # 开发环境：保持宽松
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
else:
    # 生产环境：严格配置
    allowed_origins = os.getenv("ALLOWED_ORIGINS", "").split(",")
    
    app.add_middleware(
        CORSMiddleware,
        allow_origins=allowed_origins,
        allow_credentials=True,
        allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
        allow_headers=["*"],
    )
    
    # ✅ CEP 环境特殊处理
    @app.middleware("http")
    async def cep_cors_middleware(request: Request, call_next):
        origin = request.headers.get("origin")
        
        # CEP 的 Origin 是 null 或 cep://
        if origin in ["null", None] or (origin and origin.startswith("cep://")):
            response = await call_next(request)
            response.headers["Access-Control-Allow-Origin"] = "*"
            response.headers["Access-Control-Allow-Credentials"] = "true"
            response.headers["Access-Control-Allow-Methods"] = "GET, POST, PUT, DELETE, OPTIONS"
            response.headers["Access-Control-Allow-Headers"] = "*"
            return response
        
        return await call_next(request)

还需要在文件开头添加导入:

from fastapi import FastAPI, Request  # ← 添加 Request

---

2. 删除 FastAPI 静态文件挂载 ⭐ 重要

文件: Server/app/main.py

修改前 (第 36-55 行):

# Mount archives directory for download
app.mount("/download", StaticFiles(directory="archives"), name="download")

# Mount Shell directory (登录页面)
shell_dir = Path(__file__).parent.parent / "Designer"
if shell_dir.exists():
    app.mount("/shell", StaticFiles(directory=str(shell_dir), html=True), name="shell")
    print(f"✓ Shell 已挂载: {shell_dir}")
else:
    print(f"⚠️ Shell 目录不存在: {shell_dir}")
    print("  请先运行: cd Designer && npm run build:shell")

# Mount DesignerCache directory to serve Core application files
designer_cache = Path.home() / "AppData" / "Roaming" / "DesignerCache"
if designer_cache.exists():
    app.mount("/core", StaticFiles(directory=str(designer_cache), html=True), name="core")
else:
    # Create directory if it doesn't exist
    designer_cache.mkdir(parents=True, exist_ok=True)
    app.mount("/core", StaticFiles(directory=str(designer_cache), html=True), name="core")

修改后:

# ❌ 删除所有静态文件挂载（交给 Caddy 处理）
# 生产环境不需要 FastAPI 处理静态文件

# 可以添加健康检查接口
@app.get("/health")
def health_check():
    return {"status": "healthy", "timestamp": datetime.now().isoformat()}

---

3. 后端环境变量配置

文件: Server/.env

新建或修改:

# 环境配置
ENV=production

# 项目配置
PROJECT_NAME=DesignerCEP
API_V1_STR=/api/v1

# 安全配置
SECRET_KEY=your-secret-key-here-change-this-in-production

# 数据库配置
DATABASE_URL=mysql://username:password@localhost:3306/designer_cep

# CORS 允许的来源（生产环境）
ALLOWED_ORIGINS=https://your-domain.com,https://www.your-domain.com

# 管理员配置
ADMIN_TOKEN=your-admin-token-here

⚠️ 重要：将 your-domain.com 替换为你的实际域名！

---

4. 前端 API 地址配置

文件: Designer/src/config/index.ts

修改前 (第 14-16 行):

apiServer: isDev 
  ? 'http://127.0.0.1:8000' 
  : 'http://127.0.0.1:8000',  // ❌ 生产环境还是 localhost

修改后:

apiServer: isDev 
  ? 'http://127.0.0.1:8000' 
  : 'https://your-domain.com',  // ✅ 生产环境用线上地址

或者使用环境变量 (推荐):

新建文件: Designer/.env.production

VITE_API_SERVER=https://your-domain.com

修改: Designer/src/config/index.ts

const isDev = import.meta.env.DEV;
const PROD_API_SERVER = import.meta.env.VITE_API_SERVER || 'http://127.0.0.1:8000';

export const config = {
  apiServer: isDev 
    ? 'http://127.0.0.1:8000' 
    : PROD_API_SERVER,  // ✅ 从环境变量读取
  
  apiPrefix: '/api/v1',
  
  shellLoginUrl: isDev 
    ? 'http://localhost:5173/#/login' 
    : 'https://your-domain.com/shell/#/login',  // ✅ 生产环境登录页
  
  get apiBaseUrl() {
    return `${this.apiServer}${this.apiPrefix}`;
  },
  
  getDownloadUrl(path: string): string {
    if (path.startsWith('/')) {
      return `${this.apiServer}${path}`;
    }
    return path;
  },
  
  getCoreUrl(version: string): string {
    if (isDev) {
      return `http://localhost:5173/`;
    }
    return `${this.apiServer}/core/${version}/index.html`;  // ✅ 线上加载
  }
};

---

5. 确认 Token 传递方式（已经正确）✅

文件: Designer/src/utils/request.ts

检查 (第 16-18 行):

const token = localStorage.getItem('token');
if (token) {
    config.headers['Authorization'] = `Bearer ${token}`;  // ✅ 已经正确
}

这个不需要改，已经是对的！

---

🚀 部署步骤

步骤 1: 修改代码

# 1. 后端修改
# - Server/app/main.py（CORS + 删除静态挂载）
# - Server/.env（环境变量）

# 2. 前端修改
# - Designer/.env.production（API 地址）
# - Designer/src/config/index.ts（可选）

步骤 2: 本地测试

# 1. 测试后端
cd Server
ENV=development python -m uvicorn app.main:app --reload
# 访问 http://localhost:8000/health

# 2. 测试前端
cd Designer
npm run dev
# 访问 http://localhost:5173
# 登录测试，检查 Network 标签

步骤 3: 构建生产版本

cd Designer
npm run build

# 检查生成的文件
ls -la dist/Shell/
ls -la dist/Designer/

步骤 4: 部署到服务器

# 方法 A: 自动化部署（推荐）
cd AdminTool
python auto_deploy_core.py --version 1.0.6 --deploy --update-db

# 方法 B: 手动部署
scp -r dist/Shell/* user@server:/var/www/DesignerCEP/Server/static/shell/
scp -r dist/Designer/* user@server:/var/www/DesignerCEP/Server/static/core/1.0.6/

步骤 5: 配置 Caddy

参考 Caddy部署指南.md 的完整配置。

关键配置:

your-domain.com {
    # API → FastAPI
    handle /api/* {
        reverse_proxy localhost:8000
    }
    
    # Shell 静态文件
    handle /shell/* {
        root * /var/www/DesignerCEP/Server/static/shell
        file_server
    }
    
    # Core 静态文件
    handle /core/* {
        root * /var/www/DesignerCEP/Server/static/core
        file_server
    }
    
    # 下载文件
    handle /downloads/* {
        root * /var/www/DesignerCEP/Server/static/downloads
        file_server
    }
}

步骤 6: 启动服务

# 1. 启动 FastAPI
sudo systemctl restart designer-cep

# 2. 启动 Caddy
sudo systemctl restart caddy

# 3. 检查状态
sudo systemctl status designer-cep
sudo systemctl status caddy

步骤 7: 测试上线

# 1. 测试 API
curl https://your-domain.com/api/v1/health

# 2. 测试 CEP CORS
curl -X OPTIONS https://your-domain.com/api/v1/client/login \
  -H "Origin: null" \
  -H "Access-Control-Request-Method: POST" \
  -v

# 3. 浏览器测试
# 打开 https://your-domain.com/shell/
# 登录并检查功能

---

📊 修改影响评估

修改项	风险	是否必须	回滚难度
CORS CEP 支持	⭐ 低	是	容易
删除静态挂载	⭐⭐ 中	是	中等
环境变量配置	⭐ 低	是	容易
前端 API 地址	⭐⭐ 中	是	容易
Token 方式确认	⭐ 无	否（已正确）	-

---

🔍 常见问题

Q: 改完后本地开发会受影响吗？

A: 不会！代码中有环境判断：

• 开发环境（ENV=development）：保持原样，CORS 宽松
• 生产环境（ENV=production）：严格 CORS + CEP 支持

Q: 如果改错了怎么办？

A:

1. Git 回滚：git checkout Server/app/main.py
2. 或保留 FastAPI 静态挂载（性能差一点，但能用）
3. 环境变量改回 ENV=development

Q: 必须用 Caddy 吗？

A: 不必须，但强烈推荐：

• ✅ Caddy：配置简单，自动 HTTPS
• ⚠️ Nginx：配置复杂，需要手动申请证书
• 二选一即可

---

✅ 完成后检查

• 本地开发环境测试通过
• 生产构建无错误
• API 请求正常（200）
• CORS 无错误
• CEP 扩展能登录
• 浏览器能访问
• Token 在 Header 里
• 静态文件正常加载
• HTTPS 证书有效

---

📞 如需帮助

1. 查看日志：sudo journalctl -u designer-cep -f
2. 查看 Caddy 日志：sudo journalctl -u caddy -f
3. 测试 API：curl -v https://your-domain.com/api/v1/health

---

总结：改动不大，主要是添加环境判断和 CEP CORS 支持，风险可控！