企业官网建设流程全解析

• 数据库
• 图数据库
• 向量数据库
• AI 应用
• RAG

本篇指南以 crates/cli/README.md 为骨架，结合 CLI 源码实现 与 运行时管理模块，系统讲解 HelixDB v3 CLI 的本地实例生命周期、镜像选择与拉取策略、三种存储模式（内存 / 磁盘 / S3）、磁盘缓存卷机制，以及基于 WorkOS 会话的 Helix Cloud 认证与资源管理。读完本文，你将掌握helix init / start / stop / restart / prune等本地命令的完整语义与参数细节，理解--image-version、--persist、--pull等镜像相关的源码级行为，并能用helix auth、helix database、helix query等命令安全地操作 Helix Cloud 资源。

CLI 定位与命令全景

Helix CLI（v3）是一个面向两种场景的统一命令行工具：本地 Helix 实例（通过容器运行时在开发机上运行）与Helix Cloud 资源（通过 WorkOS 会话认证的后端服务）。CLI 的完整命令定义集中在 crates/cli/src/main.rs，主要分为四组：

• 本地实例管理：init、add、start、stop、restart、status、logs、query、shell、explorer、prune、delete。
• Cloud 资源发现与管理：workspace、project、cluster、database、service-credential、api。
• Cloud 查询：query与shell通过后端查询代理（query broker）执行。
• 认证：auth login | status | logout，只存储一个轮换的 WorkOS 会话（rotating WorkOS session），不保存任何 API Key。

此外还有几个工具性命令：chef（为编码 Agent 引导出第一个 Helix 应用，别名cook）、skills（安装/更新/列出 Helix Agent 技能）、metrics（遥测管理）、update（CLI 自更新）、feedback（反馈）。

从源码看，compile、check、deploy三个历史命令已被移除并隐藏，但保留了解析分支：当用户输入helix compile或helix check时，CLI 会返回友好提示，说明 HelixDB v2 在服务端校验查询、不存在客户端编译步骤（见 main.rs 中 removed_query_command_error）；helix deploy则提示 Cloud 数据库生命周期由 Helix 控制平面管理。CLI 也明确移除了push与sync。

输出契约：stdout 只给结果，stderr 只给进度

v3 CLI 对输出流有严格约定，这也是它适合被脚本与 AI Agent 调用的基础。核心规则见 crates/cli/src/output/mod.rs：

• stdout只承载命令的结果——表格、详情视图、查询 JSON、一次性令牌或--json负载，因此永远可以安全地管道化（pipe）。
• stderr承载所有人类可读的“进度信息”——会话步骤、spinner、警告、错误，与交互式提示共用同一套 cliclack 样式。

全局标志有三个，均可在任意子命令前/后使用：

--json模式下（对应源码中OutputMode::Json）会完全抑制“进度 chrome”，连 ANSI 颜色都会被禁用，确保不会有转义序列泄漏进机器输出；解析失败时错误也以{"error": ...}形式输出到 stderr，Agent 无需解析 clap 的人类文本（见 main.rs 的 exit_with_parse_error）。另外，在--json模式下 CLI 会跳过更新检查的网络往返，避免干扰 JSON 消费者。

Cloud 相关命令的参数统一接受ID、slug 或名称，并默认使用helix.toml中链接的项目与数据库；未指定实例名时，本地命令默认选择dev，若不存在dev则选择唯一的实例，否则进入交互式选择（非交互环境下报错并列出候选，见 query.rs 的 resolve_instance_name）。

本地实例生命周期：从 init 到 delete

helix init在指定目录（默认当前目录）脚手架一个 Helix 项目，可用--path指定项目目录；helix init local创建本地实例，helix init cloud --database cluster:<id>创建指向 Cloud 数据库的实例。init还会询问是否安装 Helix Agent 技能与 docs MCP（--skills/--no-skills可跳过交互）。helix add向已有项目添加本地或 Cloud 实例，其配置加载使用宽松校验，允许“零实例”的helix.toml（这是它存在的意义——把最后一个实例删掉后还能再加回来）。

helix start <instance>默认在后台启动本地实例（别名run，--detach是隐藏的后台别名），可用--foreground前台运行并在 Ctrl-C 时停止。启动成功后输出实例 URL 与容器名。其余生命周期命令：

