Crest 文档
安装部署

Kubernetes 部署

使用 deploy/kubernetes 清单部署 Crest v1.5.7，支持前后端分离、内置 MySQL、外部 MySQL 和可选监控组件。

Crest 提供 Kustomize 清单，适合部署到 Kubernetes 集群。v1.5.7 的集群部署采用前后端分离结构：crest 是前端 Nginx 网关，crest-service 是后端 Spring Boot 服务，元数据库可选择内置 MySQL 或外部 MySQL。需要运行监控时，可启用 Prometheus 和 Grafana overlay。

Kubernetes 部署更适合已有集群和运维体系的团队。部署重点在于将命名空间、Secret、PVC、Service、Ingress、数据库、日志、备份和监控纳入统一管理。首次验证可以使用内置 MySQL，生产环境建议优先评估外部 MySQL。

集群部署完成后，应通过页面完成业务验证，而不能只依赖 Pod 状态判断。下面的工作台截图可作为第一轮页面验收参考：能登录、能加载菜单、能显示资源统计，说明前端网关、后端服务和元数据库已基本连通。

工作台

目录结构

deploy/kubernetes
├── base
│   ├── configmap-app.yaml
│   ├── configmap-nginx.yaml
│   ├── deployment.yaml
│   ├── kustomization.yaml
│   ├── pvc.yaml
│   ├── service.yaml
│   └── serviceaccount.yaml
├── internal-mysql
│   ├── kustomization.yaml
│   ├── mysql-init.sql
│   ├── mysql-my.cnf
│   ├── mysql.yaml
│   └── namespace.yaml
├── external-mysql
│   ├── kustomization.yaml
│   └── namespace.yaml
├── observability
│   ├── grafana
│   ├── prometheus
│   ├── kustomization.yaml
│   ├── networkpolicy.yaml
│   └── observability.yaml
├── internal-mysql-observability
│   ├── kustomization.yaml
│   └── observability-env-patch.yaml
└── external-mysql-observability
    ├── kustomization.yaml
    └── observability-env-patch.yaml

base 放应用公共配置，包含前端和后端两个 Deployment、两个 Service、PVC、ServiceAccount、后端配置和 Nginx 配置。internal-mysql 额外部署 MySQL StatefulSet；external-mysql 只部署 Crest，并通过 Secret 连接外部数据库。带 observability 后缀的 overlay 会额外部署 Prometheus、Grafana 和相关访问控制。

镜像与服务

默认应用镜像：

ghcr.io/sevoniva/crest-service:v1.5.7
ghcr.io/sevoniva/crest-web:v1.5.7

默认服务：

服务作用暴露方式
crest前端 Nginx 网关，提供页面、静态资源、API 转发和 WebSocket 转发ClusterIP，端口 8100
crest-service后端 Spring Boot 服务，提供接口、任务、OpenAPI 和指标端点ClusterIP，端口 8100
crest-mysql内置 MySQL 模式使用的元数据库仅集群内访问
crest-prometheus可选，抓取后端指标ClusterIP
crest-grafana可选，展示运行看板ClusterIP，按现场网关规范暴露

前端和后端容器均以非 root 用户运行，并启用只读根文件系统、禁止权限提升、丢弃 Linux capability 和 RuntimeDefault seccomp。生产环境如果使用内部镜像仓库，应先同步 crest-service、crest-web、MySQL、Prometheus 和 Grafana 镜像，再替换清单中的镜像地址。

健康检查

组件路径用途
前端网关/healthz判断 Nginx 进程和站点配置是否可用
后端存活/api/v1/actuator/health/liveness判断后端进程是否存活
后端就绪/api/v1/actuator/health/readiness校验数据库连接，适合流量接入前验证

readiness 依赖元数据库，数据库不可用时会返回失败。liveness 不访问数据库，避免数据库短暂抖动时误杀后端容器。

内置 MySQL 模式

适合快速验证和测试环境。先创建命名空间和 Secret：

kubectl create namespace crest-internal --dry-run=client -o yaml | kubectl apply -f -

kubectl -n crest-internal create secret generic crest-db-secret \
  --from-literal=CREST_DB_USERNAME=root \
  --from-literal=CREST_DB_PASSWORD='<strong-db-password>' \
  --from-literal=MYSQL_ROOT_PASSWORD='<strong-db-password>' \
  --from-literal=CREST_AES_KEY='<32-character-aes-key>' \
  --from-literal=CREST_AES_IV='<16-character-aes-iv>' \
  --from-literal=CREST_CRYPTO_MODE=standard \
  --from-literal=CREST_SM4_KEY='<16-character-sm4-key>' \
  --from-literal=CREST_INITIAL_PASSWORD='<initial-admin-password>' \
  --dry-run=client -o yaml | kubectl apply -f -

