部署手册

文档版本：v1.5
最后更新：2026-06-26
适用范围：Kubernetes 集群部署、Helm 交付、服务启动验证

文档范围

本文档只覆盖爱印云打印平台部署到 Kubernetes 并能够正常打开管理后台的必要内容，包括 Chart 获取、values.yaml、ConfigMap、Secret、Ingress、证书、镜像、安装命令与基础健康检查。

进入系统后的业务初始化、系统参数、OSS、设备型号、文生图与 ASR 等后台配置，已拆分到：

服务组成

服务	职责	默认建议
Core	核心 API 服务，提供设备、打印、固件、权限、系统参数、内置 MQTT Bridge 等能力	必选
Front	管理后台前端服务	必选
ASR Gateway	`asr-go` 语音识别网关服务	按需
ASR Upstream	`funasr-mlt-gguf`、`funasr-sensevoice` 上游识别服务	启用 ASR 时需要
PostgreSQL	业务主数据库	生产建议外部高可用
Redis	缓存与热点数据	生产建议外部高可用
Kafka / Redpanda	消息队列	生产建议外部高可用
EMQX	MQTT Broker	可外部提供或 Chart 内置
Image Review	图片审核服务	文生图场景按需

生产环境优先采用外部中间件模式。测试或演示环境可以使用 Chart 内置 PostgreSQL、Redis、Redpanda、EMQX、ASR 与 Image Review。

部署前准备

Kubernetes 集群可用。
Helm 3 可用。
Ingress Controller 已部署，例如 NGINX Ingress。
Front、Core、ASR 域名已解析到 Ingress 入口。
TLS 证书已准备，可由 cert-manager 签发或手动创建 Secret。
镜像仓库拉取凭据已准备。
外部 PostgreSQL、Redis、Kafka、EMQX 网络访问已放通。
所有生产密钥已规划为 Kubernetes Secret 或等效密钥管理方式。

获取 Helm Chart

Chart 通过 OCI Registry 发布，示例版本为 0.3.0。实际部署时请使用交付版本号。

helm pull oci://money-cn-guangzhou.cr.volces.com/coogz/byteone-helm --version 0.3.0
helm show values oci://money-cn-guangzhou.cr.volces.com/coogz/byteone-helm --version 0.3.0

命名空间与基础 Secret

先创建命名空间：

kubectl create namespace byteone

生产密钥不要写入 Git。下面仅展示 Secret 结构，值需要替换成实际环境配置。

kubectl create secret generic byteone-env \
  --from-literal=DATABASE_URL='REPLACE_WITH_DATABASE_URL' \
  --from-literal=REDIS_PASSWORD='REPLACE_WITH_REDIS_PASSWORD' \
  --from-literal=JWT_SIGNING_KEY='REPLACE_WITH_JWT_SIGNING_KEY' \
  --from-literal=LICENSE_APP='REPLACE_WITH_LICENSE_APP' \
  --from-literal=LICENSE_SECRET='REPLACE_WITH_LICENSE_SECRET' \
  --from-literal=LICENSE_ACCESS='REPLACE_WITH_LICENSE_ACCESS' \
  --from-literal=EMQX_API_KEY='REPLACE_WITH_EMQX_API_KEY' \
  --from-literal=EMQX_API_SECRET='REPLACE_WITH_EMQX_API_SECRET' \
  --namespace byteone

如果镜像仓库需要认证：

kubectl create secret docker-registry byteone-image-pull \
  --docker-server=REGISTRY_HOST \
  --docker-username=REGISTRY_USERNAME \
  --docker-password=REGISTRY_PASSWORD \
  --namespace byteone

Core 配置文件

Core 配置通常通过 ConfigMap 挂载到容器内 /app/config/config.yaml 或交付 Chart 约定路径。以下模板只保留启动与依赖连接所需配置，部署后可进入系统基础配置完成业务参数初始化。

server:
  address: ":8000"
  clientMaxBodySize: "64MB"
  accessLogEnabled: true
  errorLogEnabled: true
  graceful: true
  gracefulTimeout: 60
  swaggerPath: "/swagger"
  openapiPath: "/api.json"

database:
  default:
    link: "pgsql:REPLACE_WITH_DB_USER:REPLACE_WITH_DB_PASSWORD@tcp(postgres:5432)/byteone?sslmode=disable"
    debug: false
    timezone: "UTC"
    maxIdle: 10
    maxOpen: 100
    maxLifetime: "30s"

redis:
  default:
    address: "redis:6379"
    db: 0
    pass: "REPLACE_WITH_REDIS_PASSWORD"
    maxIdle: 10
    maxActive: 100
    idleTimeout: "60s"

logger:
  path: "logs"
  level: "all"
  stdout: true

