aws-server-sdk/README.md

AWS Server Go SDK

供其他 Go 应用通过应用密钥调用 AWS Server 平台，完成 EC2 创建、价格预估和完整生命周期管理。SDK 只使用稳定的 /api/sdk/v1 接口，不需要也不会接触管理员 Token、AWS 账号 ID 或 AWS 凭证。

安装

go get gitea.s1f.ren/shiran/aws-server-sdk@v0.1.0

初始化

client, err := awsserversdk.NewClient(
    "https://aws.example.com",
    os.Getenv("AWS_SERVER_APP_TOKEN"),
)

管理员需要先在平台创建客户端应用，为应用配置允许的 Region、权限范围和网络位置，并创建一次性显示的应用 Token。

完整创建流程

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；省略时由平台选择可用网络位置。

实例管理

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 自动生成，并在网络重试中始终复用同一个值。

错误与敏感信息

if awsserversdk.IsBudgetExceeded(err) { /* 提示额度不足 */ }
if awsserversdk.IsUnauthorized(err) { /* 检查 Token、权限范围或 Region */ }

密码和私钥使用 Secret 类型，日志和 JSON 序列化默认显示 [REDACTED]。只有显式调用 Reveal() 才能取得明文。

兼容性

• SDK v0.x 对应平台 /api/sdk/v1。
• 服务端可以增加响应字段；SDK 会忽略未知字段。
• 首版异步结果使用任务轮询，不提供 Webhook。