codex-bot
e52d2e1e4b
Verify databases and deploy Aster VM / verify-and-deploy (push) Successful in 7m25s
48 lines
3.3 KiB
Markdown
48 lines
3.3 KiB
Markdown
# 宿主基础信息：文件保存
|
||
|
||
基础信息不使用数据库。host 包保存逐键 UTF-8 JSON，CLI 提供读写，Server 启动写 host.version，部署检查通过后写 deployment.release。Storage 的数据库连接仅给未来特殊类使用。
|
||
|
||
## 文件与配置
|
||
|
||
ASTER_STATE_DIR 使用操作系统路径，默认 data/host；显式空值报错。读取一个不存在的键返回 None，不创建目录；写入时创建目录。容器为 /data/host；生产挂载到 /var/lib/endorphin-aster-vm/host，独立 PostgreSQL Compose 使用 aster-host 卷。
|
||
|
||
例如 host.version 对应 host.version.json：
|
||
|
||
```json
|
||
{
|
||
"format_version": 1,
|
||
"key": "host.version",
|
||
"value": "0.1.0"
|
||
}
|
||
```
|
||
|
||
控制键以 ASCII 字母或数字开头，最长 128 字节，其余只能是字母、数字、点、下划线或连字符。它是信息命名协议，不是文本编码限制；值支持日文、中文、emoji 等 Unicode 文本。用户文本不应被当作文件路径或控制键。
|
||
|
||
文件必须是有效 UTF-8 JSON，版本和 key 必须匹配请求。损坏记录返回错误，不清空、不用默认值偷偷替换。文件不属于 VM 堆快照，也不存数据库凭据。
|
||
|
||
## 读写与生命周期
|
||
|
||
CLI 的 metadata put/get 通过 host::MetadataStore 访问文件，不连接 SQL：
|
||
|
||
```sh
|
||
cli metadata put project.note '日本語・中文・😀'
|
||
cli metadata get project.note
|
||
cli metadata get host.version
|
||
```
|
||
|
||
MetadataStore::clone 只共享目录路径，没有缓存；每次读取重新打开文件。写入先建立同目录唯一临时文件，写完并 sync_all，再通过 rename 发布；Unix 新文件权限 0600。不同键分别写文件，不会因整张 map 的读改写丢失其他键；同键并发是最后一次成功发布生效。
|
||
|
||
没有跨键事务、分布式锁或共享网络文件系统一致性保证；文件同步与原子发布也不等于数据库的完整断电持久性协议。异常进程终止可能留下隐藏临时文件，正常失败会清理自己的临时文件。
|
||
|
||
## 旧基础信息的一次性迁移
|
||
|
||
ces-control 发布时，在 host/.legacy-imported 标记缺失的情况下，只读检查 PostgreSQL 原 public.aster_metadata 表。存在时，使用 UTF-8 客户端导出 key/value JSON，再经 cli metadata import 的标准输入导入。该命令只创建缺失文件，不覆盖 Server 刚写入的版本或其他已有文件；临时导出文件以私有权限创建并清理，不打印数据内容。
|
||
|
||
只导入缺失项通过同目录临时文件的原子 hard_link 实现，因此运行目录应使用支持该操作的本地文件系统。导入可重复执行；只有导入成功或源表不存在才写完成标记。损坏记录、不支持的控制键或 I/O 错误会停止发布，保留原库数据，不能当作迁移成功。
|
||
|
||
本迁移针对已配置的 PostgreSQL 生产路径，不自动扫描或删除其他 SQLite 文件。原数据库表与数据不会被修改／删除。此处说明发布脚本行为，不代表远端已执行成功；按约定不主动跟踪 CI 或服务器。
|
||
|
||
部署记录仍以版本镜像、release.env 与 current 链接为发布来源；deployment.release.json 是文件信息记录，不是数据库迁移表。脚本见 [scripts](../../scripts/README.md)。
|
||
|
||
返回 [运行指南](README.md) 或 [文档索引](../README.md)。
|