跳转到内容
爱印开放文档

爱印云打印运维部署交付手册

文档版本：v1.3
编制日期：2026-05-27
适用范围：生产环境交付、部署实施、运行维护、变更管理

1. 文档范围

Section titled “1. 文档范围”

本文档用于规范爱印云打印平台在 Helm / Kubernetes 环境下的交付、部署、验收、升级、回滚与故障处置流程。

本文档中的配置路径均以容器内路径或 Helm 下发方式表述，不再使用代码仓库目录作为交付视角。

2. 系统概述

Section titled “2. 系统概述”

2.1 业务组件

Section titled “2.1 业务组件”
组件职责
Core核心业务服务，提供设备管理、打印任务、固件升级、权限与系统参数能力
MsgBridgeMQTT 与 Kafka 双向桥接服务，负责设备消息路由与命令转发
Front管理后台前端服务
ASR Gateway语音识别网关服务，提供 Token、模型查询与 WebSocket 识别入口

2.2 中间件组件

Section titled “2.2 中间件组件”
组件职责
PostgreSQL业务主数据库
Redis缓存与热点数据加速
Kafka 或 Redpanda消息队列
EMQXMQTT Broker

2.3 部署模式

Section titled “2.3 部署模式”
模式适用场景管控重点
外部中间件模式甲方已提供 PostgreSQL、Redis、Kafka、EMQX网络连通、账号权限、TLS、Secret 管理
内置中间件模式需要一体化交付环境存储持久化、资源配额、备份与高可用规划

生产环境优先采用外部中间件模式。

2.4 ASR 交付策略

Section titled “2.4 ASR 交付策略”
  • 默认识别后端：funasr-sensevoice-service
  • 可选识别后端：funasr-online
  • Core 对外统一使用 funasr 作为 ASR 服务类型，内部按模型配置路由

3. 配置交付基线

Section titled “3. 配置交付基线”

3.1 容器内配置路径与下发方式

Section titled “3.1 容器内配置路径与下发方式”
组件容器内路径 / 下发方式类型说明
Core/app/config/config.yaml文件挂载Core 主配置文件
MsgBridge/app/config/config.yaml文件挂载MsgBridge 主配置文件
ASR/app/manifest/config/config.yaml文件挂载ASR Gateway 主配置文件
Front/usr/share/nginx/html/runtime-config.js文件生成由容器启动时根据环境变量渲染
EMQX容器环境变量环境变量HTTP 认证、ACL、Dashboard 参数
Helmvalues.yamlHelm values镜像、Ingress、ConfigMap、Secret、资源配额入口

3.2 配置项分类

Section titled “3.2 配置项分类”
类别典型字段建议下发方式
数据库连接database.default.linkSecret 或受控配置文件
Redis 连接redis.default.address、redis.default.pass / redis.default.passwordSecret 或受控配置文件
Kafka / Redpanda 连接kafka.brokers、SASL/TLS 参数ConfigMap + Secret
JWT 密钥jwt.signingKey、jwt.secretSecret
License 参数license.app、license.secret、license.accessSecret
EMQX 管理凭据emqx.management.apiKey、emqx.management.apiSecretSecret
Front 运行时域名BYTEONE_API_BASE_URLHelm values / Env
ASR API Keysecurity.apiKey、asr.apiKeySecret

3.3 交付要求

Section titled “3.3 交付要求”
  1. 所有生产凭据均应通过 Kubernetes Secret 或等效密钥管理机制注入。
  2. 配置文件变更应纳入版本管理和变更审计。
  3. 交付文档、Helm values、ConfigMap、Secret 名称应保持一致。

4. 服务配置模板

Section titled “4. 服务配置模板”

以下模板用于交付编排。示例值仅用于说明字段结构，部署前必须替换为生产环境实际值。

4.1 Core 配置模板

Section titled “4.1 Core 配置模板”

配置文件路径：/app/config/config.yaml

# Core 服务监听与基础接口配置
server:
  address: ":8000"                    # Core HTTP 监听地址
  protectFileDir: "resource/protected" # 受保护文件目录
  clientMaxBodySize: "64MB"           # 客户端请求体上限
  accessLogEnabled: true              # 访问日志开关
  errorLogEnabled: true               # 错误日志开关
  pprofEnabled: true                  # 诊断接口开关
  logPath: "logs/server"              # 服务日志目录
  graceful: true                      # 优雅停机开关
  gracefulTimeout: 60                 # 优雅停机超时时间（秒）
  swaggerPath: "/swagger"             # Swagger 路径
  openapiPath: "/api.json"            # OpenAPI 描述路径


