存量 OpenWork 部署如何安全完成 Gateway 数据库迁移与镜像升级【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork如果你已经运行着一套 Den/Models 或旧版 inference 部署现在要升级到支持 OpenWork Gateway 的发行版最大的风险不在 Helm 命令本身而在数据库迁移0097_gateway_access_matrix会重命名正在使用中的表和列它不是在线迁移也不是原子、可滚动兼容的迁移。在迁移前必须让所有读写方静默quiesce并让它们一直停止到 schema 验证和配套镜像上线完成为止。本文基于仓库内的 升级指南、Gateway 启用文档 和 Helm chart 文档 给出这条完整路径钉住配套发行版 → 准备与维护窗口前备份 → 静默切换中按序执行迁移 → 验证 schema 与能力契约 → 重开流量。为什么默认迁移 Hook 不能直接用于存量库Helm chart 默认启用一个pre-install,pre-upgrade迁移 Job运行node /app/ee/packages/den-db/dist/scripts/bootstrap.js这个默认路径对存量库有具体缺陷升级前必须理解时序不安全pre-upgrade Hook 在更新后的 Deployment 应用之前运行此时旧 Pod 仍在读写数据库。它不会排空模型请求、OAuth 回调、refresh worker、后台写入或 retention 任务。设置migrations.hook: false也不是解法普通 Job 同样建立不了“先迁移、再发版”的屏障Helm 的超时、重试和自动回滚都无法撤销 MySQL 的 DDL。bootstrap 基线隐患对于没有__drizzle_migrations台账的既有 schema当前 bootstrap 会把所有已提交迁移直接记为“已应用”不检查现有 schema 是否真的包含这些变更——可能把0097及其后续迁移标记为已执行而未执行。Hook 成功或台账有记录都不等于 schema 正确。因此对存量库必须在 values 中关闭 chart 自动迁移 Job改用外部受控的迁移流程migrations: enabled: false这是编排选择不是跳过迁移的许可——外部流程完成、receipt 与 schema 都检查通过之前不要上线新 runtime。备份/恢复与流量屏障保持在运维人员手中而不是交给盲目的helm upgrade --atomic。另外注意一个容易被忽略的配置点只要迁移 Job 启用它就从既有的secret.keys.databaseUrl映射获取 TCP MySQLDATABASE_URL、从secret.keys.denDbEncryptionKey获取DEN_DB_ENCRYPTION_KEY与config.databaseMode无关。即使你用 PlanetScale HTTP 模式DATABASE_HOST/DATABASE_USERNAME/DATABASE_PASSWORD预创建的 Secret 也必须为同一个数据库额外提供映射用的 TCP URL含库名、端口和经过验证的 TLS 选项。chart 没有暴露 bootstrap 的替代DATABASE_NAME/DATABASE_PORT配置项。准备条件钉住一个自洽的发行版镜像与 chart 版本要配套使用0.2.0或包含该实现的后续版本引入的 Gateway-capable chart 实现并搭配同一发行版的 Den API、Den Web、Gateway 镜像。该实现提供认证部署能力契约version: 1。不要根据数字更大的 chart 版本、旧的 stable 标签或仓库中的占位appVersion: 0.1.0推断镜像支持情况。钉住共享的image.tag并检查所有组件级覆盖denApi.image.tag、denWeb.image.tag以及生效的gateway.image.tag/inference.image.tag。非空组件 tag 优先于共享 tag共享 tag 优先于Chart.appVersion。retention 任务也使用生效的 Gateway 镜像。资源名不变保持已安装的 release 名、*-inferenceService/Deployment/容器名和选择器、以及ghcr.io/different-ai/openwork-inference镜像仓库名不变。产品命名已改为 OpenWork Gateway但已安装的资源标识符没有改名。den-gateway是另一个 Web 代理组件不是 Gateway 的替代镜像。维护窗口前完成五件事清点所有共享数据库的读写方Den API、Gateway/旧 inference、OAuth 回调与 refresh worker、管理脚本、retention 调用方以及已安装镜像、当前 values、数据库版本/模式、迁移台账和实际 schema。确认切换期间没有旧副本或 controller 会自动重启。备份数据库并安全保留现有加密密钥。在隔离环境中验证可恢复。保留行数、schema/台账证据、加密的凭据与用量历史同时避免暴露敏感列。在隔离的恢复副本上演练迁移使用所选发行版的确切 SQL 和已批准的 runner。迁移源码或 journal 注册记录不能证明生产数据能过 preflight。审阅完整的前置 schema 与已注册迁移0096前置 schema 以及0097、0098、0099以及所选发行版附带的所有后续迁移。schema-push 型数据库只有在完整 schema 验证通过后才允许做基线不能凭“表存在”猜测。准备一套完整、审阅过的 values包含migrations.enabled: false、预创建 Secret 引用、显式 destination、配套镜像以及对组件保留与能力启用的明确选择。如需删除已保存的 canonical 条目用--reset-values加这套完整配置而不是最终空覆盖文件或--reset-then-reuse-values。渲染最终结果并确认其中不含 Secret 明文。迁移执行器的硬性要求针对0097runner 必须使用单一专用 MySQL 连接按-- statement-breakpoint边界顺序执行语句并在第一个错误处停止。要求MySQL8.0.16含 8.4支持 enforced CHECK严格 SQL 模式STRICT_TRANS_TABLES或STRICT_ALL_TABLESCREATE TEMPORARY TABLES权限和普通迁移 DDL/DML 权限MariaDB 和 TiDB 会被显式拒绝无法保持连接级临时表的 serverless/HTTP 传输不满足要求——选择已审阅的迁移连接而不是绕过 preflight。仅配置运行时planetscale模式不构成验证。0097 内嵌的 preflight 会在任何持久 DDL 之前检查完整的前置 schema、索引、ID、属主、凭据 subject 和 grant 受众并拒绝重复或双受众 grant不会静默合并或删除。精确的 sentinel 与保留规则见所选发行版内的 0097 迁移契约——请使用你钉住发行版中的副本而不是未审阅的移动分支。静默切换按顺序执行的七步建立维护屏障在 ingress 和其他调用方处阻断新请求排空活跃流与 OAuth 任务停止所有相关应用读写方暂停 retention/后台任务。仅有数据库迁移锁挡不住应用写入方。确认备份与迁移起点状态遗留 schema 必须先达到经验证的0096才能应用0097已迁移或部分迁移的 schema 需要显式检查而不是重放。真正为空的数据库可以用配套发行版的 current-schema 快照初始化但不能与“缺台账的存量库”混淆。执行已批准的迁移流程先执行带内嵌 preflight 和上述连接要求的0097再按顺序执行0098_gateway_provider_model_universe和0099_gateway_credential_set_creator以及发行版要求的其他前置迁移。保持旧写入方停止——0098还会回填旧代码不维护的模型策略。验证实际 schema、保留数据与 receipt只有某条迁移的全部 SQL 成功后才记录该迁移。检查 canonical Gateway 表与选择列、gateway_providers.model_ids、gateway_credential_sets.created_by_org_membership_id——而不是只做select 1或看台账时间戳。在流量仍关闭时部署配套镜像Den API、Den Web、Gateway 使用同一发行版镜像并保持migrations.enabled: false。按 Gateway 启用文档 检查 sparse values 与必需的 Secret 引用。验证存活/就绪以及能力契约检查 liveness/readiness 后用认证请求检查每个 API 副本顶层的GET /v1/org响应中的deploymentCapabilities契约。opt-in 场景期望{ version: 1, aiGateway: true }同时确认目标组织的 dashboard grant 与新的 admin 访问。注意readiness 和能力响应不是schema 证明。用非敏感测试数据演练一个允许的 provider 流程验证桌面路由public与内部路由核对用量归因。全部通过后才能重开流量已批准的 retention 与后台任务最后恢复。迁移中途失败的处置如果内嵌 preflight 在第一条持久 DDL 之前失败关闭连接以丢弃其临时表调查被点名的检查项按已批准的保留方案解决。如果失败发生在第一次 rename 之后停止启动并检查部分状态。MySQL DDL 自动提交——失败的 Job 或进程重启都不会回滚。不要盲目重试、schema-push、盖基线也不要让任何不兼容的 runtime 对着部分表启动。预期保留的数据状态既有 provider、凭据身份、加密凭据值、grant 和用量历史由迁移的显式回填/重命名保留DEN_DB_ENCRYPTION_KEY必须保持不变。既有 provider grant 获得迁移的默认 group/set 映射历史用量的选择字段保持 unknown/null而不是被归因到虚构的选择。缺少新 set/client 绑定的未使用遗留 OAuth state 被标记为已用成员需重新发起这些登录流程但已有凭据不会被删除或吊销。Gateway 的gateway_keys初始为空成员通过常规 connect/provisioning 流程获得独立的ow_gw_前缀密钥既有 Models 的ow_inf_密钥不会被复制进去。Models 的密钥、订阅计费、限额、用量分桶和台账保持独立保留OPENWORK_INFERENCE_BASE_URL、STRIPE_INFERENCE_PRICE_ID与config.inference.*这些遗留契约不动。升级后的限制与回退边界升级完成后有两条硬性边界需要记住禁用不等于回滚 schema。想关闭能力时按意图选择操作隐藏某个组织的 dashboard、设置GATEWAY_ENABLEDfalse保留组件、或gateway.enabled: false删除组件这些开关保留已持久化的 Gateway 数据但不是凭据吊销手段也不是 schema 回滚。详见 升级指南的禁用章节。不要对已重命名的 schema 执行helm rollback回到迁移前的旧镜像。恢复路径只有两条用兼容镜像向前修复fix forward或使用单独批准的、静默状态下的数据库加镜像恢复从经验证的备份恢复。恢复会丢失备份点之后的写入并需处理凭据、用量与计费对账在 schema 与所有读写方再次一致之前保持流量关闭。就绪验证有边界/health只证明进程存活Gateway/ready只执行select 1检查数据库连通性——它不证明Gateway schema 或迁移存在。能力响应同样不是 schema 健康证明。迁移 receipt 和实际 schema 必须单独验证之后再用已批准的非敏感数据测试一个授权的 provider 路径才允许重开流量。文档明确提醒README、渲染出的 chart、健康的 Pod 或已注册的迁移都不构成生产迁移 receipt核对材料时一律以所选发行版内的文件为准。完成上述验证schema 检查、deploymentCapabilities契约、provider 流程演练并逐副本确认一致后这次存量升级才算真正结束——重开流量是最后一个动作不是第一个。【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考