ByteOne 云打印 K8s 部署指南

包含哪些服务

ByteOne Helm Chart 默认只部署 ByteOne 自身服务。数据库、缓存、消息队列、 MQTT、ASR 和图片审核都可以按需打开，也可以继续使用外部服务。

服务	说明	默认状态
`core`	ByteOne 核心 API 服务	开启
`msgbridge`	消息桥接服务	开启
`front`	ByteOne 前端	开启
`postgresql`	内置 PostgreSQL	关闭
`redis`	内置 Redis	关闭
`redpanda`	Kafka 兼容消息队列	关闭
`emqx`	MQTT Broker	关闭
`asr`	语音识别服务	关闭
`imageReview`	图片审核服务	关闭

获取 Helm Chart

Chart 通过 OCI Registry 发布，当前示例版本为 0.2.4。

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

直接安装或升级时可以这样执行：

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

部署前准备

一个可用的 Kubernetes 集群。
Helm 3。
Ingress Controller，例如 NGINX Ingress。
域名 DNS，并解析到 Ingress 入口地址。
TLS 证书，可以由 cert-manager 签发，也可以手动创建 TLS Secret。
如果镜像仓库需要认证，提前创建 imagePullSecrets。
如果使用外部依赖，提前准备 PostgreSQL、Redis、Kafka、MQTT、ASR 和 Image Review 的连接信息。

基础 values.yaml

下面是一个最小化示例。域名和 Secret 名称都只是占位，请替换成你自己的值。

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

app:
  core:
    enable: true
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-core-release:latest
    ingress:
      enable: true
      hosts:
        - byteone-core-api.example.com
    env:
      - name: ENV_TYPE
        value: production
      - name: DATABASE_URL
        valueFrom:
          secretKeyRef:
            name: byteone-env
            key: DATABASE_URL

  msgbridge:
    enable: true
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-msgbridge-release:latest
    ingress:
      enable: true
      hosts:
        - byteone-msgbridge-api.example.com
    env:
      - name: ENV_TYPE
        value: production
      - name: MESSAGE_BROKER_URL
        valueFrom:
          secretKeyRef:
            name: byteone-env
            key: MESSAGE_BROKER_URL

  front:
    enable: true
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-front-release:latest
    ingress:
      enable: true
      hosts:
        - byteone.example.com

镜像仓库认证

如果 Registry 需要登录，先创建 docker-registry Secret：

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

然后在对应服务里引用：

app:
  core:
    imagePullSecrets:
      - name: byteone-image-pull
  msgbridge:
    imagePullSecrets:
      - name: byteone-image-pull
  front:
    imagePullSecrets:
      - name: byteone-image-pull

依赖模式

使用外部依赖

生产环境通常会使用已经存在的数据库和中间件。此时保持内置依赖关闭，通过 Secret 或配置文件注入外部连接地址。

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

kubectl create secret generic byteone-env \
  --from-literal=DATABASE_URL='REPLACE_WITH_DATABASE_URL' \
  --from-literal=MESSAGE_BROKER_URL='REPLACE_WITH_BROKER_URL' \
  --namespace byteone

使用内置依赖

如果要部署一套自包含环境，可以打开内置依赖，并为有状态服务配置存储。

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

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

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

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

镜像说明

ByteOne 自身服务默认使用 release 镜像：

crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-core-release:latest
crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-msgbridge-release:latest
crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-front-release:latest

ASR 和 Image Review 默认关闭，需要时可以这样打开：

asr:
  enabled: true
  app:
    asrGo:
      image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_asr-go:latest
    funasrOnline:
      image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_funasr-online:sha-058d029
    funasrSensevoice:
      image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_funasr-sensevoice:sha-058d029

imageReview:
  enabled: true
  image:
    repository: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_image-review
    tag: sha-42c50c7

国内镜像源

在中国大陆环境中，第三方镜像可以切换到更容易拉取的镜像源：

postgresql:
  image:
    registry: swr.cn-north-4.myhuaweicloud.com
    repository: ddn-k8s/docker.io/bitnami/postgresql
    tag: 17.6.0-debian-12-r4