# PostgreSQL 连接配置
database:
  default:
    link: "pgsql:REPLACE_WITH_DB_USER:REPLACE_WITH_DB_PASSWORD@tcp(postgres:5432)/byteone?sslmode=disable" # 数据库连接串
    debug: false                       # 生产环境建议关闭 SQL 调试
    charset: "utf8"                    # 数据库字符集
    dryRun: false                      # 禁止仅模拟执行
    maxLifetime: "30s"                 # 连接生命周期
    timezone: "UTC"                    # 数据库时区
    maxIdle: 10                        # 空闲连接数
    maxOpen: 1000                      # 最大连接数


# Redis 连接配置
redis:
  default:
    address: "redis:6379"              # Redis 地址
    db: 0                              # Redis DB 编号
    pass: "REPLACE_WITH_REDIS_PASSWORD"     # Redis 密码，GoFrame 官方字段为 pass
    maxIdle: 10                        # 空闲连接数
    maxActive: 1000                    # 最大活动连接数
    idleTimeout: "60s"                 # 空闲超时
    maxConnLifetime: "60s"             # 连接生命周期


# 延迟任务队列并发配置
delayQueue:
  concurrency: 10                      # 延迟任务处理并发数


# 应用日志策略
logger:
  path: "logs"                         # 日志输出目录
  level: "all"                         # 日志级别
  stdout: true                         # 是否输出到标准输出
  rotateExpire: "1d"                   # 单日志文件轮转周期
  rotateBackupLimit: 30                # 最大保留文件数
  rotateBackupExpire: "30d"            # 备份保留时间
  rotateCheckInterval: "1h"            # 轮转检查间隔


# JWT 认证配置
jwt:
  signingKey: "REPLACE_WITH_CORE_JWT_SIGNING_KEY" # JWT 签名密钥
  expire: 86400                                   # Token 有效期（秒）
  issuer: "byteone"                               # Token 签发者


# License 在线授权配置
license:
  app: "REPLACE_WITH_LICENSE_APP"                 # 授权应用标识
  secret: "REPLACE_WITH_LICENSE_SECRET"           # 授权密钥
  access: "REPLACE_WITH_LICENSE_ACCESS"           # 授权访问令牌
  instance: "byteone-core-01"                     # 实例唯一标识
  requiredFeatures:
    - "core"                                      # 必需授权特性


# Casbin 模型文件路径
casbin:
  modelFile: "manifest/config/rbac_model.conf"    # 权限模型文件


# Kafka / Redpanda 连接与消费配置
kafka:
  brokers:
    - "redpanda:9092"                             # Broker 列表
  version: "3.6.0"                                # Kafka 协议版本
  clientId: "byteone-server"                      # 客户端标识
  tls:
    enabled: false                                # 是否启用 TLS
    insecureSkipVerify: false                     # 生产环境不应跳过证书校验
  username: ""                                    # SASL 用户名
  password: ""                                    # SASL 密码
  mechanism: "PLAIN"                              # SASL 机制
  producer:
    retryMax: 3                                   # 发送重试次数
    timeout: "10s"                                # 发送超时
    acks: "all"                                   # 应答策略
    compression: "snappy"                         # 压缩算法
  consumer:
    groupId: "byteone-core-group"                 # 消费组
    sessionTimeout: "30s"                         # 会话超时
    heartbeatInterval: "3s"                       # 心跳间隔
    minBytes: 1                                   # 最小拉取字节数
    maxBytes: 10485760                            # 最大拉取字节数
    maxPendingMessages: 10000                     # 待处理消息上限
    deviceQueueSize: 100                          # 单设备缓冲队列大小
    commitInterval: "200ms"                       # Offset 提交间隔
    idleDeviceTimeout: "5m"                       # 空闲设备工作线程回收时间


# 设备接入控制参数
device:
  bootstrap:
    tokenExpire: 3600                             # Bootstrap Token 有效期（秒）
  rateLimit:
    stateReport: 60                               # 设备状态上报频率限制


# 系统默认超级管理员
system:
  superAdmin:
    - "admin"
    - "emqx"


# Core 调用本地 ASR 服务的默认参数
asr:
  baseUrl: "http://byteone-asr-go:8250"           # ASR Gateway 地址
  apiKey: "REPLACE_WITH_ASR_API_KEY"              # ASR API Key


