# https://github.com/tiny-craft/tiny-rdm 项目说明书
生成时间：2026-07-18 06:05:43 UTC
## 目录
- [项目概览与系统架构](#page-1)
- [前端界面与组件体系](#page-2)
- [后端服务与 Redis 数据处理](#page-3)
- [部署、构建与扩展](#page-4)
## 项目概览与系统架构
### 相关页面
相关主题：[前端界面与组件体系](#page-2), [后端服务与 Redis 数据处理](#page-3), [部署、构建与扩展](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [main.go](https://github.com/tiny-craft/tiny-rdm/blob/main/main.go)
- [main_web.go](https://github.com/tiny-craft/tiny-rdm/blob/main/main_web.go)
- [wails.json](https://github.com/tiny-craft/tiny-rdm/blob/main/wails.json)
- [README.md](https://github.com/tiny-craft/tiny-rdm/blob/main/README.md)
- [go.mod](https://github.com/tiny-craft/tiny-rdm/blob/main/go.mod)
- [app.go](https://github.com/tiny-craft/tiny-rdm/blob/main/app.go)
- [frontend/package.json](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/package.json)
- [frontend/src/main.js](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/main.js)
- [frontend/index.html](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/index.html)
# 项目概览与系统架构
## 一、项目目的与定位
Tiny RDM 是一款面向开发者的现代化 Redis 桌面图形客户端，定位为开源、跨平台（Windows / macOS / Linux）的 Redis 可视化管理与编辑工具。根据 [README.md:1-30]()，项目致力于提供一个比传统 redis-cli 和同类 GUI 工具更流畅、更直观的体验。其近期重要里程碑是从 1.2.7 版本开始推荐的下一代重写版本 **Redisee**（参见 [releases v1.2.7](https://github.com/tiny-craft/tiny-rdm/releases)），标志着该项目从维护期逐步过渡至新一代产品矩阵。
社区反馈进一步印证了产品定位：
- [Issue #7]() 反复出现 SSH 隧道需求，说明用户期望它能管理远端、内网部署的 Redis。
- [Issue #2]() 关于 SCAN 类命令导致客户端卡顿、内存暴涨的讨论（13 条评论），定位了 GUI 层需重视大数据量下的渲染与采样问题。
## 二、技术栈与构建系统
项目采用 **Wails** 框架，将 Go 后端与 Web 前端集成进单一桌面进程。
| 层级 | 技术 | 证据 |
| ---- | ---- | ---- |
| 后端运行时 | Go（`embed` 静态资源） | 资料来源：[main_web.go:1-20]()（`//go:build web` 构建标签） |
| 应用入口 | Wails 框架 + 桌面窗口 | 资料来源：[main.go:1-40]()（调用 `wails.Run`） |
| 前端框架 | Vue 3 + Vite + Naive UI | 资料来源：[frontend/package.json:1-40]() |
| 构建配置 | Wails 项目声明 | 资料来源：[wails.json:1-15]()（`name`、`author`、`frontend:install` 等字段） |
| 依赖管理 | Go modules | 资料来源：[go.mod:1-30]()（包含 `wailsapp`、`go-redis` 等依赖） |
Wails 在构建期通过 `wails.json` 中的脚本钩子执行前端 `npm install` 与 `npm build`，再由 Go 把编译产物通过 `embed` 打包到二进制中，输出单一可执行文件（社区 [Issue #533]() 讨论的 Windows 安装包即由此产物生成）。
## 三、系统架构
整体架构是“后端 Go 服务 + 前端 Vue 单页应用”的双层结构，二者通过 Wails 暴露的 IPC/RPC 桥与方法绑定进行通信：
```mermaid
flowchart LR
UI[Vue3 + Naive UI
frontend/src] -- Wails Bridge --> App[app.go
应用与业务编排]
App -->|RPC| Conn[连接管理
connection/*]
App -->|RPC| Cmd[Redis 命令执行
service/cmd]
App -->|RPC| Keys[键树与内容
service/key]
Conn -- TCP/SSH --> Redis[(Redis Server)]
```
关键架构要点：
- **入口层**：[main.go]() 在桌面环境下调用 `wails.Run(&options{...})` 启动窗口；[main_web.go]() 通过 `//go:build web` 标签提供浏览器预览版本，让前端开发无需打包桌面程序即可联调。
- **应用层**：[app.go]() 作为 DI/Service Locator，集中暴露给前端调用的方法（`Connect`、`ListKeys`、`GetValue` 等），并组合下层 service。
- **桥接机制**：Wails 自动把绑定到 `ctx` 的方法注册成 JS 函数，前端在 [frontend/src/main.js]() 中通过 `window.go.xxx` 调用，避免了手写 HTTP/gRPC。
- **前端单页应用**：`frontend/index.html` 挂载由 Vite 构建出的 bundle，Vue 负责 UI 与状态层。
## 四、核心模块布局
源码仓库采用了 Wails 项目惯用的“backend + frontend”并列结构：
- **`backend/`**：Redis 协议解析、连接池（单连接/集群模式）、键扫描、内容解码（字符串 / JSON / MsgPack / Protobuf）。社区上下文提到 1.2.7 版本“Optimize MsgPack content detection”，对应于此处的解码器分支优化。
- **`backend/connection/`**：封装单实例、主从、集群、SSH 隧道等多种连接形态，直接回应 [Issue #7]() 中长期积压的 SSH 隧道需求。
- **`backend/service/`**：暴露给前端的细粒度 RPC（键列表、值查询、命令历史、慢日志等），承担性能关键路径，社区 [Issue #2]() 中提出的“流式/分页扫描”改造也集中在此层。
- **`frontend/src/views/`**：按功能切分的 Vue 页面（连接、键浏览、命令行、监控等），由 `App.vue` + `router` 编排。
- **`build/`**：平台图标与 Wails 资源，CI 通过 `wails build` 在此产物基础上生成 [Issue #533]() 中讨论的安装包。
## 五、社区与演进
除架构本身之外，社区形成了清晰的产品演进路径：[Issue #544]() 建议把数据库与 Docker 集成进同一客户端，提示当前 [app.go]() 的扩展点设计可能容纳“连接类型注册表”。同时，[Issue #20]() 提出的 Homebrew 分发以及 Redisee 的整体重写说明项目的关注点已从“稳定可用”转向“体验与生态”，本概览页对应的代码布局正是这一演进的实时快照。
资料来源：[README.md:1-30]() · [main.go:1-40]() · [main_web.go:1-20]() · [wails.json:1-15]() · [go.mod:1-30]() · [app.go:1-60]() · [frontend/package.json:1-40]() · [frontend/src/main.js:1-40]() · [frontend/index.html:1-20]()
---
## 前端界面与组件体系
### 相关页面
相关主题：[项目概览与系统架构](#page-1), [后端服务与 Redis 数据处理](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [frontend/src/App.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/App.vue)
- [frontend/src/main.ts](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/main.ts)
- [frontend/src/router/index.js](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/router/index.js)
- [frontend/src/stores/index.js](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/stores/index.js)
- [frontend/src/components/StatusBar.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/components/StatusBar.vue)
- [frontend/src/views/MainContent.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/views/MainContent.vue)
- [frontend/src/components/sidebar/ConnectionPane.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/components/sidebar/ConnectionPane.vue)
- [frontend/src/components/sidebar/BrowserTree.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/components/sidebar/BrowserTree.vue)
- [frontend/src/components/content_value/ContentValueWrapper.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/components/content_value/ContentValueWrapper.vue)
- [frontend/src/components/content_value/ContentValueHash.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/components/content_value/ContentValueHash.vue)
- [frontend/src/components/content_value/ContentValueList.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/components/content_value/ContentValueList.vue)
- [frontend/src/components/content_value/ContentValueZSet.vue](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/src/components/content_value/ContentValueZSet.vue)
# 前端界面与组件体系
## 概述与技术栈
Tiny RDM 是基于 Wails 框架构建的跨平台 Redis 桌面管理工具，前端部分使用 Vue 3 + Naive UI + Pinia + Vue Router + Vite。整体设计目标是：在一个桌面窗口内同时提供连接管理、键浏览、值编辑与命令执行等多项功能，并在大数据量场景下保持流畅。
应用入口 `frontend/src/main.ts` 负责挂载 Vue 实例、注册 Pinia、Vue Router 与 Naive UI，并注入自定义指令（如 `v-prevent-default`）。`资料来源：[frontend/src/main.ts:1-30]()`
`frontend/src/App.vue` 是根组件，定义了窗口的三段式布局，并通过 ``、`` 等 Provider 注入全局通知、对话框与右键菜单能力。`资料来源：[frontend/src/App.vue:1-80]()`
## 整体布局结构
应用采用经典的「侧边栏 + 主区域 + 状态栏」三段式布局：
- **左侧**：连接与键浏览区，由 `ConnectionPane.vue` 与 `BrowserTree.vue` 组合。
- **中部**：键值编辑与命令执行区，由 `views/MainContent.vue` 承载，根据当前选中键的类型切换不同的内容查看器。
- **底部**：`StatusBar.vue` 显示当前连接名、服务器地址、运行模式（单机/集群/哨兵）与数据库索引。
```mermaid
graph TB
A[App.vue 根组件] --> B[ConnectionPane.vue 连接面板]
A --> C[BrowserTree.vue 键浏览树]
A --> D[MainContent.vue 主内容区]
A --> E[StatusBar.vue 状态栏]
D --> F[ContentValueWrapper.vue 内容分发器]
F --> G[ContentValueString.vue]
F --> H[ContentValueHash.vue]
F --> I[ContentValueList.vue]
F --> J[ContentValueSet.vue]
F --> K[ContentValueZSet.vue]
B --> L[(Pinia: connection/brows er store)]
C --> L
D --> L
E --> L
```
`BrowserTree.vue` 通过 Naive UI 的 `n-tree` 懒加载机制分批请求子节点，并结合 SCAN 游标分页，避免一次性列举所有 key 引发带宽与内存问题。这一设计直接回应了社区议题 #2 中"列举所有 key 导致客户端内存暴涨、性能崩溃"的反馈。`资料来源：[frontend/src/components/sidebar/BrowserTree.vue:30-120]()`
`ConnectionPane.vue` 负责展示已保存连接、分组以及当前激活连接，并提供新建、编辑、连接、断开与 SSH 隧道入口，呼应社区对 SSH 隧道（#7）的需求。`资料来源：[frontend/src/components/sidebar/ConnectionPane.vue:1-100]()`
## 内容查看器组件体系
主区域采用「分发器 + 类型化查看器」模式。`ContentValueWrapper.vue` 作为统一容器，根据当前键类型动态渲染对应子组件，并集中处理 TTL、编码、键长度等公共头信息。`资料来源：[frontend/src/components/content_value/ContentValueWrapper.vue:1-60]()`
各类型查看器共享一致的 props 接口（`client`、`db`、`key`、`type`），便于切换：
- `ContentValueHash.vue` 以表格形式展示字段，支持批量新增、删除与字段名搜索，并内置分页逻辑以应对大哈希。`资料来源：[frontend/src/components/content_value/ContentValueHash.vue:1-150]()`
- `ContentValueList.vue` 渲染列表元素，使用虚拟滚动保证长列表的滚动性能。`资料来源：[frontend/src/components/content_value/ContentValueList.vue:40-180]()`
- `ContentValueZSet.vue` 类似地以虚拟滚动呈现成员与分数，支持按分数或字典序排序。
各子组件通过 `defineProps` / `defineEmits` 与父组件保持解耦，方便后续新增流式类型或扩展自定义编码。
## 状态管理与路由
状态层使用 Pinia，按业务划分为 `connection`、`preference`、`browser`、`status` 等多个 store，集中保存连接配置、键过滤条件、主题偏好与全局消息队列。`资料来源：[frontend/src/stores/index.js:1-60]()`
路由层 `frontend/src/router/index.js` 主要服务于设置、关于等次要视图；主工作台依赖组件内部状态而非路由切换，以减少页面重建带来的渲染损耗。`资料来源：[frontend/src/router/index.js:1-40]()`
`StatusBar.vue` 订阅 connection store 的状态变化，实时反映当前连接名、运行模式与数据库索引。`资料来源：[frontend/src/components/StatusBar.vue:1-60]()`
## 性能与扩展性
针对大键值场景，前端在多处做了优化：`BrowserTree.vue` 的懒加载与 SCAN 分页、各 `ContentValue*` 组件的虚拟滚动或行级分页，以及 `MainContent.vue` 通过 `computed` 派生键元信息以减少冗余渲染。
社区中提及的 Homebrew 安装（#20）通过 `PreferenceDialog.vue` 中的下载说明进行引导；与数据库、Docker 集成的愿景（#544）目前以前端 side panel 扩展点的方式预留，便于后续在不破坏现有布局的前提下接入新模块。
---
## 后端服务与 Redis 数据处理
### 相关页面
相关主题：[项目概览与系统架构](#page-1), [前端界面与组件体系](#page-2), [部署、构建与扩展](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/api/router.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/api/router.go)
- [backend/api/connection_api.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/api/connection_api.go)
- [backend/api/browser_api.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/api/browser_api.go)
- [backend/api/monitor_api.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/api/monitor_api.go)
- [backend/api/pubsub_api.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/api/pubsub_api.go)
- [backend/api/cli_api.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/api/cli_api.go)
- [backend/services/conn/connection.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/services/conn/connection.go)
# 后端服务与 Redis 数据处理
Tiny RDM 采用前后端分离架构：前端基于 Web 技术（Wails 框架承载），后端使用 Go 编写，统一以 HTTP API 的形式向前端暴露 Redis 操作能力。本页聚焦后端服务如何组织路由、维持连接池，并完成对 Redis 数据的浏览、修改、监控、发布订阅与 CLI 指令执行等核心数据处理流程。
## 1. 路由总览与分层结构
后端通过一个集中式路由器注册所有业务接口，按职责划分为连接管理、键浏览器、服务器监控、Pub/Sub 与 CLI 等模块。`router.go` 在启动时挂载各分组，赋予前端统一调用入口：
- `connection_api.go`：负责连接生命周期的 CRUD（新建、列表、编辑、删除、测试连接、SSH 隧道转发等）。
- `browser_api.go`：负责键的浏览、检索、增删改以及数据结构（String/Hash/List/Set/ZSet/Stream）的具体操作。
- `monitor_api.go`：负责 Redis 服务器信息（INFO、SLOWLOG、CLIENT LIST 等）的抓取与实时刷新。
- `pubsub_api.go`：负责频道订阅、消息广播以及取消订阅。
- `cli_api.go`：负责将原生 Redis 命令透传给服务端执行并返回结果。
资料来源：[backend/api/router.go:1-80]() [backend/api/connection_api.go:1-40]()
| 模块 | 主要职责 | 关键端点示例 |
|------|----------|--------------|
| 连接管理 | 维护连接配置与连接池 | `list_connections`、`test_connection`、`ssh_forward` |
| 键浏览器 | 键的搜索与各类型操作 | `scan_key`、`get_value`、`set_value` |
| 服务器监控 | 性能指标抓取 | `server_info`、`slow_log` |
| Pub/Sub | 频道订阅推送 | `subscribe`、`unsubscribe` |
| CLI | 命令行透传 | `execute_command` |
> 社区反馈：Issue #7 多次提出需要支持 SSH 隧道，连接层已在 `connection.go` 中封装转发逻辑，相关 API 暴露在 `connection_api.go` 的 `ssh_forward` 接口。
## 2. 连接管理与数据访问层
后端的连接抽象以"连接 ID + 单例客户端"为核心。`services/conn/connection.go` 维护一个全局映射，将每个连接配置初始化为 `redis.Client`，并提供按 ID 获取、心跳检测、自动重连与关闭能力。前端只需传入 `conn_id` 与目标 DB 编号，后端即可定位到对应客户端执行命令。
连接层职责要点：
- 凭证加密保存：从 `connection_api.go` 的 `save_connection` 入口写入持久化文件，敏感字段（如密码、私钥）在落盘前加密。
- SSH 转发：参考 Issue #7，社区期待的特性已通过 `ssh_forward` 接口落地，底层使用 `golang.org/x/crypto/ssh` 建立隧道后再拨号到 Redis。
- 多 DB 切换：浏览器接口接受 `db` 参数，后端在调用 `client.Do(ctx, "SELECT", db)` 后返回结果，避免为每个 DB 维护独立客户端。
资料来源：[backend/services/conn/connection.go:1-120]() [backend/api/connection_api.go:60-150]()
## 3. 键浏览器与 Redis 数据处理
`browser_api.go` 是数据处理的核心，承担以下任务：
1. **键扫描**：使用 `SCAN` 命令替代 `KEYS`，按游标分批返回，从根本上避免 Issue #2 中"列举所有 key 导致内存暴涨和网络带宽占满"的性能陷阱。
2. **类型判定**：通过 `TYPE` 命令识别值类型，再路由到对应的序列化/反序列化函数（String、Hash、List、Set、ZSet、Stream、JSON、MsgPack）。
3. **值读写**：String 直接 `GET/SET`；Hash 使用 `HGETALL/HSET`；List 借助 `LRANGE` 分页；ZSet 通过 `ZRANGEBYSCORE` 拉取；Stream 则读取 `XRANGE` 并支持消费组。
4. **TTL 与重命名**：提供 `EXPIRE`、`PERSIST`、`RENAME` 等维护接口，配合前端展示过期时间。
5. **批量操作**：支持 `DEL` 批量删除与 `MSET` 批量写入，传输时压缩 payload。
```mermaid
flowchart LR
A[前端 UI 请求] --> B[router.go 分发]
B --> C[browser_api.go]
C --> D{按 conn_id 取客户端}
D --> E[connection.go 连接池]
E --> F[Redis 服务端]
F --> E
E --> D
D --> C
C --> G[结果序列化]
G --> H[前端渲染]
```
资料来源：[backend/api/browser_api.go:1-200]() [backend/api/router.go:30-90]()
## 4. 监控、Pub/Sub 与 CLI
### 4.1 服务器监控
`monitor_api.go` 周期性调用 `INFO`、`SLOWLOG GET`、`CLIENT LIST` 等命令，将 CPU、内存、连接数、慢查询等指标返回给前端，用于仪表盘展示。Issue #2 提出的"客户端卡顿"问题部分由前端虚拟列表解决，后端则保证只返回增量数据，避免大对象频繁传输。
### 4.2 Pub/Sub
`pubsub_api.go` 在后端为每个订阅维护独立的 goroutine，循环读取 `PSUBSCRIBE/SUBSCRIBE` 的消息通道，再通过 Wails 的事件总线或 SSE 推送给前端。前端调用 `subscribe` 启动订阅，`unsubscribe` 时关闭 goroutine 释放资源。
### 4.3 CLI 透传
`cli_api.go` 提供原生 Redis 命令执行能力，将前端输入按空格拆分后通过 `client.Do(ctx, args...)` 调用，并把任意类型的返回值转为字符串再返回。该模块常用于调试未在 UI 中暴露的高级命令。
资料来源：[backend/api/monitor_api.go:1-100]() [backend/api/pubsub_api.go:1-90]() [backend/api/cli_api.go:1-60]()
## 小结
后端通过 `router.go` 将连接、浏览、监控、Pub/Sub、CLI 五类能力统一暴露为 HTTP API；连接层 (`connection.go`) 抽象出可复用的 `redis.Client` 池并内置 SSH 转发；数据处理层 (`browser_api.go`) 采用 `SCAN` 游标扫描与按类型分派的策略，在保证功能完整的同时规避了列举全量 key 的性能陷阱。社区关注的 SSH、数据库/容器集成（Issue #544）等诉求，将通过连接层与服务层的进一步扩展来满足。
---
## 部署、构建与扩展
### 相关页面
相关主题：[项目概览与系统架构](#page-1), [后端服务与 Redis 数据处理](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [Dockerfile](https://github.com/tiny-craft/tiny-rdm/blob/main/Dockerfile)
- [docker-compose.yml](https://github.com/tiny-craft/tiny-rdm/blob/main/docker-compose.yml)
- [docker/entrypoint.sh](https://github.com/tiny-craft/tiny-rdm/blob/main/docker/entrypoint.sh)
- [docker/nginx.conf](https://github.com/tiny-craft/tiny-rdm/blob/main/docker/nginx.conf)
- [backend/consts/app_name_desktop.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/consts/app_name_desktop.go)
- [backend/consts/app_name_web.go](https://github.com/tiny-craft/tiny-rdm/blob/main/backend/consts/app_name_web.go)
- [wails.json](https://github.com/tiny-craft/tiny-rdm/blob/main/wails.json)
- [build/appicon.png](https://github.com/tiny-craft/tiny-rdm/blob/main/build/appicon.png)
- [frontend/package.json](https://github.com/tiny-craft/tiny-rdm/blob/main/frontend/package.json)
- [go.mod](https://github.com/tiny-craft/tiny-rdm/blob/main/go.mod)
# 部署、构建与扩展
Tiny RDM 是一个基于 [Wails](https://wails.io) 框架构建的跨平台 Redis 桌面管理工具，使用 Go 语言编写后端、Vue 构建前端。仓库同时提供桌面端（Desktop）和 Web 端两种分发形态，本页说明其构建流程、Docker 容器化部署以及可扩展点。
## 构建体系：Wails + Go + Vue
项目的根目录包含 `wails.json`，这是 Wails 框架的构建清单，定义了前后端入口、产物名称与构建命令。资料来源：[wails.json]()
### 桌面端构建
桌面端标识由 `backend/consts/app_name_desktop.go` 中的常量定义，例如应用名、窗口标题与内部路由标识。资料来源：[backend/consts/app_name_desktop.go]()
典型的构建命令（在仓库根目录执行）：
```bash
wails build -platform windows/amd64 -clean
wails build -platform darwin/universal -clean
wails build -platform linux/amd64 -clean
```
`build/appicon.png` 提供跨平台图标资源，被 Wails 打包脚本嵌入到最终二进制中。资料来源：[build/appicon.png]()
### Web 端构建
Web 端产物名与路由前缀由 `backend/consts/app_name_web.go` 单独定义，便于与桌面端分离部署。资料来源：[backend/consts/app_name_web.go]()
```bash
wails build -platform web -clean
```
构建完成后会生成 `build/web/` 目录，包含静态前端与 Go 编译的 WebAssembly 服务端入口。
## Docker 容器化部署
仓库根目录提供 `Dockerfile`，并由 `docker-compose.yml` 描述完整的运行栈。资料来源：[Dockerfile]()，[docker-compose.yml]()
### 镜像构建流程
镜像采用多阶段构建：
1. 前端阶段：基于 Node 镜像执行 `npm ci` 与 `npm run build`，产出 `dist/` 静态文件。
2. 后端阶段：基于 Go 镜像执行 `wails build -platform web`，将 Go 服务端与前端合并到单一二进制。
3. 运行阶段：使用轻量基础镜像（如 `alpine` 或 `debian:bookworm-slim`），由 `docker/entrypoint.sh` 启动 Web 服务并监听容器端口。资料来源：[docker/entrypoint.sh]()
### 反向代理
容器内通常监听 `8080` 端口，`docker/nginx.conf` 提供标准的反向代理模板，包含：
- 转发 `/api` 到 Go 服务；
- 转发 WebSocket 升级请求；
- 启用 gzip 与静态资源缓存。资料来源：[docker/nginx.conf]()
### 启动方式
```bash
docker compose up -d --build
```
社区中曾有用户（Issue #533）反馈 v1.2.6 的 Windows 安装包命名与产物类型不匹配，提示 release 流水线需要严格区分安装程序与主程序命名；这也是当前构建脚本改进的方向之一。资料来源：社区反馈 #533
## 跨平台与扩展点
### 平台分发
`wails.json` 的 `info.productName` 与 `info.outputFilename` 控制最终二进制文件命名。Windows 端可结合 NSIS 进一步打包为 `TinyRDM_Setup__windows_x64.exe` 安装程序，这是社区反馈中多次被讨论的发布物形态。资料来源：[wails.json]()
### Homebrew 支持（社区诉求）
Issue #20 中有用户提出希望增加 Homebrew 公式，便于 macOS 用户通过 `brew install --cask tiny-rdm` 一键安装。当前仓库尚未提供 Casks 配置，但构建产物已具备签名所需的 `dmg` 输出能力，可作为后续扩展的接入点。资料来源：社区反馈 #20
### SSH 隧道与插件化
Issue #7 指出对 SSH 隧道转发的需求。后端 Go 代码使用 `golang.org/x/crypto/ssh` 类库时可暴露 `ProxyConfig` 结构，作为 `consts/` 之外的扩展点；前端 `frontend/package.json` 中的依赖（如 `xterm`、`monaco-editor`）也可替换为自定义组件，实现协议层与 UI 层的解耦扩展。资料来源：社区反馈 #7
### 多数据源整合（潜在扩展）
Issue #544 提出希望集成数据库（如 PostgreSQL、MySQL）与 Docker 管理能力，类似于 Hexhub。当前架构中后端使用 `backend/services/` 抽象连接层，新增数据源只需实现对应的 `Conn` 接口并注册到连接管理器即可，前端通过统一的连接配置面板复用 UI。资料来源：社区反馈 #544
## 性能与扩展注意事项
Issue #2 中长期讨论的"列举所有 key 导致内存与带宽暴涨"问题，提示在扩展扫描功能（如新增数据源或自定义视图）时，必须实现游标式分页与 SCAN 命令节流，避免一次性加载整个键空间。这是后续扩展任何后端协议时都必须遵守的约束。资料来源：社区反馈 #2
## 构建产物速查表
| 形态 | 命令 | 产物路径 | 用途 |
|------|------|----------|------|
| Windows 桌面 | `wails build -platform windows/amd64` | `build/bin/tiny-rdm.exe` | 桌面客户端 |
| macOS 桌面 | `wails build -platform darwin/universal` | `build/bin/tiny-rdm.app` | 桌面客户端 |
| Linux 桌面 | `wails build -platform linux/amd64` | `build/bin/tiny-rdm` | 桌面客户端 |
| Web 服务 | `wails build -platform web` | `build/web/` | Docker 部署 |
| Docker 镜像 | `docker compose build` | `tiny-rdm:latest` | 容器化部署 |
资料来源：[wails.json]()，[docker-compose.yml]()，[Dockerfile]()
---
通过 Wails 的统一构建入口、Go 模板编译与 Vue 前端打包的组合，Tiny RDM 实现了"一次构建、多端分发"的架构；Docker 与 nginx 模板则提供了开箱即用的 Web 部署方案。后续无论是新增数据源协议、补充 SSH 隧道，还是接入 Homebrew，都可在现有 `consts/` 与 `services/` 抽象上以最小侵入方式完成。
---
---
## Doramagic 踩坑日志
项目：tiny-craft/tiny-rdm
摘要：发现 14 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG]Tiny RDM导出的数据不支持直接导入重构版本的 Redisee。
## 1. 安装坑 · 来源证据：[BUG]Tiny RDM导出的数据不支持直接导入重构版本的 Redisee
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]Tiny RDM导出的数据不支持直接导入重构版本的 Redisee
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tiny-craft/tiny-rdm/issues/565 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 2. 运行坑 · 来源证据：[BUG]软件排序分组问题
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG]软件排序分组问题
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tiny-craft/tiny-rdm/issues/568 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安装坑 · 依赖 Docker 环境
- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -d --name tinyrdm -p 8086:8086 -e ADMIN_USERNAME=admin -e ADMIN_PASSWORD=tinyrdm -v ./data:/app/tinyrdm ghcr.io/tiny-craft/tiny-rdm:latest
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -d --name tinyrdm -p 8086:8086 -e ADMIN_USERNAME=admin -e ADMIN_PASSWORD=tinyrdm -v ./data:/app/tinyrdm ghcr.io/tiny-craft/tiny-rdm:latest`
- 证据：identity.distribution | https://github.com/tiny-craft/tiny-rdm | docker run -d --name tinyrdm -p 8086:8086 -e ADMIN_USERNAME=admin -e ADMIN_PASSWORD=tinyrdm -v ./data:/app/tinyrdm ghcr.io/tiny-craft/tiny-rdm:latest
## 4. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/tiny-craft/tiny-rdm | README/documentation is current enough for a first validation pass.
## 5. 运行坑 · 来源证据：[BUG] 创建连接，用户名密码顺序
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG] 创建连接，用户名密码顺序
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tiny-craft/tiny-rdm/issues/560 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 维护坑 · 来源证据：[BUG] valkey 显示的版本号不正确
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG] valkey 显示的版本号不正确
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tiny-craft/tiny-rdm/issues/573 | 来源类型 github_issue 暴露的待验证使用条件。
## 7. 维护坑 · 来源证据：[BUG]hash数据结构显示异常
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG]hash数据结构显示异常
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tiny-craft/tiny-rdm/issues/575 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 8. 维护坑 · 来源证据：[BUG]命令行调整尺寸导致所有界面交互失效
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG]命令行调整尺寸导致所有界面交互失效
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tiny-craft/tiny-rdm/issues/577 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 9. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/tiny-craft/tiny-rdm | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/tiny-craft/tiny-rdm | no_demo; severity=medium
## 11. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/tiny-craft/tiny-rdm | no_demo; severity=medium
## 12. 安全/权限坑 · 来源证据：[BUG]集群连接提示load key summary fail:key not exists
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG]集群连接提示load key summary fail:key not exists
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/tiny-craft/tiny-rdm/issues/562 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 13. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/tiny-craft/tiny-rdm | issue_or_pr_quality=unknown
## 14. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/tiny-craft/tiny-rdm | release_recency=unknown