Skip to content

快速上手 ​

欢迎使用 passno。passno 是一款本地优先、开源的双许可(MIT / Apache-2.0)密码管理器,在同一应用包中同时提供 macOS 桌面应用和 pn 命令行工具,并默认使用简洁明确的加密保险库格式存储你的数据。

1. 安装与首次启动 ​

  1. 从 /Applications 打开 passno(或执行 open /Applications/passno.app)。
  2. 先查找已有保险库:首次启动会先查找恢复包和 iCloud;已有保险库请点击“恢复”(详见下文“在新 Mac 上恢复”)。没找到时直接进入创建页面,页首的“已有保险库?从 iCloud 或其他位置恢复…”可以回到恢复页面;那里总会写明 iCloud 的情况:iCloud 里还没有保险库(可点“重新查找”),或这台 Mac 访问不到 iCloud(没登录 iCloud,或不是正式签名的 passno,开发版没有 iCloud 权限)。没有已有保险库时,创建主密码:输入不少于 8 位的高强度主密码并确认。主密码仅用于本地密钥派生,永远不会上传到任何服务器。
  3. 保存 Secret Key 与应急套件:系统会生成形如 A3-... 的 Secret Key,同时允许你一键下载应急套件(.md)。请务必妥善备份——恢复需要主密码与 Secret Key;若恢复包中已保存 Secret Key,新设备只需输入主密码。

2. 安装命令行工具(pn) ​

无需重装独立安装包,pn 已经随应用内置在 /Applications/passno.app/Contents/MacOS/pn:

  • 图形界面一键安装(推荐):在"设置 → 命令行工具 (pn)"中点击 安装命令行工具 (~/.local/bin/pn),无需管理员密码;如需系统全局安装,可再点击 同时链接到 /usr/local/bin/pn 并输入管理员密码。
  • 手动创建软链:
    bash
    mkdir -p ~/.local/bin
    ln -sf /Applications/passno.app/Contents/MacOS/pn ~/.local/bin/pn
  • 若终端提示 command not found: pn,请把下面一行添加到 ~/.zshrc 并重新打开终端:
    bash
    export PATH="$HOME/.local/bin:$PATH"

验证安装与保险库健康状态:

bash
pn doctor

当 cli_in_path 显示 OK 且指向 /Applications/passno.app/Contents/MacOS/pn 时,说明桌面端与终端使用的是同一套打包版本。

3. 日常使用 ​

桌面端与命令行默认共用同一目录(~/Library/Application Support/passno,可通过 PASSNO_HOME 环境变量切换测试目录),并且由本地文件锁保护,两者可安全配合使用。例如在终端用 pn add 新增条目后,已解锁的桌面窗口会在约 1~2 秒内自动显示新条目。

常用 CLI 命令速查:

bash
# 查看保险库初始化状态(不要求解锁)
pn status --json

# 使用基于 EFF 词表的 Diceware 生成易记词组或站点合规密码
pn gen --kind passphrase --length 5
pn gen --for-domain google.com

# 交互式添加条目(非交互环境下加 --password-stdin)
pn add --title "GitHub" --url "https://github.com" --username "alice@example.com" --generate

# 列出与搜索条目(--json 默认打码隐藏密码,适合脚本与 agent 安全查看元数据)
pn list --json
pn search github --json

# 获取 TOTP 验证码
pn totp <item-id>

TIP

在自动化脚本或 AI agent 环境中运行时,建议加上 --json。pn show --reveal 会拒绝非人类交互终端访问明文(退出码 8),默认只暴露条目标题、网址和标签等元数据。

4. 设置同步与备份(v0.2) ​

在 设置 → 存放位置 添加主位置:iCloud Drive、文件夹、Git、S3 / Cloudflare R2 或 WebDAV。 S3 / WebDAV 的访问凭据只保存在恢复存储中,保存后不会显示。Git 使用本机已有的 SSH 或凭据助手;地址中不要附带密码或 token。添加后自动同步,也可点击“立即同步”。 主位置用于设备互通,“添加备份”保存另一份加密副本。页面分别显示成功时间或错误; 显示“尚未同步”时不要认为已经备份。移除备份不删除远端文件。

后台在解锁、写入后、定期检查及 Mac 唤醒时同步。命令行复用同一个后台会话:

sh
pn sync status --json
pn sync now --json

以上命令不再要求重新输入主密码;锁定时可同步经过验证的密文。应急维护才使用 --no-daemon;该模式的 sync now 仍可用 --locked-only 或交互主密码。

5. 在新 Mac 上恢复(v0.2) ​

  1. 在原 Mac 设置存放位置并完成一次同步。若选 iCloud Drive,请在新 Mac 使用同一 Apple ID, 启用 iCloud Drive 与 iCloud 钥匙串,等待系统同步。
  2. 打开新 Mac 的 passno。首次启动会显示发现的保险库及来源,点击 恢复。
  3. 若提示“恢复材料已就绪”,只输入主密码。Secret Key 从恢复存储内部读取,不需要抄写。
  4. 若未自动发现,选择 从其他位置恢复…,输入原来的文件夹、Git、S3/R2 或 WebDAV 地址。 没有恢复包时需要 Secret Key;也可选择 导入应急套件,粘贴包含 passno://recovery URI 的 v0.2 套件。旧版套件仍可取出 Secret Key,配合位置手动恢复。
  5. 恢复成功后条目会显示,后台自动发布新设备。打开 设置 → 存放位置 核对最近同步时间, 再查看“设备”。恢复不会覆盖这台 Mac 已有的保险库。