# OpenAI 兼容服务配置
litellm:
  baseUrl: "https://your-openai-compatible-endpoint" # OpenAI 兼容网关地址
  chatCompletionsPath: "/v1/chat/completions"        # 对话接口路径
  apiKey: "REPLACE_WITH_LITELLM_API_KEY"             # 上游 API Key
  model: "your-model-name"                           # 默认模型名称
  strictJson: false                                  # 是否启用严格 JSON 返回
  timeout: 60                                        # 请求超时（秒）


# EMQX 管理 API 配置
emqx:
  management:
    baseUrl: "http://emqx:18083"               # EMQX 管理地址
    apiKey: "REPLACE_WITH_EMQX_API_KEY"        # EMQX API Key
    apiSecret: "REPLACE_WITH_EMQX_API_SECRET"  # EMQX API Secret
    timeout: 10                                # 管理接口超时（秒）

4.1.1 GoFrame 数据库配置项参考

Section titled “4.1.1 GoFrame 数据库配置项参考”

Core 与 ASR Gateway 使用 GoFrame ORM 读取 database 配置。当前交付模板推荐使用 database.default.link 统一描述 PostgreSQL 连接；如需拆分字段、主从节点、连接池或超时参数，可参考 GoFrame 官方 2.10.x 配置文件说明：https://goframe.org/docs/core/gdb-config-file。

link 简化格式：

type:username:password@protocol(address)[/dbname][?param1=value1&...&paramN=valueN]

PostgreSQL 示例：

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

完整配置项：

配置项是否必须默认值 / 建议说明
host使用拆分字段时必填-数据库地址。使用 link 时该字段失效
port使用拆分字段时必填-数据库端口。PostgreSQL 常用 5432
user使用拆分字段时必填-数据库账号
pass使用拆分字段时必填-数据库密码，应通过 Secret 注入
name使用拆分字段时必填-数据库名称
type使用拆分字段时必填-数据库类型，如 pgsql、mysql、mariadb、tidb、mssql、sqlite、oracle、clickhouse、dm、gaussdb
link否-自定义数据库连接串。设置后 host、port、user、pass、name、type 不再生效
extra否-不同数据库驱动的额外参数；PostgreSQL 常见参数可直接放入 link 查询串
role否master应用层主从角色：master 或 slave；未使用主从时留空
debug否false是否输出 SQL 调试日志；生产环境建议关闭
prefix否-表名前缀
dryRun否falseORM 空跑模式，只读不写；生产环境必须关闭
charset否utf8数据库编码，MySQL 类数据库常用 utf8mb4
protocol否tcp连接协议，如 tcp、udp、unix、file
weight否-负载均衡权重；未使用应用层负载均衡时留空
timezone否Local时区配置，如 UTC、Local
namespace否-用于个别数据库服务区分 Catalog / Schema
maxIdle否10连接池最大空闲连接数
maxOpen否不限制连接池最大打开连接数
maxLifetime否30s单个连接可复用的最长时间
maxIdleConnTime否30sv2.10 新增，连接池中空闲连接的最大生存时间
queryTimeout否0查询语句超时时长；0 表示不单独限制，仍受请求上下文影响
execTimeout否0写入语句超时时长；0 表示不单独限制
tranTimeout否0事务处理超时时长；0 表示不单独限制
prepareTimeout否0预准备 SQL 语句执行超时时长；0 表示不单独限制
createdAt否created_at自动创建时间字段名
updatedAt否updated_at自动更新时间字段名
deletedAt否deleted_at软删除时间字段名
timeMaintainDisabled否false是否完全关闭自动时间维护；为 true 时 createdAt、updatedAt、deletedAt 均失效

数据库集群配置可将同一个分组配置为数组，并通过 role 标识主从节点：

database:
  default:
    - link: "pgsql:REPLACE_WITH_DB_USER:REPLACE_WITH_DB_PASSWORD@tcp(postgres-primary:5432)/byteone?sslmode=disable"
      role: "master"
      weight: 100
    - link: "pgsql:REPLACE_WITH_DB_USER:REPLACE_WITH_DB_PASSWORD@tcp(postgres-replica:5432)/byteone?sslmode=disable"
      role: "slave"
      weight: 100

数据库日志配置使用特殊分组 database.logger。启用 SQL 调试日志前，应确认日志中不会暴露敏感业务数据。

database:
  logger:
    path: "/var/log/byteone/sql"
    level: "all"
    stdout: true
  default:
    link: "pgsql:REPLACE_WITH_DB_USER:REPLACE_WITH_DB_PASSWORD@tcp(postgres:5432)/byteone?sslmode=disable"
    debug: false

4.1.2 GoFrame Redis 配置项参考

Section titled “4.1.2 GoFrame Redis 配置项参考”

