Firescope 使用手册

安装

1. 从下载页面获取 Mac 版的.dmg(可选择 Apple Silicon / Intel)。
2. 打开下载的 .dmg,将 Firescope 图标拖到“应用程序”文件夹即可。
3. 从“应用程序”文件夹启动 Firescope。

Windows

1. 从下载页面获取 Firescope-Setup.exe并运行。
2. 首次运行如果出现 SmartScreen 警告,请点击“更多信息”→“仍要运行”继续。

初始设置(语言与主题)

首次启动会打开 4 步设置向导。首先选择显示语言(内置简体中文・繁體中文・日本語・English・한국어・Español・Português・Français・Deutsch 共 9 种语言)。点击后会立即在界面上生效,拿不定主意时不妨点击试试。

接下来选择外观主题。包括 Light / Dark 等共 10 种主题,同样点击即可即时预览。

连接 Firestore

连接需要使用 Firebase 的服务账号私钥(JSON)。即使还没有,按照界面提示操作,大约 1 分钟即可获取。

1. 点击“打开服务账号设置页面”,会在浏览器中打开 Firebase 控制台的相应页面(路径:项目设置 → 服务账号)。
2. 点击“生成新的私钥”下载 JSON 文件。
3. 返回 Firescope,从“选择 JSON 文件以连接”中选择刚下载的 JSON。也可以一次选择多个项目的 JSON,同时完成连接。
4. 选择连接的环境(开发 / 测试 / 预发布 / 生产)。 会在侧边栏以彩色标签显示,安全防护的强度也由该标签决定。

浏览数据

打开侧边栏的连接并点击集合,文档即会以表格形式显示。每一列的表头都带有类型徽章(string / int / time 等),数据结构一目了然。

• 点击一行,右侧面板会显示该文档的全部字段。
• 排序方式、显示条数、分组搜索(集合组)都可以在工具栏中更改。
• 读取次数会一直显示在状态栏(作为计费用量的参考)。

逻辑名称(字段名翻译显示)

可以将 carryingOutCoffinMasterId 这样的英文字段名,显示为中文等逻辑名称。通过工具栏的“逻辑名称”开关,可以随时切换物理名称与逻辑名称。

• 字典可通过工具栏的 📖 图标编辑。应用范围分为“整个连接通用”和“仅此集合(覆盖)”两层。
• “自动翻译”可通过内置字典 + 免费翻译 API,一次性填充空白项。
• “打开 Google 翻译”会以英文化的字段名打开翻译页面,只需复制译文并返回应用,即可一次性应用。
• 右键点击列标题 →“设置逻辑名称…”,可以立即单独编辑该列。
• 表头的类型徽章(string / int 等)可通过“显示类型”开关切换显示/隐藏。

标签页与分组

右键点击集合 →“在新标签页中打开”,即可像浏览器一样增加标签页。标签页可以像 Chrome 一样归入分组。

• 右键点击标签页 →“添加到新分组”即可创建分组,可设置名称和颜色。
• 点击分组色块可折叠/展开。
• 双击标签页可更改名称和背景色。
• 支持拖放排序,以及在分组之间移入移出。
• 标签页状态在重启后依然保留(可在设置中关闭)。

分屏视图

右键点击集合 →“在右侧分屏显示”,即可将两个集合左右并排显示。非常适合核对主数据与交易数据。

• 也可以从侧边栏将集合拖到屏幕左右两端来分屏。
• 拖动面板色块可以交换左右位置,或取出到新标签页。
• 分屏状态按标签页各自保留。

实时监控

点击工具栏的“监控”,当前显示集合的变更即会实时同步到表格。无论是其他应用还是服务器写入的数据,都无需刷新即可看到。

• 开始前的对话框中,可以按条件(字段、值)、排序和数量进行筛选。
• 右侧的变更动态会按时间顺序列出“新增 / 更新 / 删除”,并显示发生变化的字段名。
• 监控是只读的。监控过程中的写入操作依然会照常经过安全流水线。
• 最多可同时监控 5 个。
• 达到指定时间后会自动停止(可在设置中更改时长),避免过度消耗读取次数。

编辑数据

双击单元格即可就地编辑。 按 Enter 确认,按 Esc 取消。 int、timestamp 等类型会在写入时保持不变。

所有写入都会经过安全流水线:

1. 确认 — 会弹出与环境标签 × 操作风险相对应的对话框。对生产环境的破坏性操作需要输入项目 ID。
2. 自动备份 — 受影响的文档会在执行前生成快照。
3. 执行 — 完成写入。
4. 操作日志 — 无论成败都会被记录(可在底部栏的“操作日志”中查看)。

备份与恢复

破坏性操作执行前生成的快照,会汇集在底部栏的“备份”中。选中后会打开恢复预览,可以先查看重建 / 覆盖 / 无变化的差异,再执行恢复。

• 按 ⌘Z(或点击侧边栏的 ↩︎ 图标)即可立即恢复最近一次写入。
• 快照超过世代上限后会从最旧的开始删除。想保留的可以点击 📌 置顶。

