Skip to content

web.md

Latest commit

 

History

History
159 lines (121 loc) · 11.6 KB

web.md

File metadata and controls

159 lines (121 loc) · 11.6 KB
Raw

Flydb 本机 GUI

English | 中文

自 Flydb 0.3.5 提供。使用对应版本的 CLI 发行包；0.3.4 及更早版本不包含此入口。

打开工作台

解压 CLI 发行 ZIP，进入发行目录，运行：

bin/flydb web
# 不自动打开浏览器，或指定端口
bin/flydb web --no-open --port 8317
# 启动时登记一份配置
bin/flydb --config /path/to/project/flydb.conf web

Windows 使用 bin\flydb.bat web。只需要 Java 8+ 和浏览器；发行包内含完整静态界面， 运行时不需要 Node.js、外网或大模型。保持终端中的 Flydb 进程运行。 默认选择可用端口；指定端口被占用时换一个端口或省略 --port。

浏览器会自动打开工作台，没有账户、登录或角色设置。若自动打开失败，将终端打印的 地址复制到浏览器，也可直接打开 http://127.0.0.1:端口/ 或保存为书签。 换用 Safari 等其他浏览器无需额外步骤；同端口重启后可刷新或点击“重试”重新连接。 如果重启时端口改变，请使用新端口对应的地址。 服务只监听 127.0.0.1，不提供远程多人管理入口。

从一份配置开始

点击“添加配置”：

  • 导入已有配置：选择 .conf 文件和工作目录，直接编辑原文件。
  • 新建配置：选择项目目录，填写连接信息，生成配置及迁移目录。已有文件不会覆盖。
  • 发现配置：选择目录，勾选发现的文件后导入；扫描最多深入 6 层、检查 10,000 个条目， 以接口返回的限制提示为准。未覆盖的子目录可以单独选择。

工作目录决定相对脚本路径的含义，请与原先运行 CLI 时的目录保持一致。可以填写名称、 分组和环境标签来区分多套配置；标签只是备注。复制配置会创建新文件，已有文件拒绝覆盖。 “移出工作台”只移除登记，保留原文件和 SQL。

配置连接与驱动

“连接与配置”提供常用连接字段、JDBC URL、迁移位置、密码引用和高级键值编辑。 常用 JDBC 地址可用主机、端口、库名表单填写，特殊厂商 URL 可以直接编辑。 新建配置和连接设置均可选择 Oracle，默认端口 1521，并可选择“服务名”或“SID”。 已有普通 Oracle 服务名/SID 地址会自动填入表单；TNS 描述符、多地址等复杂格式保留直接编辑。 连接格式对应 Oracle JDBC 文档。 界面使用与 CLI 相同的配置加载器；字段定义和覆盖顺序见配置参考。

把自行获取且允许使用的 JDBC JAR 放入发行包 drivers/，或在配置的“编辑名称与分组” 中选择已有驱动目录。界面不上传、打包或分发厂商驱动。Maven 坐标、私服、本地仓库、 下载策略和离线模式沿用 CLI 规则；启用下载策略时，运行时可能访问已配置的仓库。 成功检查后的执行详情会显示解析到的驱动类和来源。

推荐保留 flydb.password=${env:DB_PASSWORD} 或 flydb.password.file=/path/to/password。 环境变量属于启动 Flydb 的进程环境，改变 shell 环境后需重新启动。页面也可填写“本次连接密码”， 它只保存在当前页面内存，刷新后清除；重新预览时应使用执行时相同的密码。 已有密码不会回传为明文，也不会被占位掩码覆盖。

展开“实际生效配置”核对值和来源，避免把环境变量覆盖误认为保存失败。 保存保留未修改的注释、换行和引用。Agent 或编辑器改动文件后，页面提示外部变化； 有草稿时先核对差异、选择冲突字段的保留值，再保存。保存时仍会比较修订，拒绝覆盖新变化。

查看、预览与执行

表单与完整文件编辑

“新建配置”和“连接与配置”均可切换 表单编辑 / 文件编辑。表单覆盖常用连接、密码引用、 脚本位置、驱动与方言及额外配置键；文件模式可直接编辑完整 UTF-8 Properties 内容。 文件模式支持行号、高亮、查找替换、撤销、键补全、自动换行和 ⌘/Ctrl+S 保存。 切换模式保留注释、顺序、续行及表单之外的键。新建时文件模式会收起位置与名称区域， 需要时展开修改；创建按钮始终位于对话框底部。

“检查配置”只检查文件语法和 Flydb 配置值，不连接数据库。创建和保存均会再次检查； 输入错误保留草稿。取消未保存的新增输入需要确认；已有配置可用“还原修改”重新载入。 文件被 Agent 或编辑器修改后，先对照最新文件与自己的草稿，再选择载入文件或继续编辑合并内容。 再次保存仍检查修订，不会静默覆盖期间的新变化。

文件模式按编辑请求读取原文件，若其中含明文凭据也会显示；内容仅存在于当前页面内存， 不进入执行记录、报告或浏览器持久存储。环境变量和密码文件的实际秘密值不会在这里展开。 新建配置复用 flydb init 的完整模板及初始化逻辑：生成 flydb.conf、 db/migration/V1__init.sql 和缺失的 drivers/README.md。界面会显示文件清单， V1__init.sql 仅含 SELECT 1; 示例，执行迁移前应替换为业务 SQL。创建本身不执行 SQL。 项目目录变化时，未自定义的默认迁移路径会更新；手工修改的路径保持不变。 已有配置或同名迁移文件会阻止初始化，已有驱动说明保留。