Core 使用 GoFrame Redis 组件读取 redis.default 配置。GoFrame 官方字段名为 pass；当前 Core 启动逻辑同时会从环境变量 REDIS_DEFAULT_PASSWORD 覆盖到 redis.default.pass，因此交付时推荐在配置文件中使用 pass，在 Secret / Env 中使用平台约定的 REDIS_DEFAULT_PASSWORD。完整配置参考 GoFrame 官方 2.10.x Redis 配置说明：https://goframe.org/docs/components/contrib-nosql-redis-config。

单实例示例：

redis:
  default:
    address: "redis:6379"
    db: 0
    user: ""
    pass: "REPLACE_WITH_REDIS_PASSWORD"
    minIdle: 0
    maxIdle: 10
    maxActive: 100
    idleTimeout: "60s"
    maxConnLifetime: "60s"
    waitTimeout: "5s"
    dialTimeout: "5s"
    readTimeout: "3s"
    writeTimeout: "3s"

集群或哨兵示例：

redis:
  default:
    address: "redis-0:6379,redis-1:6379,redis-2:6379"
    db: 0
    pass: "REPLACE_WITH_REDIS_PASSWORD"
    cluster: true
    tls: false
  sentinel:
    address: "sentinel-0:26379,sentinel-1:26379,sentinel-2:26379"
    masterName: "mymaster"
    user: ""
    pass: "REPLACE_WITH_REDIS_PASSWORD"
    sentinelUsername: ""
    sentinelPassword: "REPLACE_WITH_SENTINEL_PASSWORD"

完整配置项：

配置项是否必须默认值说明
address是-Redis 地址，格式为 地址:端口；多个地址用英文逗号分隔，支持单实例和集群
db否0Redis DB 索引
user否-Redis ACL 用户名
pass否-Redis 密码，应通过 Secret 注入
minIdle否0允许闲置的最小连接数
maxIdle否10允许闲置的最大连接数；0 表示不限制
maxActive否100最大连接数量限制；0 表示不限制
idleTimeout否10连接最大空闲时间，使用 30s、1m、1d 等时间字符串
maxConnLifetime否30连接最长存活时间，使用 30s、1m、1d 等时间字符串
waitTimeout否0等待连接池连接的超时时间
dialTimeout否0TCP 建连超时时间
readTimeout否0TCP Read 操作超时时间
writeTimeout否0TCP Write 操作超时时间
masterName否-Sentinel 模式下的 MasterName
tls否false是否启用 TLS 连接
tlsSkipVerify否falseTLS 连接时是否跳过服务端名称校验；生产环境不建议开启
cluster否false是否强制启用集群模式；单 endpoint 代理到集群时需要设置为 true
protocol否3与 Redis Server 通信使用的 RESP 协议版本
sentinelUsername否-Sentinel 模式账号
sentinelPassword否-Sentinel 模式密码

4.2 MsgBridge 配置模板

Section titled “4.2 MsgBridge 配置模板”

配置文件路径：/app/config/config.yaml

# MsgBridge 服务监听配置
server:
  name: "msgbridge"                     # 服务名称
  address: ":8001"                      # HTTP 监听地址
  logPath: "logs"                       # 日志目录
  logStdout: false                      # 业务日志是否直出标准输出
  errorStack: true                      # 错误堆栈开关
  errorLogEnabled: false                # 错误日志访问入口开关
  accessLogEnabled: false               # 访问日志开关
  graceful: true                        # 优雅停机开关


# 日志级别配置
logger:
  level: "warn"                         # 生产环境建议 warn 或 info
  stdout: true                          # 输出到标准输出


# MQTT / EMQX 连接配置
mqtt:
  broker: "tcp://emqx:1883"             # MQTT Broker 地址
  clientVersion: "0.1"                  # 客户端版本号
  username: "emqx"                      # MQTT 用户名
  password: "REPLACE_WITH_EMQX_BRIDGE_PASSWORD" # MQTT 密码
  keepAlive: 60                         # 心跳间隔
  qos: 1                                # 默认 QoS


# Kafka / Redpanda 连接配置
kafka:
  brokers:
    - "redpanda:9092"                   # Broker 列表
  tls:
    enabled: false                      # 是否启用 TLS
    insecureSkipVerify: false           # 生产环境不应跳过证书校验
  username: ""                          # SASL 用户名
  password: ""                          # SASL 密码
  mechanism: "PLAIN"                    # SASL 机制
  producer:
    partition: 0                        # 默认分区策略参数
    batchSize: 100                      # 批量发送大小
    batchTimeout: "100ms"               # 批量发送等待时间
    maxAttempts: 3                      # 最大发送重试次数
    backoffMax: "100ms"                 # 重试退避上限
  consumer:
    groupId: "msgbridge-consumer"       # 消费组
    commitInterval: "100ms"             # Offset 提交间隔
    partition: 0                        # 分区策略参数
    minBytes: 1                         # 最小拉取字节数
    maxBytes: 10000000                  # 最大拉取字节数


