Seatmap Helm chart 文档

概览

Seatmap Helm chart 部署 Editor、Booking 服务，以及 converter.enabled 为 true 时的转换器，同时包含 PostgreSQL 和 Redis 依赖。

Chart 版本：没有独立版本，使用所部署 Seatmap 版本的仓库标签，例如 1.74.0。
应用版本：镜像标签默认 latest。将每个镜像标签设为同一版本，确保 chart 与所有组件一致。

前提条件

Kubernetes 1.26+。
Helm 3.2.0+。
基础设施支持 PV 制备。
支持 LoadBalancer，供 Ingress 使用。

依赖

包含 Bitnami PostgreSQL 12.x.x 和 Redis 17.x.x。

安装

从单体仓库安装

Chart 位于 deployment/helm/seatmap/。检出目标版本标签，解析 Bitnami 依赖并安装：

git checkout ${SEATMAP_VERSION}
helm repo add bitnami https://charts.bitnami.com/bitnami
helm dependency update deployment/helm/seatmap

helm upgrade --install seatmap deployment/helm/seatmap \
  --create-namespace \
  --namespace seatmap \
  --set converter.enabled=true \
  --set global.hosts.editor=${EDITOR_HOST} \
  --set global.hosts.booking=${BOOKING_HOST} \
  --set-string editor.image.tag=${SEATMAP_VERSION} \
  --set-string editor.frontend.image.tag=${SEATMAP_VERSION} \
  --set-string booking.image.tag=${SEATMAP_VERSION} \
  --set-string booking.frontend.image.tag=${SEATMAP_VERSION} \
  --set-string converter.image.tag=${SEATMAP_VERSION} \
  --set global.s3.bucket=${S3_BUCKET} \
  --set global.s3.region=${S3_REGION} \
  --set global.s3.endpoint=${S3_ENDPOINT} \
  --set global.mail.host=${MAIL_HOST} \
  --set global.mail.fromAddress=${MAIL_FROM} \
  --set global.mail.port=${MAIL_PORT} \
  --set global.mail.strategy=${MAIL_STRATEGY} \
  --set-string secrets.s3.accessKey=${S3_ACCESS_KEY} \
  --set-string secrets.s3.secretKey=${S3_SECRET_KEY} \
  --set-string secrets.mail.username=${MAIL_USERNAME} \
  --set-string secrets.mail.password=${MAIL_PASSWORD} \
  --set-string secrets.google.apiKey=${GOOGLE_API_KEY} \
  --set imageCredentials.registry=${REGISTRY} \
  --set-string imageCredentials.username=${REGISTRY_USERNAME} \
  --set-string imageCredentials.password=${REGISTRY_PASSWORD}

本地测试

使用 kind 运行完整本地环境测试：

./deployment/helm/test-local.sh

配置

全局参数

主机配置

global:
  hosts:
    editor: editor.test-5.seatmap.dev
    booking: booking.test-5.seatmap.dev

镜像仓库

imageCredentials:
  registry: registry.gitlab.com
  username: seatmap
  password: <password>

资源配置

未设置 global.resources 时，Editor、Booking 和转换器容器没有 CPU 或内存请求及限制。default 应用于这三个服务，frontend 应用于两个前端。每个配置组都必须包含四个值。以下可作为起点：

global:
  resources:
    default:
      requests:
        cpu: '500m'
        memory: '2Gi'
      limits:
        cpu: '1000m'
        memory: '3Gi'
    frontend:
      requests:
        cpu: '100m'
        memory: '192Mi'
      limits:
        cpu: '1000m'
        memory: '512Mi'

Ingress 配置

Editor 和 Booking 使用不同主机名，各自配置 Ingress。

全局 Ingress 设置

global:
  ingress:
    className: public
    proxyBodySize: '50m'
    annotations:
      cert-manager.io/cluster-issuer: 'letsencrypt-prod'
  hosts:
    editor: editor.test-5.seatmap.dev
    booking: booking.test-5.seatmap.dev

Editor Ingress

在专用域名处理 Web 和 API 流量：

editor:
  ingress:
    enabled: true
    annotations: {} # Additional service-specific annotations
    apiPaths:
      - /api
      - /swagger-ui
      - /preview
      - /media
      - /ws
      - /webjars
      - /v3

特性：

主机为 editor.{domain}，例如 editor.test-5.seatmap.dev。
启用 TLS，使用基于主机名的证书。
根路径 / 路由到 Web 端口，API 路径路由到 API 端口。
支持 WebSocket。
可配置最大请求正文大小。

