Initialize Aster VM and deploy PostgreSQL host on ces-control
Verify databases and deploy Aster VM / verify-and-deploy (push) Waiting to run

This commit is contained in:
2026-10-17 23:42:39 +08:00
commit 9648b9e8dd
34 changed files with 3717 additions and 0 deletions
+33
View File
@@ -0,0 +1,33 @@
# 架构与语义
## 内核
`Vm` 拥有私有 `Heap`。`Vm::new` 分配一个 `Object::Class(Class)`,其描述为名称 Object、父类 None,然后保存 `ClassRef`。不存在可观察的“半初始化 VM”;`bootstrap` 只返回已建立的根类句柄。因此根类不依赖数据库、全局命名空间、元类、网络或异步运行时。
`create_class(name, parent)` 校验已有父类后创建不可变描述,父类不可事后改写,不能形成继承环;只有内核启动路径可以创建没有父类的类。`create_instance` 校验类句柄再创建独立字段表。没有复制原型或隐式字段继承。未实现方法与实例字段查找的语言规则。
句柄结构是私有 VM 身份加 `usize` 槽位。VM 身份用原子计数器分配,耗尽时返回错误,不回绕复用。`Vec` 扩容会移动 Rust 对象,但外部不保存它们的地址,旧句柄继续通过索引访问。当前绝不删除槽位,所以无代际号。VM 不实现 Clone,复制句柄不能复制 VM 身份。
检查顺序是归属、范围、种类。外部没有从整数构造句柄的 API;低层无效槽位与伪造类型用私有单元测试覆盖。通用句柄可通过 `as_class/as_instance` 做校验后的转换。不同 VM 的引用、已经销毁 VM 的引用,在新 VM 中都报 `ForeignHandle`。同一 VM 中不在有效槽位的引用报 `InvalidHandle`。写字段前检查目标和引用值,失败不会覆盖原字段。
`Value` 中标量和字符串不强制堆分配,引用目前仅指类或实例。当前字符串值是按 Rust 所有权复制的文本,并非具有对象身份的字符串实例。`Float` 使用 Rust f64/PartialEq 行为,尚未作为最终语言语义承诺。类不是自身或其他类的实例,根类也没有隐式元类。
没有 GC,循环引用不形成 Rust 引用计数环,因为边只是句柄;所有内存随 VM 释放。长期运行时分配只增不减,尚无资源限额或内存不足的可恢复错误处理。宿主必须控制使用范围。
## 宿主与持久化
`aster-storage` 不引用任何内核类型。它连接一个确定的后端,初始化 `aster_metadata(key TEXT PRIMARY KEY NOT NULL, value TEXT NOT NULL)`,通过参数绑定完成幂等更新及读取。当前 schema 是单条幂等 DDL;修改 schema 时再引入版本化迁移,禁止把 CREATE IF NOT EXISTS 当作升级已有列结构的工具。
SQLite 文件模式自动创建父目录、开启 WAL,连接池最多 5 条连接,busy timeout 为 5 秒。内存模式单连接,关闭空闲回收和最大存活时间,防止池正常轮换导致数据库消失;独立 Storage 实例的内存数据库相互隔离。`Storage` 克隆共享连接池,`close` 关闭全部克隆的池。
PostgreSQL 最多 5 条连接,获取/建立连接超时 5 秒,启动真实连接而非惰性连接。其配置失败或初始化失败均上抛,不进入 SQLite 分支。SQLite 的缺省只发生在**未配置** DATABASE_URL 时。
元数据仅供宿主管理,不代表类、实例、句柄或整堆快照。重启宿主会创建新的 VM、新的 Object 和新句柄,只保留文件/数据库内的元数据。服务仅写入 `host.version`,不会把句柄调试值写入数据库。
`aster-server` 保存只读 VM 和共享 Storage。GET /bootstrap 只读根类;GET /health 探测数据库可用性。没有对象操作 API、语言执行 API 或鉴权协议。HTTP/Tokio/SQLx 都不进入内核。后续浏览器宿主应通过明确的能力接口桥接,不能把浏览器类型塞进核心对象工厂。
## 已决定与未决定
已决定:唯一无父类 Object、类和实例分离、实例引用类、句柄由 VM 校验、存储属于宿主。
未决定:字节码格式、调用栈、方法解析、语言异常、外部对象协议、线程间共享 VM、GC/根集、堆序列化、浏览器通信、完整字符串对象/数值对象语义。不得在后续交接中把这些当成已实现契约。
+33
View File
@@ -0,0 +1,33 @@
# 开发交接
## 入口与验证
先阅读根目录 AGENTS.md。工作区四个 crate 的边界必须保持,内核无数据库/HTTP 依赖。用户明确禁止本地测试,不在本机运行检查/冒烟脚本,也不为此下载依赖。指定的远端验证环境是 ces-control;CI 在 Docker 中运行 `sh scripts/check.sh`、`python3 scripts/smoke.py` 和真实 PostgreSQL 集成测试。正式持久部署选择 PostgreSQL。检查记录见 validation.md。
核心 API 示例在 `aster-core/src/lib.rs`,由 rustdoc 实际编译执行。公开语义测试在 `aster-core/tests/runtime.rs`;伪造句柄仅在私有堆单元测试中构造,禁止为测试添加公开非法构造器。
存储测试用 `tempfile` 隔离文件,关闭池后重开,验证独立连接生命周期中的持久化。内存测试验证克隆共享、独立 store 隔离、特殊字符参数绑定、更新/缺失键。PostgreSQL 失败测试用只监听但不处理协议的本地 TCP socket,检验真实连接超时和不降级;成功测试显式 ignore,需要用户提供专用测试库。
尚未运行的冒烟脚本用于跨进程调用 CLI、启动 HTTP 宿主、探测真实 TCP 端点、发送 SIGTERM 并确认正常退出。它只创建临时目录,不改 `.env`,不操作外部服务器。端口通过临时绑定选择,释放后启动间存在很小的端口竞争窗口;在指定验证环境中若冲突,可重试整个脚本。
依赖使用 Cargo.lock。此前编译器为 1.91.1;更换依赖后须在指定环境检查 MSRV 和容器构建版本。核心测试无需数据库,但 Cargo 首次依赖解析仍可能访问注册表;不要因此在本机恢复下载或测试。
## 下一阶段建议
1. 先约定对象字段与方法查找规则、宿主调用的参数/返回值和错误边界,补语义测试。
2. 在 core 内构建最小、可测的执行循环,输入先用手写指令,继续不做解析器和渲染器。
3. 根据执行栈、对象图、宿主持有引用确定 GC 根集;如需回收槽位,升级代际/间接句柄模型并补陈旧句柄测试。
4. 对外部对象、浏览器能力、配额与取消建立最小接口,以实际需求驱动,不预先堆砌空 trait。
5. 需要升级元数据 schema 时引入可追踪的迁移;若要求 VM 快照,另行定义持久身份与格式,不能直接序列化现有句柄。
## Git 状态与后续远程
origin 为用户提供的 `ssh://git@gitea.entroia.com:22222/Zayden-Jung/endorphin-aster-vm.git`。仓库级 author 和隔离 SSH 命令已配置;不得复制其他身份或猜测 owner。发布 CI/CD 需要提交、推送并跟踪远端结果;遵守 AGENTS.md 的授权及中文逐文件报告要求。初始开发阶段记录与后续部署记录在 validation.md 中分开说明。
## 远端 CI 与部署
`scripts/ci-ces-control.sh` 构建 Dockerfile 的 ci 阶段,创建专属网络与临时 PostgreSQL,再依次运行 workspace 检查、显式 PostgreSQL 测试、SQLite/宿主端到端冒烟。Docker daemon 为 legacy builder,工作流显式设置 `DOCKER_BUILDKIT=0`;没有依赖 buildx。远端内存约 1.7 GiB,Rust 单任务编译、调试构建不生成 debug 信息。
`scripts/deploy-ces-control.sh` 仅部署已经构建的 SHA 镜像;使用文件锁防止并行切换生产版本,第一次自动生成服务器密码文件,后续保留。Compose 固定项目名,独占 PostgreSQL 数据目录,与其他项目隔离。部署通过健康检查和真实元数据写入/读取后才切换 current;失败时尝试恢复上一版健康 Compose,不删除数据库或镜像。
更换应用容器不应重建密码或清理数据目录。PostgreSQL major 版本升级与 schema 变更须另外计划迁移;禁止把应用镜像回退当作数据库回退。修改此链路后,验证必须继续放在 ces-control,不要恢复本机依赖下载。
+50
View File
@@ -0,0 +1,50 @@
# 实现与验证记录
日期:2026-10-17(Asia/Shanghai)。
## 初始开发阶段记录
用户已明确禁止在本地测试,并要求清理下载内容。停止继续下载、构建与测试;后续检查脚本仅供用户指定的 CI/部署环境使用。测试结果是此前已启动进程返回的历史记录,不代表此后又运行了测试。
尝试中断此前的 `cargo test --workspace` 时,该进程已经自然结束,返回状态 0,SQLite 构建依赖也已下载。随后按用户要求清理了本次新增缓存和构建产物,不再运行测试。
## 已观察结果
| 检查 | 实际结果 |
| --- | --- |
| `cargo fmt --all --check` | 通过;此后只修改文档与约定,没有修改 Rust 代码 |
| `cargo test -p aster-core --offline` | 3 项私有单元测试、6 项公开语义测试、1 项文档测试通过 |
| `cargo clippy -p aster-core --all-targets --offline -- -D warnings` | 通过,仅覆盖内核 |
| 此前启动的 `cargo test --workspace` | 最终返回 16 项通过、0 失败、1 项明确忽略;含核心 9 项、宿主 1 项、存储 5 项、文档 1 项 |
| PostgreSQL 失败路径 | 使用不处理协议的本地 TCP socket,连接超时并报错、不降级;已包含于上述存储测试 |
| 真实 PostgreSQL 成功路径 | 未验证;集成测试显式忽略,需专用测试库 |
| 两个 Compose 文件 | Ruby YAML 静态解析通过,未执行 Compose |
| `scripts/check.sh`/`scripts/smoke.py` | 分别通过 Shell/Python 语法检查,未运行完整脚本 |
| `cargo clippy --workspace --all-targets -- -D warnings` | 未执行,不宣称全工作区无 Clippy 警告 |
| CLI/HTTP/SIGTERM 端到端冒烟 | 未执行;宿主健康状态函数测试已在上述 workspace 测试通过 |
| Docker 构建及容器运行 | 未执行,本机无 Docker |
以上为初始阶段记录,当时没有外部部署、PostgreSQL 服务、commit 或 push。
## 清理结果
- 删除本项目创建后新增、且属于 Cargo.lock 依赖列表的 150 个 Cargo 下载归档与 150 个解压目录,包括 SQLite/SQLx 本次新增依赖。
- 删除项目 `target/` 构建产物及 Python 字节码缓存。
- 保留此前已存在的 Cargo 缓存、共享注册表索引、项目源码与 Cargo.lock;不清空其他项目的既有依赖。
- 没有运行 CLI 创建默认 `data/aster.db`。此前文件数据库测试使用的临时目录随测试自动释放。
## Git
初始阶段本地分支 main 尚无提交。origin 是用户提供的 `ssh://git@gitea.entroia.com:22222/Zayden-Jung/endorphin-aster-vm.git`。
只读 `ls-remote --symref origin HEAD` 使用专用 codex-bot 密钥、隔离 SSH 配置、禁用其他身份及交互式凭据,返回状态 0,未公布 HEAD 引用。只读成功不代表已验证写权限。
仓库级身份:`Codex Bot` / `codex-bot@gitea.entroia.local`;`core.sshCommand` 使用项目约定的隔离命令。没有读取密码或切换为仓库 owner 身份。
## ces-control CI/CD 准备
用户随后指定在 ces-control 上持久部署,并要求同时测试 SQLite 与 PostgreSQL、正式部署使用 PostgreSQL。新增的工作流和脚本将这些检查放在远端 Docker 中,不在本机下载依赖或运行测试。
准备阶段只读检查:Docker 29.1.3、Compose 2.40.3、x86_64、约 1.7 GiB 内存/4 GiB swap、73 GiB 可用磁盘;没有主机 Rust 或 buildx,已缓存 PostgreSQL 17 镜像。选用单任务 Rust 构建、legacy Docker builder,默认生产端口 18081(服务器回环地址),PostgreSQL 数据目录独立。
此处不预先宣称远端 CI 或部署已成功;最终结果以 Gitea Actions 对应运行与服务器状态核验为准。