用ffpass迁移Firefox Quantum密码：logins.json与key4.db详解

简介：ffpass是一款面向Firefox Quantum及更高版本用户的密码管理辅助工具，它解决了新版Firefox无法直接以文件形式导入或导出登录密码的痛点。该工具通过读写Firefox的加密密码数据库，支持设置主密码、自动识别Linux/macOS/Windows平台的配置文件，并可导出为CSV或从Google Chrome兼容的CSV文件导入。压缩包共17个文件，包含4个Python脚本、4个JSON配置、4个覆盖Firefox 58至84及主密码场景的db测试数据库，以及Makefile、YAML工作流和README说明，整体仅21KB，结构精简清晰。目前已有306人学习下载，适合需要批量迁移、备份或同步Firefox登录信息的普通用户和开发者。借助附带的测试用例与说明文档，读者不但能快速上手工具，还能理解Firefox密码库的加密与导入导出机制，便于二次扩展或集成到自己的自动化运维脚本中。 Firefox Quantum（也就是Firefox 57之后的版本）把所有登录密码都加密存在配置目录的logins.json里，配套的密钥则放在key4.db中。很多人在换电脑或重装系统时，直接整个复制配置目录过去，结果保存的密码还在，却无法在新机器上解密——因为logins.json里的密文必须拿到key4.db中的key才能解开。ffpass正是这样一个命令行小工具，它能自动读取Firefox的配置目录，完成密码的解密导出和反向导入。这篇主要讲我在实际项目里怎么用ffpass迁移Firefox Quantum密码，包含配置目录的定位、logins.json和key4.db的关系、导出导入的完整步骤，以及最容易让人卡壳的“key值未知”问题。

如果你正准备换电脑、清理浏览器保存的密码，或者单纯想把Firefox里的登录信息归档成一份可读文件，这篇内容可以直接照着操作。

1. Firefox Quantum的密码存储机制与ffpass的定位

1.1 从key3.db到key4.db：一次存储引擎更替

在Firefox 57之前，密码库用的是key3.db和signons.sqlite这套旧结构，解密逻辑相对简单，网上很多老教程也都是围绕那套机制写的。Firefox Quantum重构后，密码数据统一放进了logins.json，密钥库也换成了SQLite格式的key4.db。这个改动带来一个很直接的后果：以前那些解出明文密码的方法基本全部失效，如果还拿着老工具去读新配置，大概率只能得到一堆乱码。

所以要理解ffpass这类工具，首先得接受一个事实：Firefox密码模块的核心从“一个文件”变成了“两个文件协同工作”。logins.json负责存密文，key4.db负责存钥匙。导出时，ffpass既要用logins.json里的密文，也要用key4.db里的key去解密；导入时，它同样要调用这套key重新加密后写回。只备份logins.json不带key4.db，拿到新机器上基本等于白备份。

1.2 ffpass正好解决什么问题

ffpass的本质是一个本地命令行工具，它替你完成了三件事：打开logins.json、解析key4.db、用内置的NSS解密逻辑还原出明文密码。有主密码时就弹出来让你输入，没有主密码时它会在当前配置目录里自动找key。整个过程不经过任何远程服务，也不需要把数据传出去。

适合ffpass的场景很典型：一是换新电脑，把Firefox保存的登录信息迁过去；二是整理个人密码库，定期把浏览器里的密码导出到CSV留档；三是从旧版本或者损坏的配置目录里抢救数据。当然，前提是你对这台机器上的数据有完全的控制权和处置权，不要拿它去处理别人的配置。

1.3 常见误区：直接复制logins.json不叫迁移

很多人在迁移时只copy logins.json，到了新机器打开Firefox，发现密码管理列表是空的，然后觉得数据丢了。其实数据还在，只是解密它需要的key在另一个文件里。Firefox在每个配置目录下都维护了独立的密钥，新配置目录会生成新的key，对应不了老密文。这也是前面提到的，必须把logins.json和key4.db放在一起才有效。

另外还有一个容易忽略的文件是cert9.db，虽然它主要管证书，但在某些Firefox版本的会话解密里也会被用到。所以我的习惯是整个profile目录一起复制，不要挑三拣四。从这个角度说，ffpass的设计思路也是对一个完整配置目录操作，而不是单独喂给它一个logins.json文件。

2. 环境准备与安装部署

2.1 准备Python环境

ffpass是纯命令行工具，常见实现是Python脚本。我的测试环境是Ubuntu 22.04加Python 3.10，Windows 10上跑过也没问题。建议直接装Python 3.8以上版本，顺手把pip一起装好。如果你用的是macOS，系统自带的python3通常也能用，但建议用Homebrew装一个干净环境的Python，避免和系统库冲突。

安装前可以先确认版本：

python3 --version pip3 --version

如果pip3不存在，Ubuntu或Debian上可以执行sudo apt install python3-pip，Windows上安装Python时记得勾选“Add Python to PATH”，省得后面手动改环境变量。

2.2 安装ffpass与依赖

