无极开物Docs

栈（隔离实例）

在单台设备上运行多个隔离的 Kaiwu 栈（端口 + 目录 + 仓库固定）。

hstack 支持在同一台设备上并行运行多个栈。

一个“栈”本质上包含：

  • 独立的服务器端口
  • 相互隔离的 UI 构建产物、CLI 主目录与日志目录
  • 固定指向的代码仓检出（指向特定的工作树/检出目录）
  • （使用 KAIWU-server 时）按栈独立管理的隔离基础设施（Postgres/Redis/Minio）

栈通过保存在以下路径的纯文本 env 文件进行配置：

~/.KAIWU/stacks/<name>/env

创建栈

非交互式：

hstack stack new exp1 --port=3010 --server=KAIWU-server-light

自动选择端口：

hstack stack new exp2

高级用法：直接指定数据库提供商，无需额外交互提示：

# Light flavor (default): SQLite (no Docker)
hstack stack new exp-light --server=KAIWU-server-light --db-provider=sqlite

# Light flavor (optional): embedded Postgres via PGlite (PG_Light)
hstack stack new exp-pglite --server=KAIWU-server-light --db-provider=pglite

# Full server (default): Postgres (Docker-managed per stack)
hstack stack new exp-full --server=KAIWU-server --db-provider=postgres

# Full server (optional): MySQL (requires an explicit DATABASE_URL; hstack does not provision MySQL)
hstack stack new exp-mysql --server=KAIWU-server --db-provider=mysql --database-url=mysql://user:pass@127.0.0.1:3306/KAIWU

创建 PR 测试栈（便于复制粘贴）

若想让维护者快速体验你的 PR，只需提供一条命令即可完成以下操作：

  • 创建隔离的栈
  • 将 PR 检出至各工作树
  • 将这些工作树绑定至该栈
  • （可选）预置认证数据
  • （可选）以开发模式启动该栈

示例（最常见用法）：

hstack stack pr pr123 \
  --repo=https://github.com/wuji-labs/kaiwu/pull/123 \
  --seed-auth --copy-auth-from=dev-auth --link-auth \
  --dev

注意：

  • --remote（默认为 upstream）控制拉取 refs/pull/⟦K47⟧/head 所使用的 Git 远端。
  • --seed-auth 底层使用 hstack stack auth ⟦K48⟧ copy-from ⟦K49⟧，同时会尽力预置数据库 Account 记录（避免出现类似 Prisma P2003 的外键错误）。
  • --link-auth 会通过符号链接关联认证文件而非直接复制（可保持凭据同步，但会降低隔离性）。
  • 对于全量服务端栈（KAIWU-server），预置数据可能需要 Docker 基础设施处于运行状态。
  • 数据库提供商标志会透传给底层的 hstack stack new 调用：
    • --db-provider=...
    • --database-url=...（仅限全量服务端）

认证预置（推荐：dev-auth）

仅需创建一次 dev-auth 种子栈并完成认证，之后创建新栈时即可直接复用：

hstack auth seed

交互式向导（仅限 TTY）：

hstack stack new --interactive

通过该向导，你可以：

  • 选择服务器类型（KAIWU-server-light 或 KAIWU-server）
  • 为 Kaiwu monorepo 选择或创建代码仓工作树
  • 选择新建工作树所基于的 Git 远端（默认为 upstream）

创建 --server=KAIWU-server 栈时，hstack 还会预留额外端口，并将栈级别的基础设施配置持久化写入该栈的 env 文件中（确保重启后配置稳定）：

  • KAIWU_STACK_PG_PORT
  • KAIWU_STACK_REDIS_PORT
  • KAIWU_STACK_MINIO_PORT
  • KAIWU_STACK_MINIO_CONSOLE_PORT
  • DATABASE_URL、REDIS_URL、S3_*

运行栈

开发模式（交互式，推荐）：

hstack tui stack dev exp1

