Tiny RDM Redis 客户端安装部署完整指南：Mac、Windows、Linux 与 Docker 快速上手、源码构建与故障排查清单
【免费下载链接】tiny-rdmTiny RDM (Tiny Redis Desktop Manager) - A modern, colorful, super lightweight Redis GUI client for Mac, Windows, and Linux. It also provides a web version that can be deployed via Docker.项目地址: https://gitcode.com/GitHub_Trending/ti/tiny-rdm
在刚重置的 Mac 上双击 Tiny RDM，系统直接弹出"无法打开，因为无法验证开发者"；同事的 Linux 上运行编译出的二进制，窗口闪一下就退出，终端里是libwebkit2gtk相关的动态库报错。这两个现场是 Tiny RDM 首次部署最常见的坑，都发生在"装完之后、连上之前"。Tiny RDM 是一款基于 Wails 的轻量级跨平台 Redis GUI 客户端（Mac/Windows/Linux），支持 String、List、Hash、Set、ZSet、Stream 的可视化 CRUD，SSH 隧道/SSL/哨兵/集群连接、实时命令监控和 20 余种数据解码器。本文按"先选路线、再照步骤做、出错查表"的方式，覆盖桌面安装包、Docker Web 版、源码构建三条路线，并附集中排错速查表。
路线速览：先判断你该走哪条
三条路线的差异决定了你要准备的东西完全不同。按访问方式和目的自判：
判断依据：个人本机用选路线一；团队共享或无桌面环境（如远程 Linux 服务器）选路线二；要动 Go 后端（backend/services/）或 Vue 前端（frontend/src/）才走路线三。
快速上手路线：桌面包安装与 Web 版部署
桌面端：检查清单 → 安装 → 成功判定
三步走，平台差异全部收进下面这张对照表，不重复叙述。
第一步：装之前确认依赖
| 检查项 | Windows | macOS | Linux |
|---|---|---|---|
| 最低要求 | Win 10/11，x64/arm64 | macOS 12+ | x64，GTK3 + WebKit 环境 |
| 必备运行时 | WebView2 Runtime（Win10/11 通常已预装） | 无特殊依赖 | libwebkit2gtk-4.0-37、libgtk-3-0 |
| 缺失时的安装命令 | 在"设置 → 应用"中查找并安装 WebView2 | — | sudo apt install libwebkit2gtk-4.0-37 libgtk-3-0（Debian/Ubuntu）或sudo dnf install webkit2gtk4.0 gtk3（Fedora） |
| 安装包形态 | .exe安装包 | .dmg镜像 | .deb/.rpm/.tar.gz |
| 安装动作 | 双击走向导 | 拖入"应用程序" | sudo dpkg -i tinyrdm_x.x.x_amd64.deb（缺依赖再sudo apt install -f） |
第二步：启动并处理首次拦截
- macOS 若提示"无法验证开发者"，两种解法任选其一：
sudo xattr -d com.apple.quarantine /Applications/Tiny\ RDM.app后重开；或在"系统设置 → 隐私与安全性"页面底部点"仍要打开"。 - Linux 若窗口闪退，先跑
ldd检查动态库（见文末速查表），补装 WebKit 依赖即可。
第三步：成功判定
启动后左侧是连接管理面板，中间是 Key 浏览器。新建连接时填入 Redis 地址、端口、密码（支持 SSH 隧道、SSL、哨兵、集群模式），对话框会先发PING测试，返回PONG才算连上；连上后执行SET test_key "ok"再GET，能读到值即部署完成。
Web 版：Docker 五分钟部署
Web 版由 nginx（前端静态文件 + 反代，监听 8086）和 Go 后端（API/WebSocket，内部 8088）组成，仓库内已自带 docker-compose.yml，核心配置如下：
services: tinyrdm: image: ghcr.io/tiny-craft/tiny-rdm:latest ports: - "8086:8086" # 浏览器访问入口 environment: - ADMIN_USERNAME=admin # 登录用户名，必须设置 - ADMIN_PASSWORD=tinyrdm # 登录密码，必须设置 volumes: - ./data:/app/tinyrdm # 连接配置与偏好持久化docker compose up -d # 启动后浏览器访问 http://localhost:8086 登录 docker compose logs -f # 登录失败/端口不通时先看这里成功判定：8086 能登录进主界面，且容器重建后（数据落在./data）连接配置不丢。若换机器部署，只需把./data目录和 compose 文件一起带走。
源码构建路线：环境准备到产物输出
环境准备
| 组件 | 版本要求 | 验证命令 |
|---|---|---|
| Go | 1.25+（go.mod 声明go 1.25.0） | go version |
| Node.js | 20+（frontend/package.json 使用 Vite 8） | node -v |
| npm | 9+ | npm -v |
| Wails CLI | 最新 v2 | go install github.com/wailsapp/wails/v2/cmd/wails@latest |
| Linux 额外项 | build-essential、pkg-config、libwebkit2gtk-4.0-dev（仅桌面编译需要） | dpkg -l \| grep webkit2gtk |
构建步骤
git clone https://gitcode.com/GitHub_Trending/ti/tiny-rdm --depth=1 cd tiny-rdm/frontend && npm install && cd .. # 装前端依赖 wails dev # 开发模式：热重载，改前端即时生效 wails build -clean -production # 生产构建产物位置：build/bin/Tiny RDM（Windows 为.exe，macOS 为.app目录）。常用自定义选项：-icon build/appicon.png换图标、-o ./dist/换输出目录。
需要 Web 版二进制时不必手动装两套工具链，直接用仓库根目录的 Dockerfile 多阶段构建（node:22-alpine 编前端 + golang:1.25-alpine 以-tags web编后端，VITE_WEB=true切换 Web 模式）：
docker build -t tiny-rdm:local . # 产出与 compose 中同构的镜像，端口同为 8086故障速查表：报错先查这里
| 现象 / 报错 | 可能原因 | 解决 |
|---|---|---|
| macOS 提示"无法打开，因为无法验证开发者" | Gatekeeper 隔离属性 | sudo xattr -d com.apple.quarantine /Applications/Tiny\ RDM.app，或"隐私与安全性"中点"仍要打开" |
Linux 双击后窗口闪退，终端提示libwebkit2gtk-4.0/libgtk-3.so找不到 | 系统缺 WebKit/GTK 运行时 | sudo apt install libwebkit2gtk-4.0-37 libgtk-3-0（Debian/Ubuntu）；sudo dnf install webkit2gtk4.0 gtk3（Fedora） |
| Windows 启动即崩溃或白屏 | 缺 WebView2 Runtime | 安装"Microsoft Edge WebView2 Runtime"；企业机检查应用白名单 |
连接失败dial tcp: ... i/o timeout | 网络不通、安全组/防火墙拦了 6379 | nc -zv <host> 6379先验证端口；再查云安全组与 Redisbind/protected-mode |
连接失败WRONGPASS或登录后NOAUTH | 密码填错，或哨兵模式下填成了数据节点密码 | 哨兵连接应填 sentinel 的requirepass；用redis-cli -p 6379 auth <pwd>先自验 |
| 哨兵模式提示找不到 master | 客户端填的 master-name 与服务端不一致 | redis-cli -p 26379 sentinel masters抄准名字 |
集群模式部分操作报MOVED/超时 | 只配了部分节点，个别节点不可达 | redis-cli -h <node> cluster info确认cluster_state:ok，客户端节点列表补全 |
Web 版docker compose up后 8086 打不开 | 端口被占用或映射写错 | ss -lntp \| grep 8086找占用进程；compose 中改为"8087:8086" |
| Web 版一直登录失败 | ADMIN_USERNAME/ADMIN_PASSWORD未设置或改动后未重启 | 改环境变量后必须docker compose up -d重建容器才生效 |
| Linux 源码编译报 webkit 头文件缺失 | 缺开发包（运行时库不够） | sudo apt install libwebkit2gtk-4.0-dev pkg-config build-essential |
| 换机后连接配置全丢 | 没带数据目录 | 桌面版配置在~/.config/TinyRDM（macOS 为~/Library/Application Support/TinyRDM，Windows 为%APPDATA%\TinyRDM），整体拷走即可；Web 版拷./data |
进阶调优：连接、加载与扩展
- 大 Key 空间：列表 Key 默认走
SCAN分段加载而非KEYS，百万级 Key 不会把服务端卡死；List/Hash/Set/ZSet 的值也支持分段拉取，阈值可在界面偏好中调整。 - 自定义编解码：Value 展示支持自定义 decoder，解码器配置文件存放在配置目录的
TinyRDM/decoder子目录下（路径实现见 backend/utils/convert/common.go），Base64、Gzip、zstd、MessagePack 等 20 余种开箱即用。 - 连接画像迁移：连接配置支持导出/导入文件，团队内交接环境时直接传文件，不用逐条手填。
- Web 版运维：
GIN_MODE=release关闭调试日志；会话过期时长可通过SESSION_TTL（默认 24h）调整；敏感操作前用docker compose logs确认后端收到的请求。 - 监控：内置实时命令监控与慢日志面板，排查"谁在扫全库"时比直接
MONITOR可控。
下一步行动清单
- 按"路线速览"确定路线：桌面包 / Docker Web / 源码构建，三选一。
- 按对应小节的三步走完成部署，以"PING 返回 PONG、GET 能读回 SET 的值"为验收标准。
- 出错不猜：先查上文故障速查表，表中没有的再
docker compose logs -f（Web 版）或看终端输出（桌面版）。 - 需要定制时，从 frontend/（Vue 3 + Naive UI）或 backend/（Go + Wails 绑定）入手，本地用
wails dev热调。 - 语言与多语言文案在 frontend/src/langs/（中/英/日/韩/西/法/德等 10 种），接口路由见 backend/api/router.go，许可协议见 LICENSE。
【免费下载链接】tiny-rdmTiny RDM (Tiny Redis Desktop Manager) - A modern, colorful, super lightweight Redis GUI client for Mac, Windows, and Linux. It also provides a web version that can be deployed via Docker.项目地址: https://gitcode.com/GitHub_Trending/ti/tiny-rdm
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
