news 2026/9/30 9:41:12

Ever Gauzy 生产级 Kubernetes 部署指南：基于 kubeconfig 的集群部署、滚动更新与监控实战

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Ever Gauzy 生产级 Kubernetes 部署指南：基于 kubeconfig 的集群部署、滚动更新与监控实战
  • 后端
  • 前端
  • 企业应用
  • MCP 服务

【免费下载链接】ever-gauzy

Ever® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co

项目地址：https://gitcode.com/GitHub_Trending/ev/ever-gauzy
点击查看免费下载

本篇指南围绕 Ever Gauzy 官方 Kubernetes 部署方案展开，以仓库中的 .deploy/k8s/README.md 为操作主线，完整覆盖从 kubeconfig 连通性验证、kubectl apply部署、describe排障、rollout restart滚动重启，到基于 kube-prometheus-stack 的 Grafana / Prometheus 监控接入全过程。读完本文，你将掌握 Ever Gauzy（API、Web 前端、Worker 三组件）在 DigitalOcean Kubernetes 集群上的标准部署与运维方法，并能结合仓库内的生产级 Manifest 与 CI/CD 工作流完成环境变量注入和自动化发布。

前置准备：kubeconfig 与 Kubernetes Context

Ever Gauzy 的 K8s 部署约定以本地保存的 kubeconfig 文件 + 指定 context为核心工作方式。官方文档假设当前 kubeconfig 已保存为k8s-gauzy-kubeconfig.yaml：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" get nodes

同时，后续所有写操作命令都显式指定了 contextdo-sfo2-k8s-gauzy。该 context 需要在 kubeconfig 中预先定义好（例如通过doctl kubernetes cluster kubeconfig save --expiry-seconds 600 k8s-gauzy生成，参见 .github/workflows/deploy-do-prod.yml），它对应 DigitalOcean 位于sfo2区域、名为k8s-gauzy的托管集群。

说明：kubeconfig 通常包含集群证书、Token 等敏感信息，请勿提交到版本库；官方 CI 使用doctl生成**短期有效（600 秒）**的 kubeconfig，正是为了降低凭据泄露风险。

验证集群连通性

部署前先确认本地到集群的连通性，使用只读命令安全验证：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" get nodes

输出中应列出集群内各节点及其STATUS（应为Ready）、版本信息。如果该命令超时或报权限错误，说明 kubeconfig 路径、context 或集群证书配置有问题，需要先修复再进入部署阶段。

认识部署清单：k8s-manifest 家族与三组件架构

.deploy/k8s/目录下存放了整套官方部署清单，按环境与云厂商拆分：

文件适用环境/场景
.deploy/k8s/k8s-manifest.demo.yaml演示环境（DEMO=true，域名demo.gauzy.co/apidemo.gauzy.co）
.deploy/k8s/k8s-manifest.stage.yaml预发布（Stage）环境
.deploy/k8s/k8s-manifest.prod.yaml生产环境（app.gauzy.co/api.gauzy.co）
.deploy/k8s/k8s-manifest.civo.{demo,stage,prod}.yamlCivo 云托管集群
.deploy/k8s/k8s-manifest.cw.{demo,stage,prod}.yaml其他云厂商（CW）
.deploy/k8s/k8s-manifest.mcp.{demo,stage,prod}.yamlMCP Server 服务
.deploy/k8s/k8s-manifest.mcp-auth.{demo,stage,prod}.yamlMCP Auth 认证服务

README 中命令所用的k8s-manifest.yaml为占位名，实际使用时应替换为对应环境的真实清单文件（生产环境用k8s-manifest.prod.yaml）。以生产清单 .deploy/k8s/k8s-manifest.prod.yaml 为例，单文件内含三类资源，形成 Ever Gauzy 后端三组件的基础拓扑：

  • gauzy-prod-api（API 服务）：NestJS 后端，监听容器端口3000，生产环境副本数replicas: 2，资源请求cpu: 300m / memory: 896Mi，内存上限2048Mi；镜像为registry.digitalocean.com/ever/gauzy-api:latest。
  • gauzy-prod-webapp（Web 前端）：Angular 前端，监听容器端口4200，副本数replicas: 2，资源请求cpu: 50m / memory: 64Mi；镜像为registry.digitalocean.com/ever/gauzy-webapp:latest。
  • gauzy-prod-worker（后台 Worker）：队列与定时任务处理，副本数replicas: 1，内存上限2048Mi；镜像为registry.digitalocean.com/ever/gauzy-worker:latest。

