美聚
了解产品开始部署
正式文档 · 版本 1.0.0

部署与快速上手

从正式交付包开始，完成制品校验、系统安装、首轮业务配置、第一次模型调用和账务闭环验证。生产上线前仍需由客户完成网络、安全、容量、备份和故障恢复验收。

Ubuntu 24.04 LTSlinux/amd64Docker Compose v2Helm 3已验证 Kubernetes v1.32.0

1. 选择部署方式

两个版本提供相同业务功能。不要根据“功能多少”选择，而应根据客户现有平台和可用性责任选择。

标准单机版

适合 Demo、验收和规模较小的生产环境。完整栈运行在一台 Ubuntu 主机上，部署最快，但主机、磁盘和全部数据服务都是单点。

Kubernetes 集成版

适合已经有成熟 Kubernetes、数据库、Secret Manager、入口和监控平台的客户。美聚只部署应用，不建设这些平台。

不要把单机版当作高可用方案。 单机版任一主机、磁盘、Docker 或数据服务故障都可能中断全部业务。需要高可用时，应在客户平台上使用 Kubernetes 集成版并另行完成现场方案和验收。

2. 获取并验证交付包

从美聚批准的交付渠道取得以下四个同版本文件，并在开始安装前验证身份。不要只接收一个来源不明的压缩包。

文件用途
meiju-gateway-v1.0.0-linux-amd64.tar.gz正式离线交付包
*.tar.gz.sha256外层 SHA-256 校验文件
*.tar.gz.sig校验文件的 Ed25519 签名
*.tar.gz.pub.pem签名验证公钥
sha256sum -c meiju-gateway-v1.0.0-linux-amd64.tar.gz.sha256

openssl pkeyutl -verify -pubin \
  -inkey meiju-gateway-v1.0.0-linux-amd64.tar.gz.pub.pem \
  -sigfile meiju-gateway-v1.0.0-linux-amd64.tar.gz.sig \
  -rawin \
  -in meiju-gateway-v1.0.0-linux-amd64.tar.gz.sha256
两个命令应分别输出 OK 和 Signature Verified Successfully。任一检查失败都应停止安装，重新确认文件来源。
tar -xzf meiju-gateway-v1.0.0-linux-amd64.tar.gz
cd meiju-gateway-v1.0.0-linux-amd64
./verify.sh

包内 verify.sh 会继续检查内部文件、镜像和发布元数据；执行主机需要 openssl、sha256sum、tar、jq 和 rg。正式包包含 9 个美聚镜像、5 个第三方运行时镜像、Compose、Helm Chart、数据库 schema、SBOM、安全报告和部署文档。

3. 单机版前置条件

Ubuntu Server 24.04 LTS，AMD64
至少 4 vCPU、8 GiB 内存、50 GB 稳定磁盘
Docker Engine 与 Docker Compose v2
时间同步、固定地址和正确主机名
curl gzip jq openssl sha256sum tar rg
安装用户具有 Docker/root 权限

1.0.0 在 Docker Engine 29.1.3、Compose 2.40.3 上完成原生验收。参考规格不是压测容量上限，生产容量必须根据并发、请求时长、用量速率和数据保留期实测。

Docker socket 权限等价于主机 root。只允许受控运维账号执行安装。数据库和内部服务端口不得开放到主机外部。

4. 安装标准单机版

以下步骤假设已经在交付包所在目录完成外层和包内验证，并且 /opt/meiju/releases/1.0.0 尚不存在。

将版本放入不可变发布目录

cd ..
sudo install -d /opt/meiju/releases
sudo mv meiju-gateway-v1.0.0-linux-amd64 /opt/meiju/releases/1.0.0

export RELEASE=/opt/meiju/releases/1.0.0
export STATE=/opt/meiju/state
export TOOL="$RELEASE/single-node/meiju-single-node"

新版本使用新的 release 目录，不在原目录上覆盖文件。现场配置和 Secret 始终保存在独立的 $STATE。

初始化现场状态

sudo install -d -m 0700 "$STATE" /opt/meiju/backups
sudo "$TOOL" --release "$RELEASE" --state "$STATE" init

init 只创建缺失文件，会生成随机数据库密码、服务令牌和初始管理员凭证，不会覆盖已有配置。

执行安装前检查

sudo "$TOOL" --release "$RELEASE" --state "$STATE" check

只有所有检查通过后才继续。不要手工跳过镜像、签名、磁盘或配置检查。

安装并启动完整产品栈

sudo "$TOOL" --release "$RELEASE" --state "$STATE" install
sudo "$TOOL" --release "$RELEASE" --state "$STATE" status

