MagicDB Studio 安装与运行环境
按系统与处理器选择正确的软件包，完成首次启动，并确认内嵌运行时工作正常。
适用场景
本页适用于首次安装、从旧包迁移到新包、使用 Windows 便携版，以及排查“应用能打开但后端未就绪”等启动问题。MagicDB Studio 提供 Windows、macOS 与 Linux 客户端，应用包内包含后端所需的 JRE，正常使用时无需另行安装 Java。
- Windows 日常使用：优先选择安装程序；需要免安装或受限于本机安装权限时选择便携 ZIP 包。
- macOS：必须根据 Intel 或 Apple Silicon 处理器选择对应架构的软件包。
- Linux：可按发行版和使用习惯选择 AppImage 或 deb 包；AppImage 需要执行权限。
- 运行异常定位：先检查设置页的运行时状态，再导出诊断包；不要仅凭系统是否安装 Java 判断应用后端是否正常。
入口路径
从官网 下载页取得与当前系统、处理器架构匹配的软件包。应用启动后，可通过顶部导航进入设置 → 运行时检查后端最大内存与当前生效状态；通过设置 → 诊断与日志查看诊断入口。连接环境的实际可用性则在连接中心通过测试连接确认。
前置条件
| 检查项 | 确认方式 | 风险点 |
|---|---|---|
| 系统与架构 | 确认 Windows、macOS 或 Linux，以及 x64、Intel 或 Apple Silicon | 架构选错可能导致应用或内嵌 JRE 无法启动 |
| 软件包完整性 | 等待下载完成，再从本地磁盘打开 | 不完整下载或在压缩包预览中运行会造成文件缺失 |
| 可写目录 | 确保当前用户可写应用数据与日志目录 | 只读目录可能影响配置保存和诊断日志落盘 |
| 已有配置 | 升级或迁移前先保留原应用数据与连接配置的备份 | 不要用新包直接覆盖仍需回退的便携目录 |
| 数据库网络 | 准备目标主机、端口、账号及必要的 VPN、SSH 或 SSL 材料 | 客户端启动正常不代表网络和数据库权限正常 |
如设备由组织统一管理，还需确认应用执行、安装目录和网络访问未被终端策略拦截。不要为绕过策略关闭系统保护；应保留错误提示并交由管理员核验软件来源和放行方式。
编号步骤
- 确认平台与处理器架构。在系统信息中辨认 Windows x64、macOS Intel、macOS Apple Silicon 或目标 Linux 环境，然后在 下载页选择对应包。下载完成后先核对文件名中的平台与架构标识，不要仅按“最新”字样判断。
- 完成 Windows 安装或便携版解压。安装版按向导选择目录，确认目标位置后再开始安装；便携 ZIP 版必须完整解压到普通文件夹，确认可执行文件及随附资源均已落盘，再运行
MagicDB Studio.exe。不要直接从压缩软件的预览窗口启动，也不要只复制单个可执行文件。 - 在 macOS 或 Linux 放置应用。macOS 使用与芯片匹配的软件包，并按下载页说明将应用放入“应用程序”；Linux 使用 AppImage 时先赋予执行权限再启动，使用 deb 时按系统包管理流程安装。若系统给出来源或权限提示，记录原文并参考 常见问题，不要反复下载不同架构包碰运气。
- 观察首次启动。首次启动时等待桌面界面与内嵌后端完成初始化，不要连续重复打开应用。进入连接中心后，先确认界面可正常切换；此时无需配置系统 Java，也不要急于修改运行时内存。
- 检查内嵌运行时。打开设置 → 运行时，点击刷新，确认状态显示为已生效，并查看当前生效值、系统内存建议与堆内存占用。默认“自动”适合首次启动；如确需调整，先评估其他应用的内存占用，选择预设或填写自定义值，确认后保存。运行时内存变更需要重启后端才会生效，执行重启前先保存正在编辑的 SQL 与未提交工作。
- 做一次可回退的连接验证。在连接中心新建或选择测试数据源，先点击测试连接，确认主机、端口、驱动和认证均通过后再保存。首次验证优先使用非生产环境；不要为了证明安装成功而在生产库执行写入 SQL。
- 保留诊断线索。若启动、运行时或连接测试失败，记下发生时间和完整提示，通过帮助 → 导出诊断包…；白屏或页面不可用时优先使用仍可访问的帮助菜单入口。诊断包用于定位桌面端、渲染进程和后端启动问题，提交前仍应按组织要求确认可共享范围。
参数说明
| 参数或选择 | 用途 | 建议与检查 |
|---|---|---|
| Windows 安装版 | 通过安装向导部署并创建常用入口 | 适合固定设备日常使用；安装前预览并确认目标目录 |
| Windows 便携 ZIP | 免安装运行，便于独立目录保存 | 必须完整解压；升级时使用新目录，验证正常后再处理旧目录 |
| macOS 架构 | 区分 Intel 与 Apple Silicon 包 | 以“关于本机”的芯片信息为准，应用和内嵌 JRE 架构应匹配 |
| Linux AppImage / deb | 分别提供便携运行与系统包安装方式 | AppImage 检查执行权限；deb 按发行版包管理规则处理依赖与卸载 |
| 内嵌 JRE | 运行随客户端启动的后端服务 | 正常情况下无需系统 Java；排障应以运行时页状态和诊断日志为准 |
| 后端最大内存：自动 | 依据当前系统内存采用默认策略 | 首次使用优先保留自动，并观察页面给出的当前生效值 |
| 后端最大内存：预设/自定义 | 为大结果集或复杂任务调整 JVM 堆上限 | 不是越大越好；需为操作系统和其他应用保留内存，修改后重启后端生效 |
| 刷新 | 重新读取运行时状态与内存信息 | 启动后端或重启完成后使用，用于确认新状态而非仅看保存提示 |
预期结果
- 应用可从本地安装目录、应用程序目录或完整解压后的便携目录稳定启动，不依赖压缩包临时目录。
- 设置页“运行时”可读取状态；刷新后显示当前生效的后端最大内存与堆内存信息。
- 连接中心可以打开，新建连接表单和测试连接入口可用；测试失败时能得到明确提示，而不是用保存操作掩盖错误。
- 重启应用或后端后，已保存的运行时选择按页面显示生效；若未生效，应停止继续加大参数并转入诊断。
- 发生异常时可以导出诊断包，并能提供系统、架构、软件包类型、发生时间和复现步骤。
完成以上检查后，才进入数据库连接与工作台验证。建议先连接测试库，执行只读查询并核对结果，再逐步迁移日常配置和生产连接。
常见问题
Windows 便携版双击后没有正常启动，怎么办？
先确认不是在 ZIP 预览窗口中运行，并检查整个压缩包是否已完整解压。将其解压到当前用户可读写的普通目录，保留原有目录结构后重试；仍失败时记录时间并导出诊断包，不要只复制 MagicDB Studio.exe 到其他位置。
macOS 提示无法打开，是否应该改用另一个架构包？
先在“关于本机”确认芯片类型，再核对下载的是 Intel 还是 Apple Silicon 包。架构匹配但仍被系统拦截时，保留系统提示并查看 常见问题中的当前处理说明；不要通过随机更换架构或删除包内文件绕过检查。
电脑已经安装 Java，为什么运行时仍显示异常？
MagicDB Studio 后端使用随应用提供的内嵌 JRE，系统 Java 是否存在通常不能证明内嵌后端可用。请在设置 → 运行时点击刷新，确认状态；失败时导出诊断包，以日志中的 Java 解析和后端启动信息为准。
调整后端最大内存后没有变化，怎么办？
确认已经保存，并按页面提示重启后端；重启前先保存编辑器内容和未提交工作。重启完成后再次进入运行时页点击刷新，以“当前生效”值确认，而不是只看已选择的按钮。若仍不一致，回退原设置并导出诊断包。
应用能打开，但测试连接失败，算安装失败吗？
不一定。先区分运行时状态与数据源状态：运行时正常说明桌面端和内嵌后端已启动；连接失败还可能来自地址、端口、账号权限、数据库服务、VPN、SSH、SSL 或 JDBC 驱动。按 连接管理逐项核对，并先在非生产环境测试。