MyGoNavi/README.zh-CN.md

GoNavi - 现代化轻量级数据库客户端

语言: English | 简体中文

GoNavi 是基于 Wails (Go) 与 React 构建的跨平台数据库管理工具，强调原生性能、低资源占用与多数据源统一工作流。

相比常见 Electron 客户端，GoNavi 在体积、启动速度和内存占用上更轻量。

---

项目简介

GoNavi 面向开发者与 DBA，核心目标是让数据库操作在桌面端做到“快、稳、统一”。

• 原生性能架构：Wails（Go + WebView），降低运行时开销。
• 大数据可用性：虚拟滚动 + DataGrid 交互优化，提升大结果集可操作性。
• 统一连接能力：支持 URI 生成/解析、SSH 隧道、代理、驱动按需安装。
• 工程化能力完整：覆盖 SQL 编辑、对象管理、批量导出/备份、数据同步、执行日志、在线更新。

支持的数据源

内置：主程序开箱即用。
可选驱动代理：需在驱动管理中安装启用后可用。

类别	数据源	驱动模式	典型能力
关系型	MySQL	内置	库表浏览、SQL 查询、数据编辑、导出/备份
国产数据库	GoldenDB	内置	MySQL 兼容查询工作流、分布式事务场景
关系型	PostgreSQL	内置	库表浏览、SQL 查询、数据编辑、对象管理
关系型	Oracle	内置	连接查询、对象浏览、数据编辑
缓存	Redis	内置	Key 浏览、命令执行、编码/视图切换
向量数据库	Chroma	内置	Collection 浏览、向量检索、元数据过滤
向量数据库	Qdrant	内置	Collection 浏览、向量搜索、Payload 过滤
向量数据库	Milvus	内置	Collection 浏览、向量搜索、标量过滤
消息队列	RocketMQ	内置	Topic 浏览、消费组检查、消息型工作流
消息队列	MQTT	内置	Broker / Topic Filter 工作流与 QoS 连接配置
消息队列	Kafka	内置	Topic 浏览、Broker 元数据、消费组工作流
消息队列	RabbitMQ	内置	Queue / Exchange 浏览、Virtual Host 检查、Management API 工作流
关系型	MariaDB	可选驱动代理	连接查询、对象管理、数据编辑
关系型	Doris	可选驱动代理	连接查询、对象浏览、SQL 执行
列式分析	StarRocks	可选驱动代理	连接查询、对象浏览、SQL 执行
搜索	Sphinx	可选驱动代理	SphinxQL 查询与对象浏览
关系型	SQL Server	可选驱动代理	库表浏览、SQL 查询、对象管理
文件型	SQLite	可选驱动代理	本地文件库浏览、编辑、导出
文件型	DuckDB	可选驱动代理	大表查询、分页浏览、文件库管理
国产数据库	OceanBase	可选驱动代理	MySQL / Oracle 租户接入、对象浏览、查询工作流
国产数据库	Dameng	可选驱动代理	连接查询、对象浏览、数据编辑
国产数据库	Kingbase	可选驱动代理	连接查询、对象浏览、数据编辑
国产数据库	HighGo	可选驱动代理	连接查询、对象浏览、数据编辑
国产数据库	Vastbase	可选驱动代理	连接查询、对象浏览、数据编辑
国产数据库	OpenGauss	可选驱动代理	类 PostgreSQL 的库表浏览、SQL 查询、对象管理
国产数据库	GaussDB	可选驱动代理	类 PostgreSQL 的库表浏览、SQL 查询、对象管理
多模型数据库	InterSystems IRIS	可选驱动代理	Namespace 浏览、SQL 查询、对象管理
文档型	MongoDB	可选驱动代理	文档查询、集合浏览、连接管理
时序	TDengine	可选驱动代理	时序库表浏览、查询分析
时序	Apache IoTDB	可选驱动代理	Storage Group / Device / Timeseries 浏览与查询
列式分析	ClickHouse	可选驱动代理	分析查询、对象浏览、SQL 执行
联邦查询	Trino	可选驱动代理	跨多数据源联邦 SQL、catalog.schema 浏览、SQL 执行
搜索	Elasticsearch	可选驱动代理	索引浏览、Mapping 检查、JSON DSL / query_string 查询
扩展接入	Custom Driver/DSN	自定义	通过 Driver + DSN 接入更多数据源

