☸️ K3s 更新中心（高级）

本页适用于已经把 Metapi 部署到 K3s / Kubernetes + Helm 的用户。

K3s 更新中心的日常入口位于：

text

设置 → 更新中心

本文主要说明三件事：

哪些配置直接在后台页面里填写
哪些配置仍然需要主服务环境变量或 helper manifest
哪些前提不满足时，页面虽然能打开，但无法真正部署

如果你现在的环境只是一个最普通的 Docker Compose 安装，只有一个 Metapi 容器，其他什么都没有，那么先记住一句话：

IMPORTANT

如果你只是想原地给现有 Compose 容器加一个“后台点按钮更新”的能力，那你现在大概率用不上这页。

当前“更新中心”不会直接帮你更新一台普通 Docker 主机上的 Compose 容器。它依赖集群里的 Deploy Helper 去执行 helm upgrade 和 kubectl rollout status，所以只适用于已经有 K3s / Kubernetes / Helm 的环境。

但如果你是老用户，正打算 从 Docker Compose 迁到 K3s / Helm，以获得滚动更新能力，那这页仍然值得看，因为它描述的就是迁移完成后的目标形态。

配置到底在哪里配

更新中心涉及后台页面、主服务环境变量、helper 部署清单三层配置，最容易混淆，建议先看下面这张对照表。

你要配什么	去哪里配	说明
是否启用更新中心	UI：设置 → 更新中心	日常使用优先在 UI 操作
Deploy Helper URL	UI：设置 → 更新中心	例如集群内 Service 地址
Namespace / Release Name / Chart Ref / Image Repository	UI：设置 → 更新中心	都是页面里直接填的部署配置
GitHub Releases / Docker Hub / 默认部署来源	UI：设置 → 更新中心	属于页面里的版本来源策略
主 Metapi 到 helper 的认证 token	主 Metapi 环境变量	`DEPLOY_HELPER_TOKEN` 或 `UPDATE_CENTER_HELPER_TOKEN`
helper 自己监听在哪个地址和端口	helper 环境变量 / manifest	`DEPLOY_HELPER_HOST` / `DEPLOY_HELPER_PORT`
helper 自己的 Bearer Token	helper 环境变量 / manifest	`DEPLOY_HELPER_TOKEN`，且必须与主服务一致
chart 是否真的支持 digest 部署	chart 文件本身	这不是 UI，也不是普通 env，要看 chart 模板

其中可以这样理解：

日常使用时，更新中心的大部分配置直接在 设置 → 更新中心 页面填写
环境变量主要负责主服务与 helper 之间的认证，以及 helper 自身的监听参数

先判断：是否适用

你的现状	是否适用	你现在该怎么做
只有一个 `docker compose up -d` 跑起来的 Metapi 容器	不需要	继续用普通 Docker 升级方式
目前是 Docker Compose，准备迁到 K3s / Helm 来获得滚动更新	需要	把本页当成迁移后的目标架构说明，先完成迁移，再启用更新中心
有 K3s / Kubernetes 集群，但 Metapi 不是用 Helm release 部署的	暂时不建议	这套更新中心无法直接接管现有部署
Metapi 已经是 Helm release，想在后台里看版本并手动点一次升级	需要	继续看下文

如果你现在只有一个 Docker Compose 容器

这就是大多数用户的真实情况。

对这类用户来说，当前版本最实用的升级路径仍然是普通 Docker 流程：

bash

docker compose pull
docker compose up -d

如果你还想更稳一点，可以先看镜像版本或仓库 release，再决定要不要拉新镜像。

你现在不需要额外准备这些东西：

K3s / Kubernetes 集群
Helm
Deploy Helper
额外的 Bearer Token
集群内 Service 地址

除非你本来就在用 K3s / Helm，否则本页可以直接跳过。

如果你正准备从 Docker Compose 迁到 K3s

这其实是一个很合理的升级方向。

很多老用户想迁到 K3s / Helm，核心诉求通常不是“为了多一个页面”，而是为了获得这些能力：

发布时尽量减少停机时间
用 Helm 管理版本和回滚
后续在后台里看版本来源，并人工触发一次升级

对这类用户来说，本页不是“现在立刻就能用”的操作手册，而是：

“迁移完成后，你会得到什么能力”
“为了用上这个能力，集群侧要提前满足什么前提”

一个很重要的认知

“迁到 K3s” 和 “启用更新中心” 是两件相关但不同的事：

