用户手册

外观

升级与回滚 ​

Raise 系统的升级与回滚采用向后兼容策略：数据库迁移只向前增加数据表或数据列，不提供反向回滚；遇到异常回滚时，仅需换回上一版本的应用镜像或 Helm Chart。在 Docker Compose 环境下，升级流程依次为数据备份、拉取新版本镜像、执行数据库迁移与重启容器；在 Kubernetes Helm 环境下，升级通过 Hook 机制先执行数据迁移与组件引导，随后按零不可用（maxUnavailable: 0）策略滚动更新 Pod。

谁能用 ​

升级与回滚属于底层系统运维操作，涉及以下角色与权限要求：

角色 / 身份权限与访问要求说明
部署运维人员具备宿主机系统权限（root 或 sudo）或 Kubernetes 集群管理权限负责执行镜像拉取、数据库迁移、服务重启与版本回滚等底层操作。
数据库 Schema 所有者拥有数据库结构变更权限的连接凭据（KWORK_MIGRATE_DATABASE_URL）必须使用 schema 所有者凭据执行数据库迁移，严禁将所有者凭据提供给日常业务运行时。
平台运营人员运营台访问权限升级完成后登录运营台验证服务可用性。运营台未提供升级向导。
租户管理员与组织成员工作台日常使用权限租户端无升级操作界面。系统升级瞬间，正在使用工作台的成员可能会短暂感知到连接重连。

注意

执行数据库迁移必须使用 schema 所有者专用连接串（KWORK_MIGRATE_DATABASE_URL）。运行中的 kwork 主服务仅使用权限受限的 kwork_app 账号，无法也不应执行结构变更。

怎么打开 ​

系统升级与回滚不提供 Web 图形界面，所有操作均在服务器终端或集群管理终端中执行：

  1. BOM 版本清单文件： 查看 deploy/versions.env（记录各组件镜像版本与 digest）。
  2. Docker Compose 部署目录： 进入服务器的 deploy/compose 目录，安装脚本 install.sh 支持重复执行（已完成的步骤会自动跳过）。
  3. Helm 升级命令入口： 在集群管理终端执行：
    bash
    helm upgrade kwork deploy/helm/kwork -n kwork -f my-values.yaml --wait
  4. 离线升级镜像包： 离线部署包中同时包含当前新版本与上一版本的 BOM 镜像。
  5. 升级验收入口：
    • 检查容器运行状态：docker compose ps
    • 检查工作台连通性：curl -I https://app.{base}
    • 检查核心能力接口：curl -s https://api.{base}/api/capabilities
    • 访问运营后台：打开并登录 运营台。

界面一览 ​

Raise 系统未提供前端图形化的升级向导，租户端与运营台均无在线升级操作界面。升级过程在终端中运行，当重新执行 install.sh 安装脚本时，终端会按执行阶段打印以下步骤标识：

终端步骤标识阶段说明
starting postgres and zitadel检查并拉起基础数据库 PostgreSQL 与身份认证中心 Zitadel 服务。
database roles初始化并核对数据库角色与运行权限。
database migrations执行数据库 schema 结构迁移（加表、加列）。
openbao and object storage初始化或更新 OpenBao 密钥策略与 S3 对象存储配置。

常用操作 ​

Docker Compose 常规升级 ​

  1. 查阅发布说明与版本差异： 阅读新版本发布说明，对比 deploy/versions.env 的镜像 digest 变动与数据库迁移列表。
  2. 备份数据与状态： 升级前必须执行全量备份（参考 备份与恢复）。备份 PostgreSQL 数据库，并运行 backup-state.sh 脚本备份状态文件。
  3. 拉取新版本镜像： 在终端执行以下命令：
    bash
    docker compose pull
    若为离线部署环境，通过离线包加载新镜像（离线包内同时包含上一版本 BOM 镜像）。
  4. 执行数据库迁移： 在终端中运行迁移容器，传入 schema 所有者数据库连接凭据：
    bash
    docker compose run --rm -e KWORK_MIGRATE_DATABASE_URL=postgres://kwork:…@postgres:5432/app?sslmode=disable \
  kwork migrate

    破坏性变更处理

    系统的破坏性结构变更严格分两个版本完成：前一个版本先添加新列或新表，后一个版本再清理废弃的旧列或旧表，确保新旧版本代码兼容。

  5. 启动新版本容器： 执行启动命令拉起新容器：
    bash
    docker compose up -d
  6. 验收服务可用性：
    • 执行 docker compose ps 确认所有容器处于正常运行状态。
    • 执行 curl -I https://app.{base} 确认工作台门户响应正常。
    • 执行 curl -s https://api.{base}/api/capabilities 确认开放 API 核心能力接口正常。
    • 登录 运营台，确认运营后台能够正常登录访问。

