DEPLOYMENT.md

# CLI Proxy API Plus - Hugging Face Spaces 部署指南

本文檔提供完整的 Hugging Face Spaces 部署步驟說明。

## 📋 目錄

1. [前置需求](#前置需求)
2. [構建 Go 二進制](#構建-go-二進制)
3. [快速部署](#快速部署)
4. [配置 Secrets](#配置-secrets)
5. [使用說明](#使用說明)
6. [常見問題](#常見問題)

---

## 前置需求

### 必需項目

1. **Hugging Face 帳號**
   - 註冊地址: https://huggingface.co/join
   - 建議啟用兩步驗證以保護帳號安全

2. **Go 編譯環境**（用於構建二進制）
   - Go 1.26 或更高版本
   - 下載地址: https://go.dev/dl/

3. **AI 服務提供商帳號**（至少需要一個）
   - [Anthropic Claude](https://console.anthropic.com/)
   - [Google AI Studio](https://aistudio.google.com/)
   - [GitHub Copilot](https://github.com/features/copilot)
   - [AWS Kiro](https://aws.amazon.com/)

### 可選項目

- 自定義域名（可在 HF Spaces 設置中配置）

---

## 構建 Go 二進制

**重要**：HF Spaces Dockerfile 需要預先構建的 Go 二進制文件。

### 步驟 1：克隆專案

```bash
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
```

### 步驟 2：構建 Linux 二進制

**Linux/macOS:**
```bash
GOOS=linux GOARCH=amd64 go build -o hf-spaces/CLIProxyAPIPlus ./cmd/server/
```

**Windows (PowerShell):**
```powershell
$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o hf-spaces/CLIProxyAPIPlus ./cmd/server/
```

### 步驟 3：驗證構建

```bash
ls -la hf-spaces/CLIProxyAPIPlus
# 應該顯示一個約 20-30MB 的可執行文件
```

---

## 快速部署

### 方法一：從模板創建（推薦）

1. **Fork 或 Clone 本項目到您的 HF 帳號**

   ```bash
   # 使用 Git
   git clone https://huggingface.co/spaces/YOUR_USERNAME/cli-proxy-api-plus
   ```

2. **創建新的 Space**
   - 前往 https://huggingface.co/new-space
   - 選擇 **Docker** 作為 SDK
   - 設置 Space 名稱（例如：`cli-proxy-api-plus`）
   - 選擇可見性（Public 或 Private）

3. **上傳文件**
   
   將 `hf-spaces/` 目錄下的所有文件上傳到 Space 根目錄：
   - `Dockerfile`
   - `supervisord.conf`
   - `requirements.txt`
   - `entrypoint.sh`
   - `README.md`
   - `streamlit_app/` 目錄

### 方法二：使用 Git 推送

1. **創建 Space 後，克隆到本地**

   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   cd YOUR_SPACE_NAME
   ```

2. **複製文件**

   ```bash
   # 從本項目複製 hf-spaces 內容
   cp -r /path/to/CLIProxyAPIPlus-main/hf-spaces/* .
   ```

3. **提交並推送**

   ```bash
   git add .
   git commit -m "Initial deployment"
   git push
   ```

4. **等待構建完成**
   
   HF Spaces 會自動開始構建 Docker 映像，通常需要 5-10 分鐘。

---

## 配置 Secrets

### 為什麼需要 Secrets？

Secrets 用於安全地存儲敏感信息，如 API 密鑰、OAuth 憑證等。這些信息不會出現在代碼中，確保安全性。

### 如何設置 Secrets

1. **進入 Space 設置頁面**
   - 打開您的 Space 頁面
   - 點擊右上角 **Settings** 標籤

2. **找到 Variables and Secrets 區塊**
   - 滾動到 **Variables and secrets** 部分
   - 點擊 **New secret**

3. **添加以下 Secrets**

#### 基礎配置

| Secret 名稱 | 說明 | 範例值 |
|------------|------|--------|
| `SERVER_PORT` | Go API 服務器端口 | `8317` |
| `LOG_LEVEL` | 日誌級別 | `info` |

#### Claude 配置

| Secret 名稱 | 說明 | 取得方式 |
|------------|------|----------|
| `CLAUDE_API_KEY` | Anthropic API Key | [Anthropic Console](https://console.anthropic.com/) |
| `CLAUDE_CLIENT_ID` | OAuth Client ID | OAuth 應用註冊 |
| `CLAUDE_CLIENT_SECRET` | OAuth Client Secret | OAuth 應用註冊 |

#### Gemini 配置

| Secret 名稱 | 說明 | 取得方式 |
|------------|------|----------|
| `GEMINI_API_KEY` | Google AI API Key | [Google AI Studio](https://aistudio.google.com/app/apikey) |

#### GitHub Copilot 配置

| Secret 名稱 | 說明 |
|------------|------|
| `GITHUB_CLIENT_ID` | GitHub OAuth App Client ID |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth App Client Secret |

#### Kiro 配置

| Secret 名稱 | 說明 |
|------------|------|
| `AWS_ACCESS_KEY_ID` | AWS Access Key |
| `AWS_SECRET_ACCESS_KEY` | AWS Secret Key |
| `AWS_REGION` | AWS 區域（如 `us-east-1`） |

### OAuth 回調 URL 設置

在配置 OAuth 應用時，需要設置正確的回調 URL：

```
https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/oauth/callback/{provider}
```

例如：
- Claude: `https://john-cli-proxy.hf.space/oauth/callback/claude`
- Gemini: `https://john-cli-proxy.hf.space/oauth/callback/gemini`
- GitHub: `https://john-cli-proxy.hf.space/oauth/callback/github`

---

## 使用說明

### 訪問應用

部署完成後，您可以通過以下 URL 訪問：

```
https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
```

### 主要功能

#### 1. 首頁（Dashboard）

- 查看 API 服務狀態
- 查看可用的 AI 提供商
- 快速導航到各功能頁面

#### 2. 💬 Chat 頁面

- 測試 API 端點
- 選擇不同的 AI 模型
- 發送測試請求
- 查看響應結果

#### 3. 🔑 Auth 頁面

- 管理 OAuth 登錄
- 查看 API 密鑰狀態
- 刷新認證令牌

#### 4. 📊 Stats 頁面

- 查看使用統計
- 請求次數圖表
- Token 使用量
- 模型分佈

#### 5. ⚙️ Settings 頁面

- 服務器配置
- 提供商設置
- 日誌查看

### API 端點

Go API 服務器運行在內部端口 8317，Streamlit 會代理請求：

```
# OpenAI 兼容端點
POST /v1/chat/completions
POST /v1/models

# Claude 端點
POST /v1/messages

# 管理端點
GET /api/status
GET /api/models
```

---

## 常見問題

### Q: 構建失敗怎麼辦？

**A:** 檢查以下項目：
1. 確保 `Dockerfile` 在根目錄
2. 檢查 `requirements.txt` 格式是否正確
3. 查看 Build Logs 中的錯誤信息

### Q: 應用無法啟動？

**A:** 可能原因：
1. Secrets 未正確配置
2. 端口衝突（HF Spaces 要求使用 7860）
3. 依賴安裝失敗

### Q: API 請求失敗？

**A:** 檢查：
1. API 密鑰是否有效
2. OAuth 令牌是否過期
3. 網絡連接是否正常

### Q: 如何更新應用？

**A:** 
```bash
git pull origin main
git push
```

HF Spaces 會自動重新構建。

### Q: 如何查看日誌？

**A:** 
1. 進入 Space 頁面
2. 點擊 **Logs** 標籤
3. 查看實時日誌輸出

### Q: 資源限制？

**A:** HF Spaces 免費版有以下限制：
- CPU: 2 vCPU
- 內存: 16GB
- 存儲: 臨時存儲（重啟後清除）

如需更多資源，可考慮升級到 GPU Space 或使用 HF Enterprise。

---

## 進階配置

### 自定義域名

1. 進入 Space Settings
2. 找到 **Custom Domain** 區塊
3. 輸入您的域名並按照指示配置 DNS

### 持久化存儲

HF Spaces 預設使用臨時存儲。如需持久化：

1. 使用 HF Datasets 存儲配置
2. 或使用外部數據庫（如 PostgreSQL）

### 擴展功能

您可以通過修改 `streamlit_app/` 中的文件來擴展功能：

- 添加新的頁面：在 `pages/` 目錄創建新文件
- 修改主題：編輯 `.streamlit/config.toml`
- 添加新功能：修改 `app.py`

---

## 技術支持

如有問題，請：

1. 查閱 [GitHub Issues](https://github.com/router-for-me/CLIProxyAPI/issues)
2. 在 HF Space 上開啟 Discussion
3. 聯繫維護者

---

## 授權

本項目採用 MIT 授權條款。詳見 [LICENSE](../LICENSE) 文件。