Booking Ingress

使用独立专用域名：

booking:
  ingress:
    enabled: true
    annotations: {} # Additional service-specific annotations
    apiPaths:
      - /api
      - /swagger-ui
      - /custom
      - /scalar
      - /scalar.html
      - /scalar-v1.html
      - /scalar-v2-booking.html
      - /scalar-v2-management.html
      - /webjars
      - /v3
      - /csrf
      - /oauth2
      - /login
      - /.well-known

特性：

主机为 booking.{domain}，例如 booking.test-5.seatmap.dev。
启用 TLS，使用基于主机名的证书。
根路径 / 路由到 Web 端口，API 路径路由到 API 端口。
支持 WebSocket。
与 Editor 共用代理正文大小配置。

通用 Ingress 特性

两者均包含 NGINX 正文大小限制注解、WebSocket 和 TLS；根路径使用 ImplementationSpecific 类型，API 端点使用 Prefix 类型。

组件配置

PostgreSQL

通过 postgresql-secret 管理身份验证。
默认数据库和用户名为 seatmap。
初始化 uuid-ossp 扩展。

postgresql:
  enabled: true
  auth:
    existingSecret: 'postgresql-secret'
    username: seatmap
    database: seatmap

Redis

单机架构。
通过 redis-secret 启用身份验证。
最大内存 512MB，淘汰策略 allkeys-lru。

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
    existingSecret: 'redis-secret'
  master:
    persistence:
      enabled: true
      size: 8Gi

容器镜像仓库

所有服务镜像托管于 GitLab Container Registry：

服务	镜像
Editor 后端	`registry.gitlab.com/seatmap.pro/seatmap/editor-service`
Editor 前端	`registry.gitlab.com/seatmap.pro/seatmap/editor-client`
Booking 后端	`registry.gitlab.com/seatmap.pro/seatmap/booking-service`
Booking 前端	`registry.gitlab.com/seatmap.pro/seatmap/booking-client`
转换器	`registry.gitlab.com/seatmap.pro/seatmap/converter-service`
知识库	`registry.gitlab.com/seatmap.pro/seatmap/knowledge-base`

镜像标签使用语义化版本，例如发布版 1.74.0，开发或预发布版 1.75.0-dev.18-939ed1ec。

服务组件

Editor 服务

editor:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/editor-service
    tag: '1.74.0'
  frontend:
    image:
      repository: registry.gitlab.com/seatmap.pro/seatmap/editor-client
      tag: '1.74.0'

主要配置包括 HikariCP 连接池、令牌过期、SSO 集成和 Ingress API 路径。

Booking 服务

booking:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/booking-service
    tag: '1.74.0'
  frontend:
    image:
      repository: registry.gitlab.com/seatmap.pro/seatmap/booking-client
      tag: '1.74.0'

包含 JPA/Hibernate、连接池、OAuth2 支持和 Actuator 端点配置。

转换器服务

converter:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/converter-service
    tag: '1.74.0'

converter:
  config:
    async:
      enabled: true
      cpuClaimDelayMs: 5000
    rateLimit:
      jobsMax: 5000
  gpu:
    enabled: false

行为：

仅 converter.enabled 为 true 时部署转换器，如上文安装命令。
converter.config.async.enabled 默认为 true，转换排入本 release 的 Redis；设 false 则在请求内渲染，不使用 Redis。
converter.gpu.enabled 添加优先领取排队任务的 GPU Pod，CPU Pod 处理剩余任务。
启用转换器后，chart 在 <release>-converter 生成共享密钥并连接到 Editor-service。转换器部署于独立 release 时，关闭 converter.enabled，将 editor.converter 指向其 URL，并在任一方升级前为双方设置相同 secrets.converter.apiKey。

限制与集成：最大内容 32MB，最大图片 15000×15000 像素，支持 S3 存储。

外部服务配置

S3 存储

global:
  s3:
    bucket: 'seatmap-storage'
    region: 'us-east-1'
    endpoint: 'https://s3.amazonaws.com'

邮件服务器

global:
  mail:
    host: 'smtp.example.com'
    port: 587
    strategy: 'SMTP_TLS'
    fromAddress: 'seatmap@example.com'

host 和 fromAddress 未设置时，不启用密码重置邮件。strategy 可为 SMTPS（隐式 TLS，通常 465）、SMTP_TLS（STARTTLS，通常 587），或 SMTP（服务器无 STARTTLS 时明文，仅适用于可信网络）；其他值会被 chart 拒绝。留空时，Editor 在 465 端口使用 SMTPS，其他端口使用 SMTP_TLS。无需登录的邮件服务器应将 secrets.mail.username 和 secrets.mail.password 留空。