安装ffpass最简单的是用pip：

pip install ffpass

如果这个名字在你的源里已经失效，或者你想看实现源码，直接去搜索ffpass的仓库，把代码clone到本地再手动装依赖。依赖通常包括python-dateutil、pycryptodome这些，requirements.txt一般长这样：

python-dateutil>=2.8.2 pycryptodome>=3.15.0

手动方式：

git clone https://github.com/你的仓库地址/ffpass.git cd ffpass pip install -r requirements.txt

装完之后执行ffpass --help，能看到export和import两个子命令，就说明环境没问题。我在Windows上遇到过一个问题，就是本机装了多个Python版本，pip装到了老版本那里，导致命令行里找不到ffpass。解决办法是直接用python -m pip install ffpass，或者检查Scripts目录有没有被写进PATH。

2.3 找到Firefox配置目录

密码相关文件在profile目录下，不同系统路径不同：

最稳的办法是打开Firefox，地址栏输入about:support，找到“配置文件夹”那一行，点“打开所在文件夹”。你会看到logins.json、key4.db、cert9.db这几个文件，后面的所有操作都以这个目录为目标。注意路径里的“xxxx.default-release”是随机字符串加后缀，每次安装生成的都不一样，不要照抄网上的路径。

3. 核心原理解读：logins.json、key4.db与key

3.1 logins.json里面到底有什么

logins.json是JSON文件，完全明文，但里面没有可读的密码。每条登录记录大概是这样：

{ "logins": [ { "hostname": "https://example.com", "httpRealm": null, "formSubmitURL": "https://example.com/login", "usernameField": "email", "passwordField": "password", "encUsername": "MDoECD...AB=", "encPassword": "MDoECD...AB=", "encType": 1 } ] }

encUsername和encPassword是Base64编码后的密文，看着像一串随机字符，其实里面包含了初始化向量和密文信息。encType告诉工具这条记录用了哪种加密算法，ffpass读到它之后会走对应的解密分支。如果这个字段结构不对，或者密文长度异常，导出时就会跳过这条记录，或者直接报错。

3.2 key4.db与“key值未知”之谜

key4.db是一个SQLite数据库，里面存的不是单个字符串，而是一组密钥相关的二进制对象。Firefox的加密机制用到了globalSalt和派生密钥，这些数据都存在key4.db里。ffpass在解密时，需要根据logins.json里的密文类型，去key4.db中挑出对应的key记录，再算出真正的解密密钥。

当这两个文件不配套，或者某个key条目缺失，ffpass就会报“key值未知”或者类似unknown key的提示。我排查过几次，最常见的三种情况是：只复制了logins.json忘了key4.db；Firefox升级时重新生成了key4.db，老密文在新密钥下自然解不开；以及有主密码时输错了密码导致派生结果对不上。看到这个报错先不要急，把整个配置目录完整还原，或者检查主密码，大半都能解决。

3.3 解密一条密码的完整链路

用个生活化类比：logins.json里的每条记录都是一封密信，key4.db里放着保险箱钥匙的密码提示。没有主密码时，钥匙本体也在key4.db里，只是结合了一些本地信息做了混淆；设了主密码时，钥匙外面又多了一道锁，ffpass必须先让你输入主密码，把外面那层锁打开，才能用里面的钥匙去拆密信。

整个过程在本地完成，不联网。这也是ffpass这类工具的优势：它能直接操作密码数据库的原始数据，而不是在浏览器界面上一条一条复制粘贴。好处是批量操作很稳，坏处是一旦你对key值来源不熟，遇到“key值未知”容易一头雾水。所以我的建议是：动手导出之前，先把logins.json和key4.db这两个文件丢在同一个目录里，养成这个习惯能少踩很多坑。

4. 实操：密码导出与导入全过程

4.1 导出为CSV：先把密码从Firefox里“解放”出来

操作顺序很重要。第一步永远是关闭Firefox，彻底退出，最好在任务管理器里确认没有firefox进程在后台。否则logins.json正在被Firefox占用，ffpass读出来的可能是半写入状态的数据，导出后容易缺项。

第二步是复制整个配置目录。我习惯在命令行里这样操作：

cp -r ~/.mozilla/firefox/xxxx.default-release ~/ffpass-work

复制出来一份再操作，原配置保持不动，万一出问题还能退回。

第三步运行导出：

ffpass export -d ~/ffpass-work -o firefox-passwords.csv

如果设过主密码，这里会提示Master password:，输入后回车。没有主密码就直接生成CSV。正常执行时输出大概是：

[INFO] Loading key4.db ... [INFO] 3 logins found [INFO] Exporting to firefox-passwords.csv ... [INFO] Done.

导出完成后，用文本编辑器打开看一眼，正常格式是三列：

hostname,username,password https://example.com,admin@example.com,MyP@ssw0rd

4.2 导入CSV到Firefox：把整理好的密码写回去