迁到 K3s / Helm
- 是部署形态升级
启用更新中心
- 是迁移完成后，额外获得的一个后台升级入口

所以更准确的理解应该是：

先把 Docker Compose 用户迁成 Helm 用户，再谈更新中心。

那这个功能到底是干什么的

对已经在 K3s / Kubernetes 里跑 Metapi 的用户，这个“更新中心”主要解决的是：

在后台里看当前运行版本
看官方 GitHub Releases / Docker Hub 有没有新的稳定版
在后台定时检查新版本，并在首次发现时提醒一次
确认 Deploy Helper 是否健康
点一次按钮，触发一轮 Helm 升级
在页面里回看部署日志

它的定位更接近：

“集群内人工触发升级面板”

而不是：

“单容器自动升级器”
“Docker Compose 一键更新”
“无人值守自动发布系统”

使用它之前，你至少要已经有这些东西

一个可用的 K3s / Kubernetes 集群
用 Helm 部署的 Metapi release
你的 chart 至少支持下面三个 values：
- image.repository
- image.tag
- image.digest
目标 Deployment 带有 app.kubernetes.io/instance=<releaseName> 标签
主 Metapi 服务可以访问：
- GitHub API
- Docker Hub API
- Deploy Helper 的集群内地址

如果上面有任何一项不成立，就先不要配更新中心。

helper 是什么

Deploy Helper 是一个跑在集群里的小服务。它不负责对外提供 Metapi 功能，只负责接受主 Metapi 发来的部署请求，然后在集群里执行：

helm history
helm get values
helm upgrade
kubectl rollout status
必要时 helm rollback

所以你可以把它理解成：

“一个专门替管理后台执行 Helm/Kubectl 的集群内代理”

什么时候你才应该去配 helper

只有当你已经满足下面这个目标时，才值得去配：

“我已经在 K3s / Helm 里跑 Metapi 了，现在想在后台里看版本，并且人工点一下完成升级”

如果你现在只是：

“我有一个 Compose 容器，想在后台里点按钮更新它”

那答案是：

当前版本还不支持这个场景。

如果你现在是：

“我正在把 Compose 老实例迁到 K3s，希望迁完以后用后台来做后续版本升级”

那答案是：

这是一个合理场景，本页正是说明迁移后该如何接入更新中心。

K3s / Helm 用户的接入步骤

如果你确实已经是 K3s / Helm 用户，接入顺序建议如下。

1. 先部署 Deploy Helper

仓库里带了一个最小示例清单：

deploy/k3s/metapi-deploy-helper.yaml
deploy/k3s/chart

使用前至少要改这些值：

namespace
DEPLOY_HELPER_TOKEN
image

如果你准备直接按仓库示例接入，推荐把它们放到这两个路径：

/opt/metapi-k3s/metapi-deploy-helper.yaml
/opt/metapi-k3s/chart

这里有一个很容易漏掉、但会直接决定更新中心是否真的可靠的约束：

后台里的 Chart Ref
helper Pod 里挂载进去的 chart 路径

这两个值必须指向同一份 chart。

如果你在设置页把 Chart Ref 填成 /opt/metapi-k3s/chart，但 helper Pod 里根本没有把那份 chart 挂进去，那么更新中心即使能看到版本，也无法稳定把 digest 部署到真正运行中的 Pod。

最小部署命令示例：

bash

kubectl create namespace ai
mkdir -p /opt/metapi-k3s/chart
cp -R deploy/k3s/chart/. /opt/metapi-k3s/chart/
cp deploy/k3s/metapi-deploy-helper.yaml /opt/metapi-k3s/metapi-deploy-helper.yaml
kubectl apply -f /opt/metapi-k3s/metapi-deploy-helper.yaml

1.1 首次接入前一定要做的自检

新用户最容易踩的坑不是 helper 起不来，而是：

chart 虽然能执行 helm upgrade
但它其实没有消费 image.digest
同时 imagePullPolicy 还停留在 IfNotPresent

这样更新中心会显示任务成功、Helm revision 也会增加，但线上真正运行的镜像可能根本没变。

仓库自带的 deploy/k3s/chart 已经把这件事处理成默认正确：

values.yaml 里包含 image.digest
templates/deployment.yaml 在有 digest 时会渲染成 repository@digest
chart 默认 imagePullPolicy: Always
helper 示例清单也默认 imagePullPolicy: Always