# 协程守护配置
goroutineManager:
  maxGoroutines: 100                    # 最大协程数
  healthCheckInterval: "30s"            # 健康检查间隔
  restartDelay: "5s"                    # 重启延迟
  maxRestarts: 3                        # 最大重启次数
  restartCountResetTime: "5m"           # 重启计数清零周期


# 消息桥接缓冲与重试配置
bridge:
  messageBufferSize: 1000               # 消息缓冲区大小
  batchSize: 100                        # 批处理大小
  batchTimeout: "100ms"                 # 批处理等待时间
  retryInterval: "1s"                   # 失败重试间隔

4.3 ASR Gateway 配置模板

Section titled “4.3 ASR Gateway 配置模板”

配置文件路径：/app/manifest/config/config.yaml

# ASR Gateway 服务监听配置
server:
  address: ":8250"                      # HTTP / WebSocket 监听地址
  dumpRouterMap: true                   # 启动时输出路由映射


# 日志配置
logger:
  path: "logs"                          # 日志目录
  level: "all"                          # 日志级别
  stdout: true                          # 输出到标准输出


# JWT 配置
jwt:
  secret: "REPLACE_WITH_ASR_JWT_SECRET" # ASR JWT 签名密钥
  expire: 3600                          # Token 有效期（秒）


# 安全配置
security:
  apiKey: "REPLACE_WITH_ASR_API_KEY"    # 外部访问 API Key


# 数据库配置
database:
  default:
    link: "pgsql:REPLACE_WITH_DB_USER:REPLACE_WITH_DB_PASSWORD@tcp(postgres:5432)/byteone?sslmode=disable" # PostgreSQL 连接串
    debug: false                       # 生产环境关闭调试


# ASR 路由配置
asr:
  defaultServiceType: "funasr"         # 默认识别后端
  hotwordCache:
    localExpireSeconds: 1800           # 进程内热词缓存时长（秒）
  recording:
    globalEnabled: false               # 全局录制开关
    defaultDealerId: "system"          # 录音默认租户
    defaultOwnerId: "system"           # 录音默认归属用户
    storage:
      providerType: "oss"              # oss / s3
      basePath: "byteone"              # 对象键前缀
      # 对象键规则：{basePath}/asr/{dealerId}/{yyyy-MM-dd}/{filename}
      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"
  services:
    funasr:
      host: "funasr-online"            # 在线模型服务地址
      port: 10095                      # 在线模型服务端口
      ssl: false                       # 是否启用 SSL
    funasr-sensevoice:
      host: "funasr-sensevoice"        # SenseVoice 服务地址
      port: 10097                      # SenseVoice 服务端口
      ssl: false                       # 是否启用 SSL


# WebSocket 连接参数
websocket:
  maxConnections: 1000                 # 最大连接数
  timeout: 300                         # 单连接超时（秒）
  audioSampleRate: 16000               # 音频采样率
  audioChunkSize: 8000                 # 音频分片大小


# 模型清单
models:
  - code: "Fun-ASR-MLT-Nano-2512"      # 模型代码
    name: "多语言模型(Fun-ASR-MLT-Nano-2512)" # 模型名称
    modelDir: "FunAudioLLM/Fun-ASR-MLT-Nano-2512" # 模型目录
    onlineModelDir: "FunAudioLLM/Fun-ASR-MLT-Nano-2512" # 在线模型目录
  - code: "SenseVoiceSmall"            # 模型代码
    name: "多语言模型(SenseVoiceSmall)" # 模型名称
    modelDir: "damo/SenseVoiceSmall-onnx" # 模型目录
    onlineModelDir: "damo/SenseVoiceSmall-onnx" # 在线模型目录

4.4 Front 运行时配置模板

Section titled “4.4 Front 运行时配置模板”

配置文件路径：/usr/share/nginx/html/runtime-config.js

// Front 运行时配置。
// 该文件由容器启动脚本根据 BYTEONE_API_BASE_URL 环境变量渲染生成。
window.__BYTEONE_RUNTIME_CONFIG__ = Object.assign(
  {},
  window.__BYTEONE_RUNTIME_CONFIG__,
  {
    apiBaseUrl: "${BYTEONE_API_BASE_URL}", // 后端 API 访问基地址
  },
)