部署并等待服务就绪：

kubectl apply -k deploy/kubernetes/internal-mysql
kubectl -n crest-internal rollout status statefulset/crest-mysql --timeout=180s
kubectl -n crest-internal rollout status deployment/crest-service --timeout=300s
kubectl -n crest-internal rollout status deployment/crest --timeout=300s
kubectl -n crest-internal port-forward svc/crest 18100:8100

访问：

http://127.0.0.1:18100/index.html

管理员账号：

用户名：admin
密码：crest-db-secret 中 CREST_INITIAL_PASSWORD 的值

内置 MySQL 模式适合验证部署链路，不建议直接作为正式生产方案。使用前要确认 PVC 已绑定，MySQL Pod 重启后数据仍然存在。

外部 MySQL 模式

适合生产环境。先准备外部数据库：

CREATE DATABASE crest DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;

修改 deploy/kubernetes/external-mysql/kustomization.yaml 中的数据库地址、端口、库名和 JDBC 参数。然后创建命名空间和 Secret：

kubectl create namespace crest-external --dry-run=client -o yaml | kubectl apply -f -

kubectl -n crest-external create secret generic crest-db-secret \
  --from-literal=CREST_DB_USERNAME='<db-user>' \
  --from-literal=CREST_DB_PASSWORD='<db-password>' \
  --from-literal=CREST_AES_KEY='<32-character-aes-key>' \
  --from-literal=CREST_AES_IV='<16-character-aes-iv>' \
  --from-literal=CREST_CRYPTO_MODE=standard \
  --from-literal=CREST_SM4_KEY='<16-character-sm4-key>' \
  --from-literal=CREST_INITIAL_PASSWORD='<initial-admin-password>' \
  --dry-run=client -o yaml | kubectl apply -f -

部署并等待服务就绪：

kubectl apply -k deploy/kubernetes/external-mysql
kubectl -n crest-external rollout status deployment/crest-service --timeout=300s
kubectl -n crest-external rollout status deployment/crest --timeout=300s
kubectl -n crest-external port-forward svc/crest 18101:8100

外部 MySQL 模式上线前，要先由数据库负责人确认数据库、账号、备份、监控、网络白名单和 DNS 都已就绪。Crest Pod 启动失败时，优先检查 Secret、网络策略、数据库白名单和 DNS。

必须替换的 Secret

变量说明
CREST_DB_USERNAME元数据库账号
CREST_DB_PASSWORD元数据库密码
MYSQL_ROOT_PASSWORD内置 MySQL 模式需要
CREST_CRYPTO_MODE加密模式，默认 standard；需要国密时设为 sm-suite
CREST_AES_KEY32 位加密 Key
CREST_AES_IV16 位加密 IV
CREST_SM4_KEY国密 sm-suite 模式使用的 SM4 Key
CREST_INITIAL_PASSWORD管理员初始密码

生产密码不得提交到 Git 仓库。建议使用集群原生 Secret 管理方案或企业密钥管理系统。如果使用 GitOps 管理清单，建议只提交 Secret 模板或加密后的 Secret。

启用国密模式

需要 SM2、SM3、SM4 时，在所选 namespace 的 crest-db-secret 中设置：

CREST_CRYPTO_MODE=sm-suite
CREST_SM4_KEY=<16-character-sm4-key>

修改后重新应用对应 overlay，并等待后端和前端滚动完成：

kubectl apply -k deploy/kubernetes/external-mysql
kubectl -n crest-external rollout status deployment/crest-service --timeout=300s
kubectl -n crest-external rollout status deployment/crest --timeout=300s

国密模式只改变后端加密、签名和密钥保存方式，不改变用户页面操作。上线验收仍按登录、工作台、数据源、数据集、仪表盘、大屏、分享、导出和审计日志逐项验证。

SM4 Key 必须保持一致

CREST_CRYPTO_MODE=sm-suite 启用后，SM2 私钥和敏感配置会依赖 CREST_SM4_KEY 解密。升级、重启、扩容和恢复时必须使用同一个 SM4 Key。

