refactor(homepage): 官网/文档/定价源码迁出程序 + 新增独立授权与激活页 /license

- 官网源码归拢到 homepage/（index/pricing/license + docs.html + content/ + assets/ + docs-assets/），删除程序内 go:embed 的 server/internal/{site,docs}，后端只静态托管 homepage/dist 做本地预览（dist 缺失时打 warn 日志，不再内置兜底；/home 别名保留供 GUI openExternal 使用） - 文档 manifest 按现网口径重建：MCP 页标记 hidden（不再进侧栏与搜索）、补快捷键页、校正 updated 日期 - 新增独立静态页 /license：交付与激活四步（邮件交付授权码）、LIC- 在线与 LICOFF- 离线对比、授权服务器 licence.rlwj.cn 通信范围说明、授权类型与价格、10 条授权 FAQ - tools/homepage-build 支持 hidden 页与可选单页，产出 <name>.html 与 <name>/index.html - 导航/页脚接入 /license，跨页锚点补 / 前缀，页脚底栏文案同步为静态站口径 - 产物零漂移：12 页文档与现网逐字节一致（仅 mcp 隐藏页自身侧栏/上下页行为随之收敛）
2026-10-16 04:18:44 +08:00
1 parent 2c0bfafd8d
commit bf377f3b55
@@ -0,0 +1,38 @@
+OpsxDB 是一款**本地优先**的桌面数据库工作台，面向运维与开发：连库、写 SQL、看结果，全在本机完成。
+
+主交付形态是可安装的桌面应用（Tauri 2），本地 Go 后端随应用自动启动；同一套界面也可用单个二进制在 Web / 内网部署。数据全部保存在本机，不经过任何第三方服务器。
+
+## 功能总览
+
+| 能力 | 说明 |
+| --- | --- |
+| 18 种数据库 | 关系型 / NoSQL / 时序·搜索 / 国产库，全部端到端验收；常用引擎原生内置 |
+| 连接选择器 | 搜索 / 分类 / 最近 / 图标网格；粘贴连接 URL 一键填入表单；连接颜色标记区分环境 |
+| SQL 工作台 | CodeMirror 编辑器、⌘/Ctrl+Enter 执行语句或选区、多 Tab、可拖分栏、格式化、执行历史 |
+| 对象树 | 懒加载库 / 表 / 列 / 索引 / 触发器；点表名直接看前 100 行；右键管理对象 |
+| 结果处理 | 单元格编辑回写 / 右键复制（值·行·JSON·INSERT）/ CSV·JSON·INSERT 导出 / 过滤构建器 / 分页 |
+| Redis 工作台 | 单机 / Sentinel / Cluster；键树浏览（SCAN 游标）、TTL、Hash/JSON 编辑、危险命令拦截 |
+| 安全通道 | 每连接独立配置 SSL/TLS 与 SSH 隧道；后端本机监听 + 访问令牌 |
+| AI 助手 | 生成 / 解释 / 优化 / 修复 / 方言转换 / 样例；OpenAI 兼容协议 + SSE 流式输出 |
+| 危险操作防护 | DROP / TRUNCATE / 无 WHERE 的 UPDATE·DELETE 执行前确认 |
+| 桌面唯一形态 | 桌面 GUI（Tauri 2），本地后端随应用自动拉起 |
+
+## 支持的数据库
+
+| 家族 | 覆盖 |
+| --- | --- |
+| 关系型 | MySQL · MariaDB · TiDB · PostgreSQL · SQL Server · Oracle · SQLite |
+| NoSQL | Redis · MongoDB |
+| 时序 / 搜索 | Elasticsearch · ZooKeeper · InfluxDB |
+| 国产库 | 达梦 DM · OceanBase · GaussDB / openGauss · PolarDB · TDSQL · Kingbase |
+
+> 逐引擎的接入方式、默认端口与能力边界见《[驱动支持](/docs/drivers)》；全部 18 引擎均已实测验收。
+
+## 为什么选 OpsxDB
+
+- **数据主权**：连接配置与查询历史只存在本机；后端默认仅监听 127.0.0.1。
+- **开箱即用**：桌面版双击即用，本地后端随应用自动拉起；官网与文档也由它内置提供。
+- **为快设计**：点表即看数据、⌘Enter 即执行、结果三键取走（复制 / CSV / INSERT）。
+- **轻量克制**：一个 Go 二进制 + 一份前端，内网可部署，无遥测无账号。
+
+> **提示**：想马上动手？直接看下一章《快速开始》，30 秒连上第一个库。
@@ -0,0 +1,65 @@
+本章从零到出结果：起服务 → 建连接 → 执行第一条 SQL。
+
+## 1. 启动
+
+桌面版（主交付形态）双击 OpsxDB 应用即可，本地后端随应用自动拉起。
+
+从源码运行（开发）：
+
+```bash
+git clone <repo> opsxdb && cd opsxdb
+npm install
+
+./run.sh gui    # 桌面形态（开发）：Tauri 窗口 + 本地后端
+./run.sh web    # 仅启动官网与文档 → http://127.0.0.1:8788/
+./run.sh package  # 打桌面安装包（DMG，内嵌后端）
+```
+
+> **注意**：客户端只在桌面 App 里运行。`./run.sh gui` 起的 `:5174` 是桌面 devUrl 的资产服务，不是浏览器客户端；浏览器只用于官网 `/` 与文档 `/docs`（后端 `:8788` 直接提供）。
+
+## 2. 新建连接
+
+1. 打开应用，进入**连接选择器**，选择数据库类型（如 MySQL）；
+
+2. 或者直接粘贴连接 URL，点「填入」自动拆解字段：
+
+   ```
+   mysql://root:pass@127.0.0.1:3306/shop
+   ```
+
+3. 点 **测试** 验证连通性，再点 **保存并连接**。
+
+连接配置保存在本机，密码混淆存储；后续查询只携带会话 ID，不再上送账密。
+
+## 3. 第一次查询
+
+1. 左侧对象树展开库，**点表名**直接查看前 100 行（展开表可看列结构）；
+
+2. 打开 SQL 编辑器，输入：
+
+   ```sql
+   SELECT * FROM orders ORDER BY id DESC LIMIT 100;
+   ```
+
+3. 按 **⌘/Ctrl + Enter** 执行当前语句（或选中的片段）；
+
+4. 结果面板支持**复制 / 导出 CSV / 生成 INSERT**，双击单元格即复制。
+
+## 4. 验证服务
+
+```bash
+curl -s http://127.0.0.1:8788/health
+# {"ok":true,"service":"opsxdb"}
+```
+
+## 5. 手边没有数据库？
+
+本地还没有可连的库？用仓库自带的辅助脚本一键起一个（需要 Docker，一次只起一个）：
+
+```bash
+./tests/dbctl.sh up a    # MySQL
+./tests/dbctl.sh up c    # PostgreSQL（用户 opsx）
+./tests/dbctl.sh up f    # Redis
+```
+
+各驱动的验收状态见《驱动支持》。
@@ -0,0 +1,43 @@
+OpsxDB 的界面为「高频操作」设计：从打开应用到看到数据，路径越短越好。
+
+## 连接选择器
+
+启动后的第一个界面：
+
+- **搜索**：按名称快速过滤已保存的连接；
+- **分类**：关系型 / NoSQL / 国产库 / 时序·搜索 分组浏览；
+- **最近**：最近使用的连接排在最前；
+- **图标网格**：按数据库类型直选，未就绪的类型会标注「未就绪」（仅可保存配置）；
+- **URL 填入**：粘贴 `mysql://user:pass@host:3306/db` 点「填入」，字段自动拆解。
+
+## 工作台布局
+
+连接成功后进入工作台，三栏结构：
+
+| 区域 | 内容 |
+| --- | --- |
+| 左侧 | 连接列表 + 对象树（库 → 表 → 列，懒加载） |
+| 中部 | SQL 编辑器（多 Tab）+ 结果面板，可拖动分栏 |
+| 右侧 | AI 面板（生成 / 解释 / 优化 / 修复 / 方言 / 样例） |
+
+## 对象树
+
+- 点**表名**：直接打开前 100 行数据；
+- 展开**表**：查看列结构；
+- **右键表**：打开表 / 查看 DDL / 生成 SQL（SELECT·INSERT·UPDATE·DELETE）/ 重命名 / 克隆表结构·克隆表（含数据）/ 清空 / 截断 / 删除 —— 危险项红色并二次确认；
+- **右键库**：新建查询 / 新建表（生成 CREATE TABLE 模板到编辑器）/ 复制 / 设为默认库 / 刷新 / 删除库；
+- Redis：按键分隔符编文件夹，点键打开类型化详情（TTL / JSON / 增删字段）；
+- 库列表懒加载，大实例也不卡。
+
+## 编辑器与结果
+
+- CodeMirror 语法高亮，⌘/Ctrl+Enter 执行**当前语句或选区**（不是整页脚本）；
+- 多 Tab 并行查询，互不阻塞；
+- 结果面板：复制 / CSV / INSERT 三种取数方式，双击单元格复制；
+- 超过截断阈值时结果有明确提示。
+
+## 个性化
+
+- 深色 / 浅色主题切换；
+- Tab 布局与主题选择持久化，下次打开保持原样；
+- 查询历史本地留存，可回跳重跑。
@@ -0,0 +1,50 @@
+本章说明各数据库类型的连接表单、URL 格式与高级选项（SSL / SSH 隧道）。
+
+## 通用流程
+
+1. 连接选择器点「新建」或选某个数据库类型；
+2. 填写表单（不同驱动表单不同，见下表）；
+3. **测试** → 通过后 **保存并连接**。
+
+支持直接粘贴 URL 自动填表：
+
+```
+mysql://root:pass@127.0.0.1:3306/shop
+postgres://opsx:pass@127.0.0.1:5432/app
+```
+
+## 各驱动表单
+
+| 驱动 | 表单 | 特有字段 |
+| --- | --- | --- |
+| MySQL / PostgreSQL / SQL Server | standard | host · port · user · password · database · ssl · ssh |
+| Oracle | oracle | host · port · user · password · **service**（如 ORCL） |
+| SQLite | file | database 填本地文件路径（如 `~/data/demo.sqlite`） |
+| Redis | redis | host · port · password · database 序号 · **模式**（单机 / 哨兵 / 集群）· 键分隔符 |
+
+表单只收集服务端实际消费的字段；历史遗留的死参数不会出现在表单里。
+
+## MySQL 族与 PostgreSQL 族
+
+协议兼容的国产库无需单独驱动，直接复用家族驱动：
+
+- **MySQL 族**：MariaDB（3307）、TiDB（4000）、OceanBase（2881）、PolarDB / TDSQL（3306）—— 表单里选对应类型即可；
+- **PostgreSQL 族**：GaussDB / openGauss、人大金仓 Kingbase（54321）—— 走 postgres 表单，注意默认库与用户名差异。
+
+## SSL / TLS
+
+连接表单中开启 **ssl** 即可；按连接独立配置，互不影响。内网自签证书场景按需放宽校验策略。
+
+## SSH 隧道
+
+数据库在跳板机后面时，开启 **ssh** 字段组，填写跳板机地址与凭据：OpsxDB 会先建 SSH 隧道，再把数据库连接走隧道转发，无需把库端口暴露到公网。
+
+## Redis 哨兵与集群
+
+- **哨兵**：模式选 Sentinel，填写 Sentinel 节点列表（`host:port`，多行）和主节点名 `masterName`；
+- **集群**：模式选 Cluster，填写至少一个种子节点。对象树只显示 DB 0（Cluster 无 `SELECT`）；
+- 单机模式只填 host/port，与原先一致。
+
+字段细节与键浏览见 [Redis 工作台](redis)。
+
+> **提示**：连接保存后，后续查询仅携带 `sessionId`，账密不会随每次请求上送；密码在本机混淆存储。
@@ -0,0 +1,49 @@
+OpsxDB 当前支持 18 种数据库，覆盖关系型、NoSQL、时序/搜索与国产库，全部经真实实例端到端验收（ready + verified）。常用引擎以原生 Go 驱动编译内置，开箱即用；JVM 系数据库通过 Agent 桥按需接入。
+
+## 完整支持矩阵
+
+| 数据库 | 类型 | 接入方式 | 默认端口 | 状态 |
+| --- | --- | --- | --- | --- |
+| MySQL | 关系型 | 原生内置 | 3306 | ✅ 已验收 |
+| MariaDB | 关系型 | 原生内置 | 3307 | ✅ 已验收 |
+| TiDB | 关系型 | 原生内置 | 4000 | ✅ 已验收 |
+| PostgreSQL | 关系型 | 原生内置 | 5432 | ✅ 已验收 |
+| SQL Server | 关系型 | 原生内置 | 1433 | ✅ 已验收 |
+| Oracle | 关系型 | 原生内置（go-ora，不引入 JVM） | 1521 | ✅ 已验收 |
+| SQLite | 关系型 | 原生内置（本地文件） | — | ✅ 已验收 |
+| MongoDB | NoSQL | Agent 桥（官方驱动） | 27017 | ✅ 已验收 |
+| Redis | NoSQL | 原生内置 | 6379 | ✅ 已验收 |
+| Elasticsearch | 时序/搜索 | 原生内置（SQL API） | 9200 | ✅ 已验收 |
+| ZooKeeper | 时序/搜索 | Agent 桥 | 2181 | ✅ 已验收 |
+| InfluxDB | 时序/搜索 | 原生内置（Flux） | 8086 | ✅ 已验收 |
+| 达梦 DM | 国产库 | Agent 桥（JDBC） | 5236 | ✅ 已验收 |
+| OceanBase | 国产库 | 原生内置（MySQL 协议族） | 2881 | ✅ 已验收 |
+| GaussDB / openGauss | 国产库 | 原生内置（PG 协议族） | 5432 | ✅ 已验收 |
+| PolarDB | 国产库 | 原生内置（MySQL 协议族） | 3306 | ✅ 已验收 |
+| TDSQL | 国产库 | 原生内置（MySQL 协议族） | 3306 | ✅ 已验收 |
+| Kingbase | 国产库 | 原生内置（PG 协议族） | 54321 | ✅ 已验收 |
+
+## 协议族复用
+
+MySQL 族（MySQL / MariaDB / TiDB / OceanBase / PolarDB / TDSQL）共用同一原生驱动，PostgreSQL 族（PostgreSQL / GaussDB / openGauss / Kingbase）同理 —— 同族引擎的连接体验与能力完全一致，仅默认端口不同。
+
+## Agent 桥驱动（按需下载）
+
+MongoDB、ZooKeeper、达梦通过 JVM Agent 桥接入：
+
+- 首次使用时在**驱动管理器**按需下载对应组件，版本固定并做 sha256 校验（Gitee 主源 + GitHub 备源）；
+- 商业数据库（如达梦官方 JDBC）不代下，需自备 jar 放入驱动目录；
+- Agent 进程随会话池化管理，崩溃自动摘除重建，应用退出级联清理。
+
+## 各引擎能力边界
+
+| 引擎 | 浏览 | 执行 | 写入 | 说明 |
+| --- | --- | --- | --- | --- |
+| 关系型全家 | 库/表/视图/存储过程/索引/外键/触发器 | SQL | ✅（含结果集编辑回写） | MySQL 族附执行计划 |
+| Redis | 键树（SCAN 游标）/ TTL | 命令编辑器 | ✅ | 单机 / Sentinel / Cluster 三模式；危险命令族拦截 |
+| MongoDB | 库/集合 | `db.coll.find()` DSL | ✅（增删改单文档） | 官方驱动经 Agent 桥 |
+| ZooKeeper | 路径树 | GET / SET | ✅（写动词二次确认） | 经 Agent 桥 |
+| Elasticsearch | 索引浏览 | SQL API | 只读 | 官方 JDBC 付费，故走原生 SQL API |
+| InfluxDB | org/bucket 浏览 | Flux 脚本 | 只读 | 用户=org、密码=token |
+
+> **说明（Oracle）**：go-ora 纯 Go 驱动，无需安装 Java；Apple Silicon 容器环境起 Oracle XE 会遇到 ORA-00442 属环境限制，x86 或真实实例不受影响。
@@ -0,0 +1,47 @@
+SQL 工作台是日常使用率最高的界面，所有交互围绕「快」设计。
+
+## 执行模型
+
+- **⌘/Ctrl + Enter**：执行光标所在的**当前语句**；有选区时执行**选区**；
+- 不是「整页脚本」模式 —— 多条语句互不干扰，想跑哪句把光标放哪；
+- Redis 连接共用同一编辑器，按**行**执行命令（见 [Redis 工作台](redis)），不另开 CLI；
+- 执行在会话上运行，连接断开后自动提示。
+
+## 多 Tab 与分栏
+
+- 每个查询一个 Tab，并行执行互不阻塞；
+- 编辑器 / 结果区可拖动分栏，长查询时编辑器不被结果挤占；
+- Tab 与布局持久化，重开应用保持原样。
+
+## 对象树联动
+
+- 左侧对象树懒加载库 / 表 / 列；
+- **点表名 = 打开表工作台**（前 100 行 + 条件过滤 + 结构分页），并回填 SELECT；
+- 展开表看列名与类型，写 SQL 时可对照。
+
+## 查询历史
+
+- 本地留存最近 200 条（不上传、不同步）；
+- **相同语句自动去重置顶** —— 历史即「最近用过的不同语句」，高频查询永远在第一条；
+- 点击条目回填编辑器；悬停出现 **▶** 按钮，回填并直接重跑；
+- 顶部过滤框支持按语句内容或连接名搜索；
+- 条目显示时间、连接名、行数与耗时；失败的语句红色标出。
+
+## 危险 SQL 防护
+
+执行以下语句前会弹确认框：
+
+| 类型 | 规则 |
+| --- | --- |
+| 删除对象 | DROP / TRUNCATE |
+| 全表更新 | 无 WHERE 的 UPDATE / DELETE |
+
+> **注意**：确认框只拦「明确危险」的模式，不替代事务与备份习惯；生产库操作请配合审批流程。
+
+## 快捷键
+
+| 快捷键 | 动作 |
+| --- | --- |
+| ⌘/Ctrl + Enter | 执行当前语句 / 选区 |
+| 双击结果单元格 | 复制单元格内容 |
+| Esc | 关闭弹层 / 取消确认 |
@@ -0,0 +1,40 @@
+查询跑完只是开始，把结果带走才算完成 —— OpsxDB 给了三条最快路径。
+
+## 三种取数方式
+
+| 方式 | 用途 |
+| --- | --- |
+| **复制** | 直接进剪贴板，贴到群聊 / 文档 / 表格 |
+| **CSV** | 导出标准 CSV 文件，Excel / Numbers 直接打开 |
+| **INSERT** | 把结果行生成为 INSERT 语句，直接可在别的库回放 |
+
+## 表数据工作台（关系库）
+
+从对象树打开表后，结果区按 DBeaver / DBX 的数据编辑器组织，而不是只有一张裸网格：
+
+- **工具栏**：刷新、增行、删行、提交（有主键才写回）；
+- **条件过滤**：列 + 运算符（= ≠ > < 包含 空…）+ 值，可加多条 AND；应用后重查，SQL 回填编辑器；
+- **本页搜索**：不打库，只过滤当前结果；
+- **列头**：列名 + 类型色 + 主键标记，悬停看注释。
+
+## 表结构
+
+「结构」分页签：列 / 索引 / 外键 / 触发器 / DDL。MySQL 族、PostgreSQL 族、SQLite、SQL Server、Oracle 都拉元数据；DDL 可复制或插入编辑器。
+
+## 单元格操作
+
+- **双击单元格**：进入编辑（有主键时写回）；长文本可展开；
+- 列头点击排序（仅当前页）。
+
+## 截断提示
+
+为保护界面与内存，超大结果集会按阈值截断展示：
+
+- 结果面板顶部显示「已截断」提示与实际行数；
+- 需要完整数据时，缩小查询范围（加 LIMIT / WHERE）或使用导出。
+
+> **提示**：默认「点表名看前 100 行」就是截断策略的一部分 —— 快速浏览用 100 行，精确取数写 WHERE。
+
+## 与 AI 面板联动
+
+写不出来的查询可以直接在 AI 面板用自然语言描述（「查最近 7 天下单但未支付的用户」），生成 SQL 后放回编辑器执行，见《AI 助手》。
@@ -0,0 +1,93 @@
+Redis 连接使用专用表单（redis）。连上后，对象树是键空间浏览器，编辑器是 Redis 命令行 —— **和 SQL 共用同一套输入框**，不另开 CLI 页。
+
+## 为什么命令行不单独做一套
+
+SQL 工作台已经有：多 Tab、⌘/Ctrl+Enter、查询历史、书签、危险确认、取消。Redis 命令同样是「输入 → 执行 → 结果表」。
+
+拆成独立 CLI（终端 REPL）会让快捷键、历史、危险确认分叉，也和 Navicat 式多引擎工作台不一致。
+
+因此：
+
+|  | SQL | Redis |
+| --- | --- | --- |
+| 输入框 | 同一 CodeMirror | 同一 CodeMirror（占位/补全换成命令） |
+| 切分 | 分号语句 | **按行**（`SET k "a;b"` 不会被分号拆开） |
+| 执行 | ⌘/Ctrl+Enter 当前语句或选区 | ⌘/Ctrl+Enter 当前行或选区 |
+| 结果 | 结果表 | 命令结果表；从对象树打开键则进入键详情 |
+
+Another Redis Desktop Manager 的独立 CLI Tab、opsxsql 的单行命令 + 输出日志，列为后续 P1，不是现在的主路径。
+
+## 键空间浏览
+
+对象树对 Redis 显示 DB0–15（Cluster 仅 0）。展开库后：
+
+- **SCAN 过滤**：输入 `user:*` 点「应用」；生产大库请带前缀，避免扫全库。最多展示 500 个键，超出提示截断。
+- **按分隔符编文件夹**：连接表单的「键分隔符」默认 `:`，`CEX:FOLLOW:FOLLOWERS:1` 显示为 `CEX / FOLLOW / FOLLOWERS / 1`。文件夹显示数量；右键可「只看此前缀」「在此新建键」。
+- **类型色点**：string 绿 / hash 蓝 / list 橙 / set 紫 / zset 青。
+- **点键**：打开键详情（不是假 SELECT）。
+
+## 键详情
+
+对标 Another Redis Desktop Manager 的 Hash/List/Set 视图：
+
+- 类型徽章、键名（回车重命名）、TTL（回车或「保存 TTL」，`-1` 永久）、刷新、导出还原命令、删除；
+- **结构**表：Hash 为 ID / Field / Value，JSON 值自动美化；可新增字段、编辑、删除；
+- **JSON** 视图：整体格式化；
+- 表内关键字过滤。
+
+String 可直接改值保存。
+
+## 命令执行
+
+编辑器直接写 Redis 命令：
+
+```bash
+PING
+SET demo:key "hello" EX 60
+GET demo:key
+HGETALL demo:hash
+SCAN 0 MATCH demo:* COUNT 100
+INFO memory
+```
+
+- 未点名的命令走通用 `Do`（`EXISTS` / `ECHO` / `INFO` / `CLIENT LIST` 等不必再加白名单）；
+- `FLUSHALL` / `FLUSHDB` / `KEYS` / `CONFIG` 仍要二段确认；
+- `KEYS *` 在大库上会阻塞 —— 请用 `SCAN MATCH`。
+
+### 切换逻辑库（SELECT）
+
+`SELECT 1` 是 Redis 官方的切库命令，编辑器直接支持 —— 语义与 redis-cli 一致：**切换后本 Tab 的后续命令都在目标库执行**：
+
+```bash
+SELECT 1
+GET db1:only:key      # 在 db1 执行
+```
+
+- 没有也没有 `USE`（那是 SQL 语法）—— 输入 `USE db1` 会得到 Redis 原生报错
+  `ERR unknown command 'USE'`，与 redis-cli 行为一致；
+- 切库只影响当前查询 Tab（多 Tab 可各连各的库），左侧对象树点开对应库可浏览键；
+- Cluster 模式只有 DB 0，`SELECT` 无效。
+
+## 连接参数
+
+| 字段 | 说明 |
+| --- | --- |
+| host / port | 单机默认 127.0.0.1:6379 |
+| password / user | ACL / requirepass |
+| database | 逻辑库序号（0–15 常见；Cluster 忽略） |
+| 键分隔符 | 对象树文件夹分隔，默认 `:` |
+| ssl | TLS |
+| redisMode | `standalone`（默认）/ `sentinel` / `cluster` |
+| redisNodes | Sentinel / Cluster 节点列表，`host:port` 多行或逗号分隔 |
+| masterName | Sentinel 主节点名（必填） |
+| sentinelPassword | Sentinel 密码（可空） |
+
+### Sentinel
+
+模式选「哨兵」，填写至少一个 Sentinel 地址和 `masterName`（如 `mymaster`）。逻辑库序号仍可用。
+
+### Cluster
+
+模式选「集群」，填写至少一个种子节点。Cluster 不支持 `SELECT` 多库，对象树只暴露 DB 0。槽位路由由客户端处理，键浏览走 `SCAN`。
+
+> **环境**：Sentinel / Cluster 表单与后端已接好；真实拓扑联调见 `docs/BACKLOG.md` 环境缺口。
@@ -0,0 +1,35 @@
+连生产库的工具，安全必须是默认项。OpsxDB 的安全设计围绕一句话：**数据不出你的机器。**
+
+## 本地优先
+
+- 连接配置、查询历史、主题偏好全部保存在本机；
+- 无账号体系、无遥测、无云端同步；
+- 后端默认只监听 `127.0.0.1`，对外服务需要显式配置（`OPSXDB_BIND_PUBLIC=1` 或 `OPSXDB_ADDR`）。
+
+## 凭据保护
+
+| 层面 | 机制 |
+| --- | --- |
+| 存储 | 连接密码在本机混淆存储，不落明文 |
+| 传输 | 连接建立后，后续查询只携带 `sessionId`，账密不再每次上送 |
+| 会话 | 会话在服务端维护，可主动关闭（连接断开即失效） |
+
+## 加密通道
+
+**SSL / TLS**：每个连接可独立开启；数据库支持 TLS 即可启用（MySQL、PostgreSQL、SQL Server、Redis、MongoDB 均支持）。
+
+**SSH 隧道**：数据库在跳板机后时，配置 SSH 字段组，OpsxDB 先建隧道再转发数据库连接 —— 库端口不必暴露公网。
+
+## 危险操作防护
+
+- DROP / TRUNCATE 执行前确认；
+- 无 WHERE 的 UPDATE / DELETE 执行前确认；
+- 结果集按阈值截断，避免误操作拖垮界面。
+
+## 内网部署形态
+
+单二进制 + 内置静态页（官网 / 文档 / 工作台），无外部依赖：
+
+- 任意内网主机可部署；
+- 无外联请求，可在纯内网环境运行；
+- 升级即替换一个二进制。
@@ -0,0 +1,39 @@
+AI 面板的目标：让「写不出的 SQL」和「看不懂的 SQL」不再阻塞你。
+
+侧栏支持 **Ask | Agent**：Ask 只生成 SQL；Agent 调用与 MCP 同源的只读工具真查库。外部编辑器可用 `npx @rlwj-lab/opsxdb-mcp` 接入（见应用内《AI 助手》文档）。
+
+## 六种动作
+
+| 动作 | 用途 |
+| --- | --- |
+| 生成 | 自然语言 → SQL（「查最近 7 天下单但未支付的用户」） |
+| 解释 | 把一段复杂 SQL 翻译成中文说明 |
+| 优化 | 分析慢查询，给出索引 / 改写建议 |
+| 修复 | 报错信息 + SQL → 修正版本 |
+| 方言 | MySQL ↔ PostgreSQL 等跨方言转换 |
+| 样例 | 按表结构生成示例查询 |
+
+## 使用方式
+
+1. 连接库后打开右侧 AI 面板；
+2. 选择动作，输入需求或粘贴 SQL（可附上对象树上下文）；
+3. 生成结果一键放回编辑器，⌘/Ctrl + Enter 执行。
+
+> **提示**：生成的 SQL 依旧走危险语句确认流程 —— AI 产出与手写 SQL 同等对待，不放宽防护。
+
+## 接入真实模型
+
+AI 面板支持任何 **OpenAI 兼容协议**的服务（OpenAI / DeepSeek / 通义 / 本地 vLLM 等），回复以 **SSE 流式**逐字输出，等待模型时不再面对空白。
+
+配置入口（二选一）：
+
+1. AI 面板右上角「**配置**」：填 Base URL、API Key、模型名，保存后可一键测试；
+2. 配置文件 `~/.opsxdb/ai.json`（权限 0600），或环境变量 `OPSXDB_AI_PROVIDER / OPSXDB_AI_BASE_URL / OPSXDB_AI_API_KEY / OPSXDB_AI_MODEL`。
+
+> **说明**：未配置 API Key 时回落本地 stub（离线占位，内容为模板演示）；AI Key 保存后服务端只回显掩码（`sk-***`）。
+
+## 数据流向承诺
+
+- 默认只发送你明确提交的内容（附当前库表结构上下文，不含连接凭据）；
+- 可完全关闭 AI 功能（顶栏隐藏面板即可，无后台请求）；
+- 使用云端模型时在界面上明确标识，生成 SQL 依旧走危险语句确认流程。
@@ -0,0 +1,40 @@
+## 产品形态
+
+**Q：能在浏览器里操作数据库吗？**  
+不能。OpsxDB 客户端唯一形态是桌面 App（Tauri 2）；浏览器只承载官网与文档（由本地后端 `:8788` 内置提供）。开发时的 `:5174` 只是桌面 devUrl 的资产服务，不是网页客户端。
+
+**Q：官网和文档部署在哪？**  
+就内置在你运行的那个二进制里：`http://127.0.0.1:8788/` 是官网，`/docs` 是文档；无需额外部署。
+
+**Q：怎么打安装包？**  
+`./run.sh package` 产出 Tauri 安装包（DMG）并内嵌 sidecar 后端二进制。
+
+## 数据与安全
+
+**Q：我的连接密码存在哪？**  
+本机，混淆存储；查询只带会话 ID，密码不会随请求重复上送，也不会同步到云端。
+
+**Q：会上传我的 SQL 或查询结果吗？**  
+不会。没有遥测、没有账号、没有云依赖。AI 助手为可选功能：只有你主动配置了模型服务并主动提问时，才会把当次请求（含库表结构上下文，不含连接凭据）发给你指定的服务地址。
+
+**Q：能在公司内网用吗？**  
+能。单二进制 + 内置静态页，无外部依赖；默认只监听回环地址，对外需显式配置。
+
+## 驱动相关
+
+**Q：Oracle 能用吗？**  
+驱动代码就绪（go-ora 纯 Go 实现，无需 JVM），但本机 docker 验收在 Apple Silicon 上受镜像限制未通过（ORA-00442），需 x86 环境或真库完成验收，详见《驱动支持》。
+
+**Q：达梦 / MongoDB 什么时候支持？**  
+已列入路线：长尾库（达梦、MongoDB、ZooKeeper、ES、InfluxDB）规划 agent 按需接入，驱动分发走独立仓库并校验 sha256。
+
+**Q：MySQL 族 / PG 族的国产库怎么连？**  
+协议兼容直接复用家族驱动：TiDB / OceanBase / PolarDB / TDSQL 选对应类型（MySQL 协议）；GaussDB / Kingbase 走 PostgreSQL 表单。注意各自默认端口与用户名差异。
+
+## 其他
+
+**Q：和 OpsxAPI 是什么关系？**  
+同一团队的姊妹项目：OpsxAPI 是接口工作台，OpsxDB 是数据库工作台，共用一套 monorepo 脚手架（web + Gin + 可选 Tauri），产品面各自独立。
+
+**Q：快捷键有哪些？**  
+核心就一个：⌘/Ctrl + Enter 执行当前语句或选区；双击结果单元格复制。完整列表见《SQL 工作台》。
@@ -0,0 +1,48 @@
+快捷键是 OpsxDB 的第一等操作方式 —— 高频动作全部可以不碰鼠标完成。
+
+> Windows / Linux 上 `⌘` 对应 `Ctrl`。
+
+## 全局与工作台
+
+| 快捷键 | 动作 |
+| --- | --- |
+| `⌘ Enter` | 执行当前语句或选区（自动按语句切分） |
+| `⌘ P` | 快速跳转：模糊搜索库 / 表，Enter 直达数据 |
+| `⌘ T` | 新建查询 Tab |
+| `⌘ W` | 关闭当前查询（有未保存改动会确认） |
+| `⌘ 1–9` | 切到第 N 个查询 |
+| `Ctrl Tab` | 循环切换查询 |
+| `Alt ↑ / ↓` | 上一条 / 下一条语句（编辑器内） |
+| `⌘ ⇧ F` | 聚焦对象树过滤框 |
+| `F5` | 刷新对象树 |
+| `⌘ B` | 显示 / 隐藏 AI 面板 |
+| `⌘ /` | 快捷键帮助 |
+
+## 结果网格
+
+| 快捷键 / 操作 | 动作 |
+| --- | --- |
+| `↑` `↓` | 上下移动选中行 |
+| `PgUp` `PgDn` | 翻页移动 |
+| `Home` `End` | 跳到首行 / 末行 |
+| 双击单元格 / `Enter` | 进入单元格编辑 |
+| `Delete` `Backspace` | 清空选中格（进入编辑） |
+| `⌘ Z`（编辑中） | 撤销本格改动，恢复进入编辑前的值 |
+| `Esc` | 取消编辑 / 关闭弹层与菜单 |
+| `Ctrl/⌘ + C` | 复制选中单元格值（无列选中时复制整行 TSV） |
+| 右键单元格 | 编辑 / 复制单元格值 / 复制行（TSV · JSON · INSERT）/ 查看全文 |
+| 多格复制粘贴 | 与 Excel 互通：复制区域后直接粘贴进网格批量暂存 |
+| 双击分栏分隔条 | 结果区最大化 / 还原 |
+
+## 对象树
+
+| 操作 | 动作 |
+| --- | --- |
+| 双击表名 | 打开表工作台（看前 100 行） |
+| 右键库 | 新建查询 / 浏览对象 / 复制 / 设为默认库 / 刷新 / 删除库 |
+| 右键表 / 视图 | 查看数据 / 查看 DDL / 复制 / 清空截断 / 删除表 |
+| `↑` `↓` `→` `←` `Enter` | 键盘导航（展开 / 收起 / 进入） |
+
+## SQL 编辑器右键
+
+编辑器内右键可完成：执行选中语句、执行当前语句、查看数据、查看 DDL、剪切 / 复制 / 粘贴 / 全选 —— 系统默认菜单被替换，不再跳出「Look Up / 检查元素」。
@@ -0,0 +1,110 @@
+# MCP 接入
+
+把 Cursor、Claude Code、VS Code 等 AI 客户端接到 OpsxDB，即可用自然语言查看结构、查询白名单内的库，并与侧栏 Agent **共用同一套工具与安全策略**。
+
+## 什么是 MCP？
+
+MCP（Model Context Protocol）让 AI 客户端调用本机工具。OpsxDB MCP 读取桌面已保存的连接（`~/.opsxdb/connections.json`），权限由 `~/.opsxdb/mcp.json` 统一约束。
+
+```
+AI 助手 → opsxdb-mcp (stdio) → aitools Runtime → 你的数据库
+                                    ↘ 审计 ~/.opsxdb/logs/mcp-audit.jsonl
+```
+
+## 安装
+
+### 1. Node 启动器（npm）
+
+```bash
+npm install -g @rlwj-lab/opsxdb-mcp@latest
+# 或一次性
+npx -y @rlwj-lab/opsxdb-mcp
+```
+
+### 2. Go 二进制（必需）
+
+npm 包只是启动器，真正的 MCP 服务是 Go 二进制：
+
+```bash
+cd server && go build -o ../bin/opsxdb-mcp ./cmd/opsxdb-mcp
+export OPSXDB_MCP_BIN=/绝对路径/opsxdb/bin/opsxdb-mcp
+```
+
+也可把该二进制放到 PATH（需排在 npm shim 之前）。
+
+### 3. 桌面设置
+
+打开 **设置 → MCP**：
+
+- 查看 Node / npm / 包版本 / Go 二进制是否就绪
+- 复制安装命令与各客户端配置片段
+- 查看读写权限，并勾选允许访问的连接；新配置默认允许读写和危险 SQL
+
+## 配置 AI 客户端
+
+以 Cursor 为例（`~/.cursor/mcp.json` 或项目 `.cursor/mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "opsxdb": {
+      "command": "npx",
+      "args": ["-y", "@rlwj-lab/opsxdb-mcp"],
+      "env": {
+        "OPSXDB_MCP_BIN": "/绝对路径/opsxdb/bin/opsxdb-mcp"
+      }
+    }
+  }
+}
+```
+
+Claude Code 使用项目根目录 `.mcp.json`（结构相同）。VS Code / Windsurf / Codex / Claude Desktop 的片段可在 **设置 → MCP** 中按 Tab 复制。
+
+> GUI 客户端不一定继承 shell 的 PATH；请使用 `OPSXDB_MCP_BIN` 绝对路径，不要只写 `opsxdb-mcp` 或 `~`。
+
+## 安全策略
+
+| 项 | 说明 |
+| --- | --- |
+| 默认读写 | 新配置使用 `mode=read_write`；Agent 每次写入前显示确认弹框 |
+| 危险 SQL | 新配置默认 `allow_dangerous=true`，DROP/TRUNCATE/ALTER/无 WHERE 更新删除等仍须确认 |
+| 旧配置 | 沿用已保存的权限；设置中选择「使用默认权限」可启用读写与危险 SQL |
+| 连接白名单 | `allowed_connection_ids`；**空=拒绝全部** |
+| 审计 | `~/.opsxdb/logs/mcp-audit.jsonl`（含 tool、connection_id、run_id） |
+
+外部客户端若在 `read_write` 下自行传 `confirm_danger`，视为操作者授权；桌面侧栏 Agent **不会**让模型静默带确认令牌。
+保存白名单或权限后，外部 MCP 进程在下一次工具调用时读取新策略，无需重启桌面或 AI 客户端；策略文件读取失败时该次调用会被拒绝。
+
+## 工具列表
+
+| 工具 | 说明 |
+| --- | --- |
+| `opsxdb_list_connections` | 白名单内连接 |
+| `opsxdb_list_databases` | 库列表 |
+| `opsxdb_list_tables` | 表/视图 |
+| `opsxdb_describe_table` | 列定义 |
+| `opsxdb_get_schema_context` | 紧凑 schema 文本 |
+| `opsxdb_execute_query` | SQL（写入需确认，查询有行数上限） |
+| `opsxdb_execute_redis_command` | Redis（写入需确认；FLUSH*/KEYS 永拒） |
+
+## 侧栏 Ask | Agent
+
+- **Ask**：生成/解释/优化，不调库
+- **Agent**：多轮调用与 MCP 同源工具；支持 SSE 步骤时间线、「插入编辑器」「在结果区打开」
+
+详见 [AI 助手](/docs/ai)。
+
+## 开始使用
+
+在 AI 客户端中试：
+
+- 「列出我的数据库连接」
+- 「demo 库有哪些表」
+- 「查看 users 表结构并查前 5 行」
+
+## 系统要求
+
+- Node.js 18+（若用 npm/npx 启动器）
+- 已安装 OpsxDB 桌面端并至少保存一个连接
+- 已构建 `opsxdb-mcp` Go 二进制
+- 在设置 → MCP 勾选连接白名单
@@ -0,0 +1,43 @@
+{
+  "productVersion": "0.1",
+  "groups": [
+    {
+      "name": "开始使用",
+      "pages": [
+        { "file": "01-intro.md", "slug": "intro", "title": "产品介绍", "updated": "2026-09-23" },
+        { "file": "02-quickstart.md", "slug": "quickstart", "title": "快速开始", "updated": "2026-09-20" },
+        { "file": "03-interface.md", "slug": "interface", "title": "界面导览", "updated": "2026-09-20" }
+      ]
+    },
+    {
+      "name": "连接与驱动",
+      "pages": [
+        { "file": "04-connect.md", "slug": "connect", "title": "新建连接", "updated": "2026-09-20" },
+        { "file": "05-drivers.md", "slug": "drivers", "title": "驱动支持", "updated": "2026-09-23" }
+      ]
+    },
+    {
+      "name": "SQL 工作台",
+      "pages": [
+        { "file": "06-workbench.md", "slug": "workbench", "title": "SQL 工作台", "updated": "2026-09-20" },
+        { "file": "07-results.md", "slug": "results", "title": "结果与导出", "updated": "2026-09-20" },
+        { "file": "08-redis.md", "slug": "redis", "title": "Redis 工作台", "updated": "2026-09-20" }
+      ]
+    },
+    {
+      "name": "安全与 AI",
+      "pages": [
+        { "file": "09-security.md", "slug": "security", "title": "安全设计", "updated": "2026-09-20" },
+        { "file": "10-ai.md", "slug": "ai", "title": "AI 助手", "updated": "2026-09-23" },
+        { "file": "13-mcp.md", "slug": "mcp", "title": "MCP 接入", "updated": "2026-10-15", "hidden": true }
+      ]
+    },
+    {
+      "name": "参考",
+      "pages": [
+        { "file": "11-faq.md", "slug": "faq", "title": "常见问题", "updated": "2026-09-20" },
+        { "file": "12-shortcuts.md", "slug": "shortcuts", "title": "快捷键", "updated": "2026-09-23" }
+      ]
+    }
+  ]
+}