你可以在接入前先跑一次自检：

bash

helm template metapi /opt/metapi-k3s/chart \
  --set image.repository=kennethww/metapi \
  --set image.tag=latest \
  --set-string image.digest=sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  | grep -n 'image:'

你期望看到的是：

image: "kennethww/metapi@sha256:..."

如果输出仍然是：

image: "kennethww/metapi:latest"

那说明这份 chart 还是 tag 语义，先不要继续配置更新中心。

1.2 可选：引用已有的环境变量 Secret

默认的 existingSecret: "" 会继续由 chart 渲染环境变量 Secret，并保留对 AUTH_TOKEN、PROXY_TOKEN 以及非 SQLite DB_URL 的必填校验。如果你已经通过 External Secrets Operator、Sealed Secrets 或其他独立流程管理 Secret，可以把 existingSecret 设置为那个 Secret 的名称；此时 chart 不再渲染自己的 Secret，也不会添加 checksum/env-secret 注解。

外部 Secret 必须是 Metapi 专用、已经存在、并且与 Helm release 位于同一 namespace 的 Secret。envFrom 会把其中所有合法键注入容器，因此不要复用还包含其他应用配置的共享 Secret。建议让外部 Secret 明确提供 chart 原本管理的全部键：

yaml

apiVersion: v1
kind: Secret
metadata:
  name: metapi-runtime-env
  namespace: ai
type: Opaque
stringData:
  AUTH_TOKEN: <strong-admin-token>
  PROXY_TOKEN: <strong-proxy-token>
  DB_TYPE: postgres
  DB_URL: <postgres-connection-url>
  DB_SSL: "false"
  DATA_DIR: /app/data
  PORT: "4000"
  TZ: Asia/Shanghai
  CHECKIN_CRON: "0 8 * * *"
  BALANCE_REFRESH_CRON: "0 * * * *"
  DEPLOY_HELPER_TOKEN: <helper-token>
  # Required only when using Gemini CLI OAuth; otherwise leave blank.
  GEMINI_CLI_CLIENT_ID: ""
  GEMINI_CLI_CLIENT_SECRET: ""
  # Required only when using Antigravity OAuth; otherwise leave blank.
  ANTIGRAVITY_CLIENT_ID: ""
  ANTIGRAVITY_CLIENT_SECRET: ""

创建并核对这个 Secret 后，再显式启用外部 Secret 模式：

bash

helm upgrade --install metapi /opt/metapi-k3s/chart \
  --namespace ai \
  --set-string existingSecret=metapi-runtime-env

CAUTION

envFrom 只负责注入已经存在的键，Helm 和 Kubernetes 不会替 chart 校验外部 Secret 是否包含必填键。外部 Secret 不完整时，应用可能采用自身默认值；例如缺少 AUTH_TOKEN 或 PROXY_TOKEN 时，已知回退值分别是 change-me-admin-token 和 change-me-proxy-sk-token。这些值只适合本地调试，绝不能当成生产保护。部署前应逐项检查 Secret 的键，并在 Pod 内确认实际配置符合预期。

还要注意以下运维边界：

不要再通过 --set env.authToken=...、--set env.proxyToken=... 或普通 values 文件传递这些 Secret 值，否则它们仍可能进入 Helm release values 和 helm history 对应的历史 revision。改用外部 Secret 不会清除旧 revision 中已经保存的数据，需要单独轮换泄露过的凭据并按你的保留策略处理历史记录。
迁移现有 release 时，外部 Secret 应使用不同于 chart 当前生成名称（通常是 <release-fullname>-env）的新名称。不要预创建同名对象并期待 Helm 自动“接管”，也不要直接把 existingSecret 指向原来由 chart 管理的同名 Secret；升级时旧的受管资源可能被删除，导致 Deployment 引用一个不存在的 Secret。
外部 Secret 更新后，Pod 模板没有 checksum/env-secret 变化，因此不会自动滚动。确认新数据已经同步后，需要手动执行例如 kubectl rollout restart deployment/metapi -n ai，再用 kubectl rollout status 验证新 Pod 已就绪。

2. 让主 Metapi 和 helper 用同一个 token

主 Metapi 端支持这两个环境变量，设置一个即可：

DEPLOY_HELPER_TOKEN
UPDATE_CENTER_HELPER_TOKEN

helper 端使用：

DEPLOY_HELPER_TOKEN

它们的值必须完全一致。