若主密码不正确可以重新输入;网络、权限或文件校验失败时请按提示检查,勿反复创建新库 或覆盖远端。iCloud 恢复存储不可用时会明确提示,不会假装已经安全保存恢复材料。

“移除设备”会阻止其设备身份继续写入并轮换纪元;不能收回已读取的数据或已持有的 账户恢复材料。丢失设备后的完整账户密钥/Secret Key 轮换另行处理。

家人和小团队共享 ​

在 设置 → 共享 创建独立共享库,再在个人条目的 ⋯ → 共享 中选择目标库并复制。 邀请前,让对方在“我的共享身份”中提供公钥,双方通过独立渠道核对指纹。选择“只读”或 “可编辑”,生成邀请码,设置双方可访问的文件夹、Git、S3/R2 或 WebDAV 位置,然后同步。 对方在自己的个人账户中接受邀请,不需要也不应提供个人主密码或 Secret Key 给邀请人。

共享库里的条目直接出现在条目列表和浏览器插件的下拉框里,和个人条目一样查看、复制、自动填充;可编辑成员还能直接修改,改动同步给其他成员。 只读成员只能看和填充,不能修改。当前跨库附件会明确拒绝,避免产生不可读取的附件引用。

移除成员会换密钥并列出需要更改的账号;对方已保存的旧密码无法撤回。操作后同步共享库, 再到相应网站更改密码。主动退出要同步退出请求,等待 owner 同步并完成换钥。 命令行用法见 pn help share --json 和 共享开发文档。

修改主密码 ​

Mac:设置 → 安全与解锁 → 修改主密码;iPhone:设置 → 修改主密码;命令行:pn passwd。Secret Key、应急套件和条目都不变。改完后旧主密码在这台设备上立即失效,其他设备同步后也不再接受它,用新密码解锁一次就好(Touch ID / Face ID 会自动跟上)。配对过的 iPhone 要在 Mac 设置里重新配对,才能再用它解锁 Mac。改主密码不换账户密钥:如果担心主密码和 Secret Key 都泄露了,用下面的“设备真的丢失时”。

忘记主密码 ​

passno 没有服务器,任何人都找不回你的主密码。可以这样试:

  1. 这台 Mac 的 Touch ID(或 iPhone 上的 Face ID)还能解锁的话,先解锁,再到修改主密码里选“忘了当前密码?用 Touch ID / Face ID 确认”,设一个新密码。
  2. 在另一台还能打开 passno 的设备上改,这台设备同步后用新密码解锁。
  3. 应急套件里只有 Secret Key,没有主密码。

都不行的话,只能在解锁页点“忘记主密码?”→ 重新开始(或在终端运行 pn reset --move-aside)。旧保险库会移到 passno 数据目录下的 moved-aside/ 文件夹,不会删除;其他设备和 iCloud 里的副本不受影响;以后想起主密码,把它移回去还能打开。

设备真的丢失时 ​

“移除设备”只撤销旧设备身份;如果旧设备可能掌握账户恢复材料,请用 设置 → 存放位置 → 设备丢失,或 pn device revoke-lost。提供新的主密码后,系统生成全新的账户密钥、Secret Key 和应急套件,其他设备必须重新加入,服务令牌需重新签发。新应急套件保存为保险库目录下的 emergency-kit-<新库ID>.md(0600),请在本人设备上离线保管;不要把内容交给 agent。

若加入了别人管理的共享库,先请其 owner 移除旧身份,本地退出后再吊销;之后用新身份重新邀请。 处理完成会锁定,使用新密码解锁后同步个人库及各个共享库。网络存储的授权凭据若也在丢失设备上, 还应在对应服务商处更换。开发验证只使用临时 home 和模拟恢复存储,真实钥匙串验收留待本人在场。

在新 iPhone 或 Mac 上恢复 ​

在原来的设备上打开 设置 → 密钥与同步(Mac 是 设置 → 存放位置),开启 iCloud 同步。之后在登录同一个 Apple ID 的新 iPhone 或 Mac 上打开 passno,它会自动找到你的保险库,显示“恢复保险库”,只输主密码就能恢复。两边的改动会自动同步。

让 AI agent 使用某个密码 ​

  1. 在 passno App(Mac 或 iPhone 都可以)里打开这个条目,在详情底部打开“允许 agent 使用”。agent 只能拿它代填或代签,拿不到明文;第一次使用时会先弹窗问你:仅这一次、直到电脑锁定(默认),或总是允许(以后这个 agent 用这个条目、访问同一个网站都不再问,锁屏时也能用,30 天不用会自动取消,选它时要 Touch ID)。想要 15 分钟、1 小时、24 小时、7 天,在“设置 → Agent → 授权时长 → 更多时长”里打开。手动锁定 passno 会暂停所有 agent,解锁后自动恢复;撤销才是取消。
  2. 特别重要的条目,再打开“每次使用都要我确认”:agent 每次用都要你批准,并用 Touch ID 确认。嫌每次都按太烦,可以在下面的“免确认时长”和“免确认次数”里放宽一点(比如 5 分钟内或 3 次内不再问),确认一次后 agent 做同一件事在限额内不再问,锁定后重新问;取出明文始终每次都问。
  3. 在终端运行一次 pn agent setup claude(或 codex),把 passno 接入你的 agent。

共享保险库里的条目不能交给 agent。随时可以在“设置 → Agent”里撤销授权。

文档对应提交 56d1c45 · 由仓库 docs/ 自动生成