每个组件都配置了SecurityContext：allowPrivilegeEscalation: false，并使用seccompProfile: RuntimeDefault，遵循容器安全基线。

Service 与 Ingress：南北向流量接入

清单为前后端各定义了一个ClusterIP类型 Service 与对应 Ingress：

  • Servicegauzy-prod-web-lb：port: 80→targetPort: 4200，Selector 匹配app: gauzy-prod-webapp；
  • Servicegauzy-prod-api-lb：port: 80→targetPort: 3000，Selector 匹配app: gauzy-prod-api。

Ingress 使用ingressClassName: nginx，并携带两个重要注解：

annotations: nginx.ingress.kubernetes.io/force-ssl-redirect: 'true' nginx.ingress.kubernetes.io/proxy-body-size: '20m'
  • force-ssl-redirect: 'true'强制 HTTP 请求 301 跳转到 HTTPS；
  • proxy-body-size: '20m'放宽 Nginx 默认的 1MB 请求体上限，允许上传较大的文件（如头像、附件、报告截图等）。

TLS 通过secretName引用 Kubernetes Secret（如app.gauzy.co-tls、api.gauzy.co-tls），证书内容由 CI 或运维预先生成注入（详见下文 CI/CD 一节）。

部署 Ever Gauzy 到集群

当 kubeconfig 与 context 就绪、清单文件确认无误后，执行部署：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" --context do-sfo2-k8s-gauzy apply -f k8s-manifest.yaml

apply采用声明式方式：如果资源尚不存在则创建，已存在则按清单做增量更新，便于反复执行而不产生冲突。生产环境实际执行时替换为：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" --context do-sfo2-k8s-gauzy apply -f .deploy/k8s/k8s-manifest.prod.yaml

查看部署状态

部署完成后，可通过describe命令检查 Deployment 的细节（镜像、副本、事件、滚动进度等）：

kubectl describe deployment --kubeconfig="k8s-gauzy-kubeconfig.yaml"

该命令会输出集群中所有 Deployment 的状态；如需聚焦某个组件，可追加 Deployment 名称，例如：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" describe deployment gauzy-prod-api

describe输出中的Events段是排障关键：镜像拉取失败（ErrImagePull）、探针失败（Unhealthy）等问题都会在这里留下记录。

滚动重启（Redeploy）

当使用latest镜像标签时，apply本身不会触发 Pod 重建（镜像引用未变化）。因此官方流程使用rollout restart强制滚动重启，让 Pod 拉取最新的latest镜像：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" --context do-sfo2-k8s-gauzy rollout restart -f k8s-manifest.yaml

rollout restart会依次为新旧副本做滚动替换，期间服务不中断；若指定单个 Deployment，可写成：

kubectl --context do-sfo2-k8s-gauzy rollout restart deployment/gauzy-prod-api

仓库的 CI 工作流在每次发布后正是通过类似命令让三个组件（gauzy-prod-api、gauzy-prod-webapp、gauzy-prod-worker）全部重启以拾取新镜像，参见 .github/workflows/deploy-do-prod.yml。

环境变量注入：从 Manifest 占位符到运行时配置

Ever Gauzy 后端是典型的配置驱动应用：数据库、Redis、JWT、邮件、对象存储、Sentry、GitHub OAuth 等全部通过环境变量注入。生产清单 .deploy/k8s/k8s-manifest.prod.yaml 中大量变量的取值是$DB_URI、$JWT_SECRET这类占位符，例如：

env: - name: DB_URI value: '$DB_URI' - name: DB_HOST value: '$DB_HOST' - name: JWT_SECRET value: '$JWT_SECRET' - name: EXPRESS_SESSION_SECRET value: '$EXPRESS_SESSION_SECRET' - name: REDIS_URL value: '$REDIS_URL'