安全注意事项

JWT 签名密钥

Editor 使用 {release}-rsa Secret 中的 RSA 密钥对签名。安装前和升级前 hook 创建 Secret，绝不覆盖已有值，因此升级后密钥保留，已签发令牌仍可验证。

升级时，hook 原样迁移已有密钥，不使令牌失效或用户退出。如果已有密钥数据为空，则拒绝迁移并使升级失败，避免静默生成新密钥使所有有效会话失效。

仅全新安装、没有旧密钥时才生成新密钥对。升级成功后可删除旧 ConfigMap，因为不再有组件读取它。

kubectl delete configmap {release}-rsa -n {namespace}

Secret 管理

需提供：PostgreSQL 凭据、Redis 密码、S3 访问凭据、需要登录时的邮件服务器凭据、Google API 密钥，以及转换器共享密钥（启用转换器时由 chart 生成，分离 release 则使用 secrets.converter.apiKey）。

网络安全

通过 Ingress 终止 TLS，集成 cert-manager 自动管理证书，服务分别提供 API 和 Web 端口。

扩缩容

Pod 水平自动扩缩容

各服务分别使用 editor.hpa.enabled、booking.hpa.enabled、converter.hpa.enabled，默认关闭。以下目标应用于三个服务：

global:
  hpa:
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 80

自动扩缩容基于容器 requests 计算利用率，因此启用前先设置 global.resources。

副本范围由 *.hpa.minReplicas 和 *.hpa.maxReplicas 控制：Editor 2–6，Booking 2–6，Converter 1–4。

监控与指标

Spring Boot 服务启用 Actuator 端点。
Redis 指标默认关闭。
Editor 与 Booking 配置自定义指标端点。

故障排查

常见问题

镜像拉取错误：验证仓库凭据，确认镜像标签存在。
数据库连接问题：确认 PostgreSQL Secret 存在，检查连接池配置。
存储问题：验证 S3 凭据和存储桶可访问性，检查配额及限制。

调试

查看日志：

kubectl logs -f deployment/seatmap-<component>

检查服务状态：

kubectl get pods -l app.kubernetes.io/instance=seatmap

配置变量参考

全局变量

参数	说明	默认值
`global.hosts.editor`	Editor 主机名	`editor.seatmap.dev`
`global.hosts.booking`	Booking 主机名	`booking.seatmap.dev`
`global.hosts.media`	启用 converter 和 converter ingress 时的转换器主机名	`media.seatmap.dev`
`global.resources.default.requests.cpu`	默认 CPU 请求	未设置
`global.resources.default.requests.memory`	默认内存请求	未设置
`global.resources.default.limits.cpu`	默认 CPU 限制	未设置
`global.resources.default.limits.memory`	默认内存限制	未设置
`global.resources.frontend.requests.cpu`	前端 CPU 请求	未设置
`global.resources.frontend.requests.memory`	前端内存请求	未设置
`global.resources.frontend.limits.cpu`	前端 CPU 限制	未设置
`global.resources.frontend.limits.memory`	前端内存限制	未设置
`global.bookingSessions.enabled`	是否提供预订会话端点	`true`

实例变量

参数	说明	默认值
`instance.environment`	声明部署环境：production、staging、development 或 unspecified，渲染时校验	未设置
`instance.heartbeatEnabled`	Editor-service 定期诊断签到	`true`

PostgreSQL 变量

参数	说明	默认值
`postgresql.enabled`	启用 PostgreSQL 部署	`true`
`postgresql.auth.existingSecret`	身份验证 Secret 名称	`postgresql-secret`
`postgresql.auth.username`	PostgreSQL 用户名	`seatmap`
`postgresql.auth.database`	PostgreSQL 数据库名称	`seatmap`
`global.postgresql.service.port`	PostgreSQL 服务端口	`5432`

Redis 变量

参数	说明	默认值
`redis.enabled`	启用 Redis 部署	`true`
`redis.architecture`	Redis 架构类型	`standalone`
`redis.auth.enabled`	启用 Redis 身份验证	`true`
`redis.auth.existingSecret`	身份验证 Secret 名称	`redis-secret`
`redis.master.persistence.enabled`	启用持久化	`true`
`redis.master.persistence.size`	持久化容量	`8Gi`
`global.redis.port`	Redis 服务端口	`6379`

Editor 服务变量