开发模式（非交互式 / 无 TUI）：

hstack stack dev exp1

开发模式（后台运行）：

hstack stack dev exp1 --background

类生产模式（交互式）：

hstack tui stack start exp1

类生产模式（非交互式 / 无 TUI）：

hstack stack start exp1

类生产模式（后台运行）：

hstack stack start exp1 --background

构建栈产物：

hstack stack build exp1
hstack stack build exp1 --web
hstack stack build exp1 --server
hstack stack build exp1 --daemon
hstack stack build exp1 --all

构建并激活全新的全量运行时快照：

hstack stack build exp1 --activate-runtime
hstack stack start exp1 --runtime

仅将指定组件激活到当前生效的运行时：

hstack stack runtime exp1 activate --web
hstack stack runtime exp1 activate --server
hstack stack runtime exp1 activate --daemon
hstack stack runtime exp1 activate --all

注意：

  • 未指定组件标志的 hstack stack build ⟦K50⟧ 保留历史行为，仅构建 Web bundle。
  • --all 等同于 --web --server --daemon。
  • hstack stack build ⟦K51⟧ --activate-runtime 仍会在栈目录下组装完整的运行时快照（web + server + daemon）。
  • hstack stack runtime ⟦K52⟧ activate ... 会将所选的最新产物与未选中组件的当前运行时组合，生成新的生效运行时快照。
  • 仅构建产物不会改变当前生效的运行时。正在运行的栈会继续提供当前快照的服务，直到你激活新运行时。
  • --tauri 仍作为原有的本地 hstack build 标志使用，未纳入 v1 版本命名栈的产物/运行时构建体系。
  • 运行时快照目前适用于命名栈。代码仓本地的 yarn tui / hstack start 仍属于源码驱动的工作流。
  • hstack stack auth ⟦K53⟧ login 遵循相同的模式：若当前激活了有效的运行时快照，引导登录将直接使用栈托管的运行时 UI，而无需等待 Expo。

选择命名栈的启动方式：

# use source code directly (default)
hstack stack start exp1 --source

# require the active runtime snapshot
hstack stack start exp1 --runtime

# persist the default launch mode in the stack env
hstack stack env exp1 set KAIWU_STACK_RUNTIME_MODE=prefer

命名栈运行时工作流（推荐用于类生产的本地栈）

创建固定到特定检出目录/工作树的命名栈：

hstack stack new dev-built --repo=/absolute/path/to/your/dev-checkout

构建并激活栈本地的运行时快照：

hstack stack build dev-built --activate-runtime

持久化运行时偏好设置，供后续 start 与 service 运行时使用：

hstack stack env dev-built set KAIWU_STACK_RUNTIME_MODE=prefer

基于已激活的运行时快照启动：

hstack stack start dev-built --runtime

代码变更后的更新流程：

# rebuild a fresh runtime snapshot from the pinned checkout
hstack stack build dev-built --activate-runtime

# restart the service so it picks up the new active snapshot
hstack stack service dev-built restart

单组件更新流程：

# UI-only change: build the new web artifact, activate only web, then reload the browser
hstack stack build dev-built --web
hstack stack runtime dev-built activate --web
# Server-only change: build + activate only server, then restart the stack or service
hstack stack build dev-built --server
hstack stack runtime dev-built activate --server
hstack stack service dev-built restart
# CLI/daemon-only change: build + activate only daemon, then restart the daemon or service
hstack stack build dev-built --daemon
hstack stack runtime dev-built activate --daemon
hstack stack service dev-built restart

