Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add Enterprise Deployment guides (checklist, install, operations) (#5361)
Zayn Jarvis18abb3cc7163
diff --git a/docs/.vitepress/deployment-context.md b/docs/.vitepress/deployment-context.mdnew file mode 100644index 000000000..5841dfa55--- /dev/null+++ b/docs/.vitepress/deployment-context.md@@ -0,0 +1,74 @@+# 官网部署内容上下文++更新日期:2026-09-22。范围:官网内容、双语导航与阅读入口;不修改部署工具或环境。++## 内容目标++让读者完成:选择服务方式 → 准备环境 → 配置与预览 → 部署与验收 → 维护与排障。++托管服务、开源自建、Viking 私有交付分别说明。官网保留决策条件、操作主线、失败分支和验收标准;完整 CLI 参数、依赖初始化 SQL、授权操作细节继续指向对应随包手册。无需复制所有附件或增加与部署无关的产品页。++## 来源与证据范围++- 输入包:`viking-deploy-v0.3.0-20260922-87c30111.zip`,27,641,644 bytes。+- SHA-256:`11720a376d17d2a6d305854b6dc68b6e4e3d92851a94255298041fb3d1a80075`。这是本地下载记录,不是发布方签名证明。+- ZIP CRC 检查通过。静态读取包内手册;未运行 ovadmin、未接入集群、未执行部署与 smoke。+- 下载链接带签名,只用于取得输入,不写入站点、示例、日志附件或 llms.txt。+- `NOTICE.md` 将该包限定为授权测试材料,无生产、商用、对外服务或再分发授权。手册里的生产建议不覆盖此限制。本站内容以本地待审稿交付,公开发布前由内容负责人按实际授权范围确定可公开的内容;不分发原始手册、二进制或物料清单。++| 官网主题 | 随包依据 | 应保留的限制 |+| --- | --- | --- |+| 环境、资源、依赖 | `Viking部署手册.md` §1–5;`版本兼容性说明.md`;`基础组件配置要求.md` | 私有组合的规划参考不等于开源最低配置,不承诺容量或 HA |+| 安装主线 | `install.md`;`Viking部署手册.md` §6;`ovadmin使用手册.md` | VikingDB Ready 后部署 OpenViking;Operator 与 workspace 分开创建 |+| 授权首次启动 | `install.md`;部署手册 §6.4–6.5 | CRD、CR 与首次状态同步在导入前;不提供激活材料 |+| 模型与模板 | `Viking模型要求.md` §3、6 | CR 覆盖向量库维度,不覆盖 embedding 维度;修改源模板 |+| 验收 | 部署手册 §7–8;升级说明 §2.5 | 当前 generation Ready、License Active(如启用)、doctor、各产品 P0 分别验证 |+| 升级和排障 | `Viking升级说明.md`;ovadmin 手册 §3.9–4 | 配置备份不等于数据备份;回滚不可仅降镜像;失败先观测 |+| 开源 Helm 入口 | 仓库 `deploy/helm/README.md` | 使用 `deploy/helm/openviking`、`config.*` 字段与 root key;区别于私有 Operator |++版本冲突处理:部署手册把 Kubernetes 1.24+ 写为建议,版本兼容矩阵写为最低值。官网标明“兼容矩阵声明”,未补造最大版本。包版本 v0.3.0 不代表 runtime 版本。命令示例使用交付清单占位值,不沿用手册中的旧 runtime tag。++## 信息组织参考++- [MongoDB Ops Manager installation checklist](https://www.mongodb.com/docs/ops-manager/current/core/installation-checklist/):部署前先确定拓扑、安全和备份,区分测试安装与正式运行。+- [GitLab installation](https://docs.gitlab.com/install/):按 requirements、installation methods、offline、post-install、upgrade 组织任务入口。+- [GitLab requirements](https://docs.gitlab.com/install/requirements/):说明资源要求与工作负载的关系。++只借鉴任务路径,不引入 MongoDB / GitLab 的组件要求或容量数字作为 Viking 的结论。++## 站点适配位置++- `docs/{zh,en}/guides/19-deployment-checklist.md`:方式选择、条件与环境清单。+- `docs/{zh,en}/guides/20-private-deployment.md`:版本范围、物料、配置、安装、客户端与验收。+- `docs/{zh,en}/guides/21-private-operations.md`:配置生命周期、升级、回滚准备、故障表。+- `docs/{zh,en}/guides/03-deployment.md`:保留既有开源安装内容,增加新入口并修正 Helm 路径。+- `docs/.vitepress/docs-navigation.ts`:在“配置与部署”下、服务端部署之后增加“企业私有化部署”子栏目,依次放置部署前检查、安装与验收、升级与排障。+- `docs/.vitepress/theme/components/DocsHome.vue`:在既有“部署与运维”条目中增加“企业私有化部署”链接。+- 目录与搜索继续使用既有 Markdown 扫描机制;不再维护第二套页面清单。本文件置于 `.vitepress`,不进入网站正文和 llms.txt。++## 验证记录++改动前 `check:docs` 已报告 `zh/qa/harness-qa-plan.md` 缺少英文对应页。该文件是工作区已有内容,不纳入本次修复;验收应比较新增错误,不能删减检查来获得全绿。++本次验证结果:++- `npm run docs:build` 通过;构建仍有既有 promql / caddyfile 高亮回退提示。+- 文档一致性检查覆盖 100 篇英文、101 篇中文、1,104 个本地链接;仅保留改动前已有的 QA 页面英文缺失,无新增错误。+- 六个新页面进入生成 HTML、`llms.txt`、`docs-search-index.json`;本 context 与本次签名下载地址未进入公开文本产物。+- ego-browser 实测英文首页 → checklist → private deployment → operations;中文切换、首页入口、清单与安装页跳转通过。+- 首页“私有交付”筛选返回两个对应页面;全站关键词查询在远端不可用后回退本地,返回安装、运维、清单与服务端部署页。未验证远端检索;发布流程需同步并验收远端索引。+- 桌面页面与 390px 手机首页无整页横向溢出,截图检查通过。+- 未执行部署命令、集群验收、提交或线上发布。页面中的命令为随包手册静态核对结果。+++## 阅读与导航调整(2026-09-22)++按用户要求,正文移除测试包适用范围、NOTICE 和测试用途声明;来源版本及其使用限制只作为本 context 的资料记录保留。正文保留影响实际操作的版本兼容、License 激活、容量与数据恢复约束,不由删除提示推导新的生产能力承诺。++企业私有化部署页标题后提供“联系我们获取部署物料”按钮。中文跳转 README_CN.md 的商业版本锚点,英文跳转仓库首页的 commercial-editions 锚点;复用 VitePress VPButton,在正文中保留段落间距并去掉链接下划线;不发送联系消息。++调整验证:构建通过;浏览器确认“企业私有化部署”为配置与部署下的可折叠子栏目,包含三篇页面。中英文 CTA 的实际 href 与用户指定地址一致,适用范围提示已移除。桌面与手机视口检查通过。文档一致性检查仍仅报告原有 QA 页面缺少英文版本。++栏目命名:统一使用 `Enterprise Deployment / 企业私有化部署`,覆盖侧栏、首页入口、页面标题与交叉引用;保留现有 URL。++恢复记录(2026-09-24):本次内容曾于 2026-09-22 在工作区完成但未提交,后被 `git clean` 清除;现依据当时的编辑记录在 main 上重放,并把侧栏改动从 `config.ts` 迁到已合入的 `docs-navigation.ts`。diff --git a/docs/.vitepress/docs-navigation.ts b/docs/.vitepress/docs-navigation.tsindex 835fbaf28..7b2d4157d 100644--- a/docs/.vitepress/docs-navigation.ts+++ b/docs/.vitepress/docs-navigation.ts@@ -446,6 +446,25 @@ const guidesSidebar = {}} as const+const privateDeploymentSidebar = {+ en: {+ text: 'Enterprise Deployment',+ items: [+ ['19-deployment-checklist.md', 'Deployment Checklist'],+ ['20-private-deployment.md', 'Install & Verify'],+ ['21-private-operations.md', 'Upgrades & Troubleshooting']+ ]+ },+ zh: {+ text: '企业私有化部署',+ items: [+ ['19-deployment-checklist.md', '部署前检查'],+ ['20-private-deployment.md', '安装与验收'],+ ['21-private-operations.md', '升级与排障']+ ]+ }+} as const+type StructuredSidebarCopy = {readonly overview: stringreadonly topItems?: ReadonlyArray<readonly [string, string]>@@ -570,6 +589,19 @@ function guidesSection(collapsed = true): DefaultTheme.SidebarItem {const section = groupedSidebarSection(locale, 'guides', title, guidesSidebar[locale], collapsed)+ const deploymentGroupTitle = locale === 'zh' ? '配置与部署' : 'Configuration & Deployment'+ const deploymentGroup = section.items?.find((item) => item.text === deploymentGroupTitle)+ if (deploymentGroup?.items) {+ const serverIndex = deploymentGroup.items.findIndex((item) =>+ item.link === `/${locale}/guides/03-deployment`+ )+ const copy = privateDeploymentSidebar[locale]+ deploymentGroup.items.splice(serverIndex + 1, 0, {+ text: copy.text,+ collapsed: false,+ items: copy.items.map((item) => configuredSidebarItem(locale, 'guides', item))+ })+ }// Nest the Context Compilation pages under the "Integration & Extension" group.const integrationGroupTitle = locale === 'zh' ? '集成与扩展' : 'Integration & Extension'const integrationGroup = section.items?.find((item) => item.text === integrationGroupTitle)diff --git a/docs/.vitepress/theme/components/DocsHome.vue b/docs/.vitepress/theme/components/DocsHome.vueindex 335cd7ecb..97d956f59 100644--- a/docs/.vitepress/theme/components/DocsHome.vue+++ b/docs/.vitepress/theme/components/DocsHome.vue@@ -128,6 +128,7 @@ const agents = [<a :href="link('guides/01-configuration')">{{ t('Configuration', '基础配置') }}<span aria-hidden="true">↗</span></a><a :href="link('guides/04-authentication')">{{ t('Authentication', '身份认证') }}<span aria-hidden="true">↗</span></a><a :href="link('guides/05-observability')">{{ t('Observability', '可观测性') }}<span aria-hidden="true">↗</span></a>+ <a :href="link('guides/20-private-deployment')">{{ t('Enterprise Deployment', '企业私有化部署') }}<span aria-hidden="true">↗</span></a></div></section>diff --git a/docs/.vitepress/theme/docs-catalog.test.ts b/docs/.vitepress/theme/docs-catalog.test.tsindex da220bdeb..ab88e6e60 100644--- a/docs/.vitepress/theme/docs-catalog.test.ts+++ b/docs/.vitepress/theme/docs-catalog.test.ts@@ -20,8 +20,13 @@ for (const locale of ['en', 'zh']) {test(`${locale} map preserves sidebar order and compilation hierarchy`, () => {const guides = data[locale].find(section => section.id === 'guides')!const deployment = guides.pages.findIndex(page => page.file === '03-deployment.md')- assert.equal(guides.pages[deployment + 1].file, '04-authentication.md')- assert.equal(guides.pages[deployment].group, guides.pages[deployment + 1].group)+ const enterprise = guides.pages.slice(deployment + 1, deployment + 4)+ assert.deepEqual(enterprise.map(page => page.file), [+ '19-deployment-checklist.md', '20-private-deployment.md', '21-private-operations.md'+ ])+ assert.ok(enterprise.every(page => page.group.startsWith(`${guides.pages[deployment].group} / `)))+ assert.equal(guides.pages[deployment + 4].file, '04-authentication.md')+ assert.equal(guides.pages[deployment].group, guides.pages[deployment + 4].group)const compilation = guides.pages.filter(page => page.href.includes('/context-compilation/'))assert.ok(compilation.length > 0)assert.ok(compilation.every(page => page.group.includes(' / ')))diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.tsindex 647ee42b0..518b4d910 100644--- a/docs/.vitepress/theme/index.ts+++ b/docs/.vitepress/theme/index.ts@@ -1,5 +1,5 @@import { h, defineAsyncComponent } from 'vue'-import DefaultTheme from 'vitepress/theme'+import DefaultTheme, { VPButton } from 'vitepress/theme'import DocBreadcrumb from './components/DocBreadcrumb.vue'import LocaleSwitch from './components/LocaleSwitch.vue'import { useData, withBase } from 'vitepress'@@ -321,6 +321,7 @@ export default {})},enhanceApp({ app, router }: EnhanceAppContext) {+ app.component('VPButton', VPButton)app.component('DocsHome', defineAsyncComponent(() => import('./components/DocsHome.vue')))if (import.meta.env.SSR || typeof window === 'undefined') returndiff --git a/docs/.vitepress/theme/reading.css b/docs/.vitepress/theme/reading.cssindex a881e1ade..438d8d6cf 100644--- a/docs/.vitepress/theme/reading.css+++ b/docs/.vitepress/theme/reading.css@@ -78,3 +78,5 @@.VPNav .VPNavBar .content-body { gap: 5px; }.VPNav .ov-docs-search-trigger { width: 43px; min-width: 43px; padding: 0 4px; }}++.vp-doc a.VPButton { text-decoration: none; }diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex 53cfa9f6a..b00fde474 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -1,5 +1,7 @@# Server Deployment+Before provisioning a self-managed environment, review the [deployment checklist](19-deployment-checklist.md). If you have a VikingDB / OpenViking private deployment package, use [Enterprise Deployment](20-private-deployment.md) and [operations](21-private-operations.md).+OpenViking runs as an HTTP service. Choose who operates it before installing a server:| Service | What you need |@@ -404,12 +406,15 @@ To build the image yourself, pass an explicit OpenViking version:### Kubernetes + Helm-The project provides a Helm chart located at `examples/k8s-helm/`:+This chart deploys the open-source service and is separate from the private delivery ovadmin / Operator workflow. See the [Helm README](https://github.com/volcengine/OpenViking/blob/main/deploy/helm/README.md) for chart parameters.++The project provides a Helm chart located at `deploy/helm/openviking/`:```bash-helm install openviking ./examples/k8s-helm \- --set openviking.config.embedding.dense.api_key="YOUR_API_KEY" \- --set openviking.config.vlm.api_key="YOUR_API_KEY"+helm install openviking ./deploy/helm/openviking \+ --set-string config.server.root_api_key="YOUR_ROOT_API_KEY" \+ --set-string config.embedding.dense.api_key="YOUR_API_KEY" \+ --set-string config.vlm.api_key="YOUR_API_KEY"```For a detailed cloud deployment guide (including Volcengine TOS + VikingDB + Ark configuration), see the [Cloud Deployment Guide](https://github.com/volcengine/OpenViking/blob/main/examples/cloud/GUIDE.md).diff --git a/docs/en/guides/19-deployment-checklist.md b/docs/en/guides/19-deployment-checklist.mdnew file mode 100644index 000000000..1c22bf160--- /dev/null+++ b/docs/en/guides/19-deployment-checklist.md@@ -0,0 +1,80 @@+---+description: Choose hosted, self-managed, or private delivery and prepare infrastructure, models, storage, and acceptance checks.+---++# Deployment Checklist++Choose how the service will run before provisioning infrastructure. If you already have an endpoint and API key, connect through the [CLI quick start](../getting-started/02-quickstart.md).++| Goal | Deployment path | Next step |+| --- | --- | --- |+| Let the platform operate the infrastructure | Volcengine hosted OpenViking | [Hosted service entry](03-deployment.md) |+| Run the open-source service yourself | Python, Docker, or the open-source Helm chart | [Server deployment](03-deployment.md) |+| Deploy VikingDB / OpenViking on your infrastructure | Kubernetes, Operators, and ovadmin | [Enterprise Deployment](20-private-deployment.md) |++Private delivery has its own components, licensing, and configuration lifecycle. Requirements marked as private delivery do not apply to every OpenViking installation.++## For every self-managed installation++| Area | Decide before deployment | Reference |+| --- | --- | --- |+| Workload | Document count and size, vector dimensions, concurrency, ingestion frequency, retention | [Observability](05-observability.md) |+| Models | Provider, model name, API base, credentials, output dimensions, rate limits, timeouts, connectivity from the runtime | [Configuration](01-configuration.md) |+| Storage | Persistent workspace location, capacity, permissions, backup destination, restore procedure | [Storage](../concepts/05-storage.md), [snapshots](15-snapshot.md) |+| Network and identity | Client endpoint, TLS, DNS, proxy, administrator and application keys | [Public access](12-public-access.md), [authentication](04-authentication.md) |+| Operations | Owners for alerts, upgrades, credentials, and recovery | [Diagnostics](05-observability.md) |++Measure capacity with representative data. A running container or a successful health probe does not demonstrate that the deployment can handle your workload.++## Private delivery: versions and environment++Review the environment and version requirements below, then confirm component compatibility against your deployment package.++| Area | Requirement | Verify |+| --- | --- | --- |+| OS / CPU | Linux, x86_64 by default | arm64 requires matching images and binaries |+| Kubernetes | Compatibility matrix specifies 1.24+ | Actual version, CRDs, CNI, CSI, RBAC; no maximum version is declared |+| Helm / kubectl | Helm 3.x, not Helm 4; kubectl within one minor of the cluster | Tool versions on the deployment host |+| Profile | `standalone` for demos and reproductions; `cluster` for cluster evaluation | Choose a profile for the environment and verify replicas, scheduling, and recovery |+| Release combination | ovadmin, VikingDB, OpenViking runtime, and Operators form a delivery set | Record `ovadmin version --output json`; the archive version is not the runtime version |++The package gives a cluster planning reference of at least three machines with 32 CPU cores, 256 GiB RAM, and 2 TiB local disk per machine. **These are not minimum requirements for open-source OpenViking or a validated capacity guarantee.** Suitability depends on index size, vector dimensions, QPS, build concurrency, replicas, and dependency placement. A three-node deployment that also hosts infrastructure dependencies is a starting point for development, demos, or POCs.++## Private delivery: infrastructure checklist++| Area | Confirm |+| --- | --- |+| Permissions | Deployment kubeconfig; CRD and RBAC creation; Operator access to target namespaces; use the package permission matrix |+| Namespaces | Application and Operator namespaces, illustrated as `vikingdb` and `viking-system`; Secret scope |+| Scheduling | Default `cluster` selectors are `nodeLevel=online` / `nodeLevel=offline`; matching labels, tolerations, and resources |+| Registry | Full repository prefix, delivery tags, pull credentials; validate host login and cluster pulls separately |+| Storage | Available StorageClass; separate settings for VikingDB data, OpenViking workspace PVCs, and external dependencies |+| Network | Pod / Service DNS, API Server, dependency and model access, cluster DNS suffix, external endpoint and TLS |+| License | When enabled, a license matching the cluster fingerprint; expiry, renewal, and offline telemetry arrangements |++Review generated `local-path`, disk capacity, and node selectors before use. The default OpenViking workspace requests and limits are both 2 CPU / 4 GiB; these are configuration defaults, not workload sizing results.++The `cluster` delivery expects infrastructure supplied by the customer or prepared through the delivery plan:++| Component | Package recommendation | Declared minimum / condition |+| --- | --- | --- |+| MySQL | 8.0 | 5.7+ |+| Redis | 6.2.x | No minimum declared |+| Kafka | 3.x | 3.0+ |+| ZooKeeper | 3.7.2 | No minimum declared |+| HDFS | 3.3.x | High-availability topology |+| HBase | 2.5.x | Depends on HDFS and ZooKeeper |++This records the package's compatibility statement, not an ongoing certification. In addition to connectivity, verify databases, topics, namespaces, directories, permissions, and initialization against the bundled infrastructure requirements. Re-run acceptance checks after dependency changes.++## Model integration checks++- Embedding must return fixed-size dense vectors. Align actual output, `embedding.dense.dimension`, and vector database dimensions.+- Confirm whether the API base includes `/v1` or `/api/v3`. Text and multimodal embedding may use different paths and request bodies; “OpenAI compatible” alone is insufficient.+- VLM / LLM supports understanding, summaries, and memory extraction. Validate image input for image tasks and tool calls for agents that use tools.+- Test authentication, DNS, certificates, and timeouts from the Pod network. Connectivity from a laptop does not establish Pod connectivity.+- Changing embedding models can change vector semantics even when dimensions match. Plan index rebuilding before switching an existing dataset.++In private delivery, `OpenVikingWorkspace.spec.vectordb.dimension` overrides the template's storage dimension, but does not change `embedding.dense.dimension`. Check both.++Continue to [Enterprise Deployment](20-private-deployment.md) and [upgrades and troubleshooting](21-private-operations.md).diff --git a/docs/en/guides/20-private-deployment.md b/docs/en/guides/20-private-deployment.mdnew file mode 100644index 000000000..9816c83d2--- /dev/null+++ b/docs/en/guides/20-private-deployment.md@@ -0,0 +1,148 @@+---+description: Deploy VikingDB and OpenViking through configuration preview, VikingDB, OpenViking Workspaces, and P0 acceptance.+---++# Enterprise Deployment++<p><VPButton text="Contact us for deployment materials" href="https://github.com/volcengine/openviking/#commercial-editions" /></p>++Deploy VikingDB and OpenViking in your own Kubernetes cluster using the deployment package. Complete the [deployment checklist](19-deployment-checklist.md) first. For Python, Docker, or the open-source Helm chart, see [server deployment](03-deployment.md).++## 1. Prepare materials and configuration directories++After extracting the package, check `bin/ovadmin`, `viking-docs/`, and the delivery manifest. The ZIP contains the CLI and documentation; **it does not contain all runtime images**. If a `vikinglist` is supplied, it can download additional materials. Skip material downloads when images have already been synchronized.++Run these commands on the target deployment host. Replace all placeholders. `ovadmin` manages the deployment; `ov` is the application client CLI.++```bash+export VIKING_HOME=/opt/viking-deploy+export CONFIG_DIR=/opt/viking-deploy/conf+export PATH="${VIKING_HOME}/bin:${PATH}"++ovadmin version --output json++# Only when downloading through a material manifest: review first+ovadmin material download --listfile "${VIKING_HOME}/vikinglist" \+ --output-dir "${VIKING_HOME}/materials" --dry-run+```++After reviewing the download plan, remove `--dry-run` to fetch materials, then import images into the customer Registry following the package manual. Isolated environments also require import tools, infrastructure dependencies, model services, and a license renewal / telemetry return plan. Downloading the ZIP alone does not make the system offline-ready.++## 2. Generate and edit configuration++```bash+ovadmin init config \+ --dir "${CONFIG_DIR}" \+ --profile cluster \+ --image-registry '<registry.example.com/team/viking>' \+ --image-pull-secret viking-registry-secret \+ --openviking-storage-class '<storage-class-name>'+```++Edit the generated configuration before deploying:++| File or object | Responsibility |+| --- | --- |+| `ovadmin.conf` | Cluster access, configuration directory, OpenViking image, workspace resources and storage |+| `vdb.yaml` | VikingDB images, dependency references, scheduling, storage, and observability |+| ConfigMap Template | Base OpenViking runtime configuration |+| Secret Template | Model credentials and other sensitive configuration in `ov.conf.secret` |+| `OpenVikingWorkspace` | Workspace declaration, including storage and vector database overrides |+| Generated `*.ovcli.conf` | Client endpoint and API key; handle as credentials |++The full image prefix includes the repository path. Use Operator image names from the manifest: this release uses `vikingdb_operator` and `openviking_operator`, with underscores. Use tags from the delivery set, not old example tags.++Check namespaces, external Secret / ConfigMap references, node labels, and StorageClass. Complete dependency initialization using the bundled infrastructure requirements. Run preflight checks and initialize pull Secrets for namespaces configured in the delivery:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" init secret --all-namespaces+```++## 3. Deploy VikingDB++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module vikingdb --dir "${CONFIG_DIR}" --dry-run+```++Review namespaces, images, pull Secrets, dependencies, resources, and scheduling. Resolve mismatches before applying:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module vikingdb --dir "${CONFIG_DIR}" --yes+```++When licensing is enabled, the first apply may exit while waiting for License Active. Before importing, the `VikingDbCluster` CRD and target CR must exist, and the Operator must have completed its first status synchronization. Import the license bound to this cluster using the package's licensing procedure, then repeat apply with the same configuration:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license import --file '<license.vlic>'+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license status+```++Skip licensing steps when licensing is disabled. Verify VikingDB before proceeding:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" cluster get vikingdb+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" doctor+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check smoketest --target vdb --p0+```++Replace `vikingdb` if your cluster has a different name. Smoke tests create test objects and perform writes; run them in the agreed acceptance environment.++## 4. Deploy OpenViking and create a Workspace++Skip this step for a VikingDB-only delivery. Prepare the release's ConfigMap Template and model Secret Template, then preview and install the OpenViking Operator:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module openviking --dir "${CONFIG_DIR}" --dry-run++# Apply after reviewing the preview+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module openviking --dir "${CONFIG_DIR}" --yes++export WORKSPACE_NAME='<workspace-name>'+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace create "${WORKSPACE_NAME}" \+ --namespace vikingdb \+ --image '<runtime-image-from-delivery-manifest>' \+ --conf-template '<configmap-template-name>' \+ --conf-secret '<secret-template-name>' \+ --wait++ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace get "${WORKSPACE_NAME}"+```++Installing the Operator does not create the workspace. For an existing workspace, follow the package's `workspace update` procedure.++Configuration is merged in this order: ConfigMap Template → Secret Template → Workspace CR `spec.vectordb` / `spec.storage` overrides. The result is stored in `<workspace-name>-ov-conf` and mounted at `/app/ov.conf`. Edit source templates or the CR, not the generated Secret or Pod file. See [operations](21-private-operations.md) for applying template changes.++## 5. Connect and verify++```bash+export OV_CLIENT_CONF="${CONFIG_DIR}/${WORKSPACE_NAME}.ovcli.conf"+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace gen-conf "${WORKSPACE_NAME}" \+ --output "${OV_CLIENT_CONF}"+chmod 600 "${OV_CLIENT_CONF}"++ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check smoketest \+ --target openviking --p0 --openviking-conf "${OV_CLIENT_CONF}"+```++The generated configuration contains a Root API Key for initialization and administration. Application data access requires a User / Admin Key; the P0 smoke provisions a test User Key. Do not commit the client configuration or copy it into logs.++For an in-cluster client, use `gen-conf --endpoint-type service`. For an external client, supply a reachable entry point with `--endpoint '<openviking-endpoint>'`. Generating configuration does not create Ingress, TLS, or a load balancer. Add `--force` only after deciding to overwrite an existing output file.++Record all applicable acceptance results:++- Materials and running versions match; the deployment preview matches the target environment.+- `VikingDbCluster` is Ready for its current generation; License is Active when enabled.+- `OpenVikingWorkspace` is Ready when OpenViking is deployed.+- `doctor` passes; each delivered product passes its own P0 smoke.+- The application client can authenticate, import, read, and retrieve through its actual endpoint.++VikingDB P0 does not replace OpenViking P0. Running Pods do not replace these checks. These checks do not establish capacity, recoverability, or high availability.++## Bundled reference manuals++Under `viking-docs/`, consult `install.md` (entry point), `Viking部署手册.md` (full procedure), `ovadmin使用手册.md` (arguments), `Viking模型要求.md` (model templates), `基础组件配置要求.md` (dependency initialization), `版本兼容性说明.md` (compatibility), and `Viking升级说明.md` (upgrades). Continue with [upgrades and troubleshooting](21-private-operations.md).diff --git a/docs/en/guides/21-private-operations.md b/docs/en/guides/21-private-operations.mdnew file mode 100644index 000000000..bc44445a3--- /dev/null+++ b/docs/en/guides/21-private-operations.md@@ -0,0 +1,70 @@+---+description: Apply private-delivery configuration changes, prepare upgrades and rollback, and diagnose deployment failures.+---++# Enterprise Deployment: Upgrades and Troubleshooting++Use ovadmin and Operators to update configuration, upgrade, and troubleshoot your [Enterprise Deployment](20-private-deployment.md). For open-source container updates, see [server deployment](03-deployment.md); for OpenViking data-model migration, see the [migration guide](../migration/01-user-peer-model.md). Check delivery and runtime versions separately.++## Applying configuration changes++| Change | Source | Apply through |+| --- | --- | --- |+| Model endpoint, credentials, embedding configuration | Secret / ConfigMap Template | Re-render and roll the workspace |+| Workspace storage or vector backend | Workspace declaration and delivery configuration | `workspace update`; assess data migration first |+| VikingDB images, scheduling, observability | `vdb.yaml` / corresponding values | Preview, then `setup apply --module vikingdb` |+| Client endpoint | Endpoint selection during client configuration generation | Regenerate and verify caller connectivity |++After editing templates, use the actual namespace:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace restart "${WORKSPACE_NAME}" \+ --namespace vikingdb --yes --wait+```++This rolls workloads; schedule a change window. Do not maintain configuration by editing the generated Secret, Pod files, or Operator-managed Deployments. Plan index rebuilding before changing embedding semantics or dimensions.++## Upgrade checklist++1. **Record the baseline.** Preserve configuration, versions, CR status, workspace inventory, and license state. Resolve unhealthy or unlicensed states first.+2. **Establish recovery.** Back up workspace data, external dependency data, configuration, credentials, and license materials, with a restore procedure for each. A configuration copy is not a data backup. [OpenViking snapshots](15-snapshot.md) do not back up the entire external infrastructure.+3. **Check the release set.** Record `ovadmin version --output json` and `version --cluster`. Follow release notes for cross-`x.y` upgrades. Replacing an individual product image invalidates automatic reliance on the original release-set compatibility statement.+4. **Generate a candidate configuration.** Run the new delivery's `ovadmin init config` in a separate directory. Transfer confirmed namespaces, Registry, Secret references, StorageClass, scheduling, and resource values. Do not overwrite the current directory or copy old default images.+5. **Check and preview.** Run `check`, then `setup apply --dry-run` for each product being changed. Confirm image availability, dependencies, and licensing.+6. **Apply and verify.** Follow the bundled upgrade order, retain command output and events, and repeat CR Ready, License Active when enabled, doctor, and each product's P0 smoke. Validate application access afterwards.++New workspace configuration defaults requests and limits to 2 CPU / 4 GiB. Preserve approved workload sizing when preparing an upgrade; defaults do not replace a capacity plan.++If an upgrade fails, stop subsequent changes and retain failure state, previews, and events. Follow the prepared rollback procedure using the previous configuration, delivery materials, and data restore where required. **An image downgrade does not guarantee data compatibility.** Repeat acceptance after rollback; do not bypass the Operator by editing managed child resources.++## Observe before repairing++These commands inspect state. Set the configuration directory and replace cluster / workspace names:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" version --cluster+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" cluster get vikingdb+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace get "${WORKSPACE_NAME}"+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" doctor+kubectl -n vikingdb get pods,pvc,jobs,svc -o wide+kubectl -n vikingdb get events --sort-by=.lastTimestamp+```++| Symptom | Inspect first | Next action |+| --- | --- | --- |+| ImagePullBackOff / failed image check | Full prefix, delivery tag, image synchronization, per-namespace pull Secrets | Fix source configuration or synchronize images, then preview |+| Pod Pending | Labels, taints, resource requests, PVCs, node affinity | Use Pod / PVC events to distinguish scheduling from storage failures |+| PVC Pending / no StorageClass reported | Actual classes, kubeconfig context, RBAC for listing classes | Set the appropriate class explicitly; do not delete PVCs as a first response |+| License not Active | Fingerprint, expiry, system namespace, first CR synchronization | Follow the bundled licensing procedure and check status again |+| API Server fails after resources were submitted | Host-to-API network and API health | After recovery, inspect `cluster get` / `doctor` instead of reinstalling |+| Workspace Ready but import or retrieval fails | Model credentials, dimensions, API paths, limits, vector service, user key | Run OpenViking P0 and inspect the failed stage |+| Root Key works for administration but fails on data | Key type used by the application | Use a User / Admin Key |+| Model configuration did not change | Whether source templates were edited and re-rendered | Run `workspace restart`, then verify model requests |+| Internal access works but external access fails | Service DNS endpoint, Ingress / LB / TLS | Configure the external entry point and generate matching client configuration |++## Evidence for support++Provide delivery versions, timestamps, affected operations, CR conditions, relevant events, the failing doctor / P0 stage, and redacted configuration differences. Exclude kubeconfig credentials, model keys, Root/User keys, license files, full Secrets, and signed download links.++An enabled collector does not establish a working monitoring platform. The package requires VictoriaMetrics / Grafana to be prepared separately through the delivery plan. Verify metric ingestion, dashboards, alert delivery, and retention. Offline licensed environments also need renewal and telemetry return arrangements under their license policy.diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.mdindex 737eeaeca..459c5137d 100644--- a/docs/zh/guides/03-deployment.md+++ b/docs/zh/guides/03-deployment.md@@ -1,5 +1,7 @@# 服务端部署+准备自建环境前,先查看[部署前检查](19-deployment-checklist.md)。已取得 VikingDB / OpenViking 私有交付包的用户,请使用[企业私有化部署](20-private-deployment.md)及[升级与排障](21-private-operations.md)流程。+OpenViking 以 HTTP 服务运行。安装服务端之前,先选择由谁运行服务:| 服务方式 | 你需要准备什么 |@@ -399,12 +401,15 @@ docker compose up -d### Kubernetes + Helm-项目提供了 Helm chart,位于 `examples/k8s-helm/`:+这是开源服务的 Helm chart,与私有交付包的 ovadmin / Operator 流程不同。chart 参数见 [Helm README](https://github.com/volcengine/OpenViking/blob/main/deploy/helm/README.md)。++项目提供了 Helm chart,位于 `deploy/helm/openviking/`:```bash-helm install openviking ./examples/k8s-helm \- --set openviking.config.embedding.dense.api_key="YOUR_API_KEY" \- --set openviking.config.vlm.api_key="YOUR_API_KEY"+helm install openviking ./deploy/helm/openviking \+ --set-string config.server.root_api_key="YOUR_ROOT_API_KEY" \+ --set-string config.embedding.dense.api_key="YOUR_API_KEY" \+ --set-string config.vlm.api_key="YOUR_API_KEY"```详细的云上部署指南(包括火山引擎 TOS + VikingDB + 方舟配置)请参考 [云上部署指南](https://github.com/volcengine/OpenViking/blob/main/examples/cloud/GUIDE.md)。diff --git a/docs/zh/guides/19-deployment-checklist.md b/docs/zh/guides/19-deployment-checklist.mdnew file mode 100644index 000000000..1a66ad9b0--- /dev/null+++ b/docs/zh/guides/19-deployment-checklist.md@@ -0,0 +1,80 @@+---+description: 区分托管、自建和私有交付,准备集群、镜像、存储、模型与验收条件。+---++# 部署前检查++先确定服务方式,再准备环境。已有服务地址和 API Key 的用户,从 [CLI 快速开始](../getting-started/02-quickstart.md)连接即可。++| 你的目标 | 选择 | 下一步 |+| --- | --- | --- |+| 使用服务,由平台管理基础设施 | 火山引擎托管 OpenViking | [服务端部署中的托管入口](03-deployment.md) |+| 自己运行开源服务 | Python / Docker / 开源 Helm chart | [服务端部署](03-deployment.md) |+| 已取得 VikingDB / OpenViking 私有交付包 | Kubernetes、Operator 与 ovadmin | [企业私有化部署](20-private-deployment.md) |++私有交付的组件、授权和配置机制与开源服务不同。下文中标注“私有交付”的要求不适用于所有 OpenViking 安装。++## 所有自建环境都要确认++| 项目 | 部署前应有的答案 | 参考 |+| --- | --- | --- |+| 工作负载 | 文档数量与大小、向量维度、并发请求、导入频率、保留周期 | [可观测性](05-observability.md) |+| 模型服务 | provider、模型名、API Base、密钥、输出维度、限流与超时;从运行环境可访问 | [配置指南](01-configuration.md) |+| 存储 | workspace 的持久化位置、容量、权限、备份位置和恢复方式 | [存储架构](../concepts/05-storage.md)、[快照](15-snapshot.md) |+| 网络与身份 | 客户端入口、TLS、DNS、反向代理、管理员与业务用户密钥 | [公网访问](12-public-access.md)、[认证](04-authentication.md) |+| 运维责任 | 谁接收告警、执行升级、保管密钥和恢复数据 | [可观测性与排障](05-observability.md) |++资源配置需要用业务样本验证。容器启动成功、单次健康检查通过,都不足以证明容量满足要求。++## 私有交付:版本与环境++部署前核对下面的环境与版本要求,并以所用部署包的兼容矩阵确认组件组合。++| 项目 | 部署要求 | 需要核对 |+| --- | --- | --- |+| OS / CPU | Linux,默认 x86_64 | arm64 需有对应镜像和二进制 |+| Kubernetes | 兼容矩阵声明 1.24+ | 实际版本、CRD、CNI、CSI 与 RBAC;未声明最大兼容版本 |+| Helm / kubectl | Helm 3.x,不支持 Helm 4;kubectl 与集群差异不超过一个 minor | 在部署机核对工具版本 |+| profile | `standalone` 用于演示和复现;`cluster` 用于集群验证 | 按环境选择 profile,并验证副本、调度与故障恢复 |+| 版本组合 | ovadmin、VikingDB、OpenViking runtime、Operator 属于同一交付组合 | 记录 `ovadmin version --output json`;不能用包名推断 runtime 版本 |++随包文档给出的集群规划参考为至少 3 台机器,每台 32 核、256 GiB 内存、2 TiB 本地盘。**这不是开源 OpenViking 的最低配置,也不是已验证的容量承诺。** 是否适合你的环境取决于索引规模、向量维度、QPS、构建并发、副本和基础组件部署位置。将基础组件与业务混布的三节点形态,仅作为研发、演示或 POC 的起点。++## 私有交付:基础设施清单++| 范围 | 确认内容 |+| --- | --- |+| 权限 | 部署 kubeconfig;创建 CRD 和 RBAC 的权限;Operator 管理目标 namespace 的权限;按随包权限表申请 |+| Namespace | 业务与 Operator 的 namespace,默认示例分别为 `vikingdb`、`viking-system`;Secret 的作用域 |+| 调度 | `cluster` 默认使用 `nodeLevel=online` / `nodeLevel=offline`;实际节点标签、污点和资源能满足调度 |+| Registry | 完整仓库前缀、交付镜像 tag、拉取凭据;部署机登录与集群拉取分别验证 |+| 存储 | 可用 StorageClass;分别配置 VikingDB 数据盘、OpenViking workspace PVC 与外部基础组件存储 |+| 网络 | Pod / Service DNS、API Server、中间件与模型访问;集群 DNS 后缀;入口域名和 TLS |+| 授权 | 启用授权时准备当前集群 fingerprint 对应的授权文件;确认有效期、续期与离线遥测安排 |++不要直接沿用生成配置中的 `local-path`、磁盘容量或节点标签。OpenViking workspace 默认 requests / limits 均为 2 CPU / 4 GiB,这是配置默认值,需按负载核对。++`cluster` 交付依赖客户提供或按交付方案准备的基础组件:++| 组件 | 随包推荐版本 | 随包声明的最低版本 / 条件 |+| --- | --- | --- |+| MySQL | 8.0 | 5.7+ |+| Redis | 6.2.x | 未声明最低版本 |+| Kafka | 3.x | 3.0+ |+| ZooKeeper | 3.7.2 | 未声明最低版本 |+| HDFS | 3.3.x | 高可用形态 |+| HBase | 2.5.x | 依赖 HDFS 和 ZooKeeper |++这张表记录本次交付口径,不代表持续更新的兼容认证。连接可达后,还要按随包《基础组件配置要求》核对数据库、Topic、命名空间、目录、权限和初始化结果。外部依赖升级后需重新验收。++## 模型接入检查++- Embedding 必须返回固定维度的 dense vector。核对模型实际输出、`embedding.dense.dimension` 和向量库维度一致。+- 确认 API Base 是否包含 `/v1` 或 `/api/v3`。文本与多模态 Embedding 的接口、请求体可能不同,不能仅凭“OpenAI 兼容”判断可用。+- VLM / LLM 用于理解、摘要和记忆抽取。图片任务需验证图片输入,启用工具调用的 Agent 需验证 tool calls。+- 从实际 Pod 网络测试鉴权、DNS、证书和超时;本机能访问不代表 Pod 能访问。+- 已有数据更换 Embedding 模型时,即使维度相同,也要评估向量语义变化和重建索引方案。++私有交付中,`OpenVikingWorkspace.spec.vectordb.dimension` 会覆盖模板中的存储维度,但不会同步修改 `embedding.dense.dimension`。两处必须分别核对。++准备完成后进入[企业私有化部署](20-private-deployment.md)。日常维护见[升级与排障](21-private-operations.md)。diff --git a/docs/zh/guides/20-private-deployment.md b/docs/zh/guides/20-private-deployment.mdnew file mode 100644index 000000000..b02dd2f17--- /dev/null+++ b/docs/zh/guides/20-private-deployment.md@@ -0,0 +1,148 @@+---+description: 使用 Viking 私有交付包,从配置预览、VikingDB 部署到 OpenViking Workspace 与 P0 验收。+---++# 企业私有化部署++<p><VPButton text="联系我们获取部署物料" href="https://github.com/volcengine/OpenViking/blob/main/README_CN.md#%E5%95%86%E4%B8%9A%E7%89%88%E6%9C%AC" /></p>++通过部署物料,在自己的 Kubernetes 集群中安装 VikingDB 和 OpenViking。开始前,请先完成[部署前检查](19-deployment-checklist.md)。Python、Docker 和开源 Helm 安装见[服务端部署](03-deployment.md)。++## 1. 准备物料与配置目录++解压包后,核对 `bin/ovadmin`、`viking-docs/` 与交付清单。该 ZIP 包含 CLI 和文档,**不等于全部运行镜像已到位**。带有 `vikinglist` 时,可按清单下载其他物料;已同步镜像的环境不需要重复下载。++以下命令在目标部署机执行。替换所有占位值;`ovadmin` 与业务访问用的 `ov` CLI 是两个工具。++```bash+export VIKING_HOME=/opt/viking-deploy+export CONFIG_DIR=/opt/viking-deploy/conf+export PATH="${VIKING_HOME}/bin:${PATH}"++ovadmin version --output json++# 仅物料清单下载场景:先核对预览+ovadmin material download --listfile "${VIKING_HOME}/vikinglist" \+ --output-dir "${VIKING_HOME}/materials" --dry-run+```++确认下载范围后,移除 `--dry-run` 下载物料,再按随包手册导入客户 Registry。隔离环境还须准备镜像导入工具、基础组件、模型服务,以及授权续期和遥测回传方案;下载 ZIP 不意味着系统可以离线运行。++## 2. 生成并编辑配置++```bash+ovadmin init config \+ --dir "${CONFIG_DIR}" \+ --profile cluster \+ --image-registry '<registry.example.com/team/viking>' \+ --image-pull-secret viking-registry-secret \+ --openviking-storage-class '<storage-class-name>'+```++生成后,先编辑配置再部署:++| 文件或对象 | 管理内容 |+| --- | --- |+| `ovadmin.conf` | 集群访问、配置目录、OpenViking 镜像、workspace 资源与存储 |+| `vdb.yaml` | VikingDB 组件镜像、依赖引用、调度、存储与观测配置 |+| ConfigMap Template | OpenViking 基础运行配置 |+| Secret Template | 模型密钥及其他敏感配置,使用 `ov.conf.secret` |+| `OpenVikingWorkspace` | workspace 的声明,包括存储和向量库覆盖值 |+| 生成的 `*.ovcli.conf` | 客户端 endpoint 与 API Key,按凭据保管 |++完整镜像前缀必须含仓库路径。Operator 镜像名以交付清单为准,本版为 `vikingdb_operator` 和 `openviking_operator`,不要改成带连字符的名称。镜像 tag 使用交付组合,不从示例中抄旧值。++核对业务与 Operator namespace、外部依赖 Secret / ConfigMap、节点标签和 StorageClass。按随包《基础组件配置要求》完成依赖初始化。执行配置预检,并在配置所指定的 namespace 初始化拉镜像 Secret:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" init secret --all-namespaces+```++## 3. 部署 VikingDB++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module vikingdb --dir "${CONFIG_DIR}" --dry-run+```++核对预览中的 namespace、镜像、拉取 Secret、外部依赖、资源和调度。修正不一致项后再执行:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module vikingdb --dir "${CONFIG_DIR}" --yes+```++如启用 License,首次 apply 可能因等待授权 Active 而退出。导入前须已有 `VikingDbCluster` CRD、目标 CR,且 Operator 已完成首次状态同步。此时按随包授权流程导入与当前集群绑定的文件,再使用同一配置重跑 apply:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license import --file '<license.vlic>'+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license status+```++未启用授权时跳过授权步骤。确认 VikingDB Ready 后再继续:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" cluster get vikingdb+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" doctor+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check smoketest --target vdb --p0+```++如果集群名不是 `vikingdb`,替换为实际名称。Smoke 会创建测试对象并执行写入,应在约定的验收环境运行。++## 4. 部署 OpenViking 与 Workspace++如果只交付 VikingDB,跳过本节。准备好随包版本的 ConfigMap Template 和模型 Secret Template 后,预览并安装 OpenViking Operator:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module openviking --dir "${CONFIG_DIR}" --dry-run++# 核对预览后执行+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" setup apply \+ --module openviking --dir "${CONFIG_DIR}" --yes++export WORKSPACE_NAME='<workspace-name>'+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace create "${WORKSPACE_NAME}" \+ --namespace vikingdb \+ --image '<runtime-image-from-delivery-manifest>' \+ --conf-template '<configmap-template-name>' \+ --conf-secret '<secret-template-name>' \+ --wait++ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace get "${WORKSPACE_NAME}"+```++Operator 安装成功不会自动完成 workspace 创建。同名 workspace 已存在时,按随包手册使用 `workspace update`。++配置合并顺序为:ConfigMap Template → Secret Template → Workspace CR 的 `spec.vectordb` / `spec.storage` 覆盖。最终配置写入 `<workspace-name>-ov-conf` Secret 并挂载到 `/app/ov.conf`。修改源模板或 CR,不要直接编辑生成的 Secret 或 Pod 内文件。模板变更后的生效方式见[升级与排障](21-private-operations.md)。++## 5. 连接并验收++```bash+export OV_CLIENT_CONF="${CONFIG_DIR}/${WORKSPACE_NAME}.ovcli.conf"+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace gen-conf "${WORKSPACE_NAME}" \+ --output "${OV_CLIENT_CONF}"+chmod 600 "${OV_CLIENT_CONF}"++ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check smoketest \+ --target openviking --p0 --openviking-conf "${OV_CLIENT_CONF}"+```++生成配置内含 Root API Key,仅用于初始化与管理。业务数据访问需 User / Admin Key;P0 冒烟会 provision 测试 User Key。不要将客户端配置提交到代码库或贴入日志。++客户端在集群内可用 `gen-conf --endpoint-type service`。集群外需可访问的入口,可用 `--endpoint '<openviking-endpoint>'` 指定;生成配置不会替你创建 Ingress、TLS 或负载均衡。已存在的输出文件需确认后才加 `--force` 覆盖。++验收记录应包含以下结果:++- 本次物料与运行版本一致,配置预览符合目标环境。+- `VikingDbCluster` 当前 generation 为 Ready;启用授权时 License 为 Active。+- 部署 OpenViking 时,`OpenVikingWorkspace` 为 Ready。+- `doctor` 通过,VikingDB P0 与 OpenViking P0 按交付范围分别通过。+- 从业务客户端验证入口、鉴权、导入、读取和检索。++VikingDB P0 不能替代 OpenViking P0;Pod Running 不能替代上述验收。上述检查也不替代容量、恢复或高可用验证。++## 随包文档索引++在解压后的 `viking-docs/` 中查看:`install.md`(入口)、`Viking部署手册.md`(完整流程)、`ovadmin使用手册.md`(参数)、`Viking模型要求.md`(模型模板)、`基础组件配置要求.md`(初始化)、`版本兼容性说明.md`(兼容范围)、`Viking升级说明.md`(升级)。后续维护见[升级与排障](21-private-operations.md)。diff --git a/docs/zh/guides/21-private-operations.md b/docs/zh/guides/21-private-operations.mdnew file mode 100644index 000000000..bf58772c3--- /dev/null+++ b/docs/zh/guides/21-private-operations.md@@ -0,0 +1,70 @@+---+description: 私有交付的配置生效、升级验收、回滚准备和故障排查。+---++# 企业私有化部署:升级与排障++使用 ovadmin 和 Operator 维护[企业私有化部署](20-private-deployment.md),包括配置更新、版本升级和故障排查。开源服务的容器更新见[服务端部署](03-deployment.md),OpenViking 数据模型迁移见[迁移指南](../migration/01-user-peer-model.md)。交付包版本和 runtime 版本分别核对。++## 配置修改如何生效++| 修改内容 | 修改位置 | 生效路径 |+| --- | --- | --- |+| 模型地址、密钥、Embedding 配置 | Secret Template / ConfigMap Template | 重新渲染并滚动 workspace |+| workspace 存储与向量后端 | Workspace 声明及交付配置 | 按 `workspace update` 流程;先确认数据迁移影响 |+| VikingDB 镜像、调度、观测配置 | `vdb.yaml` / 对应 values | dry-run 后执行 `setup apply --module vikingdb` |+| 客户端入口 | 生成客户端配置时选择 endpoint | 重新生成并验证调用方的连接 |++模板更新后,在实际 namespace 执行:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace restart "${WORKSPACE_NAME}" \+ --namespace vikingdb --yes --wait+```++该命令会滚动工作负载,需安排变更窗口。不要修改生成的最终 Secret、Pod 文件或受 Operator 管理的 Deployment 来维持配置。替换 Embedding 模型或维度时,先确定索引重建方案。++## 升级检查单++1. **记录基线。** 保存当前配置目录、版本、CR 状态、workspace 清单和 License 状态。当前未 Ready 或授权异常时,先处理原因。+2. **确认恢复路径。** 备份 workspace 数据、外部依赖数据、配置、密钥和授权材料,并确认各自恢复步骤。配置副本不是数据备份;[OpenViking 快照](15-snapshot.md)也不能代替整套外部基础设施的备份。+3. **核对版本组合。** 记录 `ovadmin version --output json` 与 `version --cluster`。跨 `x.y` 升级按发布说明确认;单独替换某一产品镜像后,原交付组合的兼容结论不再自动成立。+4. **生成候选配置。** 在新目录运行本轮 `ovadmin init config`,迁移已确认的 namespace、Registry、Secret 引用、StorageClass、调度和资源值。不要覆盖当前配置目录或照搬旧版默认镜像。+5. **检查与预览。** 执行 `check`,分别对本次变更涉及的 VikingDB、OpenViking 执行 `setup apply --dry-run`;确认镜像已同步、依赖可达、授权匹配。+6. **执行与验收。** 按随包升级顺序变更,保留命令输出与事件。重复 CR Ready、License Active(如启用)、doctor 和各产品 P0 验收,再验证业务调用。++本轮默认 workspace requests / limits 均为 2 CPU / 4 GiB。升级候选配置要保留经过确认的资源规格,不能把默认值当成现有容量方案。++升级失败时暂停后续变更,保留失败状态、dry-run 与事件。依据预先确认的回滚方案,使用旧配置、旧交付物和必要的数据恢复。**降级镜像不保证恢复数据兼容性。** 回滚后重复完整验收,不直接编辑受管子资源绕开 Operator。++## 先收集状态,再修复++下面是读取状态的入口;替换配置目录、集群名与 workspace 名称:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" version --cluster+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" cluster get vikingdb+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" workspace get "${WORKSPACE_NAME}"+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" doctor+kubectl -n vikingdb get pods,pvc,jobs,svc -o wide+kubectl -n vikingdb get events --sort-by=.lastTimestamp+```++| 现象 | 优先检查 | 下一步 |+| --- | --- | --- |+| ImagePullBackOff / 镜像检查失败 | 完整前缀、交付 tag、仓库是否已同步、各 namespace 的拉取 Secret | 修正源配置或补齐镜像,再预览 |+| Pod Pending | 节点标签、污点、资源 requests、PVC 与节点亲和性 | 用 Pod / PVC 事件区分调度和存储问题 |+| PVC Pending / 无可用 StorageClass | 实际 StorageClass、kubeconfig context、列举存储类的 RBAC | 显式指定适用的存储类;不直接删除 PVC |+| License 非 Active | fingerprint、有效期、system namespace、CR 首次同步 | 按随包授权流程处理,再查状态 |+| API Server 访问失败,但已提交资源 | 部署机到 API Server 的网络与 API 状态 | 恢复后用 `cluster get` / `doctor` 查最终状态,不立即重装 |+| workspace Ready,但导入或检索失败 | 模型鉴权、维度、API 路径、限流、向量服务、用户 Key | 运行 OpenViking P0 并读取对应失败阶段 |+| Root Key 可管理但数据访问失败 | 是否把 Root Key 用于数据面 | 改用 User / Admin Key |+| 模型配置更新后未变化 | 修改的是否为源模板;是否重渲染 | 使用 `workspace restart`,重新验证模型请求 |+| 集群内可访问,外部不可访问 | 客户端 endpoint 是否为 Service DNS、Ingress / LB / TLS | 配好外部入口,再生成对应客户端配置 |++## 交付给支持人员的信息++提供交付版本、发生时间、受影响操作、CR 条件、相关事件、doctor 与 P0 的失败阶段,以及脱敏后的配置差异。不要上传 kubeconfig 凭据、模型密钥、Root/User Key、授权文件、完整 Secret 或带签名下载链接。++默认启用采集组件不等于监控平台已可用。本版随包说明中,VictoriaMetrics / Grafana 由交付方案单独准备。需确认指标接收、Dashboard 加载、告警接收与保留周期。离线授权环境还需按授权策略安排续期与遥测回传。