这些占位符在应用前必须被真实值替换。官方 CI 的做法是在执行apply前用envsubst渲染整个清单：

envsubst < .deploy/k8s/k8s-manifest.prod.yaml | kubectl --context do-sfo2-k8s-gauzy apply -f -

envsubst会用当前 shell 环境中同名变量替换$VAR形式的占位符，而这些环境变量本身来自 GitHub Actions Secrets（参见 .github/workflows/deploy-do-prod.yml）。手工部署时请勿把真实密钥硬编码进清单——演示清单 .deploy/k8s/k8s-manifest.demo.yaml 中有一段安全注释明确指出：会话/JWT 等签名密钥绝不应写入公开仓库，应改为从 Secret Store 注入。

值得注意的几类核心变量及其作用：

  • 数据库：DB_TYPE（默认better-sqlite3，生产常用postgres）、DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASS、DB_URI、DB_SSL_MODE、DB_CA_CERT、DB_POOL_SIZE、DB_POOL_SIZE_KNEX；
  • Redis：REDIS_ENABLED、REDIS_URL、REDIS_HOST、REDIS_PORT、REDIS_USER、REDIS_PASSWORD、REDIS_TLS，用于队列与缓存；
  • 鉴权与会话：EXPRESS_SESSION_SECRET、JWT_SECRET、JWT_REFRESH_TOKEN_SECRET、JWT_VERIFICATION_TOKEN_SECRET、JWT_REFRESH_TOKEN_EXPIRATION_TIME；
  • 站点对外地址：API_BASE_URL（如https://api.gauzy.co）、CLIENT_BASE_URL（如https://app.gauzy.co）；
  • Worker 专属：WORKER_DEFAULT_QUEUE、WORKER_QUEUE_ENABLED、WORKER_SCHEDULER_ENABLED、WORKER_TIMEZONE。

其中部分变量在镜像内已带中性默认值（如API_HOST=api、API_PORT=3000、DEMO=false、DB_TYPE=better-sqlite3），真正涉及凭据的变量则刻意不在镜像层烘焙，必须由编排器（K8s Manifest / Compose env_file）注入，详见 .deploy/api/Dockerfile。

生产 CI/CD：GitHub Actions 全自动发布链路

