DEPLOYMENT.md

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

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

📋 目錄

1. 前置需求
2. 構建 Go 二進制
3. 快速部署
4. 配置 Secrets
5. 使用說明
6. 常見問題

---

前置需求

必需項目

1. Hugging Face 帳號

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

2. Go 編譯環境（用於構建二進制）

   • Go 1.26 或更高版本
   • 下載地址: https://go.dev/dl/

3. AI 服務提供商帳號（至少需要一個）

   • Anthropic Claude
   • Google AI Studio
   • GitHub Copilot
   • AWS Kiro

可選項目

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

---

構建 Go 二進制

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

步驟 1：克隆專案

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

步驟 2：構建 Linux 二進制

Linux/macOS:

GOOS=linux GOARCH=amd64 go build -o hf-spaces/CLIProxyAPIPlus ./cmd/server/

Windows (PowerShell):

$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o hf-spaces/CLIProxyAPIPlus ./cmd/server/

步驟 3：驗證構建

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

---

快速部署

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

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

   # 使用 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 後，克隆到本地

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

2. 複製文件

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

3. 提交並推送

   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
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

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:

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
2. 在 HF Space 上開啟 Discussion
3. 聯繫維護者

---

授權

本項目採用 MIT 授權條款。詳見 LICENSE 文件。