这一步仍然是环境变量级配置，因为它本质上是主服务与 helper 之间的认证，而不是普通用户日常在 UI 里调的业务参数。

3. 在后台“设置 → 更新中心”里填配置

从这一步开始，优先按 UI 来操作，不要再回头把下面这些字段硬塞进环境变量。

需要填写的核心字段有：

字段	怎么理解	典型示例
`Deploy Helper URL`	主 Metapi 访问 helper 的地址	`http://metapi-deploy-helper.ai.svc.cluster.local:9850`
`Namespace`	目标 release 所在命名空间	`ai`
`Release Name`	Helm release 名	`metapi`
`Chart Ref`	helper Pod 能访问到的 chart 引用	`/opt/metapi-k3s/chart`
`Image Repository`	升级时写入 chart 的镜像仓库	`kennethww/metapi`
`默认部署来源`	默认从 GitHub 还是 Docker Hub 取版本	`GitHub Releases`

另外还有 3 个开关：

启用更新中心
GitHub Releases
Docker Hub

补充一点：

Docker Hub 里的主候选仍然优先 latest / main / 稳定 SemVer 标签
页面还会自动列出最近推送的 dev、分支名、临时标签或 sha-* 这类非稳定标签，并一起带出 digest
如果你要部署一个更老或更特殊、没出现在自动列表里的标签，仍然可以在 Docker Hub 卡片底部用“手动部署 Docker Hub 标签”填写

对已经跑起来的 K3s / Helm 用户来说，更新中心的日常配置主要就在这一页：

text

设置 → 更新中心

4. 实际操作顺序

推荐这样用：

先保存配置
等后台自动发现新版本，或手动点一次“检查更新”立即刷新
确认页面状态都正常：
- 当前运行版本正常显示
- 版本来源发现了可部署版本
- 如果 Docker Hub 显示的是 latest @ sha256:...，说明页面已经识别到 alias tag 当前指向的具体镜像 digest
- Deploy Helper 显示健康
如果你要跟随稳定候选，直接点部署按钮；如果你要切到最近的 dev / 分支 / 临时标签，可以直接点自动列出的那一项；只有更特殊的 tag 才需要手动填写，必要时连 digest 一起填
在页面下方看部署日志
如果升级后发现问题，可以直接在“回退历史”里点旧 revision 回滚；只要该 revision 当时记录了 digest，就会跟着一起回到对应镜像

如果实时日志流断开，页面会自动回退到最近任务快照。

4.1 新用户最值得先做的一次确认

第一次接入时，不要急着点部署。先确认下面 4 件事同时成立：

Chart Ref 和 helper 挂载路径指向的是同一份 chart。
这份 chart 支持 image.digest，并且在有 digest 时会渲染成 repository@digest。
chart 和 helper 都没有继续使用会掩盖新镜像的 imagePullPolicy: IfNotPresent。
页面里显示的目标 digest，和 helper 最终读到的运行中 digest 能对上。

只要这 4 件事成立，新用户就不会再遇到“页面说部署成功，但线上还是旧镜像”的假成功。

这套能力当前不适合什么场景

只有一台 Docker 主机、一个 Compose 文件、一个 Metapi 容器
想让后台直接远程更新 Docker Compose 服务
没有 Helm release，只是手工 apply 的 Deployment
需要全自动无人值守升级
需要灰度、分批、审批、回滚编排等更完整的发布系统

About 页和更新中心的关系

About 页里的“更新提醒”更像一个轻量入口：

让你知道大概有没有新版本

真正的配置和部署入口仍然在：

“设置 → 更新中心”

所以即使你是普通 Docker Compose 用户，也可以把 About 页里的版本提醒当成“看看最近有没有新版本”的地方，但不要把它理解成“马上就能自动更新我这台机器”。

常见问题

为什么我在设置页里能看到更新中心，但还是没法用

因为这个页面会跟着功能一起出现，但真正能否部署，取决于你有没有：

K3s / Kubernetes
Helm release
Deploy Helper
主服务的 DEPLOY_HELPER_TOKEN（或兼容别名 UPDATE_CENTER_HELPER_TOKEN）与 helper 侧 DEPLOY_HELPER_TOKEN 保持一致

另外，如果你想用“按 digest 精确部署/回退”这条链路，还要确认你的 chart 没有忽略 image.digest 这个值；否则页面虽然能显示 digest，真正部署时还是只会落到 tag 语义。

