版本：2.x

企业版部署指南

企业版面向生产环境部署，基于 Kubernetes + Helm，提供高可用、外部数据库、正式 TLS 证书与动态凭据管理，适用于正式交付与规模化运维场景。

生产安装只需两步：① 把 values-production-template.yaml 复制为 my-values.yaml 并填好必填项；② 运行 install-production.sh。安装脚本会自动安装 cert-manager、生成服务密码 Secret、创建数据库 CA 证书 Secret 并执行 helm install，你只需填好 values 并在交互提示下输入几个密码。

前置要求

集群要求

项目	最低要求
Kubernetes 版本	1.24+
节点数	≥ 2（生产建议 ≥ 3）
CPU / 节点	≥ 8 核
内存 / 节点	≥ 16 GB
磁盘 / 节点	≥ 100 GB

必备工具

kubectl（匹配集群版本）、helm 3.8+、openssl、ctr（containerd CLI，用于离线镜像加载）。

离线模式下推荐额外安装 skopeo：脚本会自动检测并优先使用它直接推送镜像到私仓，跳过 containerd 中间步骤，显著提升导入效率；未安装则回退到 ctr。

外部依赖

PostgreSQL 12+（外部数据库，见外部数据库）
ReadWriteMany 共享存储（NFS / 阿里云 NAS / AWS EFS / Azure Files / 腾讯云 CFS，见存储）
TLS 证书：由 cert-manager 签发（安装脚本自动安装 cert-manager v1.13.0）

端口放通

端口	用途
443	HTTPS 访问
5432	PostgreSQL
2049	NFS（如使用 NFS）
6443	Kubernetes API

安装流程总览

准备集群/依赖  →  创建 my-values.yaml  →  准备外部数据库  →  准备存储  →  执行安装脚本

准备 values 文件

1. 复制模板

cd <安装包目录>      # 进入安装包根目录
cp values-production-template.yaml my-values.yaml

2. 镜像仓库配置（两种模式二选一）

镜像来源与是否需要认证由 global.registryAuth.enabled 决定：

	模式 A：真在线（默认推荐）	模式 B：离线 + 私仓
适用场景	集群可出公网，镜像在公有云公开仓库	离线/内网，或要把镜像推到自己的私仓
`global.itomImage.registry`	公有云地址，如 `swr.cn-east-3.myhuaweicloud.com`	私仓地址，如 `registry.example.com:5000`
`global.registryAuth.enabled`	`false`	`true`
`global.registryAuth.username`	留空	私仓用户名
`global.registryAuth.plainHttp`	`false`	HTTP 仓库设 `true`；HTTPS 私仓设 `false`
`global.imagePullSecrets`	`[]`（模板默认，无需改）	`[]`（脚本自动注入真实 secret）
离线镜像包	不需要、也不加载	需要（脚本自动探测 `${安装包}/images` 或经 `--product-tar` 传入）
安装时是否输入 registry 密码	否	是（或经 `--registry-password-stdin` 自动化传入）

模式 A（在线，免认证）关键片段：

global:
  itomImage:
    registry: &registry "swr.cn-east-3.myhuaweicloud.com"   # 华为云 SWR 公开仓库
    tag: "<实际版本号>"
  vendorImage:
    registry: *registry
  customizedImage:
    registry: *registry
  registryAuth:
    enabled: false     # 在线模式：免认证
  imagePullSecrets: [] # 在线不挂 pull secret

模式 B（离线 + 私仓）关键片段：

global:
  itomImage:
    registry: &registry "registry.example.com:5000"   # 你的私仓地址
    tag: "<实际版本号>"
  vendorImage:
    registry: *registry
  customizedImage:
    registry: *registry
  registryAuth:
    enabled: true            # 私仓/离线模式
    username: "user"         # 私仓用户名（密码安装时交互输入）
    plainHttp: true          # HTTP 仓库设 true；HTTPS 私仓设 false
  imagePullSecrets: []       # 留空，脚本自动注入真实 secret

镜像版本号从哪来

<实际版本号>（global.itomImage.tag）可从安装目录下 version.txt 的 IMAGE_TAG 字段获取。

3. 填写其余必填项

打开 my-values.yaml，搜索 TODO-SET-。模板使用 YAML 锚点，每个值只填一处，其余位置自动跟随（标 ★ 的为唯一填写处）：