4.5 EMQX 环境变量模板

Section titled “4.5 EMQX 环境变量模板”

下发方式：容器环境变量

# EMQX Dashboard 默认管理员账号
EMQX_DASHBOARD__DEFAULT_USERNAME: admin
EMQX_DASHBOARD__DEFAULT_PASSWORD: REPLACE_WITH_EMQX_DASHBOARD_PASSWORD


# EMQX HTTP 认证配置
EMQX_AUTHENTICATION__1__BACKEND: http
EMQX_AUTHENTICATION__1__MECHANISM: password_based
EMQX_AUTHENTICATION__1__URL: "http://byteone-core:8000/api/v1/emqx/auth" # Core 认证回调地址
EMQX_AUTHENTICATION__1__METHOD: post
EMQX_AUTHENTICATION__1__HEADERS__CONTENT_TYPE: "application/json"
EMQX_AUTHENTICATION__1__HEADERS__ACCEPT: "application/json"
EMQX_AUTHENTICATION__1__BODY: '{"clientid":"$${clientid}","username":"$${username}","password":"$${password}","endpoint":"$${endpoint}","ipaddr":"$${peerhost}","protocol":"$${protocol}","port":"$${sockport}"}'


# EMQX HTTP ACL 配置
EMQX_AUTHORIZATION__SOURCES__1__TYPE: http
EMQX_AUTHORIZATION__SOURCES__1__URL: "http://byteone-core:8000/api/v1/emqx/acl" # Core ACL 回调地址
EMQX_AUTHORIZATION__SOURCES__1__METHOD: post
EMQX_AUTHORIZATION__SOURCES__1__HEADERS__CONTENT_TYPE: "application/json"
EMQX_AUTHORIZATION__SOURCES__1__HEADERS__ACCEPT: "application/json"
EMQX_AUTHORIZATION__SOURCES__1__BODY: '{"clientid":"$${clientid}","username":"$${username}","topic":"$${topic}","action":"$${action}","access":"$${access}","ipaddr":"$${peerhost}","protocol":"$${protocol}","port":"$${sockport}"}'

5. 部署前核查

Section titled “5. 部署前核查”

5.1 环境条件

Section titled “5.1 环境条件”
  1. Kubernetes 集群可用。
  2. Helm 3 可用。
  3. Ingress Controller 已部署。
  4. DNS 已完成解析。
  5. TLS 证书已准备。
  6. 镜像仓库拉取凭据已准备。
  7. PostgreSQL、Redis、Kafka、EMQX 网络访问策略已放通。

5.2 核查项

Section titled “5.2 核查项”
核查项要求
数据库连通性Core、ASR 可访问 PostgreSQL
Redis 连通性Core 可访问 Redis（ASR 不依赖 Redis）
Kafka / Redpanda 连通性Core、MsgBridge 可访问 Broker
EMQX 连通性MsgBridge 可访问 Broker，EMQX 可回调 Core
域名与证书Front、Core、MsgBridge、ASR 域名与证书匹配
Secret 管理所有生产密钥均通过 Secret 或等效机制管理

6. 标准部署流程

Section titled “6. 标准部署流程”

6.1 准备 Helm 交付物

Section titled “6.1 准备 Helm 交付物”

部署前应完成以下内容：

  1. 准备 values.yaml。
  2. 准备 Core、MsgBridge、ASR ConfigMap 对应内容。
  3. 准备数据库、Redis、JWT、License、EMQX、镜像仓库等 Secret。
  4. 准备 Front 运行时环境变量 BYTEONE_API_BASE_URL。

6.2 渲染校验

Section titled “6.2 渲染校验”
Terminal window
helm template byteone \
  oci://money-cn-guangzhou.cr.volces.com/coogz/byteone-helm \
  -f values.yaml

校验内容：

  • Ingress Host 与 TLS Secret 是否正确
  • ConfigMap 与 Secret 引用是否正确
  • Core、MsgBridge、ASR、Front 的挂载路径与环境变量是否正确
  • Service、端口、持久化卷是否符合交付要求

6.3 安装或升级

Section titled “6.3 安装或升级”
Terminal window
helm upgrade --install byteone \
  oci://money-cn-guangzhou.cr.volces.com/coogz/byteone-helm \
  --namespace byteone \
  --create-namespace \
  -f values.yaml

6.4 Front 运行时域名

Section titled “6.4 Front 运行时域名”

Front 通过环境变量 BYTEONE_API_BASE_URL 生成运行时配置文件 /usr/share/nginx/html/runtime-config.js。
示例值：https://byteone-core-api.example.com

