先核对实际发布的 Helm 包，再选择安装版本
GitHub main 源码、应用发布版本与 Helm 仓库是独立的交付入口。安装前检查将要使用的实际包，不能仅凭主分支文档判断某项能力已经发布。
helm repo add kv-shepherd https://kv-shepherd.github.io/helm-charts
helm repo update kv-shepherd
helm search repo kv-shepherd/shepherd --versions
helm show chart kv-shepherd/shepherd
helm show values kv-shepherd/shepherdadd/update 会维护本机 Helm 仓库配置与缓存，其余命令检查元数据和默认配置；这些命令均不执行安装，也不访问你的 Kubernetes 集群。记录 Chart version、appVersion 与镜像配置；评估后用 --version 固定 Chart，并使用对应发布版本的文档。可选指标与监控资源取决于所选安装包，不能只看 main 分支是否已有实现。
明确选择安装模式
Helm 适合 Kubernetes 原生安装；Docker Compose 可以在主机运行发布镜像，也可以在明确需要时从检出源码构建。Chart 与 Compose 发布模式使用不同镜像默认值，应遵循所选模式的文档。
规划状态与恢复
PostgreSQL 18 存储应用状态和 River 后台任务，默认运行不要求 Redis 或独立消息队列。应规划持久化、备份，以及解密基础设施凭据所需配置的恢复。
评估真正需要的能力
项目处于 Alpha，不替代 KubeVirt、Kubernetes 运维或更大虚拟化发行版的全部功能。选择环境前，验证团队需要的申请、部署、权限与控制台路径，并按运维文档配置监控。
操作与检查步骤
定义代表性工作流
选择一个服务、申请人、审核人和测试命名空间，先写清期望的申请、操作与审计结果。
选择 Helm 或 Compose
Kubernetes 安装使用 Chart；主机部署可以使用发布镜像 Compose。源码构建需要检出仓库，是单独的选择。
阅读安装模式准备持久化与恢复
对外提供服务前，核对数据库存储、初始管理员凭据和必需密钥，妥善保留解密已存储基础设施数据所需的值。
阅读生成凭据与恢复说明连接测试环境并验证
配置集群访问、目录、命名空间与账号分工。跑通申请到执行，检查审计证据，并测试所选监控与恢复方案。
阅读可观测范围与边界
前提条件与边界
- Alpha 的适用性取决于实际集群、认证、存储与组织运维策略。
- 轻量 Helm 示例为演示关闭数据库持久化；持续运行的服务需要独立规划存储和恢复。
- 源码开发要求 Go 1.25.12 或更新版本及 Node.js 22 或更新版本；这些构建要求与运行发布镜像不同。
- main 分支文档中的能力可能要求后续应用或 Chart 版本。应核对实际安装包及其支持的配置。
文档与实现依据
- 部署与恢复指南
安装模式、持久化、凭据与配置。
- 官方 Helm Chart
Chart 配置、镜像默认值、存储与被管理集群访问。
- 当前状态与前置要求
Alpha 范围、架构与源码要求。
- 可观测基线
已接受信号、可选打包与后续工作。
常见问题
运行发布镜像需要 Go 和 Node.js 吗？
这些前置要求针对源码开发。使用发布镜像 Compose 时，应遵循该模式的 Docker 与网络访问要求。
安装 Shepherd 就得到完整虚拟化平台了吗？
不是。它围绕已配置的 Kubernetes/KubeVirt 集群工作。基础设施及管理服务的持久化、安全和恢复仍由安装者负责。