控制台

在侧边栏的“控制台”中,可以编写 firebase-admin 风格的 JavaScript 查询。按 ⌘Enter 执行后,结果会以带类型标注的表格显示。

const snap = await db.collection('orders')
  .where('status', '==', 'paid')
  .orderBy('amount', 'desc')
  .limit(20)
  .get();
return snap.docs.map((d) => ({ id: d.id, ...d.data() }));

• 喜欢用鼠标操作的用户,也可以使用可视化构建器(获取 / 更新 / 创建 / 删除)。构建好的条件可通过“反映到代码”转换为 JS。
• 包含写入的代码会按试运行 → 写入预览 → 应用的顺序执行,数据不会突然被更改。
• 也支持联结(join)显示。

CSV 导入/导出

导出

点击集合工具栏的“CSV 导出”,即可将当前显示的查询结果(已应用筛选与排序)保存为 CSV。表头会带有类型标注,即使之后重新导入,类型也不会丢失。

导入

1. 点击工具栏的“导入”→ 选择 CSV 文件(自动识别 Shift_JIS 编码)。
2. 确认每列的类型,以及模式(upsert / 仅新增 / 仅更新)。
3. 点击“确认数量”预览将新建和覆盖的文档数量。
4. 点击“执行导入”→ 经过确认对话框后完成导入。被覆盖的部分会在执行前自动备份。

架构检查(检测架构不一致)

右键点击集合 →“架构检查…”,即可读取整个集合,自动检测类型混杂的字段、仅部分文档缺失的字段,以及可能存在拼写错误的稀有字段(上限 20,000 条)。

• 同一批文档中共同缺失的字段会归并为一张卡片。点击“全部展开”即可为所有相关行打勾,直接进行批量删除等操作。
• 点击对应文档的 ID,会自动滚动到表格中的该行并高亮显示。
• 结果在关闭向导后依然保留,可以反复查看文档并来回切换。
• 在Zod 架构校验标签页中,可以粘贴 Zod 架构(TypeScript)来校验全部文档。

环境对比与复制

与其他环境对比

右键点击集合 →“与其他环境对比…”,即可比较开发和生产等两个环境下同名的集合。差异(新增 / 删除 / 变更)会按文档和字段列出。

• 可以指定 updatedAt 等要从对比中排除的字段。
• 差异内容可以导出为 CSV。

复制到其他环境

通过“复制到其他环境…”,可以将集合复制到另一个连接(环境)。执行前会预览数量以及是否存在覆盖,写入生产环境时依然会经过与平时相同的严格确认防护。

Authentication 用户

在侧边栏的“Authentication”中,可以查看和管理 Firebase Authentication 的用户。

• 列表显示邮箱、显示名称、登录方式、创建日期和最后登录时间。也可通过逻辑名称开关以中文显示字段名。
• 支持对用户进行禁用 / 启用 / 删除,以及发送密码重置邮件。
• 可以复制用户的 UID,用于与 Firestore 中的文档进行核对。
• 破坏性操作(如删除)同样会经过与 Firestore 相同的安全流水线(确认 → 操作日志)。

更新

• 系统会每 6 小时以及每次启动时自动检查更新(也可以在“设置 → 关于”中点击“检查更新”手动检查)。
• 如果发布了强制更新,启动时的更新界面会自动完成下载 → 重启 → 应用,无需任何点击操作。
• 仅在失败时(例如离线),才会提示通过浏览器手动下载。

价格与许可

• 首次启动起的 14 天为试用期,可使用全部功能。无需注册,也无需支付信息。
• 即使试用到期,数据的浏览功能依然可以免费继续使用。
• 购买可在应用内完成:点击右下角的 ⚙ 设置 → 许可证,选择套餐(Pro / TEAM,月付 / 年付)后,会在浏览器中打开 Stripe 的结算页面。支付完成后,应用会自动激活许可证。
• 更换到另一台 Mac 时,请先在旧设备上“解除许可证”,再在新设备上激活。

套餐详情请参阅价格页面。

常见问题

无法连接 / 显示“认证失败”

请确认该 JSON 是否为目标项目的服务账号密钥。如果重新生成过密钥,建议断开旧连接后使用新的 JSON 重新连接,更加保险。

数据会被发送到其他地方吗?

不会。Firescope 会直接从你的 Mac 访问 Firestore 。密钥和数据都不会发送到外部服务器。

“生产环境防护”具体是做什么的?

这是一种根据连接的环境标签和操作风险,自动调整确认强度的机制。例如在生产环境删除集合时,必须手动输入项目 ID 才能执行。由于验证是在应用核心(主进程)而非界面提示层面完成的,因此不会因为疏忽而被绕过。

有 Windows 版吗?

有。请从下载页面获取Firescope-Setup.exe(如果出现 SmartScreen 警告,请点击“更多信息”→“仍要运行”继续)。

可以添加其他语言吗?

可以。在设置 → 语言中导出语言包(JSON)进行翻译,再导入即可添加任意语言。