oracle-freetier-instance-creation的main.py源码逐段剖析:Python调用OCI API启动免费实例的5步流程

原创2026-11-16 11:50:0543 阅读

oracle-freetier-instance-creation的main.py源码逐段剖析:Python调用OCI API启动免费实例的5步流程

oracle-freetier-instance-creation 是一个用于自动创建 Oracle Cloud 免费层(Free Tier)实例的 Python 自动化脚本。本文逐段剖析 main.py 源码,梳理它通过 Python 调用 OCI API 启动免费 ARM 实例的 5 步流程,帮助新手理解脚本如何自动绕开 "Out of host capacity" 容量错误、轮询重试直到实例成功创建。

Python OCI API自动创建Oracle Cloud免费实例示意图

一、为什么需要这个脚本?🚀

在 Oracle Cloud 控制台创建免费 ARM 实例(2 OCPU / 12 GB RAM)时,热门可用域经常出现如下报错:

  • Out of host capacity
  • Out of capacity for shape VM.Standard.A1.Flex

手动反复点"创建"既不现实也容易漏掉窗口期。这个脚本的思路是:每隔 60 秒(可由 REQUEST_WAIT_TIME_SECS 配置)调用一次 OCI API 尝试创建,成功即停,并在项目目录生成 INSTANCE_CREATED 文件记录实例详情。

二、项目文件一览

文件 作用
main.py 核心脚本,封装全部 OCI API 调用与重试逻辑
oci.env 环境变量配置(实例名、机型、重试间隔、通知渠道等)
setup_init.sh 一键入口:安装依赖并后台启动 main.py,附带进程监控与通知
setup_env.sh 交互式生成 oci.env 配置
sample_oci_config OCI API 配置文件样例(user、fingerprint、tenancy、region、key_file)
requirements.txt 依赖仅 4 个:oci、paramiko、python-dotenv、requests
email_content.html 实例创建成功后发送的 HTML 邮件模板

获取代码(如需 clone 仓库):

git clone https://gitcode.com/gh_mirrors/or/oracle-freetier-instance-creation
cd oracle-freetier-instance-creation

三、main.py 开篇:读配置、建客户端

1️⃣ 加载 oci.env 环境变量

脚本第一行实质动作是用 python-dotenv 加载 oci.env(main.py),把十几个配置项统一转成环境变量:

load_dotenv('oci.env')
OCI_COMPUTE_SHAPE = os.getenv("OCI_COMPUTE_SHAPE", ARM_SHAPE).strip()
WAIT_TIME = int(os.getenv("REQUEST_WAIT_TIME_SECS", "0").strip())

新手重点关注的几个变量:

  • OCI_COMPUTE_SHAPE:机型,VM.Standard.A1.Flex(ARM,默认)或 VM.Standard.E2.1.Micro(AMD Micro)
  • REQUEST_WAIT_TIME_SECS:容量报错后的重试间隔(秒)
  • OPERATING_SYSTEM + OS_VERSION 或直接 OCI_IMAGE_ID:指定操作系统镜像

2️⃣ 校验 oci_config 并初始化 3 个 OCI 客户端

脚本用 configparser 读取 oci_config 中的 user 字段,并做了两个"防手滑"校验:env 值与 config 值中都不允许出现空格,否则写入 ERROR_IN_CONFIG.log 并提示(main.py)。随后创建三个 SDK 客户端(main.py):

iam_client = oci.identity.IdentityClient(config)        # 租户 / 可用域
network_client = oci.core.VirtualNetworkClient(config)   # 子网
compute_client = oci.core.ComputeClient(config)          # 实例 / 镜像

三个客户端恰好覆盖后续 5 步流程所需的全部 API 能力。

四、核心:启动免费实例的 5 步流程

launch_instance() 是整个脚本的心脏,源码里用 Step 1 ~ Step 5 注释标得清清楚楚:

flowchart LR
    S1[Step 1<br/>获取 Tenancy] --> S2[Step 2<br/>获取可用域 AD]
    S2 --> S3[Step 3<br/>获取 Subnet ID]
    S3 --> S4[Step 4<br/>获取 Image ID]
    S4 --> S5[Step 5<br/>启动实例 + 轮询状态]
    S5 -- 容量错误 --> S5

第 1 步:获取租户 ID(Tenancy)

user_info = execute_oci_command(iam_client, "get_user", OCI_USER_ID)
oci_tenancy = user_info.compartment_id

根据 oci_config 里的 user 反查所属租户的 OCID。OCI 的所有资源都挂在租户之下,后续每一步查询都要带上它。

第 2 步:获取可用域(Availability Domain)

oci_ad_names = itertools.cycle(oci_ad_name)