redis:
  image:
    registry: swr.cn-north-4.myhuaweicloud.com
    repository: ddn-k8s/docker.io/bitnami/redis
    tag: 8.2.1-debian-12-r0

redpandaChart:
  image:
    repository: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/redpandadata/redpanda
    tag: v25.1.12

emqx:
  image:
    repository: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/emqx/emqx
    tag: 5.8.5

证书配置

Chart 不负责签发证书，只负责把 TLS Secret 挂到 Ingress 上。你可以使用 cert-manager 自动签发，也可以手动创建 TLS Secret。

使用 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
    - byteone-msgbridge-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

然后在 values 中引用这个 Secret：

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

安装和验证

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

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

如果只想检查渲染结果，可以先执行：

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

完整内置套件示例

下面是一份接近完整部署形态的示例：ByteOne 自身服务、PostgreSQL、Redis、 Redpanda、EMQX、ASR 和 Image Review 都由同一个 Chart 启动。示例保留了配置结构和服务连接方式，但域名、密码、Token、证书和 StorageClass 都需要替换。

先创建 Secret

Secret 的 key 名称需要与 values 中的引用保持一致。下面只使用占位值，请用你的密钥管理流程生成真实值。

kubectl create namespace byteone

kubectl create secret generic byteone-postgresql \
  --from-literal=password='REPLACE_WITH_POSTGRES_PASSWORD' \
  --namespace byteone

kubectl create secret generic byteone-redis \
  --from-literal=redis-password='REPLACE_WITH_REDIS_PASSWORD' \
  --namespace byteone

kubectl create secret generic byteone-env \
  --from-literal=POSTGRES_PASSWORD='REPLACE_WITH_POSTGRES_PASSWORD' \
  --from-literal=REDIS_PASSWORD='REPLACE_WITH_REDIS_PASSWORD' \
  --from-literal=IMAGE_REVIEW_MODEL_CACHE_TOKEN='REPLACE_WITH_OPTIONAL_TOKEN' \
  --namespace byteone

values-all-in-one.yaml

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

service:
  type: ClusterIP

serviceAccount:
  create: false
  automount: false

configMaps:
  core:
    config.yaml: |
      server:
        port: 8080
        host: "0.0.0.0"
      database:
        driver: pgsql
        host: byteone-postgresql
        port: 5432
        name: byteone
        user: byteone
        passwordEnv: POSTGRES_PASSWORD
        sslMode: disable
      redis:
        host: byteone-redis-master
        port: 6379
        passwordEnv: REDIS_PASSWORD
        database: 0
      kafka:
        brokers:
          - byteone-redpanda:9092
      mqtt:
        broker: tcp://byteone-emqx:1883
      asr:
        endpoint: http://byteone-asr-go:8250
      imageReview:
        endpoint: http://byteone-image-review:8624

  msgbridge:
    config.yaml: |
      broker:
        type: "redis"
        host: "byteone-redis-master"
        port: 6379
        passwordEnv: REDIS_PASSWORD
        database: 0
      messaging:
        queue_prefix: "byteone_msg_"
        retry_attempts: 3
        timeout: 30s
      database:
        host: "byteone-postgresql"
        port: 5432
        name: "byteone"
        user: "byteone"
        passwordEnv: POSTGRES_PASSWORD
        ssl_mode: "disable"
      kafka:
        brokers:
          - byteone-redpanda:9092
      mqtt:
        broker: tcp://byteone-emqx:1883

