---
title: 'K8S 部署脚本'
slug: 'k8s-deploy'
created: '2026-03-20T07:00:00.000Z'
status: 'ready-for-dev'
stepsCompleted: [1, 2, 3, 4]
tech_stack: ['TypeScript', '@kubernetes/client-node', 'Node.js', 'dotenv', 'express']
files_to_modify:
  - 'package.json'
  - 'scripts/deploy.ts'
code_patterns:
  - 'K8S 客户端: @kubernetes/client-node SDK 封装'
  - '部署流程: Deployment → Service → Ingress'
  - 'EIP: k8s.aliyun.com/eci-open-enable-eip 自动创建'
  - '抢占式实例: 未启用（可选优化）'
  - '命名空间: d8d-proxy (专用命名空间)'
  - '实例规格: ecs.t5-lc2m1.nano (完整字符串)'
  - 'Ingress 域名: {name}-{port}.{hostSuffix}'
test_patterns: []
---

# Tech-Spec: K8S 部署脚本

**Created:** 2026-03-20T07:00:00.000Z

## Overview

### Problem Statement

Claude API 代理服务已完成，需要添加 K8S 部署脚本来动态创建和管理 Pod 实例。每个 Pod 需要独立的出口 IP (通过 EIP)，以便分散请求绕过官方 API 的 IP 并发限制。

### Solution

1. 安装 `@kubernetes/client-node` 依赖
2. 使用已实现的 `src/k8s-client.ts` K8S 客户端封装
3. 使用已实现的 `src/deploy.ts` 部署模块
4. 创建 `scripts/deploy.ts` 命令行入口

### Scope

**In Scope:**
- 安装 @kubernetes/client-node 依赖
- 命令行部署工具
- 部署脚本：创建/删除 Deployment、Service、Ingress
- 自动 EIP 创建支持
- 专用命名空间 `d8d-proxy`
- 健康检查配置

**Out of Scope:**
- API Key 池管理（由 D8D 主项目处理）
- 复杂的监控和告警
- HPA 自动扩缩容

## Context for Development

### Codebase Patterns

**已实现的文件：**

| 文件 | 状态 | 描述 |
|------|------|------|
| `src/k8s-client.ts` | ✅ 已完成 | K8S SDK 封装类 |
| `src/deploy.ts` | ✅ 已完成 | 部署/删除/状态查询功能 |
| `.env.example` | ✅ 已完成 | K8S 环境变量配置 |
| `package.json` | ❌ 缺少依赖 | 需添加 @kubernetes/client-node |
| `scripts/deploy.ts` | ❌ 未创建 | 命令行入口 |

**阿里云 ECI 注解（已实现写法）：**
- `k8s.aliyun.com/eci-use-specs: "ecs.t5-lc2m1.nano"` - 指定 ECI 规格
- `k8s.aliyun.com/eci-open-enable-eip: "true"` - 自动创建 EIP
- `k8s.aliyun.com/eci-eip-bandwidth: "5"` - EIP 带宽 5Mbps
- `k8s.aliyun.com/eci-eip-internet-charge-type: "PayByBandwidth"` - 按带宽计费

### Files to Reference

| File | Purpose |
| ---- | ------- |
| `src/k8s-client.ts` | K8S SDK 封装（已实现） |
| `src/deploy.ts` | 部署模块（已实现） |

### Technical Decisions

- **命名空间**: `d8d-proxy` (专用，避免与 d8d-dev/d8d-prd 冲突)
- **K8S 客户端**: 使用 @kubernetes/client-node SDK
- **认证方式**: K8S_API_URL + K8S_API_TOKEN 环境变量
- **EIP 配置**: 自动创建（通过 ECI annotation）
- **容器规格**: `ecs.t5-lc2m1.nano` (0.5 CPU, 1G 内存)
- **Ingress 域名**: `{name}-{port}.{hostSuffix}`
- **镜像**: registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:${VERSION}
- **健康检查**: /health 端点
- **Ingress**: 无需 SSO 认证（代理服务）

## Implementation Plan

### Tasks

**Task 1: 安装 K8S 依赖**
- [ ] 执行 `pnpm add @kubernetes/client-node`
- [ ] 验证依赖安装成功

**Task 2: 创建命令行入口**
- [ ] File: `scripts/deploy.ts`
- [ ] Action: 创建命令行工具，支持以下命令：
  - `deploy <name> <image>` - 部署代理服务
  - `delete <name>` - 删除代理服务
  - `status <name>` - 查询服务状态
- [ ] Notes: 使用 tsx 运行，参考参数：
  - `--replicas` 副本数（默认 1）
  - `--port` 端口（默认 3000）
  - `--eip-bandwidth` EIP 带宽（默认 5）

**Task 3: 添加 npm 脚本**
- [ ] File: `package.json`
- [ ] Action: 添加部署相关脚本：
  ```json
  "deploy": "tsx scripts/deploy.ts"
  ```

### Acceptance Criteria

- [ ] **AC1: 依赖安装成功**
  - Given: 执行 pnpm install
  - When: 安装 @kubernetes/client-node
  - Then: 依赖正确安装，TypeScript 编译无错误

- [ ] **AC2: 部署命令可执行**
  - Given: 环境变量 K8S_API_URL 和 K8S_API_TOKEN 已配置
  - When: 执行 `pnpm deploy <name> <image>`
  - Then: 成功创建 Deployment、Service、Ingress，返回访问 URL

- [ ] **AC3: EIP 自动创建**
  - Given: 部署时启用 EIP 选项（默认启用）
  - When: Pod 启动
  - Then: 自动创建并绑定 EIP

- [ ] **AC4: 删除功能正常**
  - Given: 已部署的代理服务
  - When: 执行 `pnpm deploy delete <name>`
  - Then: 清理所有 K8S 资源（Deployment、Service、Ingress）

- [ ] **AC5: 状态查询正常**
  - Given: 已部署的代理服务
  - When: 执行 `pnpm deploy status <name>`
  - Then: 返回服务运行状态和访问 URL

## Additional Context

### Dependencies

**新增依赖：**
- @kubernetes/client-node - K8S 官方 Node.js SDK

### Testing Strategy

**手动测试步骤：**
1. 配置 `.env` 文件中的 K8S 环境变量
2. 执行 `pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.1`
3. 验证 Deployment、Service、Ingress 创建成功
4. 访问返回的 HTTPS URL 验证服务可用
5. 执行删除命令验证资源清理

### Notes

- 命名空间独立，避免与 d8d-dev/d8d-prd 冲突
- 代理服务无需 SSO 认证
- EIP 自动创建简化了 IP 管理
- 当前未启用抢占式实例，后续可优化成本