根据 oci.env 中的 OCT_FREE_AD(如 AD-1,支持逗号分隔多个)筛出具备免费资格的可用域,并用 itertools.cycle 包装成循环迭代器。这是"抢容量"的关键设计:某个 AD 报容量错误后,下一次请求自动换到下一个 AD 尝试。

第 3 步:获取子网 ID

  • 若 oci.env 中已填 OCI_SUBNET_ID(本地机器运行时需要),直接使用;
  • 否则调用 list_subnets 列出全部子网并取第一个——这就是官方推荐的"跑在免费 Micro 实例上"的原因:子网现成,无需手工填写。

第 4 步:获取镜像 ID

  • 提供了 OCI_IMAGE_ID 则直接采用;
  • 否则按机型调用 list_images,把精简后的镜像列表写入 images_list.json 留档,再按 OPERATING_SYSTEM + OS_VERSION(如 Canonical Ubuntu 22.04)精确匹配出镜像 OCID。

第 5 步:启动实例并轮询状态 ⚡

这一步分三个小环节,也是代码量最大的部分:

  1. 先做幂等检查:check_instance_state_and_write() 先查询是否已存在 RUNNING / PROVISIONING 状态的实例,有则直接写 INSTANCE_CREATED 退出,避免重复创建;
  2. 组装 LaunchInstanceDetails:ARM 固定 2 OCPU + 12 GB,Micro 固定 1 OCPU + 1 GB,同时配置网络(CreateVnicDetails)、SSH 公钥(metadata)与启动盘大小;
  3. 无限重试循环:调用 launch_instance 返回 200 后轮询实例状态,未到 RUNNING 就继续循环:
launch_instance_response = compute_client.launch_instance(
    launch_instance_details=oci.core.models.LaunchInstanceDetails(
        availability_domain=next(oci_ad_names),   # 容量错误后自动切换 AD
        compartment_id=oci_tenancy,
        ...
    )
)

五、错误处理:自动绕过容量错误的关键 🔧

execute_oci_command:带重试的通用 API 包装器

所有查询类 API 都经 execute_oci_command() 调用:成功返回 response.data;抛出 ServiceError 时把 status / code / message 整理成 dict 交给 handle_errors 分类处理。

handle_errors:区分"暂时不行"和"真的失败"

handle_errors() 的处理策略如下表:

错误场景 脚本行为
TooManyRequests / Out of host capacity. / InternalError / HTTP 502 休眠 WAIT_TIME 秒后重试——这就是自动占坑的核心
LimitExceeded(启动时) 重新检查实例是否已创建:已创建则退出,否则继续重试
其他未知错误 写入 UNHANDLED_ERROR.log、发送邮件通知并抛异常终止

一句话总结:容量错误在这里被当作"还没轮到"而不是"失败",这正是它和手动控制台创建的本质区别。

六、SSH 密钥与消息通知

  • SSH 密钥自动生成:若 SSH_AUTHORIZED_KEYS_FILE 指向的文件不存在,用 paramiko 生成 2048 位 RSA 密钥对(main.py),公钥通过 ssh_authorized_keys 元数据注入新实例,创建后即可直连;
  • Gmail 通知:创建成功后按 email_content.html 模板生成 HTML 邮件(实例 ID、名称、AD、机型、状态自动填充);
  • Discord / Telegram:setup_init.sh 还支持 webhook 推送,并对进程挂了信号陷阱——脚本被 Ctrl+C 中断或挂起时都会主动发一条"已停止"通知,防止"失联式运行"。

七、运行脚本与产出文件

配置完成后只需一条命令(setup_init.sh 会自动装依赖、后台运行并轮询状态):

./setup_init.sh        # 首次:安装依赖 + 后台运行
./setup_init.sh rerun  # 报错后:跳过安装直接重跑

运行中值得关注的日志 / 结果文件:

文件 含义
INSTANCE_CREATED 🎉 创建成功标志,内含实例 ID、名称、AD、机型、状态
launch_instance.log 每次 launch_instance 调用的原始输出
setup_and_info.log tenancy、AD、subnet、image 等关键参数记录
ERROR_IN_CONFIG.log 配置文件格式错误提示
UNHANDLED_ERROR.log 未处理异常详情(可据此反馈 issue)
images_list.json 匹配镜像的快照,自动生成

八、给新手的速记清单 ✅

  1. main.py 的 5 步流程——取租户 → 取可用域 → 取子网 → 取镜像 → 启动实例,本身就是一份 OCI Python SDK 最小实战示例;
  2. itertools.cycle 循环 AD + 容量错误休眠重试,是自动占坑的两大支柱;
  3. 每次启动前先做幂等检查,脚本可安全重复运行;
  4. 配置只需两份文件:oci.env(可用 setup_env.sh 交互式生成)和 oci_config(含 API Key 绝对路径),其余交给 setup_init.sh。
登录后查看全文
oracle-freetier-instance-creation