导入是把导出流程反过来。先准备一个严格三列的CSV，表头必须是hostname,username,password，每行一条记录。关键字段全部用完整URL，比如https://example.com，不要省略成example.com，否则Firefox可能不识别成同一条登录信息。

然后还是先关闭Firefox，再执行：

ffpass import -d ~/ffpass-work -i firefox-passwords.csv

ffpass会读取CSV，逐条调用当前配置里的key重新加密，然后写回logins.json。导入前我会先备份原logins.json：

cp logins.json logins.json.bak

导入后重新启动Firefox，打开“已保存的登录信息”，确认条目数量和站点都对得上。如果想更严谨一点，导入完成后再用ffpass导出一份新的CSV，和源文件对比一下内容是否一致，这样能发现有没有记录被工具漏掉。

4.3 CSV的编码与字段细节

CSV看着简单，处理不好同样翻车。第一是编码，Windows下用Excel打开中文CSV容易乱码，导出时如果ffpass支持编码参数，直接指定：

ffpass export -d ~/ffpass-work -o firefox-passwords.csv --encoding utf-8-sig

这样Excel能正常识别。第二是特殊字符，密码里如果有逗号、双引号、换行，CSV必须加引号包裹，否则导入时会错位。第三是hostname格式，部分旧记录会带httpRealm这种认证域字段，导入工具如果只按hostname匹配，可能把同一站点不同域的账号合并，需要人工检查。

如果导入时遇到“key值未知”，先想想这个CSV是不是用别的浏览器或者工具生成的，有些工具导出的CSV会在表头多一列自带列名，或者把密码放在第四列，这都会导致解析错位。

5. 常见问题与排错实录

5.1 高频报错速查表

这个表格是我实际排查时最常用的一张清单。很多问题都不是工具坏了，而是操作环境不干净。比如“Database is locked”这个错，我一开始以为是ffpass有bug，后来才发现Firefox开了一个窗口在后台，logins.json被锁住，写不进去。关掉之后马上正常。

5.2 主密码忘记之后的取舍

主密码是Firefox的一道硬门槛。如果忘了主密码，ffpass没有能力绕过它，因为key4.db里的密钥被额外加密了一层，而这一层的口令只有你自己知道。能做的只有二选一：要么接受密码库打不开，要么删除key4.db重置整个密码库，但这样做会清空所有已保存的密码，相当于从零开始。

所以我的建议一直是：设置主密码的人，一定要把主密码写进另一个密码管理器里当保底；如果你常年没有主密码，那反而不用纠结，ffpass无主密码模式基本都能直接跑通。我还见过一种情况，用户在主密码提示框里输入的是Windows登录密码，以为同一个密码，结果当然解不开。这里要提醒一句，Firefox主密码和系统密码是两码事，除非你自己当初设置成一样，否则不要混用。

5.3 备份还原时的版本和路径陷阱

Firefox的配置目录文件会被浏览器持续更新。比如你从一台Firefox 115的机器上复制了profile，放到Firefox 128上，浏览器启动后可能会自动迁移密钥，生成新的key4.db。如果迁移不完整，老logins.json里的密文就解不开，ffpass跟着报“key值未知”。

另外，路径中的profile名不要随意改，Firefox通过profiles.ini来定位目录。手动把目录移到别的位置后，最好用about:support里的“打开所在文件夹”确认实际路径，而不是靠记忆拼路径。命令行参数里的目录路径最好用绝对路径，避免某些脚本在相对路径下找不到文件。

6. 安全建议与我的使用习惯

6.1 导出明文后的善后工作

ffpass导出的CSV是明文密码，这是最大便利，也是最大风险。处理完之后我一般会做三件事：第一，把CSV从工作目录移到加密分区或移动硬盘；第二，用7-Zip等工具压缩并设置强密码，文件名上也别带password这种字眼；第三，操作完成后清理临时目录，避免留下副本。如果只是在公司电脑上临时迁移，导完就要考虑彻底删除文件。

记住一条原则：CSV的明文价值等同于你的全部账号，保管级别要向密码管理器看齐。不要把导出的CSV随手放在桌面或者下载目录里，更不要直接当附件发到聊天工具上。

6.2 我一直在用的Firefox密码备份方案

我现在每季度做一次完整备份，流程很简单：先导出CSV，再用7-Zip加密压缩；然后把整个profile目录压缩一份，注意包含logins.json和key4.db；最后把两份压缩包放到移动硬盘和网盘各存一份。这个方案的优点是，CSV方便可读，profile备份方便还原，遇到任何一边损坏都有回退余地。

Firefox Sync我也开着，但它同步的是端到端加密数据，没法导出明文，只适合日常多设备同步。真要留下一份能随时查看的密码清单，还得靠ffpass这种本地工具。经历过一次配置目录损坏之后，我就养成了这个习惯，现在每次换电脑或者重装系统，都只需要解压备份，十分钟内就能把密码完整迁过去。如果你也被Firefox密码迁移折腾过，建议先拿一个不重要的profile试一遍ffpass，跑通了再放手处理主力数据。

本文还有配套的精品资源，点击获取