重要提示：

  • 重新构建运行时快照后，无需重新安装命名栈服务。
  • 服务始终指向栈 env 文件，在下次启动或重启时会自动采用已激活的快照。
  • 若栈处于 prefer 模式，当存在有效快照时会使用该运行时快照，否则回退至源码模式。
  • 若仅激活 Web 组件，运行时服务端会直接从 runtime/current/ui 提供服务，因此执行 hstack stack runtime ⟦K54⟧ activate --web 后刷新浏览器即可。
  • 若仅激活服务端或仅激活守护进程，请重启栈进程或栈服务，使其重新加载更新后的运行时。
  • 成功激活或构建后，系统会自动清理旧的运行时快照和组件产物。
    • 默认保留当前生效的构建及前一次构建（共 2 个）。
    • 可通过 KAIWU_STACK_RUNTIME_SNAPSHOT_KEEP_COUNT=⟦K55⟧ 与 KAIWU_STACK_RUNTIME_ARTIFACT_KEEP_COUNT=⟦K56⟧ 自定义保留数量。
    • 若只需保留当前这代运行时/产物，可将相应值设为 1。

诊断检查：

hstack stack doctor exp1

编辑栈（交互式）

修改已有栈的服务器类型、端口或代码仓工作树：

hstack stack edit exp1 --interactive

切换栈的服务器类型

你可以在 KAIWU-server-light 与 KAIWU-server 之间直接切换现有栈的类型，无需完整重新运行编辑向导：

hstack stack srv exp1 -- status
hstack stack srv exp1 -- use KAIWU-server-light
hstack stack srv exp1 -- use KAIWU-server
hstack stack srv exp1 -- use --interactive

切换栈的代码仓工作树（stack wt）

如果你希望获得与 hstack wt 完全相同的交互体验，但作用范围限制在栈 env 文件内：

hstack stack wt exp1 -- status
hstack stack wt exp1 -- use pr/my-ui-pr
hstack stack wt exp1 -- use default

此操作会更新栈 env 文件（~/.KAIWU/stacks/⟦K57⟧/env），而非代码仓的 env.local（旧路径仍受支持）。

针对特定栈运行 Kaiwu CLI（stack kaiwu）

若要针对特定栈运行 kaiwu CLI 命令（而非当前 shell 环境变量所指向的栈），请运行：

hstack stack kaiwu exp1 -- status
hstack stack kaiwu exp1 -- daemon status

也可以使用栈的简写形式：

hstack exp1 kaiwu status

可用的栈封装命令

以下命令在执行时会自动加载并应用栈 env 文件：

  • hstack stack dev ⟦K58⟧
  • hstack stack start ⟦K59⟧
  • hstack stack build ⟦K60⟧
  • hstack stack runtime ⟦K61⟧ activate ...
  • hstack stack doctor ⟦K62⟧
  • hstack stack mobile ⟦K63⟧
  • hstack stack eas ⟦K64⟧ [subcommand...]
  • hstack stack kaiwu ⟦K65⟧ [-- ...]
  • hstack stack srv ⟦K66⟧ -- status|use ...
  • hstack stack wt ⟦K67⟧ -- ⟦K68⟧
  • hstack stack tailscale:status|enable|disable|url ⟦K69⟧
  • hstack stack service:* ⟦K70⟧

提示：hstack stack eas ⟦K71⟧ env:sync --environment production 会将该栈的 EXPO_* 配置值同步至 Expo 项目的 EAS 环境变量中。

全局/非栈命令：

  • hstack setup-from-source（推荐；安装 shim/运行时并初始化 monorepo）
    • 已弃用的别名：hstack setup
  • （高级）hstack init（底层命令：shim/运行时/指针环境变量）
  • （高级）hstack bootstrap（克隆/安装 monorepo 及其依赖）

服务（开机自启）

每个栈都可以拥有独立的自启服务（从而支持在用户登录时自启多个栈）。

hstack stack service exp1 install
hstack stack service exp1 enable
hstack stack service exp1 status
hstack stack service exp1 restart
hstack stack service exp1 logs

首次认证（推荐）：

hstack stack service exp1 enable --auth-now -- --method=mobile --no-open

