# xiangongyun_api **Repository Path**: hezuo_111_admin/xiangongyun_api ## Basic Information - **Project Name**: xiangongyun_api - **Description**: 基于 FastAPI + SOLID 原则设计的仙宫云 GPU 实例管理 Python SDK 与异步 API 服务 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: bwx_dev - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-10 - **Last Updated**: 2026-02-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 仙宫云 Python SDK & API 服务 > 基于 **FastAPI + SOLID 原则** 设计的仙宫云 GPU 实例管理 Python SDK 与异步 API 服务 [![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ## ✨ 特性 - 🚀 **异步 API 服务** - 基于 FastAPI 的高性能异步接口 - 🎯 **SOLID 设计** - 遵循 SOLID 原则的优雅架构 - 📦 **统一入口** - 同时提供 SDK 和 API 服务两种使用方式 - 🔒 **完整认证** - 支持 Bearer Token 认证 - 📚 **自动文档** - Swagger UI 和 ReDoc 自动生成 - 🛠️ **类型安全** - 基于 Pydantic 的类型验证 ## 📦 安装 ```bash # 克隆仓库 git clone https://github.com/your-username/xiangongyun_api.git cd xiangongyun_api # 安装依赖 pip install -r requirements.txt ``` ## ⚙️ 配置 在项目根目录创建 `.env` 文件： ```env # ==================== 仙宫云配置 ==================== # API 密钥（必填） XIANGONGYUN_API_KEY=your_api_key_here # API 地址（可选，默认为官方地址） # XIANGONGYUN_API_URL=https://api.xiangongyun.com # ==================== API 服务配置 ==================== # 访问令牌（可选，用于保护 API 服务） # SERVER_ACCESS_TOKEN=your_secret_token_here # ==================== 服务器配置 ==================== # 服务主机地址（可选，默认 127.0.0.1） FASTAPI_HOST=127.0.0.1 # 服务端口（可选，默认 8000） FASTAPI_PORT=8000 # ==================== 业务配置 ==================== # 默认镜像 ID（可选） # MIRROR_IMAGE_ID=your_default_image_id ``` ## 🚀 启动服务 ```bash # 方式一：使用 uvicorn 直接启动 python -m uvicorn api_server.main:app --host 127.0.0.1 --port 8000 # 方式二：使用 run.py 启动 python run.py ``` 服务将在 `http://127.0.0.1:8000` 启动。 访问 API 文档： - **Swagger UI**: http://127.0.0.1:8000/docs - **ReDoc**: http://127.0.0.1:8000/redoc ## 🎯 使用方式 ### 方式一：作为 Python SDK 使用 ```python from api_server import XiangongyunClient, GPUModel, ImageType # 创建客户端 with XiangongyunClient(api_key="your_api_key") as client: # 获取实例列表 instances = client.instance.list_instances() for inst in instances: print(f"{inst.name}: {inst.status}") print(f" GPU: {inst.gpu_model} x {inst.gpu_used}") print(f" 价格: ¥{inst.total_price_per_hour}/小时") # 部署新实例 instance_id = client.instance.deploy( params=DeployParams( gpu_model=GPUModel.RTX_4090, gpu_count=1, data_center_id=1, image="260cd46a-12aa-44ed-b47a-88f770b49041", image_type=ImageType.PUBLIC, name="我的GPU实例" ) ) print(f"新实例 ID: {instance_id}") # 开机实例 client.instance.boot(instance_id) # 关机实例 client.instance.shutdown(instance_id) # 销毁实例 client.instance.destroy(instance_id) ``` ### 方式二：作为 API 服务使用 #### API 调用示例 ```bash # 获取实例列表 curl -X GET "http://127.0.0.1:8000/api/v1/instances" \ -H "Authorization: Bearer your_token" # 部署新实例 curl -X POST "http://127.0.0.1:8000/api/v1/instances/deploy" \ -H "Authorization: Bearer your_token" \ -H "Content-Type: application/json" \ -d '{ "gpu_model": "NVIDIA GeForce RTX 4090", "gpu_count": 1, "data_center_id": 1, "image_id": "260cd46a-12aa-44ed-b47a-88f770b49041", "name": "我的实例" }' # 开机实例 curl -X POST "http://127.0.0.1:8000/api/v1/instances/{instance_id}/boot" \ -H "Authorization: Bearer your_token" # 关机实例 curl -X POST "http://127.0.0.1:8000/api/v1/instances/{instance_id}/shutdown" \ -H "Authorization: Bearer your_token" # 销毁实例 curl -X DELETE "http://127.0.0.1:8000/api/v1/instances/{instance_id}" \ -H "Authorization: Bearer your_token" ``` ### Python 客户端调用 API 服务 ```python import httpx class XiangongyunAPIClient: def __init__(self, base_url: str, token: str): self.base_url = base_url self.client = httpx.Client( headers={"Authorization": f"Bearer {token}"} ) def list_instances(self): response = self.client.get(f"{self.base_url}/api/v1/instances") return response.json() def deploy(self, gpu_model: str, image_id: str, name: str = ""): response = self.client.post( f"{self.base_url}/api/v1/instances/deploy", json={ "gpu_model": gpu_model, "gpu_count": 1, "data_center_id": 1, "image_id": image_id, "name": name } ) return response.json() # 使用 client = XiangongyunAPIClient( base_url="http://127.0.0.1:8000", token="your_secret_token" ) # 获取实例列表 instances = client.list_instances() print(instances) ``` ## 📁 项目结构 ``` xiangongyun_api/ ├── api_server/ # API 服务模块（整合核心功能） │ ├── core/ # 仙宫云核心模块 │ │ ├── client.py # 客户端主类 │ │ ├── config.py # 配置与枚举 │ │ ├── http.py # HTTP 客户端 │ │ ├── exceptions.py # 异常定义 │ │ ├── apis/ # API 实现 │ │ └── models/ # 数据模型 │ ├── config.py # 应用配置 │ ├── containers.py # 依赖注入 │ ├── dtos/ # 数据传输对象 │ ├── middleware/ # 中间件 │ ├── repositories/ # 仓储层 │ ├── routes/ # API 路由 │ └── services/ # 业务服务 ├── run.py # 启动脚本 ├── requirements.txt # 依赖 ├── .env # 环境配置 └── README.md # 本文档 ``` ## 🔌 API 端点 ### 基础接口 | 方法 | 端点 | 说明 | |-----|------|------| | GET | `/` | 服务信息 | | GET | `/health` | 健康检查 | ### 实例管理 | 方法 | 端点 | 说明 | |-----|------|------| | GET | `/api/v1/instances` | 获取实例列表 | | GET | `/api/v1/instances/{id}` | 获取实例详情 | | POST | `/api/v1/instances/deploy` | 部署新实例 | | POST | `/api/v1/instances/{id}/boot` | 开机实例 | | POST | `/api/v1/instances/{id}/shutdown` | 关机实例 | | POST | `/api/v1/instances/{id}/shutdown-release-gpu` | 关机实例并释放 GPU | | POST | `/api/v1/instances/{id}/shutdown-and-destroy` | 关机并销毁实例 | | POST | `/api/v1/instances/{id}/save-image` | 保存实例为镜像 | | POST | `/api/v1/instances/{id}/save-image-destroy` | 保存实例为镜像并销毁 | | GET | `/api/v1/instances/{id}/images` | 获取实例保存的镜像列表 | | DELETE | `/api/v1/instances/{id}` | 销毁实例 | ### 镜像管理 | 方法 | 端点 | 说明 | |-----|------|------| | GET | `/api/v1/images/public` | 获取公共镜像列表 | | GET | `/api/v1/images` | 获取私有镜像列表 | | GET | `/api/v1/images/{id}` | 获取单个私有镜像详情 | | DELETE | `/api/v1/images/{id}` | 删除私有镜像 | ### 账号管理 | 方法 | 端点 | 说明 | |-----|------|------| | GET | `/api/v1/account/balance` | 获取账户余额 | | GET | `/api/v1/account/info` | 获取用户信息 | | GET | `/api/v1/account/consumption` | 获取消费记录 | | POST | `/api/v1/account/recharge/order` | 创建充值订单 | | GET | `/api/v1/account/recharge/order/{trade_no}` | 查询充值订单 | ## 🏗️ 架构设计 本项目遵循 **SOLID 原则**： | 原则 | 应用 | |-----|------| | **S** 单一职责 | 每个模块职责明确（core、repositories、services、routes） | | **O** 开闭原则 | 通过扩展添加新功能，不修改现有代码 | | **L** 里氏替换 | 仓储抽象可被具体实现替换 | | **I** 接口隔离 | 各层接口独立（InstanceAPI、ImageAPI、AccountAPI） | | **D** 依赖倒置 | 依赖抽象而非具体实现（依赖注入容器） | ## 📝 导出列表 ```python # 应用 from api_server import create_app # 客户端与配置 from api_server import ( XiangongyunClient, XiangongyunConfig, GPUModel, ImageType, InstanceStatus, ) # 异常 from api_server import ( XiangongyunError, AuthenticationError, APIError, ValidationError, ) # 模型 from api_server import Instance, Image, ApiResponse ``` ## 🌐 公网访问端口地址 仙宫云容器实例的公网访问地址格式： ``` https://{实例ID}-{端口号}.container.x-gpu.com ``` 例如： - 实例 ID：`2lb5nfqs23cao61n` - 应用端口：`8188` - 访问地址：`https://2lb5nfqs23cao61n-8188.container.x-gpu.com` ## 🔑 环境变量 | 变量名 | 说明 | 必填 | 默认值 | |-------|------|------|-------| | `XIANGONGYUN_API_KEY` | 仙宫云 API 密钥 | 是 | - | | `XIANGONGYUN_API_URL` | API 地址 | 否 | `https://api.xiangongyun.com` | | `SERVER_ACCESS_TOKEN` | API 服务访问令牌 | 否 | - | | `FASTAPI_HOST` | 服务主机地址 | 否 | `127.0.0.1` | | `FASTAPI_PORT` | 服务端口 | 否 | `8000` | | `MIRROR_IMAGE_ID` | 默认镜像 ID | 否 | - | ## 📄 许可证 [MIT License](LICENSE) ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ ## 📮 联系方式 - 项目主页：[GitHub](https://github.com/your-username/xiangongyun_api) - 问题反馈：[Issues](https://github.com/your-username/xiangongyun_api/issues)