• helix stop <instance>：停止并移除后台实例的容器（保留磁盘卷与缓存卷）。
• helix restart <instance>：用现有镜像与配置重启已有容器，并在容器公布的端口上做就绪检查；如果容器不存在则直接失败。要应用新的镜像或配置，必须用helix start。注意：重启内存存储的实例会清空其数据。
• helix status [instance]：展示本地与 Cloud 实例状态；本地状态来自容器运行时的ps输出。
• helix logs <instance> [-f]：查看（或-f跟随）实例日志；Cloud 实例可通过--start/--end（RFC 3339 时间）指定查询错误窗口，默认窗口为--end前一个小时。
• helix explorer <instance>：为本地实例启动图 Explorer 容器（镜像仓库ghcr.io/helixdb/helix-explorer），UI 与/api/query、/healthz绑定在容器内 3000 端口，宿主机仅监听回环地址127.0.0.1。
• helix delete <instance> [-y]：从helix.toml与本地运行时状态中删除实例。
• helix prune [instance] [--all] [-y]：清除 Helix 拥有的本地容器、工作区与磁盘卷（详见后文“维护与清理”）。

容器名由<project>-<instance>拼接并做 Docker 名称消毒，再附带身份标签helixdb.identity=<project.len>:<project>/<instance>，保证与旧版本遗留资源、其他容器的区分与安全接管（见 local_runtime.rs 的 container_name）。

实例名校验

实例名不是任意字符串：它会被拼进.helix/<name>状态目录与容器名，因此 CLI 在命令行参数、交互提示与helix.toml加载三条路径共用同一套校验（validate_instance_name，见 crates/cli/src/config.rs）：

• 非空；
• 长度不超过 32 字符（MAX_INSTANCE_NAME_LEN）；
• 仅允许 ASCII 字母、数字、-与_。

这既防止了../../evil这类路径穿越（prune/delete会递归删除.helix/下的目录），也保证了容器名与目录名的安全；测试用例对a/b、a\b、a.b等非法名逐一验证（见 config.rs 的 validate_instance_name_rejects_path_traversal_and_empty_names）。

本地镜像选择与拉取策略

v3 CLI 默认使用其经过测试的镜像版本，latest是显式选择（opt-in）而非默认。start命令内置三个镜像相关标志：

# 使用 latest 标签并每次拉取 helix start dev --image-version latest # 固定到 v0.0.12 标签，并把解析结果持久化到 helix.toml helix start dev --image-version v0.0.12 --persist # 禁止拉取，仅使用本地缓存的镜像 helix start dev --pull never

--image-version接受一个镜像标签或sha256:<64 位小写十六进制>摘要；仓库（repository）始终是实例配置的image。--persist会把解析后的镜像、拉取策略、端口与存储设置保存回helix.toml；不带--persist时，这些标志只对本次调用生效。

对应的helix.toml片段：

[local.dev] image = "ghcr.io/helixdb/helixdb" tag = "v0.0.12" pull = "missing"

标志、配置与默认策略的优先级

标志覆盖配置（源码中config.tag = image.image_version.unwrap_or(config.tag)，见 start.rs）。在没有配置策略的情况下，默认拉取策略由标签决定（见 crates/cli/src/image.rs 与PullPolicy定义）：

--pull always要求一次成功的拉取，--pull missing允许使用缓存镜像，--pull never则要求缓存镜像存在。显式拉取策略同样适用于磁盘模式的 SeaweedFS 镜像（其默认策略为missing）。镜像版本校验规则也相当严格：普通标签必须为非空、长度 ≤128、仅含 ASCII 字母数字与_，且./-不能出现在首位；摘要则必须精确匹配 64 位小写十六进制（见 image.rs 的 FromStr 实现）。

源码级的镜像解析流程

helix start在替换任何正在运行的容器之前，会先解析所有必需的镜像；镜像解析失败时helix.toml保持不变（--persist的保存发生在prepare_start成功之后）。关键实现见 local_runtime.rs 的 prepare_start：

1. 依据config.image_ref()计算完整引用（标签用:拼接，摘要用@拼接）；
2. 按pull配置（缺省时取标签默认策略）拉取或复用本地镜像，得到不可变的镜像 ID；
3. 磁盘模式下额外解析 SeaweedFS 镜像（策略同样取pull配置，缺省为missing）；
4. Helix 与 SeaweedFS 均以解析出的不可变镜像 ID启动（而非标签），从而避免并发标签更新导致容器中途换镜像。

