Add comprehensive CORS fix guide
This commit is contained in:
donald
366
CORS_FIX_GUIDE.md
Normal file
366
CORS_FIX_GUIDE.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# CORS 錯誤解決方案
|
||||
|
||||
## 🔴 您遇到的錯誤
|
||||
|
||||
### 錯誤訊息 1: CORS Policy
|
||||
```
|
||||
Access to fetch at 'https://api.anthropic.com/v1/messages' from origin 'http://127.0.0.1:5000'
|
||||
has been blocked by CORS policy: Response to preflight request doesn't pass access control check:
|
||||
No 'Access-Control-Allow-Origin' header is present on the requested resource.
|
||||
```
|
||||
|
||||
### 錯誤訊息 2: Storage Access
|
||||
```
|
||||
Uncaught (in promise) Error: Access to storage is not allowed from this context.
|
||||
```
|
||||
|
||||
### 錯誤訊息 3: Failed to Fetch
|
||||
```
|
||||
POST https://api.anthropic.com/v1/messages net::ERR_FAILED
|
||||
TypeError: Failed to fetch
|
||||
```
|
||||
|
||||
## 🤔 為什麼會發生這些錯誤？
|
||||
|
||||
### 1. **CORS（跨來源資源共用）限制**
|
||||
- 瀏覽器的安全機制，防止網頁向不同來源的伺服器發送請求
|
||||
- Anthropic API 不允許直接從瀏覽器呼叫（沒有設定 CORS 標頭）
|
||||
- 這是為了保護 API 金鑰不被暴露
|
||||
|
||||
### 2. **API 金鑰安全問題**
|
||||
```javascript
|
||||
// ❌ 危險！前端直接呼叫會暴露 API 金鑰
|
||||
const apiKey = 'sk-ant-xxxxx'; // 所有人都能看到
|
||||
fetch('https://api.anthropic.com/v1/messages', {
|
||||
headers: { 'x-api-key': apiKey }
|
||||
});
|
||||
```
|
||||
|
||||
### 3. **Storage 限制**
|
||||
- 使用 `file://` 協定開啟的 HTML 檔案無法使用 localStorage
|
||||
- 必須透過 HTTP 伺服器運行
|
||||
|
||||
## ✅ 正確的解決方案
|
||||
|
||||
### 架構圖
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ │ │ │ │ │
|
||||
│ 前端 │ ─────▶ │ 後端 │ ─────▶ │ Claude API │
|
||||
│ (瀏覽器) │ HTTP │ (Express) │ HTTPS │ (Anthropic)│
|
||||
│ │ │ │ │ │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
↑
|
||||
│ API 金鑰
|
||||
│ 安全儲存
|
||||
```
|
||||
|
||||
### 步驟 1: 安裝依賴
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
這會安裝：
|
||||
- `express` - Web 伺服器框架
|
||||
- `cors` - CORS 中介層
|
||||
- `axios` - HTTP 客戶端
|
||||
- `dotenv` - 環境變數管理
|
||||
- 其他依賴...
|
||||
|
||||
### 步驟 2: 設定環境變數
|
||||
|
||||
編輯 [.env](.env) 檔案，加入您的 Claude API 金鑰：
|
||||
|
||||
```env
|
||||
# Claude API
|
||||
CLAUDE_API_KEY=sk-ant-api03-xxxxxxxxxxxxx
|
||||
CLAUDE_API_URL=https://api.anthropic.com/v1
|
||||
CLAUDE_MODEL=claude-3-5-sonnet-20241022
|
||||
```
|
||||
|
||||
⚠️ **重要**：`.env` 檔案已被 `.gitignore` 排除，不會被提交到 Git
|
||||
|
||||
### 步驟 3: 啟動後端伺服器
|
||||
|
||||
```bash
|
||||
# 開發模式（自動重啟）
|
||||
npm run dev
|
||||
|
||||
# 或生產模式
|
||||
npm start
|
||||
```
|
||||
|
||||
您應該會看到：
|
||||
|
||||
```
|
||||
==================================================
|
||||
🚀 HR Performance System API Server
|
||||
==================================================
|
||||
📡 Server running on: http://localhost:3000
|
||||
🌍 Environment: development
|
||||
📅 Started at: 2025-12-03 ...
|
||||
==================================================
|
||||
|
||||
📚 Available endpoints:
|
||||
GET / - API information
|
||||
GET /health - Health check
|
||||
POST /api/llm/test/* - Test LLM connections
|
||||
POST /api/llm/generate - Generate content with LLM
|
||||
|
||||
✨ Server is ready to accept connections!
|
||||
```
|
||||
|
||||
### 步驟 4: 測試 API
|
||||
|
||||
開啟瀏覽器訪問：
|
||||
|
||||
```
|
||||
http://localhost:3000/api-proxy-example.html
|
||||
```
|
||||
|
||||
或使用 curl 測試：
|
||||
|
||||
```bash
|
||||
# 測試 Claude 連線
|
||||
curl -X POST http://localhost:3000/api/llm/test/claude
|
||||
|
||||
# 生成內容
|
||||
curl -X POST http://localhost:3000/api/llm/generate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "介紹 HR 績效評核系統",
|
||||
"provider": "claude",
|
||||
"options": {
|
||||
"temperature": 0.7,
|
||||
"maxTokens": 200
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 📝 前端程式碼範例
|
||||
|
||||
### ❌ 錯誤的做法（直接呼叫）
|
||||
|
||||
```javascript
|
||||
// 不要這樣做！會被 CORS 阻擋
|
||||
async function callClaudeAPI() {
|
||||
const response = await fetch('https://api.anthropic.com/v1/messages', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'x-api-key': 'sk-ant-xxxxx', // ❌ API 金鑰暴露！
|
||||
'anthropic-version': '2023-06-01'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
model: 'claude-3-5-sonnet-20241022',
|
||||
messages: [{ role: 'user', content: 'Hello' }]
|
||||
})
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ 正確的做法（透過後端代理）
|
||||
|
||||
```javascript
|
||||
// 透過後端 API 呼叫
|
||||
async function generateContent(prompt) {
|
||||
try {
|
||||
const response = await fetch('http://localhost:3000/api/llm/generate', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
prompt: prompt,
|
||||
provider: 'claude',
|
||||
options: {
|
||||
temperature: 0.7,
|
||||
maxTokens: 2000
|
||||
}
|
||||
})
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP error! status: ${response.status}`);
|
||||
}
|
||||
|
||||
const result = await response.json();
|
||||
|
||||
if (result.success) {
|
||||
console.log('生成的內容:', result.content);
|
||||
return result.content;
|
||||
} else {
|
||||
throw new Error(result.error?.message || '生成失敗');
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('錯誤:', error);
|
||||
// 顯示錯誤訊息給使用者
|
||||
showErrorModal({
|
||||
title: 'API 錯誤',
|
||||
message: error.message
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// 使用範例
|
||||
generateContent('請介紹 HR 績效評核系統的四卡循環');
|
||||
```
|
||||
|
||||
## 🎯 API 端點說明
|
||||
|
||||
### 測試連線
|
||||
|
||||
```javascript
|
||||
// 測試 Claude API
|
||||
POST http://localhost:3000/api/llm/test/claude
|
||||
|
||||
// 測試所有 LLM
|
||||
POST http://localhost:3000/api/llm/test/all
|
||||
|
||||
// 回應格式
|
||||
{
|
||||
"success": true,
|
||||
"message": "Claude API connection successful",
|
||||
"provider": "claude",
|
||||
"model": "claude-3-5-sonnet-20241022"
|
||||
}
|
||||
```
|
||||
|
||||
### 生成內容
|
||||
|
||||
```javascript
|
||||
POST http://localhost:3000/api/llm/generate
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"prompt": "你的提示內容",
|
||||
"provider": "claude", // 可選: claude, gemini, deepseek, openai
|
||||
"options": {
|
||||
"temperature": 0.7, // 可選: 0.0-1.0
|
||||
"maxTokens": 2000 // 可選: 最大生成長度
|
||||
}
|
||||
}
|
||||
|
||||
// 回應格式
|
||||
{
|
||||
"success": true,
|
||||
"content": "生成的內容...",
|
||||
"provider": "claude"
|
||||
}
|
||||
```
|
||||
|
||||
### Help Me AI（智能填寫）
|
||||
|
||||
```javascript
|
||||
POST http://localhost:3000/api/llm/help-me-fill
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"cardType": "performance",
|
||||
"cardId": "PF-2024-001",
|
||||
"filledFields": {
|
||||
"kra1_title": "產品上市時程",
|
||||
"kra1_weight": 40
|
||||
},
|
||||
"emptyFields": [
|
||||
"kra1_output",
|
||||
"kra1_self_note"
|
||||
],
|
||||
"context": {
|
||||
"roleCard": {...},
|
||||
"competencyCard": {...}
|
||||
}
|
||||
}
|
||||
|
||||
// 回應格式
|
||||
{
|
||||
"success": true,
|
||||
"filledCount": 2,
|
||||
"suggestions": {
|
||||
"kra1_output": "Q1 完成 MVP 開發...",
|
||||
"kra1_self_note": "超額達成目標..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔒 安全性考量
|
||||
|
||||
### 1. API 金鑰保護
|
||||
- ✅ 儲存在 `.env` 檔案
|
||||
- ✅ 不提交到 Git（已在 `.gitignore` 中）
|
||||
- ✅ 只在後端使用
|
||||
- ❌ 絕不在前端程式碼中暴露
|
||||
|
||||
### 2. CORS 設定
|
||||
```javascript
|
||||
// server.js 中的 CORS 設定
|
||||
app.use(cors({
|
||||
origin: process.env.FRONTEND_URL || '*', // 生產環境應限制來源
|
||||
methods: ['GET', 'POST', 'PUT', 'DELETE'],
|
||||
allowedHeaders: ['Content-Type', 'Authorization'],
|
||||
credentials: true
|
||||
}));
|
||||
```
|
||||
|
||||
### 3. 錯誤處理
|
||||
- 統一的錯誤格式
|
||||
- 不洩露敏感資訊
|
||||
- 記錄錯誤日誌
|
||||
|
||||
## 🐛 常見問題
|
||||
|
||||
### Q1: 為什麼還是顯示 CORS 錯誤？
|
||||
|
||||
**A:** 確認以下事項：
|
||||
1. 後端伺服器是否正在運行？（`npm run dev`）
|
||||
2. 前端是否呼叫正確的 API 地址？（`http://localhost:3000`）
|
||||
3. 瀏覽器是否快取了舊的錯誤？（清除快取或使用無痕模式）
|
||||
|
||||
### Q2: API 回傳 "Claude API key not configured"
|
||||
|
||||
**A:** 檢查：
|
||||
1. `.env` 檔案中是否設定了 `CLAUDE_API_KEY`
|
||||
2. 環境變數的值是否正確
|
||||
3. 重新啟動伺服器以載入新的環境變數
|
||||
|
||||
### Q3: 連線超時
|
||||
|
||||
**A:** 可能原因：
|
||||
1. 網路連線問題
|
||||
2. API 金鑰無效
|
||||
3. Anthropic 服務暫時無法使用
|
||||
4. 超時設定太短（預設 30 秒）
|
||||
|
||||
### Q4: 如何在生產環境部署？
|
||||
|
||||
**A:** 部署步驟：
|
||||
1. 設定環境變數（不要使用 `.env` 檔案）
|
||||
2. 限制 CORS 來源為您的網域
|
||||
3. 使用 HTTPS
|
||||
4. 設定適當的速率限制
|
||||
5. 記錄和監控 API 使用情況
|
||||
|
||||
## 📚 相關檔案
|
||||
|
||||
- [server.js](server.js) - Express 伺服器
|
||||
- [routes/llm.routes.js](routes/llm.routes.js) - API 路由
|
||||
- [services/llm.service.js](services/llm.service.js) - LLM 服務
|
||||
- [config/llm.config.js](config/llm.config.js) - LLM 配置
|
||||
- [utils/errorHandler.js](utils/errorHandler.js) - 錯誤處理
|
||||
- [public/api-proxy-example.html](public/api-proxy-example.html) - 範例頁面
|
||||
|
||||
## 🎉 完成！
|
||||
|
||||
現在您可以安全地透過後端 API 呼叫 Claude 和其他 LLM 服務，不再有 CORS 錯誤！
|
||||
|
||||
如有任何問題，請參考：
|
||||
- [README.md](README.md) - 專案說明
|
||||
- [database/README.md](database/README.md) - 資料庫文件
|
||||
- [docs/GITEA_SETUP.md](docs/GITEA_SETUP.md) - Git 設定
|
||||
|
||||
---
|
||||
|
||||
**最後更新**: 2025-12-03
|
||||
**問題回報**: https://gitea.theaken.com/donald/hr-performance-system/issues
|
||||
Reference in New Issue
Block a user