endorphin-aster-vm/README.md

Aster VM

Rust 编写的可嵌入运行时。当前实现 Endor 的 VM 基础设施：EndorObject、稳定对象分配、代际句柄、显式引用计数、循环回收和 Rust 原生操作分发。VM 从空堆启动，暂不实现 Python 的 type／元类体系，也不定义语言根类和继承规则。

尚无词法／语法前端、字节码执行器或渲染器，不承诺 Python 兼容。数据库只保存宿主元数据，不保存或恢复 VM 堆。对象基础层的逐段说明见 EndorObject。

现有基础对象包括 EndorFunctionObject、EndorNativeFunctionObject、EndorDictObject、EndorCellObject、EndorBaseExceptionObject、EndorStringObject 和 EndorNumberObject。统一 EndorNumber 优先无损表示任意长度整数、精确十进制数、分数、IEEE 浮点和复数；不先实现重计算。语言函数及异常目前是数据基础，尚无语言函数执行和 raise／try／except。接口、示例与边界见 基本对象和 Number。

结构

crate	职责
aster-core	零外部依赖的 EndorObject、操作接口、引用计数、循环回收与 VM
aster-storage	SQLx PostgreSQL／SQLite 适配、元数据表初始化、读写接口；不依赖内核
aster-cli	aster bootstrap 演示，以及宿主元数据读写
aster-server	最小常驻宿主，提供健康检查与运行时信息，供 Docker 等方式运行

依赖方向：CLI／Server → Core 和 Storage；Core 与 Storage 互不依赖。未来浏览器宿主的网络、DOM、渲染等能力应留在宿主一侧。

直接运行

使用 Rust 1.91 或更高兼容版本；当前实测版本为 1.91.1，依赖锁定在 Cargo.lock。不需要 Docker。首次构建需要访问 crates.io。

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

预期输出含 runtime=EndorObject type_system=disabled、objects_distinct=true heap_objects=2 和 released heap_objects=0。这条命令不读取数据库配置、不打开数据库；即使设置了错误的 DATABASE_URL 也不影响运行时演示。

use aster_core::{Value, Vm};

fn main() -> Result<(), aster_core::VmError> {
    let mut vm = Vm::new()?;
    let object = vm.new_object()?; // 分配返回一个宿主持有的强引用。
    vm.set_attr(object, "x", Value::Number(42_i64.into()))?;
    assert_eq!(vm.get_attr(object, "x")?, Value::Number(42_i64.into()));
    vm.retain(object)?;
    vm.release(object)?;
    assert_eq!(vm.ref_count(object)?, 1);
    vm.release(object)?; // 最后一个强引用释放，对象立即清理。
    assert_eq!(vm.object_count(), 0);
    Ok(())
}

嵌入时将 aster-core 加为 Cargo 路径依赖即可。上例与 crate 文档中的可运行示例语义相同。

宿主存储

不设置 DATABASE_URL 时，使用 SQLITE_PATH 指定的 SQLite 文件，默认 data/aster.db，相对于进程工作目录；自动创建父目录及文件。部署时必须把该目录放在持久卷上。SQLITE_PATH=:memory: 仅用于临时运行／测试，不持久化。

cargo run -p aster-cli -- metadata put project 'Aster VM'
cargo run -p aster-cli -- metadata get project
SQLITE_PATH=work/custom/aster.db cargo run -p aster-cli -- metadata put stage bootstrap

PostgreSQL 通过导出的 DATABASE_URL=postgres://... 或 postgresql://... 配置，优先于 SQLITE_PATH。显式空值、错误协议、连接失败都会返回错误并以非零状态退出，绝不静默降级。DATABASE_URL 不接受 SQLite URL；SQLite 使用独立路径配置。

连接成功后执行 schema.sql 中幂等的 v1 建表语句，提供 Storage::put/get/ping/close。读写使用参数绑定，重复键执行更新，缺失键返回 None。尚无复杂迁移版本管理。

Cargo 程序不自动加载 .env，请导出需要的环境变量。.env.example 是配置示例；Docker Compose 会自动读取复制后的 .env。连接 URL 可能含密码，不要贴到日志或提交到 Git。命令行只显示脱敏错误，底层诊断作为 Rust error source 保留给宿主。

常驻宿主

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