📸 项目截图

---

核心特性

AI 智能助手 (New)

• 多模型服务商支持：内置跨平台接入 OpenAI, Google Gemini, Anthropic Claude，同时支持任意自定义兼容 OpenAI 格式的 API。
• 关联表结构上下文：原生支持将当前数据库表结构直接提取作为上下文发送给 AI，让 SQL 生成、分析变得更精准。
• 快捷指令：内置多种快捷对话指（如一键生成 SQL、解释执行逻辑、分析性能优化、表字段代码评审等）。
• 内置 MCP 工作流：可在 AI 设置里管理 MCP 服务，一键安装 GoNavi MCP 到 Claude Code / Codex，或开启 Streamable HTTP 供远端 Agent 使用。
• 远端 Agent 边界清晰：数据库连接与密码继续保留在运行 GoNavi 的主机上，云端 Agent 通过 MCP 读取结构与上下文。
• 安全控制可追溯：远端 schema-only 模式默认不暴露 execute_sql；如开启 SQL 执行，非只读语句仍需显式传入 allowMutating=true。

性能与交互

• 大数据场景下保持流畅交互（含 DataGrid 列宽拖拽、批量编辑流程优化）。
• 虚拟滚动渲染，降低大结果集卡顿风险。

数据管理（DataGrid）

• 单元格所见即所得编辑。
• 批量新增/修改/删除，支持事务提交与回滚。
• 大字段弹窗编辑。
• 右键上下文操作（NULL、复制、导出等）。
• 根据查询上下文智能切换读写模式。
• 支持 CSV / XLSX / JSON / Markdown 导出。

SQL 编辑器

• 基于 Monaco Editor。
• 上下文补全（数据库/表/字段）。
• 多标签查询工作流。

连接与驱动

• URI 生成与解析。
• SSH 隧道、代理支持。
• 连接配置 JSON 导入/导出。
• 可选驱动安装与启用管理。

Redis 工具

• 自动/原始文本/UTF-8/十六进制等视图模式。
• 内置命令执行面板。

可观测性与更新

• SQL 执行日志（含耗时）。
• 启动/定时/手动更新检查。

UI 体验

• Ant Design 5 体系。
• 深色/浅色主题切换。
• 灵活布局与侧边栏行为。

---

技术栈

• 后端: Go 1.24 + Wails v2
• 前端: React 18 + TypeScript + Vite
• UI 框架: Ant Design 5
• 状态管理: Zustand
• 编辑器: Monaco Editor

---

安装与运行

前置要求

• Go 1.21+
• Node.js 18+
• Wails CLI: go install github.com/wailsapp/wails/v2/cmd/wails@v2.11.0

开发模式

# 克隆项目
git clone https://github.com/Syngnat/GoNavi.git
cd GoNavi

# 启动开发（热重载）
wails dev

# 本地快速启动：未修改 Go 导出方法签名时使用
node tools/wails-fast-dev.mjs

# 修改 Go 导出方法签名后刷新 Wails JS 绑定
node tools/wails-fast-dev.mjs --refresh-bindings

# Windows 桌面端默认使用不透明 WebView，并关闭 Acrylic 背景

编译构建

# 构建当前平台
wails build

# 清理后构建（发布前推荐）
wails build -clean

构建产物位于 build/bin。

浏览器访问版（Web Server，实验中）

仓库主程序提供 web-server 运行模式，用同一套 Go 后端 + React 前端提供浏览器访问入口（不是桌面 Wails 窗口容器化）。

