从 Kuboard v3 迁移到 v4
Kuboard v3 与 v4 是两套独立产品，不能原地升级。集群需要重新导入 v4，用户 / 授权 / 套件 / 配置需要在 v4 重建。
本文与 安装 Kuboard v4 中的"致 Kuboard v3 用户"一节相互衔接，那里介绍了基本兼容性结论，本文给出具体迁移步骤。
v3 与 v4 可以并存部署
迁移期间，v3 与 v4 可以并存运行，互不影响：
- 部署层面：v3 与 v4 相互独立。v3 使用内置存储，v4 需要独立的数据库实例（MySQL / MariaDB / OpenGauss 三选一）。可以将两者部署在不同的服务器或容器中，也可以部署在同一 Kubernetes 集群的不同名称空间，使用不同的域名访问。
- 集群层面：同一个 Kubernetes 集群可以同时导入 v3 和 v4，两个版本都可以正常管理该集群。
- 同名集群：如果集群在 v3 与 v4 中的名字相同，套件不受影响，在 v3 / v4 中都可以正常使用；若名字不同，套件资源仍在集群中，但 v4 中需要重新执行套件的初始化 / 激活流程。
文档站安排
v3 的老文档站将迁移到独立域名 v3.kuboard.cn，与 v4 文档站（本网站）分离，便于 v3 用户继续查阅历史资料。
v3 授权与 v4 授权相互独立
v3 授权文件与 v4 授权相互独立：v3 的授权不能导入 v4，v4 的授权也不能用于 v3。迁移到 v4 时，需要为 v4 单独获取并导入授权；v3 与 v4 并存期间，两者各自需要自己的授权。免费版与增强版的功能差异，参见 许可与支持。
TIP
在 v4 界面导入授权文件后，可在授权列表页面查看状态（有效 / 无效 / 已过期），确认导入成功后再进行后续操作。
迁移路径建议
迁移路径属于操作建议，请结合您的环境验证后执行。
部署 v4 实例并初始化 按 安装 Kuboard v4 准备数据库（MySQL / MariaDB / OpenGauss 三选一），按 快速开始 或 高可用部署 启动 v4。使用默认管理员
admin（默认密码Kuboard123）登录后，立即修改密码。导入集群 在 v4 界面执行集群导入。建议集群名与 v3 中保持一致，这样套件在 v3 / v4 中都可以正常使用；导入后先核对集群状态与同步是否正常。
重建工作负载视图与集群资源配置 在 v4 中重新配置节点、名称空间、工作负载的展示与访问。检查 v3 中使用过、但 v4 中尚未验证的资源类型（存储类、Ingress、网关等）在 v4 中是否正常展示。
套件兼容检查 进入 v4 的套件市场，检查所需套件是否可安装 / 激活；如需执行初始化脚本（如 CRD、RBAC），按套件文档完成初始化后再激活。
迁移用户与权限 在 v4 中重新创建用户、用户组并配置授权规则。v4 的授权模型与 v3 不同，按 v4 的授权方式重新配置，见下文"需要手动调整的事项清单"。
验证 使用普通用户账号验证：登录、查看集群、操作工作负载、打开终端与日志（依赖 WebSocket，检查反向代理已放行）等；验证审计日志与 MCP（如使用）链路正常。
下线 v3 全部功能验证通过后，再逐步下线 v3 实例。不建议在未完成验证前停止 v3，两个版本并存部署的成本很低。
需要手动调整的事项清单
以下事项在 v4 中没有自动迁移通道，需要手工完成：
| 事项 | 说明 |
|---|---|
| 管理员与用户体系 | v4 的初始管理员为 admin（默认密码 Kuboard123），与 v3 用户无关 |
| 用户 / 用户组 | 需在 v4 中重新创建用户、用户组并配置授权规则 |
| 授权规则 | v4 使用更简洁的授权模型（kuboard 级 / 集群级授权规则），需按 v4 的方式重新给用户授权 |
| 集群导入 | 集群需要重新导入 v4，v4 会重新做全量同步 |
| 授权文件 | v3 授权文件不能用于 v4，需要为 v4 单独获取并导入授权 |
| 套件初始化 | 同名集群下套件不受影响，但 v4 中仍需按向导完成套件的安装 / 初始化 / 激活 |
| 外部用户库 | 如 v3 中集成了 LDAP 等外部用户库，v4 中需重新配置集成 |
| 反向代理 / HTTPS / WebSocket | v4 必须挂在根路径，终端与日志功能依赖 WebSocket，需要重新配置反向代理（Nginx / Ingress） |
| 密码策略与 MFA | 如 v3 中启用了密码过期、双因子认证（MFA）等策略，需要在 v4 中重新设置 |
常用迁移对照表
| Kuboard v3 | Kuboard v4 | 说明 |
|---|---|---|
| 应用商店 / 套件 | 套件市场 | v4 兼容 v3 版本的套件；安装的套件以集群内资源的形式存在 |
| 集群管理 | 集群管理（导入、编辑、同步状态） | 同一集群可同时导入 v3 与 v4，同名集群套件不受影响 |
| 工作负载 | 工作负载管理 | v4 覆盖 v3 的主要功能，支持跨集群 / 名称空间列表与模糊查询 |
| 容器终端 / 日志 | 终端与日志 | 需保证反向代理放行 WebSocket |
| 访问集群内服务 / Pod 端口 | KuboardProxy | 功能对应，配置方式见使用指南 |
| 持续部署 / 更新镜像 | 持续交付（更新镜像标签、重启工作负载） | v4 提供对应功能 |
| v3 用户 / 权限 | v4 用户 / 授权规则 | 授权模型不同，需重新配置，不能迁移 |
| v3 授权文件 | v4 授权 | 相互独立，需单独导入 v4 授权 |
| 内置存储 | MySQL / MariaDB / OpenGauss | 存储层完全不同 |
| 单机部署 | 单机或高可用部署 | v4 支持高可用，参见 高可用部署 |
TIP
表中未列出的 v3 功能，请以 v4 实际界面与 使用指南 为准逐项核对。
版本升级 vs 版本迁移
两个概念容易混淆，请注意区分：
- v4 内部升级（v4.x → v4.y）：更换镜像标签即可，数据库由 v4 自动迁移，参见 升级 Kuboard；
- v3 → v4 迁移（本文）：两套独立产品之间的迁移，不存在原地升级通道，必须按本文步骤执行。
相关文档
- 安装 Kuboard v4 —— 安装、数据库准备、环境变量、反向代理与高可用参数
- 快速开始 —— docker compose 快速拉起一个 v4 实例
- 升级 Kuboard —— v4 内部版本升级
- 高可用部署 —— v4 高可用部署
- 反向代理 —— Nginx / Ingress 配置与 WebSocket 放行
- 使用指南 —— v4 功能总览（集群、工作负载、套件市场等）
- 许可与支持 —— v4 免费版 / 增强版功能对比