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(deploy): add lessons from the v0.3.0 private deployment trial (#5457)
Zayn Jarvis3874aef98468
diff --git a/docs/en/guides/19-deployment-checklist.md b/docs/en/guides/19-deployment-checklist.mdindex 1c22bf160..f95f74b4e 100644--- a/docs/en/guides/19-deployment-checklist.md+++ b/docs/en/guides/19-deployment-checklist.md@@ -45,15 +45,22 @@ The package gives a cluster planning reference of at least three machines with 3| Area | Confirm || --- | --- || Permissions | Deployment kubeconfig; CRD and RBAC creation; Operator access to target namespaces; use the package permission matrix |+| Cluster exclusivity | One private delivery per Kubernetes cluster; see below || 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 |+| Registry | Full repository prefix, delivery tags, pull credentials; validate host login and cluster pulls separately; create repositories first if the Registry does not create them on push (for example Amazon ECR) || 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 |+| License | Offline: a license file matching the cluster fingerprint. Online: a one-time activation code and the HTTPS license endpoint, reachable from both the deployment host and the cluster. Confirm expiry, renewal, and 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 VikingDB defaults generated by the `cluster` profile assume the large machines described above; for example, `viking` defaults to 2 replicas at 16 CPU / 128 GiB each. Before deploying, add up `replicas × requests` for every component in `vdb.yaml` and compare the total with the allocatable capacity of the target node pools. `setup apply --dry-run` does not check capacity; an oversized plan only shows up after deployment as many `Pending` Pods.++**Cluster exclusivity.** The VikingDB / OpenViking CRDs are cluster-scoped, the VikingDB Operator watches all namespaces, the license webhook is always named `vikingdb-license-guard.openviking.ai`, and the Operator always reads licensing from the `viking-system` namespace. A second installation in the same cluster, even in a different application namespace, overwrites the CRDs, runs two Operators against the same resources, and competes for the webhook and license Secrets. Use separate clusters for separate environments.++**Impact on shared clusters.** The `managed-workload.openviking.ai` entry of the license webhook has no namespace selector. It validates updates and deletions of every Deployment, StatefulSet, and Job labeled `app.kubernetes.io/managed-by=Helm` in the cluster, with failure policy `Fail`. While the VikingDB Operator is unavailable, upgrades and deletions of other Helm applications in the cluster are rejected too. Assess this before sharing a cluster with other workloads, and include Operator availability in your operations scope.+The `cluster` delivery expects infrastructure supplied by the customer or prepared through the delivery plan:| Component | Package recommendation | Declared minimum / condition |@@ -67,6 +74,8 @@ The `cluster` delivery expects infrastructure supplied by the customer or preparThis 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.+The HDFS model directory (default `/home/vikingdb_data`) must be writable by the identity VikingDB runs as. fermat and other components run as `root` in their containers and do not set `HADOOP_USER_NAME`, so under simple authentication they reach HDFS as user `root`. When HDFS permission checks are enabled and `root` is not a superuser (for example, the Amazon EMR defaults), grant `root` write access to the directory; see [enterprise deployment](20-private-deployment.md#_2-generate-and-edit-configuration).+## Model integration checks- Embedding must return fixed-size dense vectors. Align actual output, `embedding.dense.dimension`, and vector database dimensions.diff --git a/docs/en/guides/20-private-deployment.md b/docs/en/guides/20-private-deployment.mdindex 55d77b03f..93dc30e99 100644--- a/docs/en/guides/20-private-deployment.md+++ b/docs/en/guides/20-private-deployment.md@@ -38,6 +38,30 @@ ovadmin material check-registry --listfile "${VIKING_HOME}/vikinglist" \Download URLs in `vikinglist` are signed and expire. If you get `HTTP 403`, ask the delivery team for a fresh list. If the deployment host cannot reach the URLs, download on a connected machine and copy the `repo` directory over. Without a Docker daemon, run `skopeo login` and add `--skopeo-bin "$(command -v skopeo)"` to `import-registry`. Tags that already exist in the Registry are skipped, so reruns are safe. Continue once `check-registry` reports no missing images.+When importing:++- If the Registry does not create repositories on push (for example Amazon ECR), list the target images with `import-registry --dry-run` and create each repository first.+- `--crane-bin` passes the `.tar.gz` files straight to `crane push`, which only accepts uncompressed tar and fails with `archive/tar: invalid tar header`. Use `--skopeo-bin`, or `gunzip` each file and push it with `crane push <file>.tar <target>`.+- `import-registry` stops the whole batch at the first failure. Fix the cause and rerun; tags already imported are skipped.++**Initialization images are not in `vikinglist`.** When dependencies are initialized by Flyway (option two in the bundled infrastructure requirements), the initialization Jobs reference the three images below by default. They are public Docker Hub images; copy them into the matching Registry paths yourself:++| Purpose | Default reference | Public source |+| --- | --- | --- |+| MySQL DDL | `${IMAGE_REGISTRY}/infra/apecloud/mysql:8.0.39` | `docker.io/apecloud/mysql:8.0.39` |+| Kafka topics | `${IMAGE_REGISTRY}/infra/apecloud/kafka:3.8.1-debian-12-r2` | `docker.io/apecloud/kafka:3.8.1-debian-12-r2` |+| HBase tables, HDFS directory | `${IMAGE_REGISTRY}/infra/apecloud/hbase-hmaster:v2.5.6-1.0.0` | `docker.io/apecloud/hbase-hmaster:v2.5.6-1.0.0` |++```bash+crane copy docker.io/apecloud/mysql:8.0.39 "${IMAGE_REGISTRY}/infra/apecloud/mysql:8.0.39"+crane copy docker.io/apecloud/kafka:3.8.1-debian-12-r2 "${IMAGE_REGISTRY}/infra/apecloud/kafka:3.8.1-debian-12-r2"+crane copy docker.io/apecloud/hbase-hmaster:v2.5.6-1.0.0 "${IMAGE_REGISTRY}/infra/apecloud/hbase-hmaster:v2.5.6-1.0.0"+```++To use your own client images, set their repository and tag under `spec.global.flywayInitImages` in `vdb.yaml`. The MySQL DDL ships inside ovadmin and runs from the Flyway Job; the package has no separate SQL files.++`setup apply --dry-run` checks every image in the Registry, so the full plan is only available after both application and initialization images are synchronized.+Isolated environments also need infrastructure dependencies, model services, and a license renewal / telemetry return plan. Having the images in place does not make the system fully offline-ready.## 2. Generate and edit configuration@@ -72,6 +96,26 @@ kubectl label node '<offline-node-name>' nodeLevel=offline --overwritekubectl get nodes -L nodeLevel```+Also add or change these items in the generated `vdb.yaml` to match your environment:++| Item | Why | What to do |+| --- | --- | --- |+| `spec.middleware.hdfs.configMapName` | `init config` does not generate it; without it, dry-run does not check the HDFS ConfigMap either | Add `hdfs: {configMapName: hadoop-config}`, matching the actual ConfigMap name |+| `spec.observability.oneAgent.enabled` | Defaults to `true` in the `cluster` profile, and one-agent writes into a `viking-infra` namespace; without the matching observability stack, apply fails with `namespaces "viking-infra" not found` | Set to `false` if the matching observability stack is not deployed |+| Component `replicas` and `resources` | Defaults assume large nodes and may exceed node pool capacity | Size to the allocatable capacity of your node pools; see the [deployment checklist](19-deployment-checklist.md) |+| `spec.tbase` scheduling | This release's Operator does not render `tolerations` under `spec.tbase` into tbase-api / tbase-scan, and direct Deployment edits are rejected by the license webhook | If dedicated nodes are tainted, use `spec.tbase.nodeSelector` to place tbase on untainted nodes with enough capacity |++When dedicated nodes are tainted, `tolerations` set per component in `vdb.yaml` take effect for the other components.++The HDFS model directory must be writable by `root` (see the [deployment checklist](19-deployment-checklist.md) for why). Flyway creates the directory as user `hadoop` with mode `755` by default, while fermat writes as `root` at runtime. After the directory exists, add an ACL as the HDFS administrator:++```bash+hdfs dfs -setfacl -R -m user:root:rwx,default:user:root:rwx,default:user:hadoop:rwx /home/vikingdb_data+hdfs dfs -getfacl /home/vikingdb_data+```++If HDFS ACLs are disabled, use `hdfs dfs -chown -R root /home/vikingdb_data` or another method that fits your policies. Without write access, VikingDB still reports Ready but indexes stay in `INIT`.+Then check namespaces, external Secret / ConfigMap references, and StorageClass. Complete dependency initialization using the bundled infrastructure requirements. Run preflight checks and initialize pull Secrets for namespaces configured in the delivery:```bash@@ -107,6 +151,19 @@ ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license statusThe `.vlic` must be issued from this cluster's `fingerprint.json`. A fingerprint from another cluster, or an edited file, fails verification.+With online licensing, no fingerprint or `.vlic` is needed. Likewise wait for the CR's first status sync, activate with the one-time activation code, and repeat apply with the same configuration:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license activate \+ --system-namespace viking-system \+ --code '<activation-code>' \+ --endpoint 'https://<license-endpoint>' \+ --yes+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license status vikingdb+```++An activation code can succeed only once; keep it out of configuration files, scripts, and logs. After activation, `license status` shows Mode `online`; the Operator handles renewal and telemetry, and stores the renewal credential in `viking-system/viking-license-renewal`. Offline and online licensing cannot be mixed. While waiting for a license, the CR reason always reads `provide offline .vlic via import secret`; in an online-licensed environment, activate as described here.+Skip licensing steps when licensing is disabled. Verify VikingDB before proceeding:```bash@@ -191,6 +248,14 @@ ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check smoketest \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.+The generated configuration stores the Root API Key in the `api_key` field. Recent `ov` CLI versions read `root_api_key` for `--sudo` administration commands, so first add a `root_api_key` field with the same value, then register an application user and write the returned User Key back into `api_key`:++```bash+ov admin register-user default '<user-id>' --sudo+```++Everyday `ov` commands then use the User Key; keep `root_api_key` for administration only.+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.The deployment is complete when all of the following hold:diff --git a/docs/en/guides/21-private-operations.md b/docs/en/guides/21-private-operations.mdindex 70bfa21e1..fe9fe763e 100644--- a/docs/en/guides/21-private-operations.md+++ b/docs/en/guides/21-private-operations.md@@ -56,13 +56,18 @@ kubectl -n vikingdb get events --sort-by=.lastTimestamp| 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 |+| License not Active | Fingerprint, expiry, system namespace, first CR synchronization; for online licensing, network and certificates from the cluster to the license service | Follow the bundled licensing procedure and check status again; for online licensing, `license renew <cluster-name> --yes` renews manually || `license checksum mismatch` | Whether the `.vlic` was issued for this cluster's fingerprint and left unmodified | Do not edit the file; request the original `.vlic` again using this cluster's `fingerprint.json` || 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 |+| VikingDB Ready, but indexes stay `INIT`; workspace `VectorDBReady` is `False` | `Permission denied: user=root` in `/var/log/tiger/hdfs_upload.log` in the fermat container | Grant `root` write access to the HDFS model directory (see [deployment](20-private-deployment.md#_2-generate-and-edit-configuration)); fermat retries the upload automatically. `slot ... resource not enough` messages in the meta logs are not necessarily the cause |+| Deployment edit rejected: `direct update is rejected ... managed by VikingDbCluster` | Whether a managed workload was edited directly | Edit `vdb.yaml`, then run `setup apply --module vikingdb` |+| tbase-api / tbase-scan `Pending` while other components run | Node taints; this release does not render `spec.tbase` `tolerations` | Use `spec.tbase.nodeSelector` to place them on untainted nodes |+| Apply fails with `namespaces "viking-infra" not found` | `spec.observability.oneAgent.enabled` | Set to `false` if the matching observability stack is not deployed |+| `open /tmp/openviking-operator-install.yaml: permission denied` | A file with the same name left by another user on the deployment host | Run `setup apply --module openviking` with `TMPDIR=<your-own-directory>` |## Evidence for supportdiff --git a/docs/zh/guides/19-deployment-checklist.md b/docs/zh/guides/19-deployment-checklist.mdindex 1a66ad9b0..f1821e227 100644--- a/docs/zh/guides/19-deployment-checklist.md+++ b/docs/zh/guides/19-deployment-checklist.md@@ -45,15 +45,22 @@ description: 区分托管、自建和私有交付,准备集群、镜像、存| 范围 | 确认内容 || --- | --- || 权限 | 部署 kubeconfig;创建 CRD 和 RBAC 的权限;Operator 管理目标 namespace 的权限;按随包权限表申请 |+| 集群独占 | 一个 Kubernetes 集群只装一套私有交付,见下文说明 || Namespace | 业务与 Operator 的 namespace,默认示例分别为 `vikingdb`、`viking-system`;Secret 的作用域 || 调度 | `cluster` 默认使用 `nodeLevel=online` / `nodeLevel=offline`;实际节点标签、污点和资源能满足调度 |-| Registry | 完整仓库前缀、交付镜像 tag、拉取凭据;部署机登录与集群拉取分别验证 |+| Registry | 完整仓库前缀、交付镜像 tag、拉取凭据;部署机登录与集群拉取分别验证;Registry 不会自动建仓库时(如 Amazon ECR)先建好仓库 || 存储 | 可用 StorageClass;分别配置 VikingDB 数据盘、OpenViking workspace PVC 与外部基础组件存储 || 网络 | Pod / Service DNS、API Server、中间件与模型访问;集群 DNS 后缀;入口域名和 TLS |-| 授权 | 启用授权时准备当前集群 fingerprint 对应的授权文件;确认有效期、续期与离线遥测安排 |+| 授权 | 离线授权:准备当前集群 fingerprint 对应的授权文件。在线授权:准备一次性 activation code 和授权服务 HTTPS 地址,部署机和集群都要能访问该地址。确认有效期、续期与遥测安排 |不要直接沿用生成配置中的 `local-path`、磁盘容量或节点标签。OpenViking workspace 默认 requests / limits 均为 2 CPU / 4 GiB,这是配置默认值,需按负载核对。+`cluster` profile 生成的 VikingDB 默认资源按上文三台大规格机器估算,例如 `viking` 默认 2 副本,每副本 16 CPU / 128 GiB。部署前把 `vdb.yaml` 里所有组件的 `replicas × requests` 加总,与目标节点池的可分配容量对比;`setup apply --dry-run` 不做容量校验,超出时只会在部署后表现为大量 Pod `Pending`。++**集群独占。** VikingDB / OpenViking 的 CRD 是集群级资源,VikingDB Operator 监听所有 namespace,授权 webhook `vikingdb-license-guard.openviking.ai` 名称固定,Operator 读取授权的 system namespace 固定为 `viking-system`。同一集群装第二套,即使业务 namespace 不同,也会覆盖 CRD、出现两个 Operator 同时处理同一资源,并争用 webhook 和授权 Secret。需要多套环境时使用不同的集群。++**共享集群的影响。** 授权 webhook 中的 `managed-workload.openviking.ai` 不限 namespace,校验集群内所有带 `app.kubernetes.io/managed-by=Helm` 标签的 Deployment、StatefulSet、Job 的更新和删除,失败策略为 `Fail`。VikingDB Operator 不可用时,集群里其他 Helm 应用的升级和删除也会被拒绝。与其他业务共用集群前,要评估这一影响,并把 Operator 的可用性纳入运维范围。+`cluster` 交付依赖客户提供或按交付方案准备的基础组件:| 组件 | 随包推荐版本 | 随包声明的最低版本 / 条件 |@@ -67,6 +74,8 @@ description: 区分托管、自建和私有交付,准备集群、镜像、存这张表记录本次交付口径,不代表持续更新的兼容认证。连接可达后,还要按随包《基础组件配置要求》核对数据库、Topic、命名空间、目录、权限和初始化结果。外部依赖升级后需重新验收。+HDFS 模型目录(默认 `/home/vikingdb_data`)要让 VikingDB 的运行身份可写。fermat 等组件在容器内以 `root` 运行,且不设置 `HADOOP_USER_NAME`,在 simple 认证下访问 HDFS 的用户就是 `root`。HDFS 开启权限检查且 `root` 不是超级用户时(如 Amazon EMR 默认配置),需给 `root` 授予该目录的写权限,做法见[企业私有化部署](20-private-deployment.md#_2-生成并编辑配置)。+## 模型接入检查- Embedding 必须返回固定维度的 dense vector。核对模型实际输出、`embedding.dense.dimension` 和向量库维度一致。diff --git a/docs/zh/guides/20-private-deployment.md b/docs/zh/guides/20-private-deployment.mdindex d68ccb830..41163c82e 100644--- a/docs/zh/guides/20-private-deployment.md+++ b/docs/zh/guides/20-private-deployment.md@@ -38,6 +38,30 @@ ovadmin material check-registry --listfile "${VIKING_HOME}/vikinglist" \`vikinglist` 里的下载地址带签名和有效期,返回 `HTTP 403` 时向交付方重新获取。部署机无法访问下载地址时,在联网机器下载后,把 `repo` 目录拷到部署机。部署机没有 Docker daemon 时,`skopeo login` 后给 `import-registry` 加 `--skopeo-bin "$(command -v skopeo)"`。Registry 中已有的同名 tag 默认跳过,可以放心重跑。`check-registry` 不再报告缺失镜像后继续。+导入时注意:++- Registry 不会自动建仓库时(如 Amazon ECR),先用 `import-registry --dry-run` 列出目标镜像,逐个创建仓库。+- `--crane-bin` 会把 `.tar.gz` 直接交给 `crane push`,而 crane 只接受未压缩的 tar,会报 `archive/tar: invalid tar header`。改用 `--skopeo-bin`,或先 `gunzip` 再用 `crane push <file>.tar <target>` 逐个推送。+- `import-registry` 遇到第一个失败就停止整批导入。修复原因后重跑即可,已导入的 tag 会跳过。++**初始化镜像不在 `vikinglist` 中。** 使用 Flyway 自动初始化基础组件(随包《基础组件配置要求》方式二)时,初始化 Job 默认引用下面三个镜像。它们是 Docker Hub 上的公开镜像,需要自行同步到 Registry 的对应路径:++| 用途 | 默认引用 | 公开来源 |+| --- | --- | --- |+| MySQL DDL | `${IMAGE_REGISTRY}/infra/apecloud/mysql:8.0.39` | `docker.io/apecloud/mysql:8.0.39` |+| Kafka Topic | `${IMAGE_REGISTRY}/infra/apecloud/kafka:3.8.1-debian-12-r2` | `docker.io/apecloud/kafka:3.8.1-debian-12-r2` |+| HBase 表、HDFS 目录 | `${IMAGE_REGISTRY}/infra/apecloud/hbase-hmaster:v2.5.6-1.0.0` | `docker.io/apecloud/hbase-hmaster:v2.5.6-1.0.0` |++```bash+crane copy docker.io/apecloud/mysql:8.0.39 "${IMAGE_REGISTRY}/infra/apecloud/mysql:8.0.39"+crane copy docker.io/apecloud/kafka:3.8.1-debian-12-r2 "${IMAGE_REGISTRY}/infra/apecloud/kafka:3.8.1-debian-12-r2"+crane copy docker.io/apecloud/hbase-hmaster:v2.5.6-1.0.0 "${IMAGE_REGISTRY}/infra/apecloud/hbase-hmaster:v2.5.6-1.0.0"+```++使用自备的客户端镜像时,在 `vdb.yaml` 的 `spec.global.flywayInitImages` 中配置 repository 和 tag。MySQL DDL 内置在 ovadmin 中,由 Flyway Job 执行,交付包里没有单独的 SQL 文件。++`setup apply --dry-run` 会逐个检查 Registry 中的镜像,业务镜像和初始化镜像都同步完成后才能预览完整计划。+隔离环境还要准备基础组件、模型服务,以及 License 续期和遥测回传方案;镜像到位不代表系统可以完全离线运行。## 2. 生成并编辑配置@@ -72,6 +96,26 @@ kubectl label node '<offline-node-name>' nodeLevel=offline --overwritekubectl get nodes -L nodeLevel```+生成的 `vdb.yaml` 还要按实际环境补充或修改下面几项:++| 项目 | 原因 | 做法 |+| --- | --- | --- |+| `spec.middleware.hdfs.configMapName` | `init config` 不生成此字段;缺少时 dry-run 也不会校验 HDFS ConfigMap | 手工加上 `hdfs: {configMapName: hadoop-config}`,名称与实际 ConfigMap 一致 |+| `spec.observability.oneAgent.enabled` | `cluster` profile 默认为 `true`,one-agent 的下游写入 `viking-infra` namespace;没有配套观测栈时 apply 报 `namespaces "viking-infra" not found` | 未部署配套观测栈时设为 `false` |+| 各组件 `replicas` 与 `resources` | 默认值按大规格节点估算,可能超出节点池容量 | 按节点池可分配容量调整,见[部署前检查](19-deployment-checklist.md) |+| `spec.tbase` 调度 | 本版 Operator 不把 `spec.tbase` 下的 `tolerations` 渲染到 tbase-api / tbase-scan;直接修改 Deployment 会被授权 webhook 拒绝 | 专用节点带污点时,用 `spec.tbase.nodeSelector` 把 tbase 调度到无污点、容量足够的节点 |++专用节点带污点时,其他组件在 `vdb.yaml` 中逐一配置 `tolerations` 即可生效。++HDFS 模型目录要让 `root` 可写(原因见[部署前检查](19-deployment-checklist.md))。Flyway 默认以 `hadoop` 用户创建目录并设为 `755`,运行时 fermat 以 `root` 写入。目录创建后,用 HDFS 管理员身份添加 ACL:++```bash+hdfs dfs -setfacl -R -m user:root:rwx,default:user:root:rwx,default:user:hadoop:rwx /home/vikingdb_data+hdfs dfs -getfacl /home/vikingdb_data+```++HDFS 未开启 ACL 时,改用 `hdfs dfs -chown -R root /home/vikingdb_data` 或其他符合客户规范的授权方式。缺少写权限时,VikingDB 仍会 Ready,但索引一直停在 `INIT`。+然后核对业务与 Operator namespace、外部依赖 Secret / ConfigMap 和 StorageClass。按随包《基础组件配置要求》完成依赖初始化。执行配置预检,并在配置所指定的 namespace 初始化拉镜像 Secret:```bash@@ -107,6 +151,19 @@ ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license status`.vlic` 必须由本集群的 `fingerprint.json` 签发,其他集群的指纹或改过的文件都会校验失败。+使用在线授权时,不需要 fingerprint 和 `.vlic`。同样等 CR 完成首次状态同步后,用一次性 activation code 激活,再用同一配置重跑 apply:++```bash+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license activate \+ --system-namespace viking-system \+ --code '<activation-code>' \+ --endpoint 'https://<license-endpoint>' \+ --yes+ovadmin -c "${CONFIG_DIR}/ovadmin.conf" license status vikingdb+```++activation code 只能成功使用一次,不要写入配置文件、脚本或日志。激活后 `license status` 的 Mode 为 `online`,续期和遥测由 Operator 自动完成,续期凭据保存在 `viking-system/viking-license-renewal`。离线和在线两种方式不能混用。等待授权时,CR 的原因文案固定为 `provide offline .vlic via import secret`,在线授权环境按本段激活即可。+未启用授权时跳过授权步骤。确认 VikingDB Ready 后再继续:```bash@@ -191,6 +248,14 @@ ovadmin -c "${CONFIG_DIR}/ovadmin.conf" check smoketest \生成配置内含 Root API Key,仅用于初始化与管理。业务数据访问需 User / Admin Key;P0 冒烟会 provision 测试 User Key。不要将客户端配置提交到代码库或贴入日志。+生成配置把 Root API Key 写在 `api_key` 字段。较新的 `ov` CLI 执行 `--sudo` 管理命令时读取 `root_api_key` 字段,因此先在客户端配置中加一个值相同的 `root_api_key`,再注册业务用户,并把返回的 User Key 写回 `api_key`:++```bash+ov admin register-user default '<user-id>' --sudo+```++之后日常的 `ov` 命令使用 User Key,`root_api_key` 只留给管理命令。+客户端在集群内可用 `gen-conf --endpoint-type service`。集群外需可访问的入口,可用 `--endpoint '<openviking-endpoint>'` 指定;生成配置不会替你创建 Ingress、TLS 或负载均衡。已存在的输出文件需确认后才加 `--force` 覆盖。以下条件全部满足即完成部署:diff --git a/docs/zh/guides/21-private-operations.md b/docs/zh/guides/21-private-operations.mdindex 0896fc9d9..e29f75629 100644--- a/docs/zh/guides/21-private-operations.md+++ b/docs/zh/guides/21-private-operations.md@@ -56,13 +56,18 @@ 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 首次同步 | 按随包授权流程处理,再查状态 |+| License 非 Active | fingerprint、有效期、system namespace、CR 首次同步;在线授权还要查集群到授权服务的网络和证书 | 按随包授权流程处理,再查状态;在线授权可用 `license renew <集群名> --yes` 手动续期 || `license checksum mismatch` | `.vlic` 是否由本集群 fingerprint 签发、文件是否被改动 | 不修改文件内容;用本集群 `fingerprint.json` 重新申请原始 `.vlic` || 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 | 配好外部入口,再生成对应客户端配置 |+| VikingDB Ready,但索引一直 `INIT`;workspace 的 `VectorDBReady` 为 `False` | fermat 容器 `/var/log/tiger/hdfs_upload.log` 中的 `Permission denied: user=root` | 给 `root` 授予 HDFS 模型目录写权限(见[部署文档](20-private-deployment.md#_2-生成并编辑配置)),fermat 会自动重试上传。meta 日志中同时出现的 `slot ... resource not enough` 不一定是原因 |+| 修改 Deployment 被拒绝:`direct update is rejected ... managed by VikingDbCluster` | 是否直接修改了受管工作负载 | 改 `vdb.yaml` 后执行 `setup apply --module vikingdb` |+| tbase-api / tbase-scan `Pending`,其他组件正常 | 节点污点;本版不渲染 `spec.tbase` 的 `tolerations` | 用 `spec.tbase.nodeSelector` 调度到无污点节点 |+| apply 报 `namespaces "viking-infra" not found` | `spec.observability.oneAgent.enabled` | 未部署配套观测栈时设为 `false` |+| `open /tmp/openviking-operator-install.yaml: permission denied` | 部署机上其他用户留下的同名文件 | 以 `TMPDIR=<自有目录>` 运行 `setup apply --module openviking` |## 交付给支持人员的信息