缺其中任何一项，都只能看，不能真正部署。

为什么页面显示任务成功，但线上镜像还是没变

最常见的根因只有两类：

你的 chart 其实没有消费 image.digest
你的 Deployment 或 helper 还在使用 imagePullPolicy: IfNotPresent

这两种情况叠在一起时，就会出现“Helm revision 往前走了，但实际运行的 imageID 没动”的假成功。

如果你是第一次接入，最稳妥的方式就是直接从仓库自带的：

deploy/k3s/chart
deploy/k3s/metapi-deploy-helper.yaml

开始，不要自己先抄一份简化版再改。

为什么我只有 Docker Compose，按钮没有意义

因为当前部署链路不是去操作外部 Docker 主机，而是去调用集群里的 helper，然后由 helper 执行 helm / kubectl。

那普通 Docker Compose 用户现在该怎么升级

继续使用正常 Docker 流程即可：

bash

docker compose pull
docker compose up -d

如果你担心直接升级，可以先看仓库 Releases 或镜像 tag，再决定是否升级。

☸️ K3s 更新中心（高级）

配置到底在哪里配

先判断：是否适用

如果你现在只有一个 Docker Compose 容器

如果你正准备从 Docker Compose 迁到 K3s

推荐的迁移顺序

一个很重要的认知

那这个功能到底是干什么的

使用它之前，你至少要已经有这些东西

helper 是什么

什么时候你才应该去配 helper

K3s / Helm 用户的接入步骤

1. 先部署 Deploy Helper

1.1 首次接入前一定要做的自检

1.2 可选：引用已有的环境变量 Secret

2. 让主 Metapi 和 helper 用同一个 token

3. 在后台“设置 → 更新中心”里填配置

4. 实际操作顺序

4.1 新用户最值得先做的一次确认

这套能力当前不适合什么场景

About 页和更新中心的关系

常见问题

为什么我在设置页里能看到更新中心，但还是没法用

为什么页面显示任务成功，但线上镜像还是没变

为什么我只有 Docker Compose，按钮没有意义

那普通 Docker Compose 用户现在该怎么升级

相关入口

☸️ K3s 更新中心（高级） ​

配置到底在哪里配 ​

先判断：是否适用 ​

如果你现在只有一个 Docker Compose 容器 ​

如果你正准备从 Docker Compose 迁到 K3s ​

推荐的迁移顺序 ​

一个很重要的认知 ​

那这个功能到底是干什么的 ​

使用它之前，你至少要已经有这些东西 ​

helper 是什么 ​

什么时候你才应该去配 helper ​

K3s / Helm 用户的接入步骤 ​

1. 先部署 Deploy Helper ​

1.1 首次接入前一定要做的自检 ​

1.2 可选：引用已有的环境变量 Secret ​

2. 让主 Metapi 和 helper 用同一个 token ​

3. 在后台“设置 → 更新中心”里填配置 ​

4. 实际操作顺序 ​

4.1 新用户最值得先做的一次确认 ​

这套能力当前不适合什么场景 ​

About 页和更新中心的关系 ​

常见问题 ​

为什么我在设置页里能看到更新中心，但还是没法用 ​

为什么页面显示任务成功，但线上镜像还是没变 ​

为什么我只有 Docker Compose，按钮没有意义 ​

那普通 Docker Compose 用户现在该怎么升级 ​

相关入口 ​

☸️ K3s 更新中心（高级）

配置到底在哪里配

先判断：是否适用

如果你现在只有一个 Docker Compose 容器

如果你正准备从 Docker Compose 迁到 K3s

推荐的迁移顺序

一个很重要的认知

那这个功能到底是干什么的

使用它之前，你至少要已经有这些东西

helper 是什么

什么时候你才应该去配 helper

K3s / Helm 用户的接入步骤

1. 先部署 Deploy Helper

1.1 首次接入前一定要做的自检

1.2 可选：引用已有的环境变量 Secret

2. 让主 Metapi 和 helper 用同一个 token

3. 在后台“设置 → 更新中心”里填配置

4. 实际操作顺序

4.1 新用户最值得先做的一次确认

这套能力当前不适合什么场景

About 页和更新中心的关系

常见问题

为什么我在设置页里能看到更新中心，但还是没法用

为什么页面显示任务成功，但线上镜像还是没变

为什么我只有 Docker Compose，按钮没有意义

那普通 Docker Compose 用户现在该怎么升级

相关入口