官方仓库通过 GitHub Actions 实现"构建镜像 → 部署到 DO 集群"的完整链路，工作流 .github/workflows/deploy-do-prod.yml 展示了生产环境自动部署的四个关键步骤，同样适用于手工运维参考：

  1. 登录容器镜像仓库：doctl registry login --expiry-seconds 600，使用短期凭据拉取registry.digitalocean.com/ever/*镜像；
  2. 生成并保存集群凭据：doctl kubernetes cluster kubeconfig save --expiry-seconds 600 k8s-gauzy，等效于准备 README 中假设的 kubeconfig；
  3. 注入 TLS 证书：从 GitHub Secrets 解码INGRESS_WEBAPP_CERT/INGRESS_API_CERT等，执行kubectl create secret tls app.gauzy.co-tls ... | kubectl apply -f -，为 Ingress 提供 HTTPS 证书；
  4. 渲染并应用清单 + 滚动重启：envsubst替换占位符后apply，再对gauzy-prod-api、gauzy-prod-webapp、gauzy-prod-worker依次rollout restart。

该工作流还体现了生产发布的两个工程细节：通过concurrency合并排队中的发布且不中断正在进行的 apply（避免滚动更新中途被杀死导致集群处于半更新状态）；GITHUB_TOKEN使用最小权限（contents: read）。

集群监控：kube-prometheus-stack 接入 Grafana 与 Prometheus

官方推荐的监控方案是 DigitalOcean 的 Kubernetes Monitoring Stack（基于 kube-prometheus-stack）。部署完成后通过port-forward将监控面板暴露到本地：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" port-forward svc/kube-prometheus-stack-grafana 8090:80 -n kube-prometheus-stack

此时 Grafana 即可在 http://localhost:8090 访问。默认登录凭据：

  • 用户名：admin
  • 密码：prom-operator

安全提醒：登录后必须立即修改默认密码！该默认口令为监控栈的公共默认值，直接暴露在公网环境存在极大风险。

Prometheus 同样通过 port-forward 暴露：

kubectl --kubeconfig="k8s-gauzy-kubeconfig.yaml" port-forward svc/kube-prometheus-stack-prometheus 9090 -n kube-prometheus-stack

随后即可在 http://localhost:9090 打开 Prometheus 查询界面，验证指标抓取（Targets）状态并执行 PromQL 查询。port-forward适合日常排障和临时查看；长期暴露监控面板应改为 Ingress + 认证的正式方案。

多环境管理：Demo / Stage / Prod 一套清单多处复用

Ever Gauzy 的清单设计支持同一套资源模板在多个环境间复用，核心差异点集中在三处：

  1. 域名与 Ingress Host：Demo 用demo.gauzy.co/apidemo.gauzy.co，Prod 用app.gauzy.co/api.gauzy.co，Civo 环境则用appcivo.gauzy.co/apicivo.gauzy.co（见 .deploy/k8s/k8s-manifest.civo.prod.yaml）；
  2. DEMO环境变量：Demo 清单显式设置DEMO: 'true'并配合NODE_ENV: development，生产则为DEMO: 'false'+NODE_ENV: production；
  3. 副本数与资源配额：生产 API/Web 均为replicas: 2以保证可用性，Demo 通常为单副本以节省成本。

这种"同一 YAML 模板 + 环境差异化参数"的模式，配合envsubst渲染，使得从演示环境到生产环境的升级路径非常平滑——只需切换清单文件与注入不同的环境变量即可。

小结

Ever Gauzy 的 Kubernetes 部署体系可以归纳为一条清晰的运维链路：准备 kubeconfig →get nodes验证连通 →apply应用 Manifest →describe检查状态 →rollout restart滚动更新 → port-forward 接入 Grafana/Prometheus 监控。在此基础上，仓库提供了覆盖多环境、多厂商的现成清单（.deploy/k8s/），以及完整的 GitHub Actions 自动发布参考（.github/workflows/deploy-do-prod.yml），无论是手工运维还是流水线发布都能直接落地。实操时请始终牢记两条红线：敏感变量必须通过 Secret 注入而非硬编码进清单；Grafana 等监控组件使用默认口令时必须第一时间修改。

  • 后端
  • 前端
  • 企业应用
  • MCP 服务

【免费下载链接】ever-gauzy

Ever® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co

项目地址：https://gitcode.com/GitHub_Trending/ev/ever-gauzy
点击查看免费下载

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/30 9:41:09

AI内容工业化：把AI嵌入工作流实现高效变现

1. 这门课不是教你怎么“用AI”&#xff0c;而是帮你把AI变成能收钱的流水线我去年在杭州带一个本地生活类短视频团队&#xff0c;遇到个特别典型的场景&#xff1a;老板花三万块请了个“AI内容顾问”&#xff0c;结果三个月后剪辑组还在手动扒抖音热榜、文案组每天凌晨三点改脚…

作者头像 李华
网站建设 2026/9/30 9:36:36

森林火灾识别算法实战：基于YOLO的烟雾检测与告警闸门设计

简介&#xff1a;一份基于计算机视觉的森林火灾识别算法设计PDF&#xff0c;面向人工智能、计算机视觉方向的学习者与森林防火相关研发人员&#xff0c;系统梳理从图像获取、预处理、特征提取到机器学习分类与预警的完整流程。内容结合机器学习与图像处理技术&#xff0c;适合用…

作者头像 李华
网站建设 2026/9/30 9:36:35

Windows C++开发：MSVC与MinGW之争及VSCode配置实践

1. 为什么我在Windows上坚持用MSVC&#xff0c;而不是MinGW 很多初学C的朋友在Windows上装好VSCode之后&#xff0c;第一步就是去搜“MinGW怎么配”。确实&#xff0c;网上MinGW的教程一抓一大把&#xff0c;配置流程看起来也更简单——装个编译器&#xff0c;配一下环境变量&a…

作者头像 李华