proxycast/docs/content/04.api-reference/4.management-api.md

---
title: 管理 API
description: ProxyCast 远程管理 API 端点
navigation:
  icon: i-heroicons-cog-6-tooth
---

# 管理 API

ProxyCast 提供远程管理 API，用于配置和监控服务。

## 认证

所有管理 API 请求需要在 `Authorization` 头中提供密钥：

```bash
Authorization: Bearer your-secret-key
```

## 访问控制

管理 API 的访问受以下配置控制：

| 配置项 | 说明 |
|--------|------|
| `secret_key` | 管理密钥，为空时禁用所有管理端点（返回 404） |
| `allow_remote` | 是否允许远程访问，为 false 时仅允许 localhost |

::alert{type="warning"}
当前版本未启用 TLS，仅支持本地访问，`allow_remote` 必须保持为 `false`。
::

## /v0/management/status

获取服务器状态信息。

### 请求

```bash
GET /v0/management/status
Authorization: Bearer your-secret-key
```

### 响应

```json
{
  "status": "running",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "tls_enabled": false,
  "active_credentials": 5,
  "total_requests": 1234,
  "providers": {
    "kiro": {
      "enabled": true,
      "credentials_count": 2
    },
    "gemini": {
      "enabled": true,
      "credentials_count": 1
    }
  }
}
```

## /v0/management/credentials

### 获取凭证列表

```bash
GET /v0/management/credentials
Authorization: Bearer your-secret-key
```

### 响应

```json
{
  "credentials": [
    {
      "id": "kiro-main",
      "provider": "kiro",
      "type": "oauth",
      "status": "valid",
      "expires_at": "2025-01-01T00:00:00Z",
      "disabled": false
    },
    {
      "id": "gemini-key-1",
      "provider": "gemini_api_key",
      "type": "api_key",
      "status": "valid",
      "disabled": false,
      "excluded_models": ["gemini-2.5-pro"]
    }
  ]
}
```

### 添加凭证

```bash
POST /v0/management/credentials
Authorization: Bearer your-secret-key
Content-Type: application/json
```

#### 添加 OAuth 凭证

```json
{
  "provider": "kiro",
  "id": "kiro-new",
  "token_file": "kiro/new-token.json"
}
```

#### 添加 API Key 凭证

```json
{
  "provider": "openai",
  "id": "openai-new",
  "api_key": "sk-xxx...",
  "base_url": "https://api.openai.com/v1"
}
```

#### 添加 Gemini API Key

```json
{
  "provider": "gemini_api_key",
  "id": "gemini-key-new",
  "api_key": "AIzaSy...",
  "base_url": "https://generativelanguage.googleapis.com",
  "excluded_models": ["gemini-2.5-pro", "*-preview"]
}
```

### 响应

```json
{
  "success": true,
  "credential_id": "kiro-new"
}
```

### 删除凭证

```bash
DELETE /v0/management/credentials/{credential_id}
Authorization: Bearer your-secret-key
```

### 响应

```json
{
  "success": true
}
```

## /v0/management/config

### 获取配置

```bash
GET /v0/management/config
Authorization: Bearer your-secret-key
```

### 响应

```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 8999,
    "tls": {
      "enable": false
    }
  },
  "routing": {
    "default_provider": "kiro"
  },
  "quota_exceeded": {
    "switch_project": true,
    "switch_preview_model": true,
    "cooldown_seconds": 300
  }
}
```

### 更新配置

```bash
PUT /v0/management/config
Authorization: Bearer your-secret-key
Content-Type: application/json
```

```json
{
  "routing": {
    "default_provider": "gemini"
  },
  "quota_exceeded": {
    "cooldown_seconds": 600
  }
}
```

### 响应

```json
{
  "success": true,
  "restart_required": false
}
```

> **注意**: 某些配置更改（如 TLS、端口）需要重启服务器才能生效。

## 错误响应

### 401 Unauthorized

密钥无效或缺失：

```json
{
  "error": {
    "message": "Invalid or missing secret key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

### 403 Forbidden

远程访问被禁止：

```json
{
  "error": {
    "message": "Remote access not allowed",
    "type": "permission_error",
    "code": "remote_access_denied"
  }
}
```

### 404 Not Found

管理 API 已禁用（secret_key 为空）：

```json
{
  "error": {
    "message": "Management API is disabled",
    "type": "not_found_error",
    "code": "endpoint_not_found"
  }
}
```

## 示例代码

### cURL

```bash
# 获取状态
curl http://127.0.0.1:8999/v0/management/status \
  -H "Authorization: Bearer your-secret-key"

# 获取凭证列表
curl http://127.0.0.1:8999/v0/management/credentials \
  -H "Authorization: Bearer your-secret-key"

# 添加凭证
curl http://127.0.0.1:8999/v0/management/credentials \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "id": "openai-new", "api_key": "sk-xxx"}'
```

### Python

```python
import requests

BASE_URL = "http://127.0.0.1:8999"
SECRET_KEY = "your-secret-key"

headers = {
    "Authorization": f"Bearer {SECRET_KEY}",
    "Content-Type": "application/json"
}

# 获取状态
response = requests.get(f"{BASE_URL}/v0/management/status", headers=headers)
print(response.json())

# 添加凭证
credential = {
    "provider": "openai",
    "id": "openai-new",
    "api_key": "sk-xxx"
}
response = requests.post(
    f"{BASE_URL}/v0/management/credentials",
    headers=headers,
    json=credential
)
print(response.json())
```