注意：

  • 即使守护进程尚未认证，服务也会维持服务器与 UI 的运行；一旦凭据就绪，便会自动启动守护进程。
  • 命名栈服务遵循与 hstack stack start ⟦K72⟧ 相同的运行时模式。
    • KAIWU_STACK_RUNTIME_MODE=source：始终基于实时检出目录运行。
    • KAIWU_STACK_RUNTIME_MODE=prefer：若存在生效的运行时快照则优先使用，否则回退至源码模式。
    • KAIWU_STACK_RUNTIME_MODE=require：必须存在有效的已激活运行时快照，否则报错退出。
  • --method=mobile 要求手机能够访问到一个公网可达的 URL（例如 Tailscale Serve HTTPS 或反向代理）。若该栈的公开 URL 解析为 localhost / 127.0.0.1，则在配置好远程访问前，移动端认证将无法正常工作。

实现说明：

  • 服务名称/标签作用域限定在栈级别：
    • main → dev.KAIWU.stack
    • exp1 → dev.KAIWU.stack.exp1
  • macOS：基于 launchd LaunchAgents 实现
  • Linux：基于 systemd 用户服务 实现（若可用）
  • 服务会持久化 KAIWU_STACK_ENV_FILE，因此你可以直接修改栈 env 文件而无需重新安装服务。
  • 激活服务端或守护进程的运行时变更不会热替换正在运行的服务进程。执行 hstack stack build ⟦K73⟧ --activate-runtime 或 hstack stack runtime ⟦K74⟧ activate --server|--daemon|--all 后，需运行 hstack stack service ⟦K75⟧ restart 使服务基于新的生效快照重启。
  • 仅激活 Web 组件则属于例外：执行 hstack stack runtime ⟦K76⟧ activate --web 后，服务会直接提供更新后的 runtime/current/ui bundle，只需刷新浏览器即可。

为命名栈配置 Tailscale Serve

若需要手机/远程访问以及安全的浏览器特性支持，可通过 HTTPS 暴露命名栈：

hstack stack tailscale:enable dev-built
hstack stack tailscale:url dev-built

随后将该可共享 URL 持久化至栈 env 文件中，以便认证流程与客户端优先使用该地址：

hstack stack env dev-built set KAIWU_STACK_SERVER_URL=https://your-machine.your-tailnet.ts.net

此后，命名栈服务及基于运行时的认证流程将在适当时机使用该公开 URL。

为各个栈选择代码仓/工作树

创建栈时，可以将其指向特定的代码仓工作树：

  hstack stack new exp3 \\
  --repo=local/my-feature \\
  --server=KAIWU-server

工作树路径说明相对于工作区进行解析：

main                -> <workspace>/main
dev                 -> <workspace>/dev
pr/<...>            -> <workspace>/pr/<...>
local/<...>         -> <workspace>/local/<owner>/<...>
tmp/<...>           -> <workspace>/tmp/<owner>/<...>

因此 --repo=pr/foo 会映射至：

<workspace>/pr/foo

你也可以传入绝对路径。

栈 env 与代码仓 env 的优先级

启动时，hstack 会按以下顺序加载环境变量：

  1. ~/.KAIWU-stack/.env（默认配置）
  2. ~/.KAIWU-stack/env.local（可选的全局覆盖项；持久化配置推荐使用栈 env）
  3. KAIWU_STACK_ENV_FILE（栈 env；优先级最高）

hstack stack ... 会设置 KAIWU_STACK_ENV_FILE=~/.KAIWU/stacks/⟦K77⟧/env 并清除所有已导出的 KAIWU_STACK_* 变量，确保栈 env 保持最高权威性。

关于各类目录/路径（home、workspace、runtime 与栈存储空间）的完整说明及详细的环境变量优先级规则，请参阅：[路径、目录与环境变量优先级](/hstack/paths-and-env)。

克隆代码仓的回退顺序（在运行 hstack init 之前）：

  1. ⟦K78⟧/.env（默认配置）
  2. ⟦K79⟧/env.local（可选覆盖项）
  3. KAIWU_STACK_ENV_FILE（栈 env）

