ZooKeeper Viewer

中文 README | English README

在 VS Code 内直接浏览和管理 Apache ZooKeeper数据，可进行多连接管理、节点搜索、JSON/TXT 查看与编辑节点数据、节点增删，以及数据导入导出等。

为什么使用

• 轻量敏捷：依托vscode，插件足够轻量，无需其他依赖。
• 高效浏览：节点按需懒加载，可按名称、创建时间或更新时间排序
• 安全连接：支持多地址、Chroot、digest 认证和 TLS；密码保存在 VS Code SecretStorage 中
• 完整搜索：支持精确路径、名称前缀、路径通配符、正则和节点内容搜索
• 可视化友好：支持json、txt查看节点数据，是否换行按需开关，一键去除多余换行，编辑友好。
• 便捷迁移：单节点或完整子树可无损导出为 JSON，并可恢复到 ZooKeeper
• 中英文界面：可跟随 VS Code，也可手动切换中文或 English

使用环境说明

• VS Code 1.60.0 或更高版本
• Apache ZooKeeper 3.4 或更高版本
• Windows、macOS 或 Linux

安装

• VS Code 软件内安装： 在 VS Code 扩展视图中搜索 ZooKeeper Viewer，点击 安装；

• 在线插件市场安装： 打开 Visual Studio Marketplace 页面。

• Github 离线下载relase包安装：

  • 在 Github Relase 下载最新包

  • 下载完成后在VS Code 插件视图中选择从 从VISX安装离线安装。或者运行命令安装：

    code --install-extension zk-viewer-vscode.vsix
    

• 源码打包安装：

  • 下载源码 https://github.com/BeWaterMyFriend7/zk-viewer-vscode.git

  • 进入项目根目录，执行打包命令

    npm run package          # 打包 dist/zk-viewer-vscode.vsix
    

  • VS Code 离线安装插件

快速上手

1. 点击活动栏中的 ZooKeeper 图标。
2. 点击侧边栏标题栏的 加号，填写连接名称和服务器地址，例如 localhost:2181。
3. 点击 连接（插头图标）。
4. 展开节点树；双击节点打开详情，或右键执行新增、删除、复制路径、搜索和导出。
5. 点击标题栏的 放大镜，快速搜索或定位节点。

操作手册

连接管理

点击标题栏的 加号，或在命令面板中运行 ZooKeeper: Add Connection...。

新增连接会打开一个多字段表单，一次填完名称、地址、Chroot、用户名 / 密码、TLS 与会话超时；地址默认填 localhost:2181 供你修改。保存前可点击 Test Connection 用当前填写的字段（编辑时密码留空则用已保存密码）发起一次真实连接测试，连接失败会就地提示原因。

连接配置保存在 VS Code 扩展全局状态中，同一 Profile、同一扩展运行环境下的不同窗口和工作区共享连接列表。旧版本保存在工作区状态中的连接会在首次打开该工作区时自动迁移。不同 Profile，以及本地与远程扩展宿主，仍可能使用彼此独立的状态。密码使用 VS Code SecretStorage 单独加密保存，不会写入普通配置或日志。通过标题栏的省略号菜单可编辑或删除连接，删除连接时也会清除对应密码。

网络断开时扩展会交给底层库在观察窗口内复用当前会话自动恢复（临时节点不丢失）；只有会话真正过期、认证失败或窗口超时才重建会话并停止后台重连，等待手动重新连接。可通过 zkViewer.maxReconnectAttempts 与 zkViewer.reconnectDelayMs 调整窗口时长（约为二者乘积）。

节点浏览与管理

• 展开节点时仅加载当前层级，不会一次读取整棵树。
• 节点图标：普通持久节点按是否有子节点区分为文件夹 / 文件图标；持久顺序、临时、临时顺序节点保留各自的专属图标。图标按类型着色以便一眼区分。
• 右键节点可新增、编辑、删除、复制路径、搜索子树、导出和刷新。
• 在标题栏省略号菜单中选择 Sort Nodes...，可按名称、创建时间、更新时间正序或倒序排列，也可保留服务器顺序。

搜索与定位