参数	说明	默认值
`editor.image.repository`	Editor 服务镜像仓库	`registry.gitlab.com/seatmap.pro/seatmap/editor-service`
`editor.image.tag`	Editor 服务镜像标签	`latest`
`editor.frontend.image.repository`	Editor 前端镜像仓库	`registry.gitlab.com/seatmap.pro/seatmap/editor-client`
`editor.frontend.image.tag`	Editor 前端镜像标签	`latest`
`editor.config.initial.delay`	初始延迟	`5000`
`editor.config.spring.datasource.hikari.connectionTimeout`	数据库连接超时	`60000`
`editor.config.spring.datasource.hikari.maximumPoolSize`	数据库连接池大小	`20`
`editor.config.spring.flyway.outOfOrder`	允许 Flyway 乱序迁移	`false`
`editor.hpa.minReplicas`	HPA 最小副本数	`2`
`editor.hpa.maxReplicas`	HPA 最大副本数	`6`

Booking 服务变量

参数	说明	默认值
`booking.image.repository`	Booking 服务镜像仓库	`registry.gitlab.com/seatmap.pro/seatmap/booking-service`
`booking.image.tag`	Booking 服务镜像标签	`latest`
`booking.frontend.image.repository`	Booking 前端镜像仓库	`registry.gitlab.com/seatmap.pro/seatmap/booking-client`
`booking.frontend.image.tag`	Booking 前端镜像标签	`latest`
`booking.config.spring.profiles.include`	Spring 激活的 profile	`prod`
`booking.config.spring.jpa.generateDdl`	启用 DDL 生成	`true`
`booking.config.spring.jpa.hibernate.ddlAuto`	Hibernate DDL 自动策略	`update`
`booking.config.seatmap.watermark.disabled`	禁用预订组件品牌标识	`false`
`booking.hpa.minReplicas`	HPA 最小副本数	`2`
`booking.hpa.maxReplicas`	HPA 最大副本数	`6`

转换器服务变量

参数	说明	默认值
`converter.enabled`	部署转换器服务	`false`
`converter.ingress.enabled`	通过 global.hosts.media 暴露转换器	`false`
`converter.image.repository`	转换器镜像仓库	`registry.gitlab.com/seatmap.pro/seatmap/converter-service`
`converter.image.tag`	转换器镜像标签	`latest`
`converter.config.max.contentLength`	最大内容长度	`33554432`
`converter.config.max.image.width`	最大图片宽度	`15000`
`converter.config.max.image.height`	最大图片高度	`15000`
`converter.hpa.minReplicas`	HPA 最小副本数	`1`
`converter.hpa.maxReplicas`	HPA 最大副本数	`4`
`converter.gpu.enabled`	在软件渲染部署外额外运行 GPU 加速部署	`false`
`converter.gpu.renderGroupId`	授予 GPU 转换器 Pod 的主机 render 组 ID	`109`
`converter.config.async.enabled`	在本 release Redis 中排队，false 则在请求内渲染	`true`
`converter.config.async.cpuClaimDelayMs`	GPU 先于 CPU 领取任务的时间，无 GPU Pod 时传 0	`5000`
`converter.config.rateLimit.jobsMax`	GET /jobs/{id} 每 IP 每分钟允许请求数	`5000`

外部服务变量

参数	说明	默认值
`secrets.s3.accessKey`	S3 访问密钥	`secrets.s3.accessKey`
`secrets.s3.secretKey`	S3 私密密钥	`secrets.s3.secretKey`
`secrets.mail.username`	邮件服务器用户名	`""`
`secrets.mail.password`	邮件服务器密码	`""`
`secrets.google.apiKey`	Google API 密钥	`secrets.google.apiKey`
`secrets.google.serverApiKey`	地址搜索的服务器端 Google 密钥，空时回退到 secrets.google.apiKey	`""`
`secrets.converter.apiKey`	转换器 bearer 令牌，空时按 release 生成并跨升级保留，分离 release 时需设置	`""`
`global.s3.bucket`	S3 存储桶名称	`seatmap-storage`
`global.s3.region`	S3 区域	`us-east-1`
`global.s3.endpoint`	S3 端点	`https://s3.amazonaws.com`
`global.mail.host`	邮件服务器主机	`""`
`global.mail.port`	邮件服务器端口	`587`
`global.mail.strategy`	邮件安全策略：SMTPS、SMTP_TLS 或 SMTP	`""`
`global.mail.fromAddress`	邮件发件地址	`""`

支持与维护

通过版本标签定期更新。
通过 Helm upgrade 修改配置。
管理 PostgreSQL 和 Redis 持久化存储。