管理按栈配置的环境变量（包括 API 密钥）

通过 CLI 在栈 env 文件中添加或更新环境变量：

hstack stack env <stack> set KEY=VALUE [KEY2=VALUE2...]

移除变量：

hstack stack env <stack> unset KEY [KEY2...]

查看变量：

hstack stack env <stack> get KEY
hstack stack env <stack> list
hstack stack env <stack> path

注意：

  • 推荐在此处配置守护进程所需的提供商 API 密钥（例如：OPENAI_API_KEY）。
  • 变量变更将在栈/守护进程下次启动时生效。重启即可加载变更：
    • main：hstack start --restart
    • 命名栈：hstack stack start ⟦K80⟧ -- --restart（或 hstack stack dev ⟦K81⟧ -- --restart）

自托管快捷命令（在非栈封装环境下运行时，默认对应 main）：

hstack env set OPENAI_API_KEY=sk-...

守护进程认证与首次运行时的“无设备”提示

在全新设备（或任何新建的栈）上，守护进程可能需要先完成认证才能注册“设备”。如果 UI 显示“无设备”（或守护进程显示 auth_required），通常意味着该栈专用的 CLI 主目录下尚无认证凭据：

  • ~/.KAIWU/stacks/⟦K82⟧/cli/access.key

检查或认证某个栈：

hstack stack auth <stack> status
hstack stack auth <stack> login

注意：

  • 你可以使用 --identity=⟦K83⟧ 在不同账号下为同一个栈运行多个守护进程。
    • default（不带标志）：~/.KAIWU/stacks/⟦K84⟧/cli/...
    • --identity=account-b：~/.KAIWU/stacks/⟦K85⟧/cli-identities/account-b/...
  • 若要认证某个身份且不自动打开浏览器，请使用 --no-open（该命令会输出对应 URL，方便你在指定的浏览器配置文件或无痕窗口中打开）：
hstack stack auth <stack> login --identity=account-a --no-open
hstack stack auth <stack> login --identity=account-b --no-open
  • 显式启动/停止某个身份的守护进程：
hstack stack daemon <stack> start --identity=account-a
hstack stack daemon <stack> stop  --identity=account-a
  • 对于 main 栈，请使用 ⟦K86⟧=main 以及默认的 ⟦K87⟧=3005（除非你进行过修改）。
  • 若使用了 Tailscale Serve，KAIWU_WEBAPP_URL 应设为对应的 HTTPS URL（即从 hstack tailscale url 获取的地址）。
  • 日志位于以下路径：
    • 默认身份：~/.KAIWU/stacks/⟦K88⟧/cli/logs/
    • 命名身份：~/.KAIWU/stacks/⟦K89⟧/cli-identities/⟦K90⟧/logs/

JSON 模式

用于脚本或程序化调用：

hstack stack list --json
hstack stack new exp3 --json
hstack stack edit exp3 --interactive --json
© 乾元执中（南京）科技有限公司 · WUJI-Labs

认证（dev-auth 种子预置）

一次性创建 dev-auth 种子栈，后续新建栈即可直接复用，无需重新登录。

工作树与 fork

创建干净的上游 PR 工作树，同时隔离仅用于 fork 的补丁。

On this page

创建栈创建 PR 测试栈（便于复制粘贴）认证预置（推荐：dev-auth）运行栈命名栈运行时工作流（推荐用于类生产的本地栈）编辑栈（交互式）切换栈的服务器类型切换栈的代码仓工作树（stack wt）针对特定栈运行 Kaiwu CLI（stack kaiwu）可用的栈封装命令服务（开机自启）为命名栈配置 Tailscale Serve为各个栈选择代码仓/工作树栈 env 与代码仓 env 的优先级管理按栈配置的环境变量（包括 API 密钥）守护进程认证与首次运行时的“无设备”提示JSON 模式