start还有一层保护：若运行时守护进程（Docker/Podman）未运行，CLI 会尝试自动启动它（macOS 上按活动后端选择colima start、open -a Docker、open -a OrbStack或podman machine start，Linux 上用systemctl start docker），并轮询最长 120 秒等待就绪；启动失败会给出指向另一套运行时（如已装 Podman 则提示在helix.toml中把container_runtime改为"podman"）或安装命令的提示。

三种存储模式与磁盘缓存卷

本地实例支持三种存储模式（LocalStorageMode，见 crates/cli/src/config.rs）：

• memory（默认）：纯内存存储。helix stop/helix restart都会清空数据；CLI 会在首次启动时打印警告（通过实例工作区中的.warned-memory标记保证只提示一次，见 start.rs 的 warn_about_storage）。
• disk：本地磁盘存储，通过helix start dev --disk启用（与--storage-uri互斥）。
• s3：远程 S3 兼容对象存储，通过--storage-uri s3://bucket/prefix配合--s3-region、--s3-endpoint-url、--s3-allow-http启用。

S3 配置可以写入helix.toml：

[local.dev] storage = "s3" [local.dev.s3] bucket = "my-bucket" prefix = "my-prefix/" region = "eu-west-2" endpoint_url = "https://s3.example.com"

配置校验要求：storage = "s3"时必须存在s3配置表且 bucket/prefix/region 非空，endpoint_url必须以http://或https://开头；反过来，配置了s3表但存储模式不是s3也会报错（见 config.rs 的 validate）。S3StorageConfig::from_uri会把s3://bucket/path/to/db规范化为 bucket=bucket、prefix=path/to/db/，默认 region 为us-east-1、默认前缀为db/。

磁盘模式：SeaweedFS 私有 S3 边车

磁盘模式运行 SeaweedFS（ghcr.io/chrislusf/seaweedfs:4.47，按 digest 固定，见 local_runtime.rs 的 SEAWEEDFS_IMAGE）作为私有 S3 边车，bucket 名为helix-db，数据存放在helix-<project>-<instance>-seaweedfs-data卷中。边车通过seaweedfs网络别名加入实例的私有网络，S3 端口为 8333，凭据为固定的helix/helix-local-secret，不对外发布任何宿主机端口。SeaweedFS 自身会创建 bucket，CLI 在边车容器内用一次带签名的 HEAD 探测等待 bucket 就绪（最长 60 秒，见wait_for_seaweedfs_bucket）。

磁盘缓存卷：64 MiB 与 1 GiB

无论磁盘模式还是 S3 存储，都会挂载一个helix-<project>-<instance>-cache卷到服务器容器内的/var/cache/helix，用于服务器侧磁盘缓存：

• 磁盘模式下缓存预算为64 MiB（DISK_MODE_CACHE_BYTES）——因为 SeaweedFS 已把数据放在本机，更大的缓存只是复制；
• S3 存储下预算为1 GiB（S3_CACHE_BYTES）——足以容纳约 8,200 个打开文件的开发工作集，而服务器默认的 8 GiB 缓存需要 26,600 个文件描述符，在部分环境中会导致启动失败。

helix stop会保留缓存卷（下次启动可复用最近读取的数据），helix prune会删除它。

从 MinIO 迁移到 SeaweedFS

在切换到 SeaweedFS 之前的 CLI 版本使用 MinIO，而 MinIO 镜像已不再发布。因此，helix start、helix stop与helix prune都会移除旧的-minio边车容器；start与stop保留不可读的-minio-data卷，且只要该卷存在，start就会打印警告。由于 SeaweedFS 无法读取 MinIO 的磁盘格式，迁移数据需要先按 本地工作流指南（对应docs/cli/workflows/local.mdx中的 “migrate-minio-disk-data” 一节）中的步骤复制，迁移完成后用docker volume rm <helix-<project>-<instance>-minio-data>（或podman volume rm ...）单独删除旧卷——注意不要用helix prune，因为prune会连同新的 SeaweedFS 卷一起删除。

Cloud 资源管理与会话认证

WorkOS 会话认证

helix auth login走完整的 OAuth 风格浏览器流程（实现见 crates/cli/src/commands/auth.rs）：CLI 在127.0.0.1:8765起一个本地回调监听器，调用 Cloud 后端的/v1/auth/login:start拿到登录 URL 并打开浏览器，用户完成后回调携带code与state，CLI 再通过/v1/auth/exchange换取访问令牌、刷新令牌与过期时间，最终只把会话（credentials）写入本地存储。若后端要求邮箱验证，CLI 会提示输入发送到邮箱的验证码。整个过程有 5 分钟超时。