7. 验收与健康检查

Section titled “7. 验收与健康检查”

7.1 基础检查

Section titled “7.1 基础检查”
Terminal window
kubectl get pods,svc,ingress -n byteone
kubectl logs deploy/byteone-core -n byteone
kubectl logs deploy/byteone-msgbridge -n byteone

7.2 服务健康检查

Section titled “7.2 服务健康检查”
  • Core 根路径返回 ok
  • MsgBridge 根路径返回 ok
  • MsgBridge 状态接口可访问
  • ASR 健康接口可访问
  • Front 页面可正常登录并访问后端接口

7.3 业务链路检查

Section titled “7.3 业务链路检查”
  1. 设备认证接入成功
  2. 打印任务下发成功
  3. 设备回执回流并落库成功
  4. 设备上下线事件可见
  5. ASR 默认识别链路可用

8. 容量与扩缩容

Section titled “8. 容量与扩缩容”

目标能力：接入设备数 50000，同时在线数 1000，并发吞吐量 20。

8.1 业务组件资源基线

Section titled “8.1 业务组件资源基线”
组件副本数CPU LimitMemory Limit
Core224Gi
MsgBridge212Gi
Front2500m512Mi
ASR Gateway212Gi
funasr-sensevoice-service248Gi
funasr-online148Gi

8.2 中间件资源基线

Section titled “8.2 中间件资源基线”
组件最低建议
PostgreSQL高可用主备架构，4C8G 起
Redis主从或托管高可用，2C4G 起
Kafka 或 Redpanda3 节点
EMQX2 节点以上

8.3 扩缩容原则

Section titled “8.3 扩缩容原则”
  • Core：依据 API 压力、Kafka 消费延迟、数据库连接数扩容
  • MsgBridge：依据 MQTT 消息量、Kafka 消费延迟、EMQX 连接数扩容
  • Front：依据访问并发量扩容
  • ASR Gateway / 模型服务：依据识别并发量和响应时间扩容
  • PostgreSQL、Redis、Kafka、EMQX：按甲方中间件标准执行扩容

9. 备份、升级与回滚

Section titled “9. 备份、升级与回滚”

9.1 备份要求

Section titled “9.1 备份要求”
  • PostgreSQL：执行全量与增量备份
  • Redis：开启持久化并执行备份
  • Kafka 或 Redpanda：执行消息保留与异地备份
  • ConfigMap、Secret、Helm values：纳入版本管理和审计

9.2 升级

Section titled “9.2 升级”
Terminal window
helm upgrade byteone \
  oci://money-cn-guangzhou.cr.volces.com/coogz/byteone-helm \
  --namespace byteone \
  -f values.yaml

升级前必须完成：

  1. 导出当前 release 历史信息
  2. 备份数据库
  3. 记录当前 revision
  4. 明确回滚条件

9.3 回滚

Section titled “9.3 回滚”
Terminal window
helm history byteone -n byteone
helm rollback byteone <REVISION> -n byteone

回滚后必须重新执行一次健康检查与业务链路检查。

10. 故障处置

Section titled “10. 故障处置”

10.1 镜像拉取失败

Section titled “10.1 镜像拉取失败”
  • 检查 imagePullSecrets
  • 检查镜像仓库网络连通
  • 检查仓库账号权限与凭据有效期

10.2 Ingress 访问异常

Section titled “10.2 Ingress 访问异常”
  • 检查 DNS 解析
  • 检查 TLS Secret 所在命名空间
  • 检查 Host 与证书域名一致性
  • 检查 Ingress Controller 状态

10.3 Core 启动失败

Section titled “10.3 Core 启动失败”
  • 检查 PostgreSQL 连接配置
  • 检查 License 配置
  • 检查 Kafka / Redpanda 连通性
  • 检查 EMQX 管理接口地址与凭据

10.4 MsgBridge 启动失败

Section titled “10.4 MsgBridge 启动失败”
  • 检查 MQTT Broker 地址与账号密码
  • 检查 Kafka / Redpanda 连通性
  • 检查 EMQX 主题授权
  • 检查消费组是否正常创建

10.5 ASR 服务异常

Section titled “10.5 ASR 服务异常”
  • 检查默认模型路由配置
  • 检查 ASR API Key 与 JWT 密钥
  • 检查 Redis 与 PostgreSQL 回源访问
  • 检查网关与识别后端网络连通

10.6 EMQX 认证或授权异常