ASTER_LISTEN 默认 127.0.0.1:8080。宿主启动时创建 VM、连接数据库、初始化表并写入 host.version=0.1.0；初始化失败即退出。/health 实际探测数据库，成功返回 200，失联返回 503；/bootstrap 返回 object_model=EndorObject、type_system=false、heap_objects=0，多次读取不分配对象。支持 Ctrl-C／Unix SIGTERM 优雅退出。

这两个端点不提供执行语言、对象写入或业务 API。服务没有认证层；示例 Compose 端口仅绑定宿主回环地址，外部访问由后续宿主部署决定。

Docker：默认 SQLite

cp .env.example .env
docker compose up --build -d
curl --fail http://127.0.0.1:8080/health
docker compose exec aster aster metadata put project 'Aster VM'
docker compose exec aster aster metadata get project
docker compose down
docker compose up -d
docker compose exec aster aster metadata get project

容器以 UID 10001 运行，aster-sqlite 命名卷挂载到 /data，保存数据库和 WAL 文件。down 保留卷；down -v 会删除持久数据。构建采用多阶段 Dockerfile，运行镜像同时含 aster-server 和 aster。Compose 的 SQLite 方案不会透传宿主 DATABASE_URL，以保证默认方案明确使用 SQLite。

Docker：选择 PostgreSQL

先将 .env 中的 POSTGRES_PASSWORD 换成随机十六进制字符串（可用 openssl rand -hex 24 生成）。该值同时用于数据库和连接 URL；使用其他字符时需要自行正确处理 URL 编码。

docker compose -f docker-compose.postgres.yml up --build -d
docker compose -f docker-compose.postgres.yml exec aster aster metadata put project 'Aster VM'
docker compose -f docker-compose.postgres.yml exec aster aster metadata get project
docker compose -f docker-compose.postgres.yml down

这是独立替代方案，只传入这一个 Compose 文件，不与默认文件叠加；两个方案不要同时占用同一个宿主端口。PostgreSQL 17 使用 aster-postgres 命名卷，数据库不向宿主公开端口。示例内部网络禁用数据库 TLS；跨不可信网络的部署应使用 PostgreSQL TLS 验证配置，例如 URL 参数 sslmode=verify-full。更改已有 PostgreSQL 卷的密码需要数据库管理操作，修改 .env 不会修改旧卷中的用户密码。

ces-control CI/CD 与持久化部署

正式部署选择 PostgreSQL；默认 SQLite Compose 仍保留作为独立运行选项。

.gitea/workflows/ci-deploy.yml 在 ces-control Runner 上响应 main push 和手动触发：先在远端 Docker 容器中执行 fmt、workspace 测试、严格 Clippy、真实 PostgreSQL 集成测试和 SQLite／HTTP 冒烟检查，通过后构建生产镜像，再部署。使用独立的临时 PostgreSQL 容器做测试，不连接生产数据库。测试容器与网络在退出时清理，编译缓存仅保留在远端专属 Docker 卷中。

正式服务由 docker-compose.ces-control.yml 管理，默认仅绑定 127.0.0.1:18081，内部连接 PostgreSQL 17。应用／数据库使用 unless-stopped 自动重启，日志轮换；数据库不发布端口。部署使用 commit SHA 标记镜像与 release 目录，健康检查或元数据读写失败时尝试恢复上一版应用，保留数据库。

服务器路径	用途
/opt/endorphin-aster-vm/releases/<sha>/	固定版本的 Compose 与镜像配置
/opt/endorphin-aster-vm/current	最近健康版本的符号链接
/etc/endorphin-aster-vm/production.env	首次自动生成的数据库密码和端口，权限 0600
/var/lib/endorphin-aster-vm/postgres	PostgreSQL 持久数据，替换应用／数据库容器后保留

无需在 Gitea 中设置生产数据库密码。不要删除或重新生成已有数据库对应的 production.env；修改密码需先通过 PostgreSQL 管理操作完成同步。首次部署没有可用的旧版可以回退；数据库 schema 的未来升级也需要另行设计兼容性，应用回退不等于回退数据库。

在服务器查看／停止当前部署（停止不删除数据）：

docker compose -p endorphin-aster-vm \
  --env-file /etc/endorphin-aster-vm/production.env \
  --env-file /opt/endorphin-aster-vm/current/release.env \
  -f /opt/endorphin-aster-vm/current/compose.yml ps
