endorphin-aster-vm/docs/operations/README.md

运行与宿主存储

这里说明跨 CLI、Server 和 Storage 的运行流程。当前本机禁止构建、测试、冒烟与依赖下载；以下命令供用户指定的远端环境执行。环境变量见 配置，容器和生产服务见 部署，检查见 验证。

构建与 CLI

工作区要求 Rust 1.91 或兼容更高版本；构建镜像固定 rust:1.91.1-bookworm，依赖由 Cargo.lock 锁定。

cargo build --workspace --locked
cargo run -p cli -- bootstrap

bootstrap 创建两个 Record，输出 runtime=EndorObject、type_system=disabled、objects_distinct=true 和 heap_objects=2，显式释放后输出 released heap_objects=0。它不读取数据库配置，因此无效 DATABASE_URL 也不影响该命令。

cargo run -p cli -- metadata put project 'Aster VM'
cargo run -p cli -- metadata get project

每次 metadata 命令读取宿主存储配置、连接、操作并关闭连接池；缺失键显示 (missing)。命令和退出码的源码位置见 cli/src。

HTTP 宿主

cargo run -p server
curl --fail http://127.0.0.1:8080/health
curl --fail http://127.0.0.1:8080/bootstrap

Server 创建空 VM、连接存储、初始化元数据表并写入 host.version，随后绑定监听地址。连接、初始化或绑定失败会退出，不降级换库。默认地址为 127.0.0.1:8080。

端点	行为
GET /health	实际 ping 数据库；成功返回 200，失联返回 503，含 status 和 storage 后端名
GET /bootstrap	返回 object_model=EndorObject、type_system=false、heap_objects=0；只读，不分配对象

当前未提供语言执行、对象写入或认证 API。Unix 上 Ctrl-C／SIGTERM 触发 Axum 优雅退出，等待服务结束后关闭共享 Storage；最后的 Arc 释放时销毁 Vm。没有执行中脚本的取消协议。

存储契约

Storage 不依赖 Core，只保存宿主元数据。连接时执行 schema.sql：aster_metadata 的 key 为非空文本主键，value 为非空文本。put 使用参数绑定并更新重复键，get 对不存在的键返回 None。当前只有幂等建表，没有版本化迁移；CREATE IF NOT EXISTS 不能升级已有列结构。

后端	当前行为
SQLite 文件	默认 data/aster.db，相对当前工作目录；创建父目录和文件，开启 WAL，最多 5 个连接，busy timeout 5 秒
SQLite 内存	SQLITE_PATH=:memory:；单连接、不做空闲回收和最大存活轮换；不同 Storage 实例隔离
PostgreSQL	DATABASE_URL 显式选择；最多 5 个连接，连接池获取超时 5 秒，启动即真实连接；失败不回退 SQLite

Storage 克隆共享连接池，close 会关闭所有克隆使用的池。元数据可跨进程保存；VM 堆、句柄、全局对象和执行帧不持久化。重启服务创建新的空 VM。

出错时先查哪里

现象	定位
bootstrap 正常，metadata／服务启动失败	存储配置、storage/src
/health 返回 503	当前数据库连接；该端点不检测语言执行能力
容器替换后元数据丢失	卷与生产数据路径，先确认是否使用内存库
重启后找不到原 VM 对象	当前未实现 VM 快照，见 生命周期

返回 文档索引。