Orisumi

开发环境的启动与隔离

Orisumi.Dev 是启动环境的统一入口，每个检出目录运行一套环境，数据卷可选，服务按需启动

背景

人和多个 Agent 会同时修改 Orisumi。改完代码后，需要启动相关的服务，读取日志和追踪，再检查实际行为。

现在启动环境要直接调用 Aspire。端口和数据卷写在 AppHost 的配置中，所以两套环境同时运行会互相冲突，隔离时要手动传入端口和卷名。只验证 API，也要启动文档站和 Web 控制台。运行时的检查写在 README 中，每次由执行的人或 Agent 手动完成。

决定

入口

  • Orisumi.Dev 提供启动、停止、查看和读取环境的命令，人和 Agent 使用同一组命令。
  • Orisumi.Dev 通过 Aspire 启动环境。AppHost 仍然是资源、依赖关系和启动顺序的唯一来源。
  • 环境的状态可以用 JSON 读取，包括已启动的服务、各入口和看板的地址，以及数据库连接。
  • Orisumi.Dev 打包为 .NET 全局工具，命令名是 orisumi。

隔离

  • 每个检出目录同时运行一套环境。
  • 主检出目录使用固定端口。工作树使用分配的端口，分配结果保存在这个工作树的 .artifacts/ 中。端口包括入口、数据库、看板和遥测接收。
  • 需要同时运行不同的代码时，使用工作树。

数据

  • 每个检出目录有自己的默认数据卷，默认卷在环境停止后保留。
  • 启动时可以改用临时卷。环境停止时，临时卷被删除。
  • 启动时可以重建默认卷，卷中的数据全部删除。

按需启动

  • 启动时可以选择服务，AppHost 补齐它们的依赖。不选择时启动全部服务。
  • NGINX 的配置按服务分成片段，每个服务加载“已启动”或“未启动”的片段。三个入口总是监听，在同一套环境中端口保持不变。
  • 转给未启动服务的请求返回 503。

冒烟场景

  • 运行时检查写成可执行的场景。场景对运行中的环境执行；检查启动、停止和数据保留的场景自己启动和停止环境。场景的结果和其他验证证据保存在同一个运行目录中。
  • 场景按能力划分。第一批是环境场景和 API 场景，之后每个 Observer 一个场景。Observer 的场景对环境运行几轮采样，再通过 API 读回结果。
  • 场景写明它的前提，例如本机能力或环境的状态。前提不满足时，场景报告为跳过。
  • 写入数据的场景只对使用临时卷的环境执行，场景数据不进入默认卷。
  • 热更新和页面由人或浏览器工具检查。

理由

端口分配、卷名和隔离参数需要一个地方统一管理。Orisumi.Dev 已经负责验证，由它同时管理环境，Agent 只需要学一组命令。状态可以用 JSON 读取，Agent 拿到地址就能直接请求。.NET 全局工具在每个平台上用同一种方式安装，命令也相同。

同一个检出目录中的两套进程运行同一份代码，也共用同一份构建输出。watch 模式在每次修改后重新构建，两套进程的构建会互相冲突。同一份代码只需要隔离数据，所以换一个卷就够了；需要隔离代码时，工作树正好提供独立的源码和构建输出。

按需启动由 AppHost 处理，连接字符串、端口和迁移顺序就只写一份。NGINX 的配置片段仍然是普通的 NGINX 配置，可以直接阅读和审查。入口端口保持不变，人和 Agent 不必在每次启动后查地址。服务未启动时返回 503，结果一眼可辨；否则 Web 控制台入口的 /api 请求会落到 Vite 的 SPA 回退上，返回一个看起来正常的首页。

重写期间直接修改 Initial migration，已经应用过它的卷不会再更新表结构，所以默认卷需要能直接重建。

手动步骤每次的做法都可能不同，结果也不进入证据。写成场景后，同一项检查每次的执行方式相同，结果可以查证。按能力划分场景，在场景还少的时候也不会切得过细。

放弃的方案：

  • 仓库根目录的 shell 脚本。 Windows 不能直接运行。
  • 直接使用 aspire 命令和参数。 每次都要手写端口和卷名，用 --isolated 之后还要另外查询实际分配的端口。
  • 在一个检出目录中运行多套环境。 每套环境都要有独立的构建输出目录，复杂度高，能得到的只有数据隔离，而换卷已经能做到。
  • 每个服务使用单独的启动脚本。 依赖关系分散在多处，容易互相不一致。
  • 部分启动时不运行 NGINX。 入口地址会随所选的服务变化。

代价

  • Orisumi.Dev 依赖 Aspire CLI 的命令和输出格式，升级 Aspire 时要核对。
  • 安装的 orisumi 是安装时的版本，Orisumi.Dev 改动后要重新安装。分支上的 Orisumi.Dev 与安装的版本不同时，用 dotnet run 运行这个分支的版本。
  • 在同一个检出目录中并行验证，需要先创建工作树。
  • 工作树删除后，它的默认卷仍然存在，需要另外清理。
  • NGINX 的配置分成多个文件。
  • 场景要随服务和 Observer 一起维护。

规则位置

贡献者

页面历史

本页内容

背景决定入口隔离数据按需启动冒烟场景理由代价规则位置贡献者页面历史