app:
  core:
    enable: true
    replicaCount: 1
    name: core
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-core-release:latest
    port: 8080
    env:
      - name: ENV_TYPE
        value: production
      - name: TZ
        value: Asia/Shanghai
      - name: POSTGRES_PASSWORD
        valueFrom:
          secretKeyRef:
            name: byteone-env
            key: POSTGRES_PASSWORD
      - name: REDIS_PASSWORD
        valueFrom:
          secretKeyRef:
            name: byteone-env
            key: REDIS_PASSWORD
    configMount: true
    mountPath: /app/manifest/config
    ingress:
      enable: true
      hosts:
        - byteone-core-api.example.com
    service:
      enable: false
    imagePullSecrets: []
    resources:
      requests:
        cpu: 250m
        memory: 512Mi
      limits:
        cpu: "1"
        memory: 1Gi

  msgbridge:
    enable: true
    replicaCount: 1
    name: msgbridge
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-msgbridge-release:latest
    port: 8080
    env:
      - name: ENV_TYPE
        value: production
      - name: TZ
        value: Asia/Shanghai
      - name: POSTGRES_PASSWORD
        valueFrom:
          secretKeyRef:
            name: byteone-env
            key: POSTGRES_PASSWORD
      - name: REDIS_PASSWORD
        valueFrom:
          secretKeyRef:
            name: byteone-env
            key: REDIS_PASSWORD
    configMount: true
    mountPath: /app/manifest/config
    ingress:
      enable: true
      hosts:
        - byteone-msgbridge-api.example.com
    service:
      enable: false
    imagePullSecrets: []
    resources:
      requests:
        cpu: 150m
        memory: 256Mi
      limits:
        cpu: 500m
        memory: 512Mi

  front:
    enable: true
    replicaCount: 1
    name: front
    image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_byteone-front-release:latest
    port: 80
    env:
      - name: ENV_TYPE
        value: production
      - name: API_BASE_URL
        value: https://byteone-core-api.example.com
    configMount: false
    ingress:
      enable: true
      hosts:
        - byteone.example.com
    service:
      enable: false
    imagePullSecrets: []
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 300m
        memory: 256Mi

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
      accessModes:
        - ReadWriteOnce
      size: 20Gi
  replica:
    replicaCount: 0

redpanda:
  enabled: true
redpandaChart:
  console:
    enabled: false
  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

asr:
  enabled: true
  ingress:
    enabled: true
    className: nginx
    annotations: 
    hosts:
      - host: asr.byteone.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: byteone-tls
        hosts:
          - asr.byteone.example.com
  configMaps:
    asrGo:
      config.yaml: |
        server:
          address: ":8250"
          dumpRouterMap: true
        logger:
          path: "logs"
          level: "all"
          stdout: true
        asr:
          defaultServiceType: "funasr"
          services:
            funasr:
              host: "asr-funasr-online"
              port: 10095
              ssl: false
            funasr-sensevoice:
              host: "asr-funasr-sensevoice"
              port: 10097
              ssl: false
  app:
    asrGo:
      enabled: true
      image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_asr-go:latest
      imagePullSecrets: []
    funasrOnline:
      enabled: true
      image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_funasr-online:sha-058d029
      imagePullSecrets: []
    funasrSensevoice:
      enabled: true
      image: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_funasr-sensevoice:sha-058d029
      imagePullSecrets: []

imageReview:
  enabled: true
  name: image-review
  replicaCount: 1
  image:
    repository: crpi-uhy920dintikwpn3.cn-shenzhen.personal.cr.aliyuncs.com/coohub/0xfe10_dynamic-actions_image-review
    tag: sha-42c50c7
    pullPolicy: IfNotPresent
  imagePullSecrets: []
  service:
    type: ClusterIP
    port: 8624
  env:
    - name: HOST
      value: "0.0.0.0"
    - name: PORT
      value: "8624"
    - name: ENABLE_CACHE
      value: "true"
    - name: MODEL_CACHE_TOKEN
      valueFrom:
        secretKeyRef:
          name: byteone-env
          key: IMAGE_REVIEW_MODEL_CACHE_TOKEN
          optional: true
  persistence:
    enabled: true
    storageClass: your-storage-class
    size: 10Gi
    mountPath: /.opennsfw2

常见问题

镜像拉取失败

先确认节点能访问对应 Registry。如果是私有仓库，检查 imagePullSecrets 是否创建在同一个 namespace，并且已经挂到对应服务。

Ingress 没有 HTTPS

确认 DNS 已解析到 Ingress 入口地址，TLS Secret 与应用在同一个 namespace，并且 ingress.tls.hosts 中包含实际访问域名。

Pod 一直重启

kubectl logs deploy/byteone-core -n byteone --previous
kubectl describe pod -n byteone -l app=byteone-core

如果日志里出现文件监听数量不足，可以在节点上调高 inotify 限制：

sudo sysctl -w fs.inotify.max_user_instances=1024
sudo sysctl -w fs.inotify.max_user_watches=1048576