数据库操作

  1. “刷新状态”读取数据库历史和脚本，不执行迁移 SQL；“校验”检查一致性。
  2. “预览迁移”先校验，再显示实际待执行脚本、顺序、SQL、行号、数量和计划摘要。
  3. 核对目标，点击“确认并执行”。目标、配置、脚本或待执行集合变化会要求重新预览。
  4. 执行详情显示 JDBC 确认数、耗时、最后活动和事务结果；结束后独立展示状态核验结果。

预览不能证明任意 SQL 在厂商数据库上必然成功。SQL 回调和 Java 回调沿用 Core 原有生命周期， 不属于迁移 SQL 预览清单；确认后不应更换回调文件或驱动 JAR。Core 会执行锁内核对过的迁移解析结果。 配置或脚本后续更新不改变已经开始执行的快照。

关闭详情、刷新或关闭浏览器不会取消后台任务。关闭 Flydb 服务或终止操作系统进程可能中断执行； 恢复时没有可信终态的记录显示“结果待核验”，不能将其视作成功或直接重试写入。 先检查目标库和迁移历史，再决定处置。没有自动重放、自动 repair 或模拟进度。

“高级操作”中的基线、撤销、修复分别说明影响并确认目标。撤销先预览匹配的 U__ 脚本； 基线只登记存量版本；修复历史不撤销已执行 SQL。

“清空数据库（clean）”会按方言删除当前连接 schema 的表、视图、序列及 Flydb 历史/锁表， 不限于 Flydb 管理的对象，不是只删除迁移记录。先核对弹窗中的目标连接、账号和备份， 勾选风险确认并输入 CLEAN，再点击“确认清空”。此确认五分钟内单次有效；配置变化后必须重新确认。 确认页面不连接数据库或枚举对象，实际 schema 由连接决定。本地配置和 SQL 文件会保留。 只对本次操作解除 clean 禁用保护，不改写 flydb.conf；失败也可能已删除部分对象，核对现场后再决定后续操作。

与 CLI / Agent 共用

默认执行记录保存在 ~/.flydb/workbench。普通 CLI 操作也登记到同一目录，Web 未启动时仍可记录； 再次打开后从“全部执行记录”查看。当前配置的历史按配置路径关联，不要求 CLI 知道界面分组。

export FLYDB_WORKBENCH_DIR=/path/to/local-state
bin/flydb --config /path/to/flydb.conf info
bin/flydb web

也可仅为 Web 使用 --state-dir，此时若希望观察 CLI，需给 CLI 设置相同的 FLYDB_WORKBENCH_DIR。 记录只覆盖采用本实现的同机 CLI；不自动发现其他机器、旧 CLI 或应用 starter 的执行。 CLI 的 --json stdout 仍为既有机器契约的一行 JSON。

导出和复制采用当前界面语言，保留 SQL、路径和厂商错误原文。密码、URL 秘密参数及名称含 password/secret/token/credential 的配置值会脱敏；业务 SQL 中未标识的敏感常量不可能自动穷尽识别， 分享报告前按项目数据要求检查。记录保留在本地；当前列表显示最近 200 条，旧记录文件不会自动删除。 当前项目和全部执行记录每页 10 条，顶部和底部都可翻页或直接输入页码。后台刷新保留当前页，切换项目后项目记录回到第一页。

语言、主题与问题定位

配置名称右侧的“复制给 Agent”在三个页签均可使用，窄屏位于名称下方。复制内容包含原配置路径、 工作目录、脱敏连接信息、最近一次检查的迁移统计与最多 50 条脚本、最近 10 条执行摘要及错误。 内容标明状态过期、未保存草稿未包含、记录或错误截断等情况，不读取原文件正文、不包含临时密码或 SQL 正文。 复制只写入本机剪贴板，不会自动发送给 Agent；粘贴时可补充具体诉求。Agent 需能访问这些本地路径， 并先核验最新现场，复制上下文本身不授权数据库写入。浏览器禁止自动复制时可在弹窗中手动复制。

侧边栏可新建空分组，点击组名折叠或展开，组旁菜单可重命名、上移、下移或删除。 拖动组名到另一组前可排序，拖到“未分组”可排在末尾；拖动配置到目标组可移动配置， 也可用配置旁的文件夹按钮选择分组。删除分组仅将配置移到“未分组”，保留配置文件及数据库数据。 分组与顺序随工作台保存在本机，重启后保留；折叠状态在当前浏览器记忆。搜索会临时展开匹配组。

左下角可随时切换中文/English 和明暗主题，偏好保存在浏览器。切换语言不会清空当前草稿。 窄屏从左上角菜单选择配置，长 SQL 在预览区域内滚动。 大预览使用只读编辑器，仅渲染可见区域；Ctrl/⌘ F 查找完整 SQL，长行可横向滚动。 “下载完整 SQL”导出当前脚本的全部预览语句；迁移列表每页 10 项，预览目录每页 50 项，支持搜索全部版本、脚本和直接输入页码。迁移列表顶部和底部均有分页入口。 筛选与分页只改变显示范围，总数统计与确认执行仍使用完整集合。

  • 驱动不可用：核对现有 JAR、Java 版本、驱动类名、坐标和离线配置。
  • 连接失败：核对实际 JDBC URL、数据库凭据与网络；保留输入后修正再检查。
  • 校验或迁移失败：打开原始详情，按错误码参考定位，不自动修复历史。
  • 执行记录无法读取（UNREADABLE_RECORD）：表示本地记录读取失败，不代表数据库为空或迁移失败。保留状态目录中的 runs/<报告 id>/summary.json 与 events.jsonl，排查文件大小、完整性和访问权限；核对数据库状态后再决定后续操作。
  • 页面未连接：保持终端进程运行，确认端口后刷新或点击“重试”；换端口时使用新的本机地址。
  • 配置冲突：先合并文件变化再保存；原文件未被覆盖。

构建、架构、接口和验收证据分别见设计、 本机 API和验收记录。