curl --fail http://127.0.0.1:18081/health
curl --fail http://127.0.0.1:18081/bootstrap
# 同样参数接 stop 停服，接 up -d --wait 恢复。

本机不执行上述 CI 测试，也不为其安装 Rust／SQLite／PostgreSQL。正式部署与测试只运行在用户指定的 ces-control。该工作流不改动 autodl-gpu-runner-controller、rednote 或 TiktokUI。工作流语义依据 Gitea Actions 文档，环境文件加载依据 Docker Compose 文档。

验证（在用户指定的环境执行）

当前工作约定禁止在本地运行测试，也不为本地测试下载依赖。下面的脚本和示例在指定的 ces-control CI／部署环境执行，不代表每次修改后已全部执行。实际结果及此前清理情况见 验证记录。

sh scripts/check.sh
python3 scripts/smoke.py

检查脚本运行 fmt、workspace 测试和拒绝所有 warning 的 Clippy；冒烟脚本使用临时 SQLite 文件，验证独立引导、跨进程持久化、配置错误、HTTP 端点和 SIGTERM 退出，不需要外部数据库。

PostgreSQL 集成测试默认显式忽略，需要测试数据库。以下是指定验证环境中的 Docker 示例；仅操作专用测试容器，不使用生产库，当前不在本机执行：

docker run --rm -d --name aster-pg-test \
  -e POSTGRES_PASSWORD=aster-test -e POSTGRES_USER=aster -e POSTGRES_DB=aster \
  -p 127.0.0.1:55432:5432 postgres:17-bookworm
# 等待以下命令成功后再运行测试：
docker exec aster-pg-test pg_isready -U aster -d aster
ASTER_TEST_POSTGRES_URL='postgres://aster:aster-test@127.0.0.1:55432/aster?sslmode=disable' \
  cargo test -p aster-storage --test postgres --locked -- --ignored
docker stop aster-pg-test

测试会留下唯一键的元数据，专用测试库可随容器删除。缺少测试 URL 时显式运行该测试会失败，不会假装通过。真实 PostgreSQL 成功路径及容器结果以 验证记录 为准。

当前语义与后续开发

• EndorObject 是 Rust 运行时公共对象结构，包含身份、引用计数、原生载荷和托管属性。没有语言类或类型指针；ObjectPayload 是 Rust 操作接口，诊断名称不参与语言类型判断。
• ObjectRef 包含私有 VM 身份、槽位和代数。Box<EndorObject> 保持存活对象地址稳定；槽位复用更新代数，旧句柄不会指向新对象。外部不构造堆索引，也不操作裸指针。
• 分配返回一个外部强引用；复制句柄或含句柄的 Value 不增加计数。额外持有使用 retain，结束持有使用 release。对象属性和载荷声明的边各自持有内部强引用；读属性与原生调用返回借用值，需长期持有时显式 retain。
• 最后一个强引用释放时，迭代清理依赖对象并调用 Rust Drop。collect_cycles() 从外部强引用追踪，显式回收不可达环；不会自动定时执行。销毁 VM 时统一释放剩余对象。
• 支持 repr／str、身份与内容比较、哈希、真值、属性读写删除、原生函数调用。操作由 Rust 载荷实现；不支持的操作返回错误。原生调用可返回标量或已有对象的借用句柄，当前不能在回调中修改 VM；没有语言函数执行器。
• 标量与字符串可直接保存在 Value，数字统一为 Value::Number；需要对象身份时可分配 String／Number 对象。字典和 Cell 支持 VM 管理的可变引用；函数和异常保存数据并参与 GC。数值比较／哈希、语言函数执行、异常继承与传播、语言根类、元类、描述符及 VM 堆持久化留待以后实现。

下一阶段可围绕执行栈的强引用根管理和可变 VM 调用上下文推进执行器；GC 已有手动全堆版本，尚无分代、增量、并行收集或语言终结器／复活语义。详见 架构、对象基础层 与 开发交接。

依赖 API 依据 SQLx 0.8.6 官方文档 和 Axum 官方文档 实现。SQLx 0.9 要求更高 Rust 版本，本阶段使用与本机工具链兼容的 0.8.6；确切解析版本以锁文件为准。