CKMAN 4.0.0 发布｜重新设计备份与恢复，引入用户体系、节点级配置、SQLite 本地存储与全新文档站

CKMAN（ClickHouse Manager）4.0.0 是一次 架构级 版本升级。我们重做了备份/恢复模块、重构了任务运行时、引入了用户角色体系、单节点配置覆盖能力、Nacos 配置热重载、SQLite 本地持久化，并把整个文档站迁到了 VitePress。本文带你过一遍这次版本里最值得关注的变化，以及升级 / 降级的注意事项。

📦 下载地址：https://housepower.github.io/ckman/zh/download 📚 在线文档：https://housepower.github.io/ckman/

一、🗄️ 备份与恢复：从「定时脚本」走向「任务化引擎」

这是 4.0.0 投入工程量最大的模块。3.x 时代的备份基于 cron + 直接调用 ClickHouse 完成，存在状态不可见、跨节点重复执行、checksum 受网络抖动影响等顽疾。4.0.0 我们把整套备份/恢复 重写为一个独立服务：

1. 新的数据模型与执行模型

BackupPolicy / BackupRun 两层模型：策略（"什么时候、备什么、备到哪儿"）与运行（"这一次到底发生了什么"）彻底分离，台账可追溯。
partition 级隔离：Backup / Restore / Check 都按 partition 串行写状态机，单个分区失败不会污染整个 Run。
Executor + Storage 抽象：S3 与 Local 两种 storage 后端开箱即用，新增后端只需实现 Storage 接口。
Pool + Scheduler + Service 三件套：worker pool 承载实际备份执行，Scheduler 周期性 Reconcile 调度，Service 提供 HTTP 入口。

备份策略列表 — 含立即/定时、daily/增量、指定执行实例等新模型能力

新建一条备份策略时，daily 模式 / 增量方式 / 指定执行实例 / cron 表达式 / S3 目标都在同一张表单里完成：

新建备份策略 — daily / 增量 / 指定执行实例 / cron / 时间范围 / S3 目标

恢复时按"来源 Runs 预览 + 分区级勾选"操作，避免误恢复，单分区也能精确捞回：

新建恢复 — Runs 预览 + 分区级勾选

2. 关键能力

能力	说明
一次提交 = 一个任务	BackupPolicy 关联 TaskID/TaskName，前端可在任务中心查看进度
指定执行实例	多 ckman 集群部署下，定时备份固定到指定节点执行，避免 checksum 跨区拉满带宽
拒绝重复定时备份同一张表	提交期校验，避免无效任务堆积
S3 endpoint 自动去尾斜杠	修复多个版本下 URL 拼接出 `//` 导致 sign 校验失败的老坑
daily 模式 partition_key 校验	提交期就告诉你这张表能不能用 daily，不再让你等到运行时报错
compression!=none 跳过 md5	压缩归档自身已带完整性，避免无意义比对
markFailed 同步标记残留分区	Executor 异常中断时，未走完的 partition 不再永远停在 RUNNING
DeleteRun 仅删 ckman 台账	远端归档保留，删错不丢数据

二、👤 用户与角色管理（Phase 1）：告别明文 user.yml

3.x 的用户是写在 users.yml 里的明文 + bcrypt hash，多实例部署下同步是个痛点。4.0.0：

用户存储下沉到持久化层：local（SQLite）/ MySQL / PostgreSQL / DM8 四种后端同时实现。
登录走 DB：返回 policy / enabled，禁用账号一律拒绝登录。
首次启动种子默认 admin，密码同 3.x 默认（详见在线文档"安装与初始化"页）。
用户管理 UI 完整接入：列表 / 新建 / 编辑 / 删除 / 改密 / 启停。
退役 cmd/password 命令行工具，统一从 UI 走。

用户管理列表 — admin / 普通用户 / 游客三种角色 + 启用开关 + 创建时间

新建账号时，角色 / 启用状态 / 密码确认都在一个弹窗里完成，不再需要任何 yml 配置或 CLI 干预：

新增用户弹窗 — 角色 + 启用开关 + 密码确认

三、🧩 单节点配置覆盖（Per-Node Override）