值	唯一填写处（路径）	说明	示例
镜像版本	`global.itomImage.tag`	产品镜像 tag	使用实际版本号
访问域名 ★	`app.host`	FQDN，证书 CN/SAN 也用它	`cmdb.example.com`
访问路径前缀	`app.contextPath`	默认 `/itom`，可改为 `/` 或 `/cmdb`	`/itom`
外部 DB 主机 ★	`externalDatabase.host`	PostgreSQL 地址	`pg.internal`
外部 DB 端口	`externalDatabase.port`	PostgreSQL 端口	`5432`
外部 DB 用户名	`externalDatabase.user`	PostgreSQL 用户名	`itom_user`
DB CA 证书路径	`externalDatabase.ssl.caCertPath`	仅 verify-ca/verify-full 必填	`conf/certificates/db-ca.pem`

★ 两项：ingress.hosts / ingress.tls / env.HOST 自动跟随域名；env.POSTGRES_HOST 自动跟随 DB 主机。

域名与数据库关键片段示例：

app:
  host: &domain "cmdb.example.com"   # 唯一填写处
  contextPath: "/itom"               # 访问路径前缀，可改为 / 或 /cmdb
externalDatabase:
  enabled: true
  host: &dbhost "pg.external"        # 唯一填写处
  port: 5432
  user: "itom_user"
  ssl:
    mode: "verify-full"
    caCertPath: "conf/certificates/db-ca.pem"

自检

填完后执行 grep -n "TODO-SET-" my-values.yaml，应无任何输出。安装脚本也会校验，残留 TODO-SET- 会直接报错中止。

4. TLS 模式（二选一）

模式	适用场景	你要做什么
`selfSigned`（默认）	无自备 CA	什么都不用做，cert-manager 自签并自动续期
`userCA`	有企业内部 CA	把 `ca.crt` / `ca.key` 放到 `conf/certificates/`，设 `tls.mode: "userCA"`（脚本会导入到 cert-manager 作为 CA Issuer）

5. 高可用（可选）

生产模板已默认开启高可用：各业务服务 replicaCount: 2、keycloak/forwardauth/traefik replicas: 2、nats 集群 3 节点。如需更高可用可调大副本数，资源紧张可回调。

外部数据库

生产使用外部 PostgreSQL（模板已设 postgresql.enabled: false + externalDatabase.enabled: true）。

安装前在 PostgreSQL 中创建

一个用户 + 三个库。推荐库名 hyo_itom / hyo_proxy / hyo_keycloak（已在模板预填）；可自定义，但必须与下方 SQL 的库名及 my-values.yaml 保持一致：

-- 创建应用用户（密码须与安装时交互输入的数据库密码一致）
CREATE USER itom_user WITH PASSWORD 'your_strong_password';

-- 创建数据库并设置 OWNER（推荐：OWNER 自动拥有该数据库的完整权限，无需额外 GRANT）
CREATE DATABASE hyo_itom OWNER itom_user;
CREATE DATABASE hyo_proxy OWNER itom_user;
CREATE DATABASE hyo_keycloak OWNER itom_user;

-- ⚠️ 如果不想让 itom_user 成为 OWNER，需在每个数据库中单独授权 schema 和表权限：
-- \c hyo_itom
-- GRANT USAGE, CREATE ON SCHEMA public TO itom_user;
-- ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO itom_user;
-- ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO itom_user;
-- -- 如需访问已有表（迁移前由 superuser 创建的）：
-- GRANT ALL ON ALL TABLES IN SCHEMA public TO itom_user;
-- GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO itom_user;
-- （hyo_proxy / hyo_keycloak 同理，需逐个 \c 切换后执行）

要点：

externalDatabase.databases 三个库名已预填推荐值（与上方 SQL 一致）；如自定义库名，须同步修改 CREATE DATABASE 与 GRANT ... ON DATABASE 的库名。
数据库密码不写进文件：安装时交互输入（须与上面 SQL 里的密码一致）。
DB CA 证书：放到安装包内（如 conf/certificates/db-ca.pem）；仅当 ssl.mode 为 verify-ca 或 verify-full 时需要，disable/prefer 模式可省略。
确保 K8s 节点到 PostgreSQL 的 5432 端口已放通。

存储

生产多节点部署需要 ReadWriteMany 共享存储。存储通过 --storage-values overlay 指定，不写进 my-values.yaml。

NFS（默认）

编辑 examples/values-storage-nfs.yaml，改 NFS 地址与路径：

storage:
  nfs:
    server: "<nfs_server_ip>"        # 你的 NFS 服务器地址
    dataPath: "<nfs_data_path>"      # NFS 数据路径
    logsPath: "<nfs_logs_path>"      # NFS 日志路径

前提：NFS 服务器已导出对应路径（建议 no_root_squash）。nfs-subdir-external-provisioner 由安装脚本自动检测——若集群未安装，安装时自动安装（在线用产品 SWR 镜像，离线包已内置 chart 与镜像）；加 --skip-nfs-provisioner 可跳过。

云厂商共享存储

安装包内置多种云存储 overlay，按所用云厂商选用并填入对应参数：