启用监控组件

启用 Prometheus 和 Grafana 时，先创建 crest-observability-secret：

kubectl -n crest-internal create secret generic crest-observability-secret \
  --from-literal=CREST_PROMETHEUS_TOKEN='<prometheus-scrape-token>' \
  --from-literal=GF_SECURITY_ADMIN_PASSWORD='<grafana-admin-password>' \
  --dry-run=client -o yaml | kubectl apply -f -

内置 MySQL 模式：

kubectl apply -k deploy/kubernetes/internal-mysql-observability

外部 MySQL 模式：

kubectl apply -k deploy/kubernetes/external-mysql-observability

Grafana 默认是 ClusterIP 服务，按现场网关规范暴露。临时查看可使用：

kubectl -n crest-internal port-forward svc/crest-grafana 3000:3000

Prometheus 同样只在集群内访问：

kubectl -n crest-internal port-forward svc/crest-prometheus 9090:9090

指标、看板和告警规则说明见 监控与可观测性。

常用排查命令

kubectl get pods -n crest-internal
kubectl describe pod -n crest-internal <pod-name>
kubectl logs -n crest-internal deploy/crest-service --tail=200
kubectl logs -n crest-internal deploy/crest --tail=200
kubectl get svc -n crest-internal
kubectl get pvc -n crest-internal

排查顺序建议：

  1. kubectl get pods 看 Pod 是否 Running。
  2. kubectl describe pod 看调度、镜像拉取、挂载和探针。
  3. kubectl logs 优先查看后端 crest-service，再查看前端网关 crest。
  4. kubectl get svc 看 Service 端口。
  5. kubectl get ingress 看域名、证书和路径。
  6. 进入浏览器验证登录、工作台和系统管理。

集群上线检查

检查项说明
Pod 状态crest、crest-service 和 MySQL Pod 应为 Running
PVC数据卷应绑定成功
Secret不应保留占位值
Service前端 Service 指向网关，后端 Service 只供集群内访问
Ingress域名、证书和路径正确
健康检查/healthz、liveness 和 readiness 返回正常
日志没有数据库连接失败、Flyway 迁移失败和持续 5xx
监控启用后 Prometheus target 正常，Grafana 看板有数据

Kubernetes 环境中，备份、日志和监控通常由平台统一提供。上线前应确认 Crest 的 PVC、数据库、日志和监控都已纳入平台运维范围。

推荐发布流程

准备命名空间和密钥

创建专用命名空间，替换所有占位密码和密钥，确认 Secret 来源可靠。

部署到测试集群

先在测试集群执行 kubectl apply -k，确认 Pod、Service、PVC 和日志正常。

完成页面验证

登录 Crest，创建一个数据源、一个数据集和一个简单仪表盘，确认数据库迁移和文件目录正常。

配置 Ingress

绑定正式域名和 HTTPS 证书，检查反向代理头、上传大小、WebSocket 和访问路径。

接入日志和监控

确认应用日志、数据库日志、Prometheus 指标和 Grafana 看板进入现场运维体系。

切换生产流量

在变更窗口发布，观察应用日志、Pod 重启、数据库连接、接口错误率和用户登录反馈。

常见生产调整

调整项建议
副本数先确认应用、文件目录和会话策略是否支持，再分别调整 crest 和 crest-service
资源限制后端按查询量、导出量和并发访问设置 requests 与 limits；前端网关按静态资源和转发压力设置
Ingress固定域名、HTTPS、上传大小、WebSocket、超时时间和访问日志策略
日志采集同时采集前端网关、后端服务、MySQL 和监控组件日志
监控接入启用 Prometheus 指标后，确认 target、看板、告警规则和通知渠道
备份外部 MySQL 由数据库平台备份，PVC、上传目录、字体、导出文件和密钥也要纳入备份
网络策略保留后端和监控组件的内网访问边界，不直接暴露 crest-service 和 Prometheus

离线安装

制作 Crest 离线安装包，并在不能访问外网的服务器上完成部署。

外部 MySQL

在生产环境中为 Crest 准备外部 MySQL 数据库和连接配置。

本页目录

目录结构镜像与服务健康检查内置 MySQL 模式外部 MySQL 模式必须替换的 Secret启用国密模式启用监控组件常用排查命令集群上线检查推荐发布流程准备命名空间和密钥部署到测试集群完成页面验证配置 Ingress接入日志和监控切换生产流量常见生产调整