点击标题栏的 放大镜，或运行 ZooKeeper: Search Nodes...。

搜索结果按路径排序。点击结果后，节点树会展开并定位到对应节点。内容搜索可限定子树范围，搜索过程中可按 Esc 取消。

默认最多遍历 500000 个节点；达到 zkViewer.maxSearchNodes 上限时，界面会提示结果可能不完整。将该设置设为 0 可取消数量限制。zkViewer.maxNodeDataBytes 用于限制内容搜索读取的数据大小，默认 0 表示不限制。

查看与编辑节点数据

1. 选中节点，点击 查看详情或者在新标签页查看详情。
2. VS Code 标签页使用紧凑标题：深层路径仅显示 .../父节点/当前节点；面板内仍显示完整路径，超长时单行省略，悬停可查看全文并可选择复制。
3. 节点详细信息默认折叠。展开后以可读名称显示节点类型、创建/修改时间、数据大小、直接子节点、数据/子节点/ACL 版本及创建/修改事务 ID。
4. JSON 数据默认按 2 空格缩进展示；可切换到 TXT 查看原始文本，并可控制换行。
5. 详情默认只读。顶部工具栏左侧的 Edit / Save 与右侧显示选项分组排列，点击 Edit 后才可修改。
6. JSON 模式保存时会校验并紧凑化；TXT 模式按输入内容原样保存。
7. 保存时携带加载时的节点版本号。若其他客户端已修改节点，扩展会报告版本冲突且不会覆盖远端数据。

非 JSON 文本会自动切换为文本展示；二进制数据以十六进制只读展示。

当前 JSON 编辑区是轻量文本框：合法 JSON 在加载和切换到 JSON 模式时会格式化，无效 JSON 会保留原文并提示错误；保存时会再次校验，但编辑过程中不提供 VS Code 原生编辑器的语法高亮、自动补全或实时格式化。

详情页的数据编辑器（JSON / TXT 切换、换行、一键压缩）被抽取为共用组件，新增节点表单也复用同一套展示与编辑逻辑。

新增与删除节点

右键父节点并选择 Add Node...。节点名不能包含 /，也不能是 . 或 ..。 新增节点会打开一个表单弹窗：父路径只读显示（默认当前选中节点），节点名输入，节点类型下拉选择，节点数据区复用详情页的数据编辑器（支持 JSON / TXT 切换、换行开关与一键压缩）。

删除节点前会要求确认。节点包含子节点时，可选择递归删除；扩展会先删除子节点，再删除父节点。

导入与导出

• Export Node Data...：导出当前节点。
• 导出节点及所有子节点数据...（命令 Export Node and Descendant Data...）：导出当前节点及完整子树。
• 标题栏省略号菜单中的 Import Node Data...：读取标准导出 JSON 并恢复节点。
• View Import Format：查看只读格式说明并下载模板。

导出数据包含完整 path、data 和 encoding。文本使用 utf8，无法无损表示为 UTF-8 的数据使用 base64。

导入前可选择跳过或覆盖已存在节点。扩展会在写入前校验格式版本、路径范围、重复路径、Base64 数据和外部父节点；缺失节点按父级优先创建为持久节点。

语言

点击标题栏语言按钮，选择：

• 跟随 VS Code
• 中文
• English

切换后会立即更新菜单、通知、搜索、导入导出和已打开的详情面板。

隐私与安全

• 扩展不包含遥测或使用情况上报。
• ZooKeeper 数据只在 VS Code 与你配置的 ZooKeeper 服务器之间传输。
• digest 密码使用 VS Code SecretStorage 保存。
• 节点详情默认只读；修改和删除操作需要显式触发，删除包含确认步骤。

请仍遵循最小权限原则，为日常浏览使用只读或受限的 ZooKeeper 账号。

已知限制

• 二进制节点数据仅支持十六进制只读展示。
• 临时节点会按 ZooKeeper 语义在会话断开后消失。
• 超大集群的全树内容搜索可能耗时较长，建议从目标子树开始搜索。

支持与反馈

遇到问题请查看 支持说明，或提交 GitHub Issue。

许可证

Apache License 2.0