Overlay 文件	平台
`examples/values-storage-alicloud-nas.yaml`	阿里云 ACK NAS
`examples/values-storage-aws-efs.yaml`	AWS EKS EFS
`examples/values-storage-azure-files.yaml`	Azure AKS Files
`examples/values-storage-tencent-cfs.yaml`	腾讯云 TKE CFS

阿里云 NAS 的两个 StorageClass（alicloud-nas-data / alicloud-nas-logs）由 Helm chart 在安装时自动创建（ACK 自带 CSI NAS Driver，无需另装 provisioner）。

验证 StorageClass

kubectl get sc

执行安装

./scripts/install-production.sh \
  -n itom-prod \
  -f my-values.yaml \
  --storage-values examples/values-storage-nfs.yaml

语言

安装脚本自动检测操作系统语言；可用 --lang en|zh 强制指定输出语言。

脚本会依次提示输入（每项都需两次确认、不能留空）：

在线模式（registryAuth.enabled=false）：① Keycloak 系统租户 sysadmin 密码（租户 100000000）；② Keycloak 默认租户 admin 密码（租户 100000001）；③ 外部数据库密码。
离线/私仓模式（registryAuth.enabled=true）：额外先输入 ① registry 密码（→ imagePullSecret），其余同上。

说明：

在线模式无 registry 密码提示（镜像公开拉取）。
Keycloak 密码需满足策略：至少 8 位，含大写 / 小写 / 数字 / 特殊字符。
Keycloak master admin 等其余内部服务密钥由脚本自动生成。
TLS 由 cert-manager 按 tls.mode 自动签发，无需输入任何证书。
若 AI 配置留空，脚本会警告 AI 功能不可用，交互模式下会询问是否继续（AI 为可选功能，确认后可继续安装）。

访问地址

安装完成后，通过浏览器访问（<webSecurePort> 对应 my-values.yaml 中的 app.webSecurePort，生产模板默认 31025；contextPath 默认 /itom）：

https://<app.host>:<webSecurePort><contextPath>/ui/100000001

如需把服务通过公网负载均衡暴露，可追加 --expose-values examples/values-expose-<云厂商>.yaml（支持阿里云 CLB / AWS NLB / Azure LB / 腾讯云 CLB）。

凭据管理

所有密码仅存于集群 K8s Secret，磁盘不留任何明文凭证文件。

Secret	存什么
`${RELEASE}-secrets`（默认 `itom-secrets`）	服务密码：Keycloak、数据库、加密密钥等
`${RELEASE}-registry-secret`（默认 `itom-registry-secret`）	镜像仓库凭证（仅离线/私仓模式）

交互输入过的密码你已知；自动生成的密码随时用下面命令从 Secret 取回（示例：数据库密码）：

kubectl get secret itom-secrets -n itom-prod -o jsonpath='{.data.postgres-password}' | base64 -d

${RELEASE}-secrets 常用 key 速查：

key	用途
`keycloak-admin-password`	Keycloak master realm 管理员（仅 Keycloak 运维用）
`keycloak-sysadmin-password`	系统租户 sysadmin 引导凭证
`keycloak-tenant-admin-password`	默认租户 admin 引导凭证
`keycloak-client-secret` / `keycloak-service-account-client-secret`	OAuth 客户端密钥
`postgres-password`	外部数据库密码
`forwardauth-cookie-secret` / `forwardauth-encryption-key`	Forwardauth 会话/加密密钥
`field-encryption-master-key`	字段加密主密钥（SM4，轮换会使已加密字段无法解密）
`csrfTokenSecret`	CSRF Token 签名密钥

AI 模型配置（可选）

AI 助手及 AI 驱动的运维能力需要 OpenAI 兼容的 LLM。三项均为启用 AI 的必填项，任一留空则 AI 功能关闭。

值	路径	说明
模型名	`services.aiAgent.env.ITOM_MODEL_NAME`	LLM 模型标识
Base URL	`services.aiAgent.env.ITOM_MODEL_BASE_URL`	OpenAI 兼容端点
API Key	`services.aiAgent.env.ITOM_MODEL_API_KEY`	LLM bearer 密钥（留空则关闭 AI）

在 my-values.yaml 中填写：

services:
  aiAgent:
    env:
      ITOM_MODEL_NAME: "GLM-5"
      ITOM_MODEL_BASE_URL: "https://open.bigmodel.cn/api/coding/paas/v4"
      ITOM_MODEL_API_KEY: "xx-xxxx"

或安装时通过 CLI 参数传入 --itom-model-name / --itom-model-base-url / --itom-model-api-key。辅助任务模型（ITOM_MEMORY_* / ITOM_ARTIFACT_* / ITOM_PII_LLM_*）为可选成本优化项，留空则回退主模型。事后启用 AI 可用 ./scripts/update-secret.sh ai-model（见修改密码）。