Section titled “10.6 EMQX 认证或授权异常”
  • 检查 /api/v1/emqx/auth 回调地址是否可达
  • 检查 /api/v1/emqx/acl 回调地址是否可达
  • 检查 EMQX 环境变量是否正确展开
  • 检查 Core 服务名、端口和路径是否正确

11. 常见问题

Section titled “11. 常见问题”

11.1 是否支持仅使用外部中间件

Section titled “11.1 是否支持仅使用外部中间件”

支持。生产环境应优先采用外部中间件模式。

11.2 Core 是否支持多副本

Section titled “11.2 Core 是否支持多副本”

支持。多副本部署时，license.instance 必须保持实例级唯一。

11.3 MsgBridge 多副本是否会重复消费

Section titled “11.3 MsgBridge 多副本是否会重复消费”

不会。系统通过共享订阅与消费组机制分摊消息处理。

11.4 默认 ASR 后端应使用哪个

Section titled “11.4 默认 ASR 后端应使用哪个”

默认使用 funasr-sensevoice-service。如存在多语种识别需求，可启用 funasr-online。

11.5 内置中间件是否可用于生产

Section titled “11.5 内置中间件是否可用于生产”

可以用于生产环境，但应结合甲方对高可用、备份、容量和审计的要求进行评估。

12. 系统配置与模拟调试操作说明（含截图）

Section titled “12. 系统配置与模拟调试操作说明（含截图）”

本节用于补充后台常用配置项的落地顺序，适用于部署完成后的初始化操作。
截图采集时间：2026-06-01。
说明：涉及密钥字段的截图已做脱敏处理。

12.1 系统参数配置

Section titled “12.1 系统参数配置”

先进入 系统管理 -> 参数管理，按键名搜索并逐项配置。

参数管理-ASR地址 参数管理-ASR API Key 参数管理-IP白名单

建议按下表配置：

参数键示例值说明
network.asr_addressws://asr.local/ws/asrASR 服务地址
network.asr_api_key***已脱敏***ASR 语音识别服务 API Key
device.test_print_file_iddemo_test_print_file_20260601测试打印使用的文件 ID
device.jwt_expire_seconds86400设备 JWT 过期时间（秒）
api.whitelist_ips127.0.0.1
10.0.0.25
192.168.31.200		重要 API 访问 IP 白名单（回车分隔）
mqtt.port1883MQTT 服务器端口
mqtt.hostmqtt.local.lanMQTT 服务器地址

12.2 在线存储配置

Section titled “12.2 在线存储配置”

进入 系统管理 -> 在线存储配置，确认当前生效存储类型，并填写 OSS/S3 的端点、Bucket、密钥、下载签名等信息后保存。

在线存储配置

12.3 AI 图像引擎配置

Section titled “12.3 AI 图像引擎配置”

进入 AI管理 -> AI图像引擎，新增或编辑图像引擎，填写引擎类型、平台地址、鉴权用户名和鉴权密钥。

AI图像引擎列表 AI图像引擎编辑

示例配置：

字段示例值
编码doc_demo_engine_20260601
引擎类型swarmui
鉴权用户名doc_demo_user
鉴权密钥***已脱敏***

12.4 设备型号新增

Section titled “12.4 设备型号新增”

进入 设备管理 -> 设备型号管理，新增型号并保存基础信息（型号编码、型号名称、设备类别、文件限制）。

设备型号列表

示例型号：

字段示例值
型号编码DOC_P5802_AI
型号名称Doc Demo Model P5802 AI
设备类别label-printer

12.5 设备型号功能配置

Section titled “12.5 设备型号功能配置”

在型号行点击 功能配置，按业务要求配置：

  1. 文本生图 功能选择 AI业务。
  2. 标签打印热词(ASR) 功能选择 热词类型、ASR服务类型、ASR模型名称。

设备型号功能配置

本次示例：

功能配置
文本生图AI涂鸦(豆包)(ai_doodle_doubao)
标签打印热词(ASR)标签打印机日常热词(label-daily-v1) + FunASR + SenseVoiceSmall

12.6 新增设备并填写 SN

Section titled “12.6 新增设备并填写 SN”

进入 设备管理 -> 设备管理，新增设备并填写 SN、关联型号、设备名称等基础字段。

设备列表-SN查询

示例 SN：DOCSN20260601001。

12.7 页面获取设备密钥（用于模拟调试）

Section titled “12.7 页面获取设备密钥（用于模拟调试）”

在设备列表的目标设备上点击 查看，打开密钥弹窗并复制密钥用于设备端模拟调试。
请勿在工单、IM 或公共文档中明文传播密钥。

设备密钥查看-已脱敏