install 会验证并导入 OCI 镜像、执行 migration、创建首管理员并启动服务；重复执行会保留已有配置和业务数据。

浏览器访问 http://SERVER:8080/console/。如无法访问，先检查云防火墙、主机防火墙、端口监听和 status 输出。

生产入口

正式环境应由客户入口终止 HTTPS，只公开 Console 的同源入口，并把 MEIJU_SESSION_COOKIE_SECURE 设为 true。不要直接公开 PostgreSQL、Redis、ClickHouse、AISIX status 或内部指标端口。

5. Kubernetes 前置条件

在运行 Helm 前，客户平台团队必须关闭以下清单。Chart 不会自动安装缺失的平台组件。

依赖准备结果
Kubernetes 与 HelmHelm 3 可访问目标集群；节点可运行交付的 linux/amd64 镜像；1.0.0 已验证 Kubernetes v1.32.0
PostgreSQL提供可建表、执行 migration 的连接 URL，并纳入客户备份与高可用体系
Redis提供地址和可选密码，用于准入、预占和余额投影
ClickHouse先应用交付包 db/clickhouse/ 中的 schema，再提供 HTTP(S) URL
存储动态供应 3 个 RWO PVC，并支持 Pod 重建后重新挂载原卷
镜像仓库14 个 OCI archive 已导入客户批准的 Registry，节点可按 digest 拉取
Secret Manager具备工作负载身份、最小只读策略和上游凭证轮换能力
入口与监控准备 HTTPS Controller、DNS、证书；Prometheus 可抓取 6 个指标 Service
Kubernetes 集成版不是“自带 Kubernetes 的安装包”。客户平台的 CNI、CSI、数据库、入口、Secret Manager、监控、备份与 SLA 均在美聚应用之外。

6. 安装 Kubernetes 集成版

将版本放入不可变发布目录

cd ..
sudo install -d /opt/meiju/releases
sudo mv meiju-gateway-v1.0.0-linux-amd64 /opt/meiju/releases/1.0.0
export RELEASE=/opt/meiju/releases/1.0.0

每个版本使用独立目录。不要在已经验签的发布目录中修改 Chart、镜像、schema 或元数据。

将 OCI 镜像导入客户 Registry

export RELEASE=/opt/meiju/releases/1.0.0
export REGISTRY_PREFIX=registry.example.com/approved/meiju
export REGISTRY_EVIDENCE=/secure/path/meiju-registry-evidence

install -d -m 0700 "$REGISTRY_EVIDENCE"
MEIJU_D5_REGISTRY_TLS_VERIFY=true \
  "$RELEASE/scripts/d5-registry-publish.sh" \
  "$RELEASE" "$REGISTRY_PREFIX" "$REGISTRY_EVIDENCE"

该工具从包内 OCI archive 发布 14 个固定镜像，并从 Registry 重新读取 manifest 校验 digest。它需要 Docker、jq、sha256sum、tar，以及环境可取得脚本固定的 Skopeo 镜像。离线现场应由平台团队预先导入该工具镜像，或使用客户批准的等价 OCI 导入工具。最终引用记录在 registry-images.tsv。

初始化 ClickHouse schema