安装后验证

# Pod 状态（应全为 Running / Completed）
kubectl get pods -n itom-prod

# PVC 状态（应全为 Bound）
kubectl get pvc -n itom-prod

# 证书状态
kubectl get certificate -n itom-prod

# 访问（端口转发测试）
kubectl port-forward -n itom-prod svc/itom-cmdb-ui 8000:8000
# 浏览器打开：http://localhost:8000

升级与回滚

升级（保留现有密码）

日常升级（如换镜像版本）不要重跑 install-production.sh——它会重新生成服务密码。直接 helm upgrade 即可，集群中已有的 ${RELEASE}-secrets 会被复用：

# 1. 改 my-values.yaml（如更新 global.itomImage.tag）
# 2. 解压安装包内的 chart
tar xzf charts/itom-*.tgz -C /tmp
# 3. 升级（复用现有 Secret，不重新生成密码）
helm upgrade itom /tmp/itom -n itom-prod \
  -f my-values.yaml \
  -f examples/values-storage-nfs.yaml

提示

若确需轮换全部服务密码（如安全审计），再重跑 install-production.sh（会重建 ${RELEASE}-secrets）。

回滚

helm history itom -n itom-prod
helm rollback itom <REVISION> -n itom-prod

证书由 cert-manager 自动续期，无需手动操作。升级前建议备份数据库：pg_dump -h <host> -U <user> hyo_itom > hyo_itom_backup.sql。

修改密码

安装后可用 scripts/update-secret.sh 单独更新某个密码，无需重跑安装脚本。所有密码走交互输入或 stdin/环境变量，不进命令行参数。

# 通用形式
./scripts/update-secret.sh -n <namespace> [-r <release>] <子命令> [选项]

子命令	说明
`db-password`	改外部数据库密码。顺序很重要：先在 PostgreSQL 执行 `ALTER USER ... WITH PASSWORD ...`，再运行本命令更新 Secret 并自动滚动相关 Deployment（滚动期间有短暂连接中断）。
`registry-password`	重建 imagePullSecret，无需重启（新调度的 Pod 用新凭证拉镜像）。
`ai-model`	更新 AI 模型配置（用于事后启用/变更 AI）。

Keycloak 登录密码（sysadmin / tenant admin）的真实值存在 Keycloak 自己的数据库，Secret 里的对应 key 仅引导期用。事后改登录密码请走 Keycloak 管理台（master realm 管理员 → 对应 realm → Users → Credentials → Reset），不要改 Secret。

常见问题排查

现象	排查命令 / 原因
Pod `CrashLoopBackOff`	`kubectl logs <pod> -n itom-prod --previous`；常见原因：镜像未加载、DB 未就绪、资源不足
数据库连接失败	`kubectl exec deploy/itom-cmdb -n itom-prod -- sh -c 'PGPASSWORD=$POSTGRES_PASSWORD psql -h $POSTGRES_HOST -U $POSTGRES_USER -d $POSTGRES_DB -c "SELECT 1"'`；核对密码与 SSL 模式
PVC 一直 `Pending`	`kubectl describe pvc <name> -n itom-prod`；检查 StorageClass 是否存在、NFS provisioner 是否运行、NAS 挂载点 VPC 是否匹配
浏览器证书错误	`kubectl describe certificate itom-tls -n itom-prod` 看 Events；确认 `app.host` 域名解析正确
镜像拉取失败	检查 imagePullSecret 是否创建、registry 连通性、镜像是否已加载到所有节点
在线模式 Pod `ImagePullBackOff`	确认 `global.imagePullSecrets: []`（模板默认）、镜像在公有云为公开、节点可出网

更多排查：

kubectl describe pod <pod-name> -n itom-prod | grep -A5 Events
kubectl logs <pod-name> -n itom-prod --tail=100

下一步

安装完成后，您可以：

参考全局工具栏了解界面基本操作
参考导航菜单了解功能模块导航
开始使用快速开始指南进行首次配置

前置要求​

集群要求​

必备工具​

外部依赖​

端口放通​

安装流程总览​

准备 values 文件​

1. 复制模板​

2. 镜像仓库配置（两种模式二选一）​

3. 填写其余必填项​

4. TLS 模式（二选一）​

5. 高可用（可选）​

外部数据库​

安装前在 PostgreSQL 中创建​

存储​

NFS（默认）​

云厂商共享存储​

验证 StorageClass​

执行安装​

访问地址​

凭据管理​

AI 模型配置（可选）​

安装后验证​

升级与回滚​

升级（保留现有密码）​

回滚​

修改密码​

常见问题排查​

下一步​