3.x 集群下所有节点共享一套 config.d/*.xml，遇到"只想让某台节点放开 max_memory_usage"这种需求只能 SSH 手改、再被下次重新部署覆盖掉。4.0.0：

在集群模型中新增 NodeOverrides，按节点维度持久化 XML 片段；
提供 GET / PUT / DELETE /api/v1/ck/node/override 三个端点；
调用 SYSTEM RELOAD CONFIG 实现热生效，无需重启；
部署时自动保留 config.d/node_override.xml，重新部署不会清掉这个文件；
前端提供按节点的 XML 编辑器（深色主题 + 代码字体 + XPath 提示）。

单节点个性化配置 — 「表格 / XML 高级」双 tab，XML 编辑器深色主题

四、🔁 Nacos 配置中心 + 热重载

多实例 ckman 想统一改配置？以前要 SSH 到每台机器改 ckman.hjson 再重启。4.0.0：

启动时从 Nacos 拉取配置，按 section 与本地 ckman.hjson 合并；
接入 applier registry，三类热重载入口（日志级别、ClickHouse 连接池、备份调度）；
bootstrap 字段（监听端口等）变更不热生效，WARN 日志提示需要重启；
配置内容格式按本地文件扩展名解析（兼容 hjson / yaml）。

五、💾 本地持久化层切换到 SQLite

local 后端从早期"裸 JSON 文件"升级为 纯 Go 实现的 SQLite（基于 glebarez/sqlite，无 cgo 依赖，单二进制依旧）：

第一次启动自动一次性迁移老 clusters.json 等文件到 SQLite；
优雅关闭时写一份 snapshot，防进程被 kill 丢数据；
降级通道：ckmanctl dump-to-json 一键把 SQLite 还原回老格式 JSON，方便回滚老版本。
老 local 实现保留为 repository/legacyjson，仅供迁移使用。

六、🖥️ ckmanctl sql：交互式 SQL 子命令

新增 ckmanctl sql，直接对 ckman 自己的持久化层做 SQL：

bash

# REPL
$ ckmanctl sql
ckman> SHOW TABLES;
ckman> SELECT * FROM tbl_cluster LIMIT 5;

# 一次性执行
$ ckmanctl sql -e "SELECT count() FROM tbl_task" --format json

支持 table / vertical / json / csv 四种渲染；
翻译 SHOW DATABASES / SHOW TABLES / DESC <t> 这类 meta 命令到底层 SQL；
错误 / 行数摘要走 stderr，stdout 只输出查询结果（pipe 友好）。

ckmanctl sql REPL — show tables 看到 4.0.0 新增的 tbl_user / tbl_backup_policy / tbl_backup_run，select 查 tbl_cluster

七、⚙️ 任务系统 & Rebalance 重构

boot recovery：进程重启后，把本实例残留 in-flight 的 Task 标记为 interrupted，杜绝幽灵任务。
真实的任务取消：Runner 现在能真正打断正在跑的任务，并修了取消与并发状态写之间的 race / lost-update 问题。
Step 字段：长任务现在能在前端展示当前阶段（如"准备 → 备份 → 校验 → 完成"）。
Rebalance：抽到独立 package，加 Strategy 接口；新增 Plan 预览端点，前端按表分组展示 engine 与 warnings，确认无误再执行；执行走 runner 任务，修了原实现的锁泄漏与错误吞掉问题。

任务详情 — 顶部「当前操作」就是新增的 Step 字段，下方是节点级进度

Rebalance 模块在 4.0.0 还多了一张「均衡信息」面板，按表展示当前每张表在各 shard 上的行数 / 磁盘占用 / 分区数 + 一个直观的「不均衡率」百分比，配合 Plan 预览端点确认无误后再执行：

均衡信息 — 按表展示 imbalance ratio + 各 shard 行数/磁盘/分区分布

八、🎯 节点指定 Schema 同步源

AddNode / StartNode / SyncLogicTable 在新节点初始化 schema 时，过去会"找一台健在的就用"，常见问题是恰好挑到了一台旧节点。4.0.0：

在请求体中显式接收 SourceSchemaHost；
内部新增 PickAvailableSchemaSource 工具函数（连接探测 + 注入 connFn 消除全局可变状态）；
增加节点时前端可指定从哪台拉 schema。

九、📚 全新文档站 + 下载页

把 docs/ 从手写 markdown 全面迁移到 VitePress；
VitePress 产物嵌入 ckman 二进制（go:embed），离线集群也能本地访问文档；
全新 下载页 内嵌发布说明，不再跳 GitHub；
下载卡合并 x86 / arm 到同一张卡，nav 紧凑化；
中英双语 README，突出官方站点 https://housepower.github.io/ckman/。

VitePress 文档站首页 — 一站式入口，nav 含指南/下载/部署/配置/功能/参考

下载页按平台与架构合并卡片，x86 / arm 同卡同时展示：

新下载页 — Linux 通用归档 / RHEL / Debian / Docker 一目了然

十、🔧 其他值得一提的修复 / 优化

Prometheus metrics 默认开启，导入集群时自动清理老的 prometheus 配置。
Cache disk 支持。
多分区 API：get / drop / operate partition 批量端点齐全。
migrate table API：跨集群迁移表结构与 materialized view，补齐 ON CLUSTER。
静态二进制：CGO_ENABLED=0 编译，彻底告别 GLIBC 版本不匹配。
ARM 安装包兜底：Config 步骤前置 mkdir -p config.d / users.d / clickhouse-keeper，规避部分 ARM 包缺目录导致部署失败。
HTTP query_id 支持：可在 query 接口指定 query_id 便于追踪。
RSA padding 升级：修复弱加密告警。
Keeper：开机自启、非 leader 节点连接超时、FetchSchemerFromOtherNode 在 zoopath 已存在时不工作等问题统一修掉。
接口权限（enforce）：对 data_manage 等模块补齐校验，并清掉 dead backup_history 规则。
logic 集群 DML：现在支持非 logic 集群。
熔断 / Nacos SDK v2 / session 去 thread_ids：性能与可观测性细节优化。

升级注意事项

4.0.0 在持久化层与备份模型上有结构性变化，强烈建议先在测试环境完整跑一遍升级链路再上生产。以下按场景分四个维度说明。

1️⃣ 持久化层迁移：自动 or 不动，取决于你用的是哪种 backend

当前 `persistent_policy`	升级行为	你需要做什么
local（默认）	首次启动自动把 `clusters.json` / `query_history.json` / `task.json` / `backup.json` 一次性迁移到 SQLite	✅ 无需手工干预，但强烈建议先备份原 JSON 文件作为兜底
mysql	GORM AutoMigrate 自动新建 `tbl_user` / `tbl_backup_policy` / `tbl_backup_run`，老表不变	确认账号有 `CREATE / ALTER` 权限
dm8（达梦）	同 MySQL	同 MySQL
postgres ⚠️	GORM 在 PG 下 AutoMigrate 有已知 bug 被禁用，所以老表（cluster / logic / query_history / task）一直依赖 `resources/postgres.sql` 手工初始化。4.0.0 在启动时通过 `CREATE TABLE IF NOT EXISTS` 自动建出新的 3 张表（不会动现有数据）	升级用户：什么都不用做，新表会在首次启动时由 ckman 自动建好。新装用户：请使用 4.0.0 附带的新版 `resources/postgres.sql`，里面已经补齐了 `tbl_backup_policy` / `tbl_backup_run` / `tbl_user`，并修复了 3.x 老脚本里 `tbl_backup` 主键写错列名的 bug

💡 PG 用户如果想在升级前先把所有表准备好再启动 ckman（例如严格的变更管控环境），可以从 4.0.0 release 包里取出 resources/postgres.sql 中「-- 4.0.0 新增」三段独立执行，不需要重跑全部 DDL。

🐛 PG 3.x 老 bug 提示：如果你历史上跑过 3.x 的 postgres.sql，理论上 tbl_backup 这张表当时建表就会因为 PRIMARY KEY ("task_id") 引用不存在的列而失败 —— 也就是说你的 PG 库里很可能根本没有 tbl_backup 表。这种情况下 ckmanctl upgrade backup 会扫不到任何老备份数据；如果你确实在 3.x 用过 PG 的备份功能，请提 issue 给我们看看你那边的表结构是怎么落出来的。

2️⃣ 降级回 3.x：必须按通道走，不要直接换二进制

不同 backend 下降级方式不同：

local 后端

bash

# 1. 关停 4.0.0 ckman
systemctl stop ckman

# 2. 用 4.0.0 的 ckmanctl 把 SQLite 导出回旧 JSON 格式
ckmanctl dump-to-json -c /etc/ckman/conf/ckman.hjson

# 3. 替换为旧版本二进制并启动
systemctl start ckman

⚠️ 千万不要：在没 dump 的情况下直接替换二进制 —— 旧版本读不懂 SQLite，会把集群列表当成"空"重新初始化。

mysql / postgres / dm8 后端

老版本看不到 4.0.0 新加的 tbl_user / tbl_backup_policy / tbl_backup_run 表，不会主动删除，但功能数据用不上；
4.0.0 新建的用户会回落到老版本的 users.yml：你需要手动把这些账号同步回 yml 才能继续登录；
4.0.0 新模型的备份策略降级后会"消失"（老 cron 不读新表），原老 tbl_backup 表 4.0.0 仍保留只读，因此老调度可以继续工作；
DDL 不会自动回滚，新表会以"孤儿表"形态保留在库里，升回 4.x 时自动复用，不需要清理。

3️⃣ 备份/恢复存量数据：不自动迁移，必须显式触发

我们刻意没让 ckman 启动时自动迁备份数据 —— 老 cron 与新 Scheduler 同时跑同一份策略会产生重复 BACKUP，风险太高。正确的做法：

bash

# 1. 先 dry-run，看看会迁多少条
ckmanctl upgrade backup --dry-run --verbose

# 2. 确认无误后正式执行
ckmanctl upgrade backup

# 3. 跑稳一段时间后（建议至少一个备份周期），再清理老数据
ckmanctl upgrade backup --cleanup

迁移的核心规则：

维度	行为
聚合粒度	按 `(cluster, database, table, schedule_type, crontab, instance)` 聚合旧的 `tbl_backup` 行为一条新的 `BackupPolicy`
历史 Run	旧的每次执行落到新 `BackupPolicy` 下的 `BackupRun`
状态映射	`SUCCESS` / `FAILED` 保持；其它（`waiting` / `init` / `prepare` / `backup` / `restore` / `check` / `close` / 空值）一律映射为 `INTERRUPTED`
备份风格推导	partition 列表中含 `all` → `FULL`；否则 → `PARTITION`
找不到对应策略的 Run	创建 legacy placeholder policy 承接（不丢历史）
默认不删老数据	没加 `--cleanup` 之前，老 `tbl_backup` 表保持原样；新老并存期间老 cron 不再被 4.0.0 触发，你看到的所有新执行都来自新引擎
目标库非空保护	新的 `tbl_backup_policy` / `tbl_backup_run` 非空时迁移会拒绝执行，避免误覆盖；如确认需要继续，可加 `--force`（不推荐，建议先清空新表或用全新 ckman 实例）

🚨 特别注意：S3 类备份策略迁移后，请进入 UI 复核一次 S3 secret —— 老数据导出时不会重新加密 secret，但新版本 UI 默认会在编辑 Policy 时把 secret 视作不变（修过 secret 字段才会更新）。

4️⃣ 用户体系首次启动行为

第一次启动 4.0.0 会自动种子一个默认 admin 账号，密码遵循 3.x 默认（详见在线文档"安装与初始化"页）。
老 users.yml 不再被读取，但文件保留。如果你 3.x 时代在 yml 里手工加过非 admin 用户，请通过 UI 重新创建。
JWT token 绑定客户端 IP 的行为不变，升级后所有用户的 token 立即失效，需要重新登录。

5️⃣ 配置文件兼容性

ckman.hjson / ckman.yaml 字段向后兼容，但建议补上以下两个新增段，便于使用新能力：
- nacos.sync_config = true 启用 Nacos 配置热重载；
- nacos.cfg_namespace_id = "xxx" 指定配置命名空间（与 service discovery 命名空间可不同）。
老的 cmd/password 工具已下线，对应 init 流程改由 UI / 默认 admin 完成。

升级流程速查表

text

3.x → 4.0.0 推荐步骤：

  ① 备份 conf/clusters.json 及其它 *.json （local backend 用户）
  ② 备份 ckman.hjson
  ③ 若使用 postgres：检查 4.0.0 新版 resources/postgres.sql，
     新装用户先跑一次 DDL；升级用户可跳过（启动时自动建新表）
  ④ 关停 ckman → 替换为 4.0.0 二进制
  ⑤ 启动 ckman，观察日志确认：
       - "migrate local json to sqlite ... done"（仅 local 用户）
       - "seed default admin user"（首次启动）
  ⑥ 用 UI 登录验证集群列表完整
  ⑦ ckmanctl upgrade backup --dry-run 检查备份迁移
  ⑧ ckmanctl upgrade backup 正式迁移
  ⑨ 观察一个备份周期，确认新引擎工作正常
  ⑩ ckmanctl upgrade backup --cleanup 清理老表

鸣谢

感谢社区在这一年里提的所有 issue 与 PR，尤其是备份/恢复模块的早期 beta 体验者 —— 你们的真实使用场景把我们从 3.x 的多个老坑里拉了出来。

🌟 觉得好用，欢迎来 GitHub 给我们一个 Star：https://github.com/housepower/ckman

CKMAN 4.0.0 发布｜重新设计备份与恢复，引入用户体系、节点级配置、SQLite 本地存储与全新文档站 ​

一、🗄️ 备份与恢复：从「定时脚本」走向「任务化引擎」 ​

1. 新的数据模型与执行模型 ​

2. 关键能力 ​

二、👤 用户与角色管理（Phase 1）：告别明文 user.yml ​

三、🧩 单节点配置覆盖（Per-Node Override） ​

四、🔁 Nacos 配置中心 + 热重载 ​

五、💾 本地持久化层切换到 SQLite ​

六、🖥️ ckmanctl sql：交互式 SQL 子命令 ​

七、⚙️ 任务系统 & Rebalance 重构 ​

八、🎯 节点指定 Schema 同步源 ​

九、📚 全新文档站 + 下载页 ​

十、🔧 其他值得一提的修复 / 优化 ​

升级注意事项 ​

1️⃣ 持久化层迁移：自动 or 不动，取决于你用的是哪种 backend ​

2️⃣ 降级回 3.x：必须按通道走，不要直接换二进制 ​

local 后端 ​

mysql / postgres / dm8 后端 ​

3️⃣ 备份/恢复存量数据：不自动迁移，必须显式触发 ​

4️⃣ 用户体系首次启动行为 ​

5️⃣ 配置文件兼容性 ​

升级流程速查表 ​

鸣谢 ​

CKMAN 4.0.0 发布｜重新设计备份与恢复，引入用户体系、节点级配置、SQLite 本地存储与全新文档站

一、🗄️ 备份与恢复：从「定时脚本」走向「任务化引擎」

1. 新的数据模型与执行模型

2. 关键能力

二、👤 用户与角色管理（Phase 1）：告别明文 user.yml

三、🧩 单节点配置覆盖（Per-Node Override）

四、🔁 Nacos 配置中心 + 热重载

五、💾 本地持久化层切换到 SQLite

六、🖥️ ckmanctl sql：交互式 SQL 子命令

七、⚙️ 任务系统 & Rebalance 重构

八、🎯 节点指定 Schema 同步源

九、📚 全新文档站 + 下载页

十、🔧 其他值得一提的修复 / 优化

升级注意事项

1️⃣ 持久化层迁移：自动 or 不动，取决于你用的是哪种 backend

2️⃣ 降级回 3.x：必须按通道走，不要直接换二进制

local 后端

mysql / postgres / dm8 后端

3️⃣ 备份/恢复存量数据：不自动迁移，必须显式触发

4️⃣ 用户体系首次启动行为

5️⃣ 配置文件兼容性

升级流程速查表

鸣谢