从 Kuboard v3 迁移到 v4
Kuboard v3 与 v4 是两套独立产品，不能原地升级。v4 内置了「从 v3 迁移」向导，可以把 v3 的用户、用户组、角色、第一阶段授权（Kuboard 授权）以及品牌 / 登录策略迁移过来，并读取各集群的 Kubernetes RBAC（第二阶段授权） 自动转换为 v4 的授权规则。
集群本身需要在 v4 中重新导入，且集群凭据必须由您重新提供（v3 出于安全不在接口中返回 kubeconfig / Token）。
一句话
可以用向导迁移「人」和「权限」；集群凭据、授权文件、MFA、访问密钥需要重新配置。
v3 与 v4 可以并存部署
迁移期间，v3 与 v4 可以并存运行，互不影响：
- 部署层面：v3 使用内置存储，v4 需要独立的数据库实例（MySQL / MariaDB / OpenGauss 三选一）。可以部署在不同服务器 / 容器，也可以部署在同一 Kubernetes 集群的不同名称空间，使用不同域名访问。
- 集群层面：同一个 Kubernetes 集群可以同时导入 v3 和 v4，两个版本都可以正常管理该集群。
- 同名集群：集群在 v3 与 v4 中名字相同时，套件不受影响；名字不同时，套件资源仍在集群中，但需要在 v4 中重新执行初始化 / 激活流程。
文档站安排
v3 的老文档站将迁移到独立域名 v3.kuboard.cn，与 v4 文档站（本网站）分离，便于 v3 用户继续查阅历史资料。
迁移前准备
请在开始迁移前准备好以下信息：
| 准备项 | 说明 |
|---|---|
| v3 访问方式 | v3 的地址（协议://主机[:端口]，不要带路径）。若 v3 使用自签证书，迁移时勾选「跳过 TLS 证书校验」 |
| v3 管理员凭据 | 首选「用户名 / 密码」模式（需 v3 管理员账号，能读取全部用户与权限）；账号开启双因子认证时还需要 6 位验证码 |
| v3 访问密钥（可选） | 若 v3 使用外部 SSO / LDAP 等登录方式，密码模式可能不可用，请在 v3「个人信息 → 访问密钥」创建 AK/SK，迁移时用「访问密钥」模式 |
| 各集群的 kubeconfig 或 ServiceAccount Token | v3 不会返回集群凭据，需要您为每个集群准备一份可直连 apiserver 的凭据；v3 的 agent 集群必须额外提供可访问的 apiserver 地址 |
| 集群 RBAC 读权限 | 二阶段授权需要读取集群内 RoleBinding / ClusterRoleBinding。凭据至少需要 list 这些资源的权限，否则向导会提示「该集群无法自动迁移集群授权」，可跳过 |
| v4 授权文件 | v3 授权不能用于 v4，请提前为 v4 申请 |
| v4 配置备份 | 建议迁移前在 v4 做一次「配置备份」导出，便于失败时回滚 |
使用迁移向导
登录 v4 → 系统管理 → 设置 → 从 v3 迁移，按 7 个步骤操作：
- 连接 v3：填写 v3 地址与凭据，点击「测试连接」。向导会显示 v3 中的用户 / 用户组 / 角色 / 绑定 / 集群数量（数量是下界：只统计当前账号有权限读取的对象）。
- 选择内容：默认全选。不可迁移项会灰显并说明原因。
- 集群凭据：为每个 v3 集群填写 kubeconfig 或 ServiceAccount Token，逐行校验（或「全部校验」）。可以显式跳过某个集群。
- 集群授权（二阶段）：向导读取各集群的 Kubernetes RBAC，按 v3 的用户 / 用户组翻译成 v4 角色与组角色绑定。默认勾选已匹配主体的行，可逐行取消；未匹配主体可以手工映射到 v4 已有用户组。
- 差异预览：显示「将新建 / 更新 / 无变化 / 冲突 / 跳过」的完整清单与「需人工处理」项。此时尚未写入 v4。
- 执行迁移：二次确认后先导入集群，再写入用户 / 组 / 角色 / 绑定。二阶段授权在独立事务里执行，失败会整体回滚并给出重试入口。
- 迁移报告：列出已迁移、已跳过、需人工处理、不支持项与后续动作；可下载 JSON 报告与 v4 配置快照。
幂等
整个向导可以重复执行：已存在的对象以「无变化」为主，不会重置已存在用户的密码，也不会重复创建角色 / 绑定。建议在所有校验通过后一次执行完成。
迁移期间请不要让用户开始使用 v4
重复执行会以 v3 的数据为准生成差异；如果用户已在 v4 中修改过权限，再次导入旧数据可能覆盖这些修改。
迁移后必做
| 事项 | 说明 |
|---|---|
| 通知用户修改密码 | 迁移用户的初始密码统一为 Kuboard123，首次登录会被强制修改密码 |
| 补齐集群凭据 | 迁移时未提供凭据或校验失败的集群，需要在 v4「集群管理」中补充 kubeconfig / Token 并等待全量同步完成 |
| 复核二阶段授权 | 报告中的「降级规则 / 聚合角色 / 未匹配主体」需要人工在 v4 手工补授权 |
| 重新配置 SSO / LDAP / OIDC | v3 的登录集成不会迁移，需要在 v4「系统设置 → 用户登录设置」重新配置 |
| 重新申请并导入授权文件 | v3 授权文件不能用于 v4 |
| 重新绑定 MFA | MFA 不迁移，用户需在「个人信息」中重新绑定 |
| 重建访问密钥（AK/SK） | v3 访问密钥不迁移（管理员无法批量读取），需在 v4「个人信息 → 访问密钥」重新创建，并更新 MCP / CI 配置 |
| 重新配置审计策略 | v3 的审计策略与历史日志不迁移；需要时请在 v4 重新配置 |
| 验证 | 用普通用户验证：登录、改密、查看集群 / 名称空间、打开终端与日志（依赖 WebSocket）；确认无误后再下线 v3 |
不支持迁移的内容
以下内容在 v3 中没有可读接口，或在 v4 中没有对应实现，迁移后需要手工重建：
| 事项 | 原因 | 您需要做什么 |
|---|---|---|
| v3 授权文件（License） | 产品策略：v3 / v4 授权不通用 | 为 v4 单独申请并导入授权 |
| 用户密码 | v3 API 不返回密码 | 使用初始密码登录并立即修改 |
| 双因子认证（MFA） | v3 明文种子 / 恢复码与 v4 的 TOTP + bcrypt 不兼容 | 用户在 v4 重新绑定 |
| v3 访问密钥（AK/SK） | 属于 v3 用户作用域，管理员无法批量读取 | 在 v4 重新创建，更新 MCP / CI 配置 |
| 审计策略 / 审计日志 | 结构与存储不同（v3 历史日志在时序库） | 在 v4 重新配置策略；历史日志按需单独归档 |
| 访问网关（KuboardAccessGate） | v4 没有对应功能 | 接受该项丢失 |
| SSO / LDAP / OIDC 配置 | v3 通过环境变量 + 内置 SSO，v4 为独立的登录来源配置 | 在 v4 重新配置 |
| 用户偏好（默认页 / 收藏 / act-as） | v4 没有对应存储 | 用户重新设置 |
| K8s 对象缓存 / 套件状态 | 缓存可从 apiserver 重建；套件状态保存在集群内 | 等待 v4 同步完成；套件按安装文档重新初始化 |
集群 RBAC 中无法表达为 v4 授权的规则也会跳过（迁移报告会列出），包括：
- 使用
resourceNames限定具体资源名的规则； nonResourceURLs（如/healthz、/metrics）等非资源型权限；use/bind/escalate/impersonate等 v4 不支持的动词；- 空规则、依赖
aggregationRule动态聚合的角色（通常需要人工确认后重建）。
这些情况下宁可少授权，不会越权，请在迁移报告的「需人工处理」里逐项补齐。
集群名长度
v4 的集群编辑页要求集群名 3–24 个字符。v3 的集群名如果超出范围，迁移可以成功（直写数据库），但在 v4 界面编辑前需要先改名。
v3 授权与 v4 授权相互独立
v3 授权文件与 v4 授权相互独立：v3 的授权不能导入 v4，v4 的授权也不能用于 v3。迁移到 v4 时，需要为 v4 单独获取并导入授权；v3 与 v4 并存期间，两者各自需要自己的授权。免费版与增强版的功能差异，参见 许可与支持。
迁移失败与回滚
- 迁移前：在 v4 做一次「配置备份」导出（保留当前状态的快照），v3 保持运行。
- 迁移失败：
- 元数据导入是单事务，失败整体回滚；
- 集群导入逐集群隔离，失败的不入库，可在报告中看到原因；
- 二阶段授权导入整体回滚（默认），不影响已导入的元数据。
- 需要完全回退：
- 用「配置备份」导入迁移前的快照（
replace模式 + 覆盖会删除迁移新增的对象，请先确认影响范围）； - 或直接重建 v4 数据库（迁移工具只读 v3，v3 不受影响）。
- 用「配置备份」导入迁移前的快照（
- v3 下线：确认所有用户可登录、集群同步正常、二阶段授权核对完成之后再下线 v3。
常见问题
Q：迁移向导连不上 v3？ 请确认是 v4 后端能访问 v3（不是浏览器）；v3 使用自签证书时勾选「跳过 TLS 证书校验」；地址只填协议、主机和端口。
Q：v3 使用 SSO / LDAP 登录，密码模式不可用？ 改用「访问密钥（AK.SK）」模式，在 v3 的「个人信息 → 访问密钥」创建后填入。
Q：集群校验失败？ 确认 kubeconfig / Token 完整、apiserver 地址从 v4 后端可访问、自签证书勾选「跳过主机名校验」。v3 的 agent 集群必须提供可直连 apiserver 的凭据。
Q：集群校验成功，但提示「无法读取 RBAC」？ 该凭据缺少读取 RoleBinding / ClusterRoleBinding 的权限，二阶段授权无法自动迁移。可以跳过该集群的集群授权，或换一个有 RBAC 读权限的凭据后重新读取。
Q：迁移后用户登录却看不到资源？ 请确认：用户所在的组已启用、组已绑定角色、且迁移报告中的二阶段授权已核对。若刚完成迁移，可刷新页面或请管理员在「平台健康诊断」清一次权限缓存后重试。
Q：迁移会覆盖 v4 现有的 admin 账号吗？ 不会。v3 的内置 admin 会被跳过，v4 的 admin 与已存在用户都不会被重置密码。
版本升级 vs 版本迁移
两个概念容易混淆，请注意区分：
- v4 内部升级（v4.x → v4.y）：更换镜像标签即可，数据库由 v4 自动迁移，参见 升级 Kuboard；
- v3 → v4 迁移（本文）：两套独立产品之间的迁移，使用迁移向导 + 手工补齐不支持项，不存在原地升级通道。
相关文档
- 安装 Kuboard v4 —— 安装、数据库准备、环境变量、反向代理与高可用参数
- 快速开始 —— docker compose 快速拉起一个 v4 实例
- 升级 Kuboard —— v4 内部版本升级
- 高可用部署 —— v4 高可用部署
- 反向代理 —— Nginx / Ingress 配置与 WebSocket 放行
- 使用指南 —— v4 功能总览（集群、工作负载、套件市场等）
- 许可与支持 —— v4 免费版 / 增强版功能对比