本机直接启动

go build .
.\GoNavi-Wails.exe web-server --addr 127.0.0.1:34116

未配置密码时，首次访问会进入 /setup 完成 Web 管理员密码初始化；可选启用 Google Authenticator，服务端会落地 web_auth.json、Session Cookie、恢复码与登录失败限流。

当前阶段已具备：

• 浏览器端 Wails bridge（window.go.* / window.runtime.* -> HTTP / SSE）
• 首次初始化页、登录页、登出接口
• Session 空闲超时 / 绝对超时 / 记住登录时长
• Google Authenticator TOTP 与恢复码
• Docker / Compose 部署入口（见下方）

当前仍在继续收口：

• 外部 SQL / 连接包导入导出等文件型能力的浏览器上传下载工作台
• 更多桌面专属能力的 Web 门禁与替代交互
• 反向代理 / HTTPS / 零信任部署说明

Docker / Podman（Web Server）

cp docker.web-server.env.example docker.web-server.env
# 编辑 GONAVI_HOST_DATA_ROOT 为绝对路径
# 可选设置至少 6 位的 GONAVI_WEB_PASSWORD
docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d

也可以把相同变量写入项目目录下的标准 .env 文件，此时可省略 --env-file docker.web-server.env。

浏览器打开 http://127.0.0.1:34116（或宿主机映射端口）。设置 GONAVI_WEB_PASSWORD 后，新创建的容器会同步该密码并直接进入登录页；未设置时首次访问完成 /setup。

Web 工具中心支持通过浏览器上传/下载连接恢复包；数据目录页显示当前容器挂载目录。Docker 的数据根目录由 GONAVI_HOST_DATA_ROOT 挂载控制，如需切换请修改 env 后重新创建容器，避免在容器内迁移到未持久化路径。

请把 GoNavi 活动数据目录挂载为 /data。建议至少包含 connections.json、daily_secrets.json；如需可选驱动代理应包含 drivers/。Web 认证状态写入同目录下的 web_auth.json。

GONAVI_WEB_PASSWORD 会覆盖 web_auth.json 中已有的密码哈希，但保留 2FA 和会话策略；移除环境变量后继续使用最后一次同步的密码。env 文件包含明文密码，可被有容器检查权限的用户看到，请限制文件读取权限。

修改 env 密码后，需要重新创建容器，让 Compose 重新读取 env 文件：

docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d --force-recreate

Docker Desktop 的 Restart 和 docker restart 会沿用旧容器环境，不会重新读取 env 文件。

新部署直接设置环境密码时会启用纯密码认证。如需启用 2FA，请先留空 GONAVI_WEB_PASSWORD 并通过 /setup 初始化，再将它设置为同一密码后重新创建容器。

容器内默认监听 0.0.0.0:34116（GONAVI_WEB_ADDR）。不要把未加固的 Web 入口直接暴露到公网；生产环境请配合反向代理与 HTTPS。

默认 Compose 拉取 GHCR 预构建镜像。本地源码构建叠加 override：

docker compose --env-file docker.web-server.env \
  -f docker-compose.web-server.yml \
  -f docker-compose.web-server.local.yml \
  up -d --build

健康检查：GET /__gonavi/healthz。

Docker / Podman（MCP Server）

容器化另提供 gonavi-mcp-server（仅 MCP HTTP，不含桌面 GUI / Web UI）。

cp docker.mcp-server.env.example docker.mcp-server.env
docker compose --env-file docker.mcp-server.env -f docker-compose.mcp-server.yml up -d

请把 GoNavi 的活动数据目录挂载进容器。该目录内至少应包含 connections.json、daily_secrets.json，如需可选驱动代理还应包含 drivers/。

默认 Compose 会直接拉取 GHCR 预构建镜像。如果你要用当前仓库源码本地构建，再叠加一个 override：

docker compose --env-file docker.mcp-server.env \
  -f docker-compose.mcp-server.yml \
  -f docker-compose.mcp-server.local.yml \
  up -d --build

