101 lines
3.5 KiB
Markdown
101 lines
3.5 KiB
Markdown
# AWS Server Go SDK
|
|
|
|
供其他 Go 应用通过应用密钥调用 AWS Server 平台，完成 EC2 创建、价格预估和完整生命周期管理。SDK 只使用稳定的 `/api/sdk/v1` 接口，不需要也不会接触管理员 Token、AWS 账号 ID 或 AWS 凭证。
|
|
|
|
## 安装
|
|
|
|
```bash
|
|
go get gitea.s1f.ren/shiran/aws-server-sdk@v0.1.0
|
|
```
|
|
|
|
## 初始化
|
|
|
|
```go
|
|
client, err := awsserversdk.NewClient(
|
|
"https://aws.example.com",
|
|
os.Getenv("AWS_SERVER_APP_TOKEN"),
|
|
)
|
|
```
|
|
|
|
管理员需要先在平台创建客户端应用，为应用配置允许的 Region、权限范围和网络位置，并创建一次性显示的应用 Token。
|
|
|
|
## 完整创建流程
|
|
|
|
```go
|
|
ctx := context.Background()
|
|
|
|
options, err := client.Catalog.GetCreateOptions(ctx, "ap-northeast-1")
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
estimate, err := client.Pricing.EstimateInstance(ctx, "ap-northeast-1", awsserversdk.CreateInstanceRequest{
|
|
PlacementID: options.Placements[0].PlacementID,
|
|
ImageID: options.Images[0].ImageID,
|
|
InstanceType: options.InstanceTypes[0].InstanceType,
|
|
RootVolume: &awsserversdk.VolumeSpec{SizeGiB: 30, Type: "gp3"},
|
|
AssociateEIP: true,
|
|
})
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
log.Printf("hourly=%f calendar_month=%f %s", estimate.HourlyPrice, estimate.CalendarMonthPrice, estimate.Currency)
|
|
|
|
operation, err := client.Instances.Create(ctx, "ap-northeast-1", awsserversdk.CreateInstanceRequest{
|
|
PlacementID: options.Placements[0].PlacementID,
|
|
ImageID: options.Images[0].ImageID,
|
|
InstanceType: options.InstanceTypes[0].InstanceType,
|
|
Name: "sdk-created",
|
|
RootVolume: &awsserversdk.VolumeSpec{SizeGiB: 30, Type: "gp3"},
|
|
SecurityGroupMode: "common_ports",
|
|
AssociateEIP: true,
|
|
})
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
task, err := operation.Wait(ctx)
|
|
```
|
|
|
|
创建接口不接受 `account_id` 和 `subnet_id`。可以传管理员配置的 `placement_id`；省略时由平台选择可用网络位置。
|
|
|
|
## 实例管理
|
|
|
|
```go
|
|
instances, _ := client.Instances.List(ctx, region, awsserversdk.InstanceListOptions{Limit: 50})
|
|
details, _ := client.Instances.GetDetails(ctx, region, instanceID)
|
|
|
|
stop, _ := client.Instances.Stop(ctx, region, instanceID)
|
|
_, _ = stop.Wait(ctx)
|
|
resize, _ := client.Instances.Resize(ctx, region, instanceID, awsserversdk.ResizeInstanceRequest{InstanceType: "t3.small"})
|
|
_, _ = resize.Wait(ctx)
|
|
rebuild, _ := client.Instances.Rebuild(ctx, region, instanceID, awsserversdk.RebuildInstanceRequest{ImageID: "ami-..."})
|
|
_, _ = rebuild.Wait(ctx)
|
|
```
|
|
|
|
其他服务入口：
|
|
|
|
- `SecurityGroups`：查看、添加和删除安全组规则。
|
|
- `Volumes`：创建、挂载、卸载、扩容和删除数据卷。
|
|
- `EIPs`：申请或更换 EIP、设置 PTR 反向解析。
|
|
- `Traffic`：查询和修改实例出站流量额度。
|
|
- `Access`：登录信息、密码轮换和 SSH Key；需要敏感权限。
|
|
- `Agent`：Agent 状态、命令、升级、MOTD 和 SSH 审计。
|
|
- `Tasks`：应用自身任务的分页查询和等待。
|
|
|
|
所有修改方法接受可选的 `WithIdempotencyKey`。省略时 SDK 自动生成，并在网络重试中始终复用同一个值。
|
|
|
|
## 错误与敏感信息
|
|
|
|
```go
|
|
if awsserversdk.IsBudgetExceeded(err) { /* 提示额度不足 */ }
|
|
if awsserversdk.IsUnauthorized(err) { /* 检查 Token、权限范围或 Region */ }
|
|
```
|
|
|
|
密码和私钥使用 `Secret` 类型，日志和 JSON 序列化默认显示 `[REDACTED]`。只有显式调用 `Reveal()` 才能取得明文。
|
|
|
|
## 兼容性
|
|
|
|
- SDK `v0.x` 对应平台 `/api/sdk/v1`。
|
|
- 服务端可以增加响应字段；SDK 会忽略未知字段。
|
|
- 首版异步结果使用任务轮询，不提供 Webhook。
|