主机一键升级（Compose） ​

如果采用主机一键脚本部署：

  1. 登录服务器终端，进入 deploy/compose 目录。
  2. 确认已完成数据库与状态文件的备份（参考 备份与恢复）。
  3. 拉取最新代码并执行一键升级命令：
    bash
    git pull && sudo ../setup-host.sh --yes
    脚本会自动重新构建本地镜像、执行数据库迁移，并沿用原有 .env 文件中的全部配置参数滚动重启服务。

重跑 install.sh 脚本升级 ​

在 deploy/compose 目录下重新运行 install.sh 脚本升级系统（脚本已做幂等处理，已完成的步骤自动跳过）：

  1. 启动基础设施：必要时启动 PostgreSQL 与 Zitadel 服务（starting postgres and zitadel）。
  2. 配置角色权限：配置并核对数据库角色（database roles）。
  3. 执行数据迁移：执行数据库结构迁移（database migrations）。
  4. 基础设施引导：附加 --infra 参数完成 S3 对象存储与 OpenBao 密钥管理系统的初始化引导（openbao and object storage）。
  5. 身份中心引导：执行 bootstrap zitadel 引导（该操作具备幂等性，客户端密钥沿用原有配置，不重复生成）。
  6. 启动业务服务：拉起全部服务容器并完成升级。

手工升级关键迁移核对 ​

手工升级或跨版本升级时，必须核对以下关键迁移项：

  • audit/0003：必须由数据库 schema 所有者执行。
  • 0025_uninstall_keeps_settings.sql：升级时必须执行该迁移，若遗漏此迁移，在后续安装应用时会报错 500。
  • 审计对象锁：审计对象锁定功能只能在新建存储桶时启用；已有部署若需启用审计锁，应更换为专用存储桶，不要对旧的分段数据进行迁移。

Helm Chart 升级 ​

在 Kubernetes 集群环境下使用 Helm 进行升级：

  1. 核对并编辑 my-values.yaml 配置文件，确认镜像版本与参数。
  2. 在终端执行 Helm 升级命令：
    bash
    helm upgrade kwork deploy/helm/kwork -n kwork -f my-values.yaml --wait
  3. 系统自动按顺序执行 Hook（Hook 执行顺序与全新安装保持一致）：
    • 执行可选数据库角色初始化。
    • 执行 kwork migrate 数据库迁移。
    • 并行执行 bootstrap s3 与 bootstrap zitadel 初始化引导。
  4. 客户端密钥沿用：
    • Bootstrap 的执行结果保存在 Secret <release>-zitadel-bootstrap 中（该 Secret 在卸载时不会被删除）。
    • 客户端密钥仅在首次创建时返回，后续升级自动沿用（通过 KWORK_BOOTSTRAP_OUT 与 KWORK_ZITADEL_BOOTSTRAP_FILE 机制），密钥不会输出到 Job 日志中。
  5. 滚动更新应用 Pod：
    • 升级采用 maxUnavailable: 0 策略进行平滑滚动，确保升级过程中始终有旧版本副本对外提供服务。
    • 当配置或 Secret 发生变动时，Pod 模板的校验和会同步改变，自动触发 Pod 重启。
  6. 健康探针与平滑下线：
    • 业务 Pod 在 8009 内部端口提供 /livez 存活探针与 /readyz 就绪探针。
    • 容器停止时触发 preStop 生命周期钩子：先休眠 5 s，再执行 20 s 排空。
    • Pod 配置 terminationGracePeriodSeconds: 35，底层集群要求 Kubernetes 版本 ≥ 1.30。

集群扩容与连接数规划 ​

升级时若需要增加服务副本数：

  1. 修改 my-values.yaml 中的副本数配置 kwork.replicas。
  2. 核对 PostgreSQL 数据库最大连接数，确保满足以下约束公式： [ \text{副本数} \times (\text{连接池数} \times \text{database.maxConns} + 1) < \text{max_connections} ]
  3. 重新执行 helm upgrade 命令应用扩容配置。

