麦地缓存使用文档
01快速开始
麦地缓存是一款开源的 Redis 图形化桌面客户端。整个流程只有三步：装好应用、新建连接、然后就能看到你的数据。
1. 下载并安装
在首页下载区选择你的系统安装包，装好打开即可，无需额外配置。
2. 新建连接
点右上角「新建连接」，填入主机与端口，点「测试连接」确认通了再保存。
3. 开始管理
左侧选连接，Key 列表自动加载；点任意 Key 查看内容、改值或调整 TTL。
02安装
安装包由 GitHub Actions 在打 tag 时自动构建，文件名形如 myredis-<版本>-<平台>。
在首页点对应平台按钮即可直接下载，也可以到
GitHub Releases 查看全部版本。
macOS
- 下载
.dmg（Universal，Apple Silicon 与 Intel 通用）并打开。 - 把「麦地缓存」拖进「应用程序」文件夹。
- 首次打开若提示「无法验证开发者」，到系统设置 → 隐私与安全性里点击「仍要打开」即可。
Windows
.exe：NSIS 安装向导，双击后一路下一步，会自动创建开始菜单与桌面快捷方式。.msi：适合需要批量分发或走组策略的场景。
Linux
# Debian / Ubuntu：用 apt 安装可自动处理依赖
sudo apt install ./myredis-*-linux-x64.deb
# 或者免安装的 AppImage，赋予执行权限后直接运行
chmod +x myredis-*-linux-x64.AppImage
./myredis-*-linux-x64.AppImage从源码构建
需要先安装 Rust 工具链与 Tauri CLI（cargo install tauri-cli）。
# 克隆仓库
git clone https://github.com/myredisapp/myredis.git
cd myredis
# 本地开发调试
cargo tauri dev
# 构建当前平台的安装包
cargo tauri build03连接 Redis
点击左上角（窄窗口下在菜单里）的「新建连接」，填写下面几个字段。 只有「主机」和「端口」是必填的，其余按你的服务器配置来。
| 字段 | 说明 |
|---|---|
| 连接名称 | 只用于显示，随便起个能认出来的名字，例如「本地开发」「生产环境」。 |
| 主机 | Redis 服务器地址，例如 127.0.0.1 或 redis.example.com。 |
| 端口 | 默认 6379。 |
| 用户名（可选） | Redis 6.0 及以上支持 ACL 用户名；留空则按传统单密码方式认证。 |
| 密码（可选） | 服务器设置了 requirepass 时填写；没有密码就留空。 |
| 只读连接 | 勾选后禁止一切写操作，连接生产环境时建议打开。详见只读模式。 |
| 集群模式 | 连接 Redis Cluster 时勾选，填任意一个节点地址即可。详见集群模式。 |
| Key 分隔符 | 默认 :，决定 Key 列表如何折叠成文件夹。详见浏览与查找 Key。 |
先测试，再保存
填完后点「测试连接」，按钮会短暂显示「测试中…」，随后给出结果：
✓ 连接成功（PONG）——凭据与网络都没问题，可以点「保存连接」了。✗ 连接失败：…——按提示检查地址、端口、密码与防火墙。排查看常见问题。
保存后连接会出现在左侧列表里，点击即连接。连接成功的连接会显示绿点与「在线」标记，并且可以同时保持多条连接在线，随时点切换。
连接列表上的操作
把鼠标移到连接条目上，右上角会出现刷新图标与 … 菜单：
- 刷新：重新连接并从服务器重新拉取 Key 列表。
…编辑 / 复制 / 关闭连接 / 删除：「复制」会带着现有配置新建一条，名字自动加「副本」，很适合照着改一个测试环境连接。
列表底部除了「添加连接」，还有 「导入」 与 「导出」 两个按钮， 用来把连接配置整体搬到另一台机器，详见下面的常见问题。
连接配置存在哪
所有连接配置保存在应用配置目录下的 connections.json：
- macOS：
~/Library/Application Support/com.maidi.cache/connections.json - Windows：
%APPDATA%\com.maidi.cache\connections.json - Linux：
~/.config/com.maidi.cache/connections.json
换机器时不必手动拷这个文件，直接用侧栏底部的 「导出」 生成一个 JSON 文件， 在新机器的 「导入」 里选它即可。
04浏览与查找 Key
连接成功后，应用会自动加载当前数据库的 Key 列表，显示在中间一栏。每一行都带着类型徽标（STR / HASH / LIST / SET）和剩余 TTL。
切换数据库
连接后在工具栏左侧的 Db0 下拉框里切换逻辑库（默认提供 Db0–Db15）。
切换后 Key 列表与「Key 总数」会一起刷新。集群模式下没有这个概念，详见集群模式。
搜索
工具栏搜索框按 Key 名过滤，不区分大小写、按包含匹配。比如输入 user，
user:1001、my_user、USER:1002 都会被筛出来。
搜索是直接在服务器上扫 Key 名完成的，所以还没加载出来的 Key 也能搜到， 不受列表当前加载了多少影响。
列表按需加载
为了不让几万个 Key 把界面拖卡，Key 列表是分批加载的：一次先取一批，往下滚到底就自动接着取； 如果没有滚动条（比如文件夹都折叠着、内容撑不满一屏），点列表底部的「加载更多」手动取下一批。
列表最下面那行常驻显示已加载多少个 Key；当前数据库的 Key 总数看左下角的「Key 总数」， 它来自服务器的实时统计，和已加载数量不是一回事。
文件夹折叠
Key 列表会按连接配置里的「Key 分隔符」（默认 :）折叠成树。开启文件夹后，
user:1001:name 会落到 user: 这一层里，层级多的时候会清爽很多。
- 想按别的分隔符分组（例如
/或.），在连接配置里改「Key 分隔符」后重新连接。 - 搜索时会临时展开成平铺列表，方便你直接看到命中的 Key。
- 每个连接展开的文件夹状态会被记住，切来切去不会丢。
05查看与编辑 Key
在 Key 列表里点任意一行，右侧就是详情区：顶部是 Key 名、类型徽标与 TTL 输入框，下面是值，底部是操作按钮。
String：查看与修改
- 点击 Key，值会加载到编辑框里。
- 直接改动内容；如果是 JSON，可以先点「格式化」再改，读起来清楚得多。
- 点「保存」写回服务器。
- 只想拿走内容？点「复制」即可复制到剪贴板。
修改 TTL（过期时间）
详情区顶部的 TTL 输入框就是过期时间，单位是秒：
| 填写 | 含义 |
|---|---|
-1 | 永不过期（页面上显示为「永不过期」） |
| 正整数 | 从现在起多少秒后过期，例如 3600 表示一小时 |
改完 TTL 需要点「保存」才会生效；也就是说让一个 Key 永不过期的方法，是把 TTL 改成 -1 再保存。
填了别的值会提示 TTL 必须为 -1 或正整数。
其他类型（Hash / List / Set / ZSet）
详情区会按 Key 的实际类型选择展示方式：Hash、List、Set、ZSet 会以字段/元素列表的形式呈现， 每一行都可以直接修改、删除，底部虚线行用于新增：
- Hash：显示全部字段与值，可改值、删字段、加字段。
- List：按下标显示全部元素，可改值、删元素，可在左端或右端插入新元素。
- Set：显示全部成员，可改成员名（等价于删旧加新）、删成员、加成员。
- ZSet：显示成员与分值，可改成员名与分值、删成员、加成员。
这些类型的修改是即时保存的（点行内的 即写入服务器）， 顶部的「保存」按钮只负责 TTL。Stream 等其余类型仍提示「暂不支持此类型」。
06新增与删除 Key
新增 Key
点工具栏的「新增 Key」，填写三个字段：
- Key 名称：若已存在同名 Key，会提示
Key 已存在并拒绝创建。 - 值：多行文本框，支持换行。
- TTL（秒）：默认
-1表示永不过期。
点击「创建」后，新 Key 会立刻出现在列表里（当前仅支持创建 String 类型）。
删除 Key
选中 Key 后点详情区的「删除」，会弹出确认框。确认后立即从服务器删除，不可恢复， 所以删之前建议先「复制」一份值留底。
07内置终端
窗口底部是内置终端面板，在这里输入命令按 Enter 执行。点面板标题栏或右侧箭头可以折叠，
拖动面板上沿还能调整高度。命令会真实转发到已连接的 Redis 服务器执行，
结果按 redis-cli 风格展示（OK、(nil)、(integer) N、数组逐行输出）。
| 命令 | 当前行为 |
|---|---|
PING | 返回服务器真实的 PONG |
GET / HGETALL / LRANGE / SMEMBERS / ZRANGE … | 直接在服务器上执行并返回真实结果 |
KEYS pattern | 真实执行（会阻塞生产实例，慎用），例如 KEYS user:* |
INFO / DBSIZE | 返回服务器真实信息 |
SET key value 等写命令 | 真实写入服务器；只读连接下会被拦截 |
FLUSHDB | 真实清空当前数据库，不可恢复 |
HELP | 显示终端使用说明 |
FLUSHDB 这类危险命令执行前请三思；
只读连接下写命令会被直接拒绝。日常查看建议优先用详情区。
08服务器状态
连接列表下方的四个小格子是当前连接的实时指标，大约每 5 秒自动刷新一次：
| 指标 | 含义 |
|---|---|
| 磁盘 | Redis 持久化目录所在磁盘的使用率。鼠标悬停可看到具体目录与百分比。 |
| 内存 | 来自 INFO used_memory，已自动换算为 KB / MB / GB。 |
| 连接数 | 来自 INFO connected_clients，当前客户端连接数。 |
| Key 总数 | 当前数据库的 DBSIZE，会跟着工具栏的 Db 选择器一起变化。 |
窗口顶部的状态栏则显示 已连接 · 主机:端口；如果是只读连接，后面会多一个「(只读)」标记。
09只读模式
创建或编辑连接时勾选「只读连接」，这条连接就进入只读模式 —— 查看类操作一切照旧， 所有会改动数据的入口则被关闭：
- 「新增 Key」按钮：禁用
- 「保存」按钮与 TTL 输入框：禁用
- 窗口状态栏显示「(只读)」
这层保护不只做在界面上：即使绕过按钮，后端也会在写入前拦截，返回
当前为只读连接，禁止写操作。查线上数据时强烈建议打开。
需要临时写入时，取消勾选并重新连接即可 —— 这样也有意让「改生产数据」变成需要刻意确认的动作。
10集群模式
连接 Redis Cluster 时，在连接配置里勾选「集群模式」，主机与端口填任意一个节点的地址即可， 客户端会自己发现整个集群的拓扑。
集群模式下有几处与单机不同，先了解一下能少踩坑：
- 不能切换数据库：集群只有 db0，工具栏的 Db 选择器会被隐藏，切换会返回「集群模式不支持切换数据库」。
- Key 列表由各主节点汇总：客户端会向所有主节点分别扫描，去重排序后展示，所以看到的是全集群的 Key。
- 内存与连接数为主节点汇总值，Key 总数同样是各主节点之和。
- 磁盘指标可能显示
-：集群模式下CONFIG GET dir通常取不到，属正常现象。
MOVED。
按提示改用「集群模式」重新连接即可。
11主题与界面
应用内置五款「四季」主题，点窗口右上角的调色盘图标，在「选择主题」里挑一个：
| 主题 | 风格 |
|---|---|
| 春分 | 清新芽绿，明亮 |
| 立夏 | 晴空湛蓝，明快清爽 |
| 初秋 | 暖金麦色，沉稳温润 |
| 深秋 | 暗金夜色，默认主题 |
| 冬至 | 晴日雪白，简洁明亮 |
主题选择会保存在本地，下次打开还是这一款；本页与首页也共用同一份记录，你在哪里换的装，切页面时都会跟着。
调整布局
- 折叠连接列表：点标题栏的菜单图标，窄屏或专心看数据时很实用。
- 拖动分隔条：连接列表宽度、Key 列表宽度、终端高度都可以拖。
- 这些布局偏好会被记住，不用每次重新摆。
12快捷键
| 按键 | 作用 |
|---|---|
| Enter | 在终端输入框里执行命令 |
| Enter | 连接配置弹窗打开时，保存连接 |
| Esc | 关闭当前弹窗 |
| Enter | 「新增 Key」里在名称或 TTL 输入框中直接创建 |
| Ctrl / ⌘ + Enter | 「新增 Key」里在值文本框中提交（值可以带换行） |
点击弹窗外的灰色区域同样可以关闭弹窗。
13功能现状
为了避免你在界面上找不到某个按钮，这里如实列一下当前版本的能力边界。
已经可用
- 单机 / 集群连接，支持 ACL 用户名、密码、只读保护，连接配置本地持久化
- 连接配置的导入 / 导出（JSON 文件，可选是否带密码），换机器不用再手动拷配置
- Key 列表浏览、关键字搜索（服务器端扫描，未加载的 Key 也能搜到）、按自定义分隔符折叠文件夹
- Key 列表分批加载与虚拟滚动，Key 很多时也不会卡
- String 类型值的查看、编辑、保存、复制、JSON 格式化
- Hash / List / Set / ZSet 内容的加载与字段级新增、修改、删除
- TTL 查看与修改（
-1表示永不过期，任意类型均可改） - 新增 String Key、删除 Key（带确认）
- 内置终端：命令真实转发到服务器执行，结果按 redis-cli 风格展示
- Key 导入 / 导出（JSON 格式，导入前确认覆盖策略）
- 服务器指标：内存、连接数、Key 总数、磁盘占用
- 自动更新：后台下载新版本（下载期间可继续使用），下好后重启应用即完成升级
- 五款四季主题、面板拖拽与布局记忆
仍在开发中
当前没有明确排期的功能缺口。已知的改进项（性能、工程流程）记录在仓库的 DEVELOPMENT.md 里。
14常见问题
提示连接失败 / 连接超时，怎么排查？
按这个顺序检查，基本能定位到原因：
- 主机和端口是否写对；本机测试用
127.0.0.1:6379确认打通链路。 - 服务器是否设置了密码（
requirepass）；有密码时密码字段不能空。 - 用了 ACL 的话，用户名也要填；只填密码会认证失败。
- Redis 的
bind是否只监听了127.0.0.1，以及protected-mode是否开启。 - 服务器防火墙 / 安全组是否放行了该端口。
先点「测试连接」拿到具体报错，通常比猜更快。
操作时报 MOVED / 提示槽位相关错误？
你连的是 Redis Cluster，但连接没有勾选「集群模式」。编辑该连接，勾上「集群模式」后重新连接即可。 参考集群模式。
点「保存」没反应，或者提示「只读连接，禁止写操作」？
这条连接是只读连接。只读模式下「新增 Key」「保存」以及 TTL 输入框都会被禁用，后端也不会接受写命令。 确实需要写入时，编辑连接取消勾选「只读连接」并重新连接。
为什么 Hash / List / Set / ZSet 的详情是空的？
选中 Key 后详情区会异步从服务器加载字段内容，加载完成前会短暂显示「加载中」。
如果一直为空，点详情区的「刷新」重新加载；仍不对就检查终端里 TYPE key 的实际类型。
「导入」「导出」是什么格式？
导出会把当前数据库的全部 Key（String / Hash / List / Set / ZSet，含 TTL） 下载为一个 JSON 文件；导入选择该文件后，会提示「已存在的同名 Key 将被覆盖」， 确认后开始导入并报告成功 / 跳过 / 失败的数量。Stream 等类型暂不参与导出。
搜索框里输入 * 为什么没有通配效果？
列表搜索框是纯文本包含匹配，不解析通配符。需要按模式找 Key，可以在内置终端里用
KEYS user:* 这样的命令匹配。
Key 列表里的 TTL 显示「永不过期」，但服务器上有 TTL？
Key 的 TTL 是在列表加载时读取的，服务器上的过期时间如果在之后被改动，列表不会自动同步。 点该连接上的刷新图标重新连接，或重新选中这个 Key，即可看到最新的 TTL 与内容。
连接配置和密码保存在哪里？安全吗？
保存在应用配置目录的 connections.json 里（路径见连接 Redis），
用户名与密码是明文存储的。请不要把该文件提交到代码仓库或分享给他人；共用电脑上使用时要留意这一点。
可以把连接配置迁移到另一台机器吗？
可以。在旧机器上点侧栏底部的 「导出」，会下载一个
maidi-connections-<日期>.json；把它拷到新机器，点 「导入」
选中该文件即可。
导出时可以选择是否包含密码（默认包含，密码是明文，请妥善保管文件）。 导入按连接 ID 匹配：同 ID 的连接会被文件里的配置覆盖，其余保留；单条格式不对只会跳过并报出来， 不影响其它连接。
当然，手动复制 connections.json 到新机器的同路径也依然有效。
怎么更新到新版本？
应用启动后会在后台静默检查一次新版本：有新版本时右上角的更新按钮会亮起小红点， 底部也会轻提示一句，不会打断你正在做的事。
点那个按钮可以看到新版本号和更新说明，点 「立即更新」 就开始在后台下载 —— 下载期间可以继续使用，窗口底部会出现一条进度条显示下载进度。下载完成后会弹窗提示， 点 「立即重启」 重启即可完成升级（关掉弹窗也没关系，底部进度条上一直有重启入口）。
更新包在做签名校验，下载不完整或来源不对的包不会被执行； 更新只替换程序本身，连接配置和布局偏好都会保留。
15反馈与链接
文档和功能都会随着版本继续补齐。用起来有问题、或者想要某个能力，欢迎直接提。