镜像固化

本章讨论一个经常被问到的问题：能不能把容器运行后的状态“固化“成一个新的镜像，下次直接启动就能恢复？

答案是不能直接做到，但有更好的替代方案。本章解释为什么，以及正确的做法。

1. 为什么不能直接固化运行状态为镜像

容器镜像的本质

容器镜像（Container Image）由多层只读的文件层叠加而成：

graph TB
    subgraph IMAGE_LAYERS["镜像层 - 只读，构建时确定"]
        L1["基础层：操作系统 + Python"]
        L2["应用层：agentcore 代码"]
        L3["配置层：默认配置文件"]
    end

    subgraph RUNTIME_LAYER["运行时层 - 可写，容器存活期间"]
        RW["运行时写入：checkpoint、缓存、临时文件"]
    end

    L1 --- L2 --- L3 --- RW

关键区别：

• 镜像层：构建时通过 Dockerfile 确定，所有容器共享，不可修改
• 运行时层：容器启动后产生的文件修改，仅存于内存/临时存储，容器销毁后消失

为什么 docker commit 不可行

虽然 Docker 提供了 docker commit 命令可以把运行时层“拍照“成新镜像，但在 K8s/K3s 环境下这条路不可行：

2. 正确的替代方案

方案一：Backend 管理的状态持久化（当前推荐）

通过 Backend 统一持久化状态，不依赖把运行状态固化进镜像：

graph LR
    subgraph "第一轮 Run"
        R1[agentcore] -->|checkpoint_put| B1["Backend"]
    end

    subgraph DATA_SIDE["数据层"]
        HOST["Backend 数据库"]
    end

    subgraph "第二轮 Run"
        B2["Backend"] -->|checkpoint_get_result| R2[agentcore]
    end

    B1 -.->|写入| HOST
    HOST -.->|读取| B2

优势：状态权威来源集中在 Backend，容器内不需要直接持有数据库连接或数据库文件。

方案二：预热镜像（Prewarmed Image）

将不变的基础环境和依赖预先打包到镜像中，减少每次运行的初始化时间：

graph TB
    subgraph BUILD_PHASE["构建时 - 开发者操作"]
        BASE["基础镜像<br/>Python + 基础库"]
        DEP["安装 Agent 依赖<br/>pip install xxx"]
        MODEL["预下载模型文件"]
        IMG["预热镜像<br/>registry/agent-prewarmed:v1"]
    end

    BASE --> DEP --> MODEL --> IMG

    subgraph RUN_PHASE["运行时"]
        POD["容器启动"]
        FAST["跳过安装步骤<br/>直接开始执行"]
    end

    IMG -->|拉取| POD
    POD --> FAST

适用场景：

• Agent 依赖大型 Python 库（如 PyTorch、Transformers）
• Agent 需要预下载模型文件
• 需要减少冷启动时间

操作方式：Agent 包开发者编写自定义 Dockerfile，在 RuntimeProfile 中指定预热镜像地址。

方案三：镜像层缓存

让 K3s 节点缓存常用的基础镜像层，避免每次运行都从 Registry（镜像仓库）拉取：

3. 推荐实践

4. 技术可行性总结

下一步

了解了镜像策略后，请继续阅读 AgentCore 通信机制。