版本回滚 ​

若新版本上线后遇到异常需要紧急回退：

  1. 回滚原则：
    • 镜像回退：换回上一版本的 BOM 镜像。
    • 数据库迁移不回滚：迁移仅向前加列或加表，新列对旧版本代码无害。各条迁移是否可回退并未逐个核对，因此发版前必须先做好全量备份。
    • 严禁反向撤销：切勿使用 helm rollback 指望撤销数据库 schema 变动，Hook 不会执行反向迁移。
  2. Compose 镜像回滚：
    • 方式一：将 deploy/versions.env 中的镜像 digest 恢复为上一版本 BOM 的旧 digest，执行 docker compose up -d。
    • 方式二：编辑 deploy/compose/.env 文件，将 KWORK_IMAGE 与 GATEWAY_IMAGE 改回上一版本镜像标签，随后执行：
      bash
      docker compose up -d kwork gateway
  3. Helm 镜像回滚： 使用旧版 Chart 与上一版本镜像配置，再次执行 helm upgrade 命令覆盖发布。
  4. 离线包回滚： 离线升级包中已包含上一版本的 BOM 镜像，可直接加载旧镜像并重启。

升级后常规维护 ​

系统升级完成后，根据变动项完成以下常规维护：

  1. 更新 OpenBao 访问策略： 重新运行 install.sh 脚本会更新 openbao-kwork.hcl 策略文件（例如清除凭据操作需要具备 secret/metadata/kwork/cred/* 的 delete 权限）。
  2. Langfuse SSO 客户端核对： 旧部署首次升级到包含 Langfuse 的版本时，系统 bootstrap 引导过程会自动创建该客户端并仅返回一次密钥。
  3. 监控配置生效： 若修改了 otelcol.yaml 或 prometheus.yml，重新运行 install.sh 会自动重启采集器与 Prometheus；若为手动修改，需在终端执行：
    bash
    docker compose restart otel-collector prometheus
  4. PostgreSQL 大版本升级处理： 若升级涉及 PostgreSQL 大版本切换，升级完成后必须立刻执行全量备份，并在配置中更换 BACKUP_S3_PREFIX（参考 备份与恢复）。

状态说明 ​

系统升级过程中的阶段流转与状态说明如下：

Docker Compose 升级流程 ​

备份数据与状态 → 拉取新镜像 (docker compose pull) → 数据库迁移 (kwork migrate) → 启动容器 (docker compose up -d) → 服务验收

Helm 升级流程 ​

可选数据库角色 Hook → 数据库迁移 Hook (kwork migrate) → 组件引导 Hook (S3 / Zitadel) → 滚动更新 Pod (maxUnavailable: 0)

探针与生命周期状态 ​

状态 / 端点端口与配置说明
存活探针（livez）8009 端口 /livez检查应用进程是否处于存活状态。
就绪探针（readyz）8009 端口 /readyz检查应用是否已完成初始化并可接收流量。
平滑下线排空preStop 钩子触发停止后先休眠 5 s，再执行 20 s 排空；配合 KWORK_AGENT_DRAIN_S 等待任务处理完毕。

让助手帮你做 ​

系统升级与版本回滚属于底层服务器与容器集群运维工作，助手未接入任何宿主机或集群的管理指令，无法通过助手在工作台中执行升级、迁移或回退操作。

你可以在日常使用中向助手咨询升级规则与回滚流程，例如：

升级 Raise 前需要备份哪些数据与配置文件？ 为什么数据库迁移不支持反向回滚？ 在 Docker Compose 环境下如何将镜像回退到上一版本？ Helm 升级时如果有 Hook 执行失败，当前正在运行的服务会受影响吗？ 升级服务时对正在使用工作台的成员会有什么影响？

设置 ​

系统没有单独的升级开关图形界面。升级与停机排空相关的系统环境变量如下：

环境变量 / 配置项必填默认值说明
KWORK_MIGRATE_DATABASE_URL执行迁移时必填空业务数据库迁移连接地址。必须使用具备 schema 所有者权限的连接凭据，严禁提供给普通运行时使用。
KWORK_MIGRATE_AUDIT_DATABASE_URL按需配置空审计数据库迁移连接地址。必须由 schema 所有者凭据执行。
KWORK_AGENT_DRAIN_S否60服务下线时 Agent 任务的排空等待时长（秒）。Compose 环境中容器停止宽限期默认为 90 s。

注意事项 ​

  • 所有者凭据权限隔离：数据库迁移必须使用 schema 所有者专用连接串（KWORK_MIGRATE_DATABASE_URL），严禁将其配置给日常业务运行时。运行中的 kwork 主服务仅使用权限受限的 kwork_app 账号。
  • 数据库迁移单向不可回滚：迁移脚本仅向前增加数据表和数据列，不提供回滚。新数据列对旧版本代码无害。发版前必须先完成全量数据备份。
  • 避免短时强行停机：Agent 任务排空等待时间由 KWORK_AGENT_DRAIN_S 控制（默认 60 s），Compose 停止宽限期默认为 90 s。切勿在终端执行 docker stop -t 10 强行短时停止容器，否则会导致排空不彻底。
  • 升级对在线业务的影响：
    • 服务切换瞬间，工作台可能会短暂提示「连接中断，正在重新连接…」。
    • 知识库同步可能短暂出现 1012 状态。
    • 助手正在写入的单步操作会尽量在排空时间内写完；若超时未完成，将在心跳恢复后重新执行。
  • 商业许可生效差异：修改许可证（License）时，席位配额、应用列表与到期时间支持热更新；但许可证中的「模块」与「功能」仅在服务启动时读取，修改后必须重启服务才能生效。
  • 多副本启动重试保护：多副本并发启动时，内置应用发布遇到冲突会自动重试。
  • Kubernetes 部署配置要求：
    • 必须设置 enableServiceLinks: false，否则名为 kwork 的 Service 会自动注入 KWORK_PORT 等环境变量，与系统配置发生冲突。
    • 网关证书 PVC 标记了 helm.sh/resource-policy: keep，卸载 Helm release 时不会被删除。
    • Helm 升级过程中任一 Hook 失败，整次 release 升级即宣告失败，正在运行的旧版本服务保持不变。

目前不支持 ​

  • 无图形化升级向导：运营后台未提供升级向导或在线升级操作按钮，所有升级均通过终端命令行或 Helm 执行。
  • 无自动蓝绿与金丝雀发布：自动蓝绿发布与金丝雀发布未作为产品功能提供。
  • Helm 不支持托管 ISV 运行时：Helm 部署形态不支持托管 ISV 运行时（目前仅提供 Docker 适配器）。
  • Helm 部分场景未经验证：在 Helm 部署形态下，Agent 走完登录流程、真实负载均衡与 ACME 证书集成、多节点排空、网关多副本运行，文档明确标明未在真实集群上进行验证。

常见问题 ​

升级遇到问题需要回退时，数据库迁移可以一起回滚吗？ ​

不能。Raise 的数据库迁移只向前增加数据表或数据列，不提供反向回滚；新增加的列对旧版本代码无害。回滚时仅需换回上一版本 BOM 镜像或旧版 Helm Chart。在发版与升级前，必须先完成全量数据备份。

执行 Helm 升级时，如果某个 Hook 失败会发生什么？ ​

Helm 任一 Hook 失败时，整次 release 升级宣告失败，正在运行的旧版本 Pod 保持不变，不会中断当前业务。注意切勿使用 helm rollback 指望撤销数据库结构变更，Hook 不会执行反向迁移。

升级服务切换时，终端用户端会有什么感知？ ​

在服务切换瞬间，工作台可能短暂显示「连接中断，正在重新连接…」；知识库协同可能短暂出现 1012 状态；助手正在处理的单步操作会尽量在排空期内完成，超时未完成的任务会在心跳恢复后重跑。

为什么执行数据库迁移不能使用运行时的数据库连接？ ​

数据库迁移需要执行建表、加列等结构定义操作，必须使用具备 schema 所有者权限的连接凭据（KWORK_MIGRATE_DATABASE_URL）。为了保障生产环境最小权限安全，运行中的 kwork 主服务仅拥有权限受限的 kwork_app 账号，不能持有所有者凭据。

升级后修改了许可证（License），为什么新增的功能没有出现？ ​

许可证中的席位配额、应用授权清单与到期时间支持热更新，但其中启用的「模块」与「功能」仅在服务启动时读取。若修改了许可证中的模块或功能配置，必须重启服务方可生效。