平台团队使用批准的 ClickHouse 客户端，按文件名顺序执行 $RELEASE/db/clickhouse/*.sql。这些 SQL 创建 meiju 数据库、用量表及 1.0.0 所需字段，并可幂等重复执行。执行后确认 meiju.usage_events 可查询，再继续安装。

准备 Chart 和现场 values

export RELEASE=/opt/meiju/releases/1.0.0
export CHART="$RELEASE/kubernetes/meiju-1.0.0.tgz"
export VALUES=/secure/path/meiju-values.yaml

cp "$RELEASE/kubernetes/meiju-values.example.yaml" "$VALUES"

至少修改 Redis 地址、三个 StorageClass、Secret Manager、镜像 repository 和 HTTPS 入口。保持镜像 digest 不变，不使用浮动 tag。

创建命名空间和 runtime Secret

kubectl create namespace meiju

kubectl -n meiju create secret generic meiju-runtime \
  --from-literal=database-url='postgres://USER:PASSWORD@HOST:5432/meiju' \
  --from-literal=customer-key-service-token='RANDOM_SERVICE_TOKEN' \
  --from-literal=clickhouse-url='https://USER:PASSWORD@HOST:8443'

Redis 需要认证时增加 redis-password。生产 Secret 应由客户批准的 Secret 交付机制创建，不写进 values、Git 或操作记录。

只为全新数据库准备首管理员

kubectl -n meiju create secret generic meiju-initial-admin \
  --from-literal=username=admin \
  --from-literal=password='RANDOM_12_TO_256_BYTE_PASSWORD' \
  --from-literal=email=admin@example.test

仅在全新数据库中将 initialAdmin.enabled 设为 true。已有管理员的数据库必须保持 false。

依次验证渲染和目标 API

helm lint "$CHART" -f "$VALUES"
helm template meiju "$CHART" -n meiju -f "$VALUES" > /tmp/meiju-rendered.yaml
kubectl -n meiju apply --dry-run=server -f /tmp/meiju-rendered.yaml

检查渲染出的镜像引用、StorageClass、入口、NetworkPolicy 和 Secret 名称，再进入真实安装。

安装并检查工作负载

helm upgrade --install meiju "$CHART" \
  --namespace meiju \
  -f "$VALUES" \
  --wait --timeout 10m --history-max 10

helm -n meiju status meiju
kubectl -n meiju get pod,pvc,service
kubectl -n meiju get events --sort-by=.lastTimestamp

migration Job、Pod 探针和 3 个 PVC 都应正常。PVC 保存已发布网关配置、AISIX spool 和 Collector 队列，不能作为缓存随意删除。

首次登录并修改密码后，删除一次性的 meiju-initial-admin Secret，同时把 initialAdmin.enabled 恢复为 false。

7. 首次登录

标准单机版

初始用户名和密码位于以下两个只允许管理员读取的文件中：

sudo cat "$STATE/secrets/initial-admin/username"
sudo cat "$STATE/secrets/initial-admin/password"

Kubernetes 集成版

使用部署前创建的 meiju-initial-admin Secret 中的用户名和密码。入口应通过客户 HTTPS 域名访问。

首次登录后立即修改管理员密码。 单机版在 bootstrap 写入 .complete 后可删除 username 和 password 文件，但不要删除 .complete；Kubernetes 版删除一次性首管理员 Secret。

8. 首轮业务配置

请按下面顺序操作。上游、模型、价格和客户权限是相互引用的资源，颠倒顺序会导致后续页面没有可选目标。

创建上游服务及上游模型

进入“上游服务”，添加 Base URL、凭证引用和状态。打开该服务的编辑页，在下方表格中添加它实际提供的模型 ID。不同服务可以使用不同的上游模型命名。

让运行时取得上游凭证

Kubernetes 版在客户 Secret Manager 中按刚才填写的 secret_ref 保存 API Key。单机版从编辑页 URL 取得上游资源 ID，将字母转成大写、所有非字母数字字符替换为下划线，然后用 root 专用编辑器在 $STATE/secrets/upstream.env 中加入 MEIJU_UPSTREAM_SECRET_资源ID后缀=API_KEY。文件保持 0600，修改后执行生命周期工具的 start。不要把凭证明文放入命令行历史、上游 URL、名称或备注。

创建对外模型和路由策略

进入“模型路由”，创建客户调用时使用的稳定模型 ID，再配置路由目标。按现实需求选择故障切换、轮询或权重策略；上游目标必须指向已经登记的上游模型。

创建并发布价格版本

为对外模型配置输入和输出 token 单价，核对计价单位及生效时间，然后发布价格版本。已发布版本用于解释历史费用，不应通过覆盖旧版本改变历史账务。

创建客户并授予权限

创建客户，配置可调用模型、RPM、TPM、并发和总配额，按业务需要完成充值或授信，再发送账户激活邀请。

由客户创建 API Key

客户通过邀请激活账户，登录客户门户并自行创建 API Key。管理员不代客户创建、查看或修改 Key。客户可自行轮换和停用；停用不可逆。

发布网关配置

管理员在“网关配置”中查看待发布版本的完整快照，确认上游、对外模型、路由目标和统计数量后发布。只有发布后的网关资源配置才进入 AISIX 数据面。

两类生效机制不同：客户 API Key 的创建、轮换和停用会自动发布，不依赖管理员动作；上游、模型和路由等网关资源变更必须由管理员显式“发布到网关”。
恢复上游服务不会自动恢复其下属上游模型。账户冻结可恢复，账户关闭不可逆；API Key 停用也不可逆。执行这些操作前先确认影响范围。

9. 第一次模型调用

使用客户自己创建的 API Key 和刚刚发布的对外模型 ID。生产环境必须使用客户 HTTPS 网关域名。

export MEIJU_BASE_URL=https://gateway.example.com
export MEIJU_API_KEY='CUSTOMER_CREATED_API_KEY'
export MEIJU_MODEL_ID='YOUR_PUBLIC_MODEL_ID'

curl "$MEIJU_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $MEIJU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MEIJU_MODEL_ID\",
    \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}],
    \"stream\": false
  }"

成功响应应包含模型回复和用量信息。若返回未授权，检查 API Key 状态、客户状态和模型权限；若模型不可用，检查当前发布配置、上游模型状态、凭证引用和上游 HTTPS 连通性。

10. 验证完整业务闭环

“接口返回 200”只证明请求链路可用，不足以完成产品验收。一次真实调用后继续检查以下记录：

用量页面出现相同请求，客户和模型归属正确
输入、输出 token 与响应一致
命中调用时有效的已发布价格版本
费用记录和账本扣减只发生一次
客户余额等于充值、调整与扣费的合计
重点账户对账结果为平衡
最终账务检查标准：balanced=true 且 difference_micro=0。如不满足，不应继续扩大流量或切换生产入口。

11. 日常运维与升级

单机版状态与日志

sudo "$TOOL" --release "$RELEASE" --state "$STATE" status
sudo "$TOOL" --release "$RELEASE" --state "$STATE" logs
sudo "$TOOL" --release "$RELEASE" --state "$STATE" stop
sudo "$TOOL" --release "$RELEASE" --state "$STATE" start
sudo "$TOOL" --release "$RELEASE" --state "$STATE" restart

单机版一致性备份

sudo "$TOOL" --release "$RELEASE" --state "$STATE" backup /opt/meiju/backups

该操作会短暂停止完整 Compose 栈，归档 6 个数据卷、现场配置和 Secret，再恢复原运行状态。备份包含明文数据库密码和上游凭证，必须存放到加密、独立、受访问控制的介质；本机目录不是异地备份。

单机版升级

sudo /opt/meiju/releases/NEW_VERSION/single-node/meiju-single-node \
  --release /opt/meiju/releases/NEW_VERSION \
  --state "$STATE" \
  upgrade /opt/meiju/backups

升级会先冷备份，再验签、导入镜像、执行向前 migration 并启动。不可逆 migration 不强行向后回滚。

Kubernetes 升级与应用回退

helm upgrade meiju /path/to/new/meiju-NEW_VERSION.tgz \
  --namespace meiju -f "$VALUES" --wait --timeout 10m

helm -n meiju history meiju
helm -n meiju rollback meiju REVISION \
  --wait --timeout 10m --cleanup-on-fail
Helm rollback 不会回退 PostgreSQL 或 ClickHouse schema。升级前由客户完成权威数据备份，并根据 Release Notes 确认 migration 和回退路径。

12. 故障定位

标准单机版

  1. 运行生命周期工具 status，确认容器和健康检查。
  2. 用 logs 查看 migration、Console、控制面、AISIX、Collector 和计费服务。
  3. 检查主机磁盘、Docker daemon、时间同步和端口占用。
  4. 检查当前已发布网关配置、上游状态、凭证文件和 HTTPS 连通性。
  5. 检查 AISIX spool、Collector 队列、用量事件和账务对账。

Kubernetes 集成版

  1. 检查 helm status/history 和 migration Job。
  2. 检查 Pod 状态、事件、探针和容器日志。
  3. 核对 runtime Secret 键名及数据库 DNS、TLS 和认证。
  4. 检查 PVC Bound/挂载状态与 StorageClass 事件。
  5. 检查 NetworkPolicy、入口和监控 namespace selector。
  6. 最后沿 AISIX、Collector、Usage Worker、Billing 检查用量与账务。
先判断问题属于应用、平台还是上游模型。Kubernetes、网络、存储、数据库和证书问题由客户平台团队处理；美聚提供接口契约和应用侧诊断支持。

13. 限制与责任边界

范围美聚客户
软件制品镜像、Chart、Compose、migration、版本说明与完整性证据按批准流程接收、验签和保管
基础平台定义资源、接口和数据契约主机、Kubernetes、网络、存储、数据库与 Secret Manager
安全入口提供同源应用路径和安全配置项DNS、TLS 证书、负载均衡、防火墙与访问控制
备份恢复说明数据语义、顺序和恢复后产品检查备份产品、调度、介质、加密、恢复基础设施与演练
高可用与 SLA说明应用单点和可扩展边界设计故障域、平台高可用、值守、切换和 SLA

1.0.0 不提供 GPU/Kubernetes 管理、模型部署与推理运维、跨 AIDC 算力调度、动态批发定价、流水分成、自动退款，也不对客户机房或平台作统一 SLA 承诺。

生产上线条件不止是安装成功。客户还必须完成容量压测、TLS 与网络检查、Secret 轮换、备份恢复演练、监控通知、故障值守和业务验收，并为真实环境确定 RPO、RTO 与 SLA。