关键安全边界：Cloud CLI 不接受 API-Key 登录，不接受 service-credential 登录，不支持直连网关路径，也不支持自定义查询授权。租户创建时会一次性返回一个默认的读写应用密钥，仅供直连网关客户端使用——CLI 会显示它但从不存储或使用；额外的应用密钥始终作为显式管理的机密处理。auth status展示当前邮箱并列出所属 workspace（同时验证会话仍有效）；auth logout尝试吊销远端会话并清除本地凭据。

资源命令

• helix workspace：列出并查看 Helix Cloud workspace。
• helix project：管理 Cloud 项目与当前目录的链接（helix.toml中的project配置）。
• helix cluster：列出并查看集群。
• helix database：管理 Cloud 数据库与应用密钥。helix init cloud --database cluster:<id>或helix add cloud会把cluster:<id>/tenant:<id>写进helix.toml的[enterprise.<name>]配置（见 config.rs 的 DatabaseReference，ID 需为 1～128 位 ASCII 字母数字或-/_）。
• helix service-credential：管理工作区拥有的、用于无头 API 与 MCP 自动化的凭据。
• helix api：携带当前会话直接调用 Helix Cloud API 路径。

Cloud 查询如何工作

helix query与helix shell对 Cloud 目标走后端查询代理，其执行细节在 crates/cli/src/commands/query.rs：

• 目标是本地实例时，请求 POST 到http://<host>:<port>/v2/query，支持--host/--port覆盖；
• 目标是 Cloud 数据库时，--host/--port与--warm均被拒绝（只对本地查询有效），查询 JSON 会被 base64 编码后放进{"database": {"clusterId"|"tenantId": ...}, "queryJson": ...}负载，POST 到/v1/databases:query-read（read 请求）或/v1/databases:query-write（write 请求），响应中的statusCode与responseJson再解码还原。

查询输入四选一：--file <REQUEST.json>、--body '<JSON>'、-e/--ts '<TS表达式>'（TypeScript DSL 内联，类似mysql -e）、--ts-file <QUERY.ts>。请求必须包含request_type（小写read或write）与query字段；--warm仅对 read 请求有效，会附加X-Helix-Warm: true头预热缓存。结果以高亮 JSON 打印到 stdout，状态码与耗时以暗色脚注输出到 stderr。

维护与清理：prune 语义

helix prune的删除范围需要精确理解（实现见 crates/cli/src/commands/prune.rs 与 local_runtime.rs 的 prune_instance）：

• 删除：实例容器、Explorer 容器、SeaweedFS 边车容器、私有网络、-seaweedfs-data卷、-minio-data旧卷、磁盘缓存卷、以及.helix/<instance>工作区目录；
• 不删除：远程 S3 对象存储数据（提示语明确说明）。

prune --all会清理所有本地实例，非交互环境下必须追加--yes确认。prune对实例名同样执行路径穿越校验，并在删除前确认.helix不是指向项目外部的符号链接（assert_safe_helix_dir），相关回归测试见 prune.rs 的测试。

其余维护命令：helix update更新 CLI 到最新版本（--force强制、--v1更新到最后一个 v1 兼容版本）；helix skills管理 Helix Agent 技能与 docs MCP；helix metrics管理遥测采集（登录后user_id会被清空）；helix feedback <message>向 Helix 团队发送反馈。首次运行 CLI 会展示品牌横幅与分组命令速览，并检查 CLI 与技能更新。

小结

Helix v3 CLI 的设计目标可以概括为三点：本地与 Cloud 的统一入口（同一套命令、同一份helix.toml）、对脚本与 Agent 友好的输出契约（stdout 结果 / stderr 进度、--json永不提示）、克制的安全边界（只存 WorkOS 会话、无 API-Key 登录、密钥一次性显示）。镜像选择上，默认固定测试过的标签、latest显式选择、标志覆盖配置、启动前解析全部镜像并用不可变 ID 运行；存储上，内存/磁盘（SeaweedFS 边车）/S3 三种模式配合持久化缓存卷各司其职。理解这些底层约定（对应 crates/cli/src/local_runtime.rs 与 crates/cli/src/config.rs 中的实现），就能在本地开发、CI 与 Cloud 生产环境之间平滑迁移。更完整的逐命令参考见 CLI 命令参考文档。

• 数据库
• 图数据库
• 向量数据库
• AI 应用
• RAG