jwt:
  signingKey: "REPLACE_WITH_CORE_JWT_SIGNING_KEY"
  expire: 86400
  issuer: "byteone"

license:
  app: "REPLACE_WITH_LICENSE_APP"
  secret: "REPLACE_WITH_LICENSE_SECRET"
  access: "REPLACE_WITH_LICENSE_ACCESS"
  instance: "byteone-core-01"
  requiredFeatures:
    - "core"

kafka:
  brokers:
    - "redpanda:9092"
  clientId: "byteone-server"

emqx:
  management:
    baseUrl: "http://emqx:18083"
    apiKey: "REPLACE_WITH_EMQX_API_KEY"
    apiSecret: "REPLACE_WITH_EMQX_API_SECRET"
    timeout: 10

mqtt:
  enabled: true
  broker: "tcp://emqx:1883"
  clientVersion: "1.0"
  keepAlive: 60
  cleanSession: true
  qos: 1
  qosUp: 1
  qosDown: 1

ASR Gateway 配置文件

需要部署 ASR 时，ASR Gateway 配置通常挂载到 /app/manifest/config/config.yaml。

server:
  address: ":8250"
  dumpRouterMap: true

logger:
  path: "logs"
  level: "all"
  stdout: true

jwt:
  secret: "REPLACE_WITH_ASR_JWT_SECRET"
  expire: 3600

security:
  apiKey: "REPLACE_WITH_ASR_API_KEY"

database:
  default:
    link: "pgsql:REPLACE_WITH_DB_USER:REPLACE_WITH_DB_PASSWORD@tcp(postgres:5432)/byteone?sslmode=disable"
    debug: false

asr:
  hotwordCache:
    # 热词缓存仅使用进程内本地缓存，不依赖 Redis
    localExpireSeconds: 1800
  recording:
    # 全局录制开关；true 时默认录制所有会话
    globalEnabled: false
    defaultDealerId: "system"
    defaultOwnerId: "system"
    storage:
      providerType: "oss" # oss 或 s3
      basePath: "byteone"
      oss:
        endpoint: "oss-cn-xxxx.aliyuncs.com"
        region: "cn-xxxx"
        accessKeyId: "REPLACE_WITH_OSS_ACCESS_KEY_ID"
        accessKeySecret: "REPLACE_WITH_OSS_ACCESS_KEY_SECRET"
        bucket: "your-oss-bucket-name"
      s3:
        internalEndpoint: "s3.internal.example.com"
        externalEndpoint: "s3.amazonaws.com"
        region: "us-east-1"
        accessKeyId: "REPLACE_WITH_S3_ACCESS_KEY_ID"
        secretAccessKey: "REPLACE_WITH_S3_SECRET_ACCESS_KEY"
        bucket: "your-s3-bucket-name"
  models:
    # enabled=true 的模型才会对外暴露并允许客户端选择；upstream 是该模型内部连接的上游识别服务。
    - code: "Fun-ASR-MLT-Nano-GGUF"
      enabled: true
      modes: ["offline"]
      upstream:
        provider: "funasr"
        host: "funasr-mlt-gguf"
        port: 10095
        ssl: false
    - code: "SenseVoiceSmall"
      enabled: true
      modes: ["offline", "online", "2pass"]
      upstream:
        provider: "funasr"
        host: "funasr-sensevoice"
        port: 10097
        ssl: false
    - code: "MicrosoftAzureSpeech"
      enabled: false
      modes: ["offline", "online", "2pass"]
      upstream:
        provider: "microsoft"
        host: "eastus.stt.speech.microsoft.com"
        port: 443
        ssl: true
        region: "eastus"
        key: "REPLACE_WITH_AZURE_SPEECH_KEY"
        format: "detailed"
        profanity: "raw"
        audioContentType: "audio/wav; codecs=audio/pcm; samplerate=16000"
        sendWAVHeader: true

websocket:
  maxConnections: 1000
  timeout: 300
  audioSampleRate: 16000
  audioChunkSize: 8000

Front 运行时配置

Front 启动时通过环境变量生成 /usr/share/nginx/html/runtime-config.js，其中 BYTEONE_API_BASE_URL 必须指向 Core 对外访问地址。

app:
  front:
    env:
      - name: BYTEONE_API_BASE_URL
        value: https://byteone-core-api.example.com

基础 values.yaml

下面示例使用外部中间件，只部署 Core 与 Front。域名、镜像、Secret 名称请按实际环境替换。

ingress:
  enable: true
  className: nginx
  tls:
    - secretName: byteone-tls
      hosts:
        - byteone.example.com
        - byteone-core-api.example.com

app:
  core:
    enable: true
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-core-release:latest
    port: 8000
    imagePullSecrets:
      - name: byteone-image-pull
    env:
      - name: ENV_TYPE
        value: production
      - name: TZ
        value: Asia/Shanghai
    configMount: true
    mountPath: /app/config
    ingress:
      enable: true
      hosts:
        - byteone-core-api.example.com

  front:
    enable: true
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-front-release:latest
    port: 80
    imagePullSecrets:
      - name: byteone-image-pull
    env:
      - name: ENV_TYPE
        value: production
      - name: BYTEONE_API_BASE_URL
        value: https://byteone-core-api.example.com
    ingress:
      enable: true
      hosts:
        - byteone.example.com

postgresql:
  enabled: false
redis:
  enabled: false
redpanda:
  enabled: false
emqx:
  enabled: false
asr:
  enabled: false
imageReview:
  enabled: false

内置依赖示例

自包含环境可打开内置依赖，并为有状态服务配置存储类。

postgresql:
  enabled: true
  auth:
    username: byteone
    database: byteone
    existingSecret: byteone-postgresql
  primary:
    persistence:
      enabled: true
      storageClass: your-storage-class
      size: 20Gi

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
    existingSecret: byteone-redis
  master:
    persistence:
      enabled: true
      storageClass: your-storage-class
      size: 20Gi

redpanda:
  enabled: true
redpandaChart:
  statefulset:
    replicas: 1
  storage:
    persistentVolume:
      enabled: true
      storageClass: your-storage-class
      size: 20Gi

emqx:
  enabled: true
  replicaCount: 1
  persistence:
    enabled: true
    storageClass: your-storage-class
    size: 20Gi

TLS 证书

使用 cert-manager 时：

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: byteone-tls
  namespace: byteone
spec:
  secretName: byteone-tls
  dnsNames:
    - byteone.example.com
    - byteone-core-api.example.com
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

手动创建 TLS Secret 时：

kubectl create secret tls byteone-tls \
  --cert=fullchain.pem \
  --key=privkey.pem \
  --namespace byteone

渲染校验

安装前先渲染 Chart，确认 Ingress、Secret、ConfigMap、镜像与挂载路径符合预期。

helm template byteone \
  oci://money-cn-guangzhou.cr.volces.com/coogz/byteone-helm \
  --version 0.3.0 \
  --namespace byteone \
  -f values.yaml

重点检查：

检查项	要求
Ingress Host	Front、Core、ASR 域名与 TLS 配置一致
Secret 引用	Secret 名称与 key 存在
ConfigMap 挂载	Core、ASR 配置挂载到应用实际读取路径
镜像	镜像地址、tag、imagePullSecrets 正确
Service 端口	Core、Front、ASR 端口与 Ingress 后端一致

安装或升级

helm upgrade --install byteone \
  oci://money-cn-guangzhou.cr.volces.com/coogz/byteone-helm \
  --version 0.3.0 \
  --namespace byteone \
  --create-namespace \
  -f values.yaml

服务验证

查看资源：

kubectl get pods,svc,ingress -n byteone
kubectl logs deploy/byteone-core -n byteone

基础验收：

Core Pod、Front Pod 状态为 Running。
Front 域名可以打开登录页。
使用管理员账号可以登录后台。
Front 调用 Core API 无跨域或 502/504 错误。
Core 根路径或健康接口可访问。
如果启用 ASR，ASR Gateway 日志正常且 WebSocket 入口可访问。

常见问题

镜像拉取失败

检查节点是否能访问 Registry。
检查 imagePullSecrets 是否创建在 byteone 命名空间。
检查 values 中是否已挂载到对应服务。

Ingress 无法访问

检查 DNS 是否解析到 Ingress 入口。
检查 TLS Secret 是否与应用在同一命名空间。
检查 Host 是否与证书域名一致。
检查 Ingress Controller 是否正常。

Core 启动失败

检查 PostgreSQL 连接串与网络策略。
检查 Redis 密码字段，GoFrame 推荐使用 pass。
检查 License、JWT、EMQX 管理 API 等 Secret 是否注入。
使用 kubectl logs deploy/byteone-core -n byteone --previous 查看重启前日志。

Front 能打开但接口失败

检查 BYTEONE_API_BASE_URL 是否指向 Core 外部域名。
检查 Core Ingress 是否可访问。
检查浏览器控制台 CORS、401、502、504 错误。

部署完成后的下一步

服务正常打开后，按以下顺序完成后台初始化：

系统基础配置：配置系统参数、OSS/S3、ASR 地址、白名单等。
设备维护：维护设备型号、NN 号、设备档案、设备扩展配置。
文生图功能配置：配置 AI 图像引擎、LLM 模型、文生图业务与设备功能开关。