如果你使用 Podman，可直接复用同一套 OCI 镜像，走 podman run 或 Quadlet。仓库内已经提供 deploy/podman/gonavi-mcp-server 作为 Podman 原生部署入口，适合 Linux 服务器 / NAS 的 rootless systemd 常驻服务。

部署矩阵：

• Web UI：docker-compose.web-server.yml（镜像 ghcr.io/syngnat/gonavi-web-server）
• MCP：docker-compose.mcp-server.yml（镜像 ghcr.io/syngnat/gonavi-mcp-server）
• Podman / Quadlet：deploy/podman/gonavi-mcp-server
• Kubernetes：deploy/k8s/gonavi-mcp-server（kustomization.yaml + overlays）
• Helm Chart：deploy/helm/gonavi-mcp-server
• 仅构建环境：Dockerfile.build-env

完整部署方式与安全边界见 cmd/gonavi-mcp-server/README.md。

Docker / Podman（仅构建环境）

如果只是想要一套稳定的 Linux 构建环境来编译 Wails，可直接使用 Dockerfile.build-env：

docker build -f Dockerfile.build-env -t gonavi-build-env:local .
docker run --rm -it -v "$PWD:/workspace" -w /workspace gonavi-build-env:local bash

同一个 Dockerfile 也可以直接给 Podman 使用，例如 podman build -f Dockerfile.build-env -t localhost/gonavi-build-env:local .，然后执行 podman run --rm -it -v "$PWD:/workspace" -w /workspace localhost/gonavi-build-env:local bash。

这个镜像默认安装 WebKitGTK 4.0 构建依赖，兼容面更适合常见 Linux / NAS 场景。镜像底座本身支持多架构，amd64 / arm64 会跟随容器平台。

仓库会把预构建镜像推送到 GHCR：

• ghcr.io/syngnat/gonavi-web-server:latest
• ghcr.io/syngnat/gonavi-mcp-server:latest
• ghcr.io/syngnat/gonavi-build-env:latest

这个镜像只负责构建 Linux 产物，不会把 Wails 桌面 GUI 变成可浏览器访问的 Web 服务。

跨平台发布（GitHub Actions）

仓库内置发布流水线，推送 v* Tag 可自动构建并发布 Release。 Release 更新说明会基于已合并 Pull Request 自动生成，并按 .github/release.yaml 分类。

支持目标：

• macOS (AMD64 / ARM64)
• Windows (AMD64)
• Linux (AMD64，含 WebKitGTK 4.0 / 4.1 变体)

---

常见问题

macOS 提示“应用已损坏，无法打开”

在未进行 Apple Notarization 时，Gatekeeper 可能拦截应用。

sudo xattr -rd com.apple.quarantine /Applications/GoNavi.app

Linux 缺少 libwebkit2gtk / libjavascriptcoregtk

# Debian 13 / Ubuntu 24.04+
sudo apt-get update
sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.1-0 libjavascriptcoregtk-4.1-0

# Ubuntu 22.04 / Debian 12
sudo apt-get update
sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.0-37 libjavascriptcoregtk-4.0-18

Linux 中文显示为方框

Ubuntu 24.04 LTS 的最小化桌面或服务器环境可能没有安装中文 CJK 字体，GoNavi 打开后中文会显示为方框。安装 Noto / 文泉驿字体后重启 GoNavi：

sudo apt-get update
sudo apt-get install -y fonts-noto-cjk fonts-wqy-microhei
fc-cache -fv

---

贡献指南

欢迎提交 Issue 与 Pull Request。

完整流程、分支模型与维护者同步规则请查看：

• CONTRIBUTING.zh-CN.md

外部贡献者应从 dev 拉出分支，并统一向 dev 发起 Pull Request。

Star History (Star 增长趋势)

友情链接

• linux.do
• AI全书

开源协议

本项目采用 Apache-2.0 协议。