常见问题与排查

常见问题的简短解答。更深入的背景：安全、服务器安装、使用应用、Nearby、浏览器扩展、CLI。

主密码与恢复

我忘记了主密码。能恢复保险库吗？

不能。 OpenKey 是零知识的：服务器从未见过主密码或明文保险库密钥。没有密码（以及仍有已解锁会话或您可解锁的加密本地备份的任何设备），密文无法恢复。

请保持强且唯一的主密码，并至少保留一份 Pro 加密本地备份（.okbak）或离线导出。

服务器管理员能重置我的密码吗？

不能。管理员可以删除或扣留密文，并观察元数据（邮箱、大小、时间）。他们无法解密您的保险库，也无法为您设置新的主密码。

如何更改主密码？

在应用中，使用会轮换凭据的账户 / 安全流程（服务器上的 /auth/rekey）。保险库密钥本身保持不变；仅更新认证哈希与服务器上已封装的保险库密钥。之后在其他设备上用新主密码同步。

同步与服务器

同步失败或登录返回错误

1. 确认 http(s)://your-host/health 返回健康状态。
2. 每个客户端使用完全相同的服务器 URL（尾部斜杠可以；生产环境优先 HTTPS）。
3. 检查 JWT_SECRET 已设置（≥ 32 字符，非占位符）— 否则 API 将拒绝启动。
4. 若使用扩展 / Web，检查 CORS_ORIGINS 包含您的扩展 / Web 来源（绝不要用 *）。
5. 认证端点按 IP 限流（AUTH_RATE_LIMIT_*）。多次登录失败后请等待一分钟再试。
6. 在首台设备上注册一次；在其他设备上用相同邮箱 + 主密码登录，然后立即同步。

手机无法访问 http://localhost:8000

手机上的 localhost 是手机本身。请在同一 Wi‑Fi 上使用电脑的局域网 IP（http://192.168.x.x:8000），或通过反向代理 / 隧道暴露 HTTPS。移动端可能阻止明文 HTTP — 除本地调试外请优先使用 HTTPS。

两台设备同步后显示不同的保险库内容

同步是按 revision 的 last-write-wins，不是 CRDT。并发编辑可能互相覆盖。一次只在一台设备上编辑后再次拉取/推送。Nearby 局域网同步使用相同的 LWW 规则。

如何删除我的服务器账户？

客户端在重新证明当前 auth_hash 后调用已认证的 POST /auth/delete。这会永久移除服务器端密文。设备上的本地保险库不受影响 — 如需删除或擦除，请另行处理。

应用与 Pro

免费与 Pro 有何区别？

见使用应用中的对照表。简言之：免费包含核心保险库 + 带条目限额的服务器同步；Pro 解锁无限条目、导出、加密备份、Nearby、组织/共享、附件与自定义图标。

Nearby 找不到另一台设备（Pro）

1. 两台设备均已解锁，设置 → 附近设备 已启动，同一 Wi‑Fi（非访客/客户端隔离网络）。
2. 优先使用 扫描配对二维码，而非输入代码；允许相机 / 本地网络权限提示。
3. 临时禁用 VPN / 专用中继。在 macOS 上，若二维码连接失败，允许防火墙回拨。
4. 配对，然后 链接保险库（相同保险库密钥指纹）。完整指南：Nearby。
5. 可选 仅受信任网络：添加您的 SSID，否则在未知网络上 Nearby 会暂停。
6. 商店 IAP 平台（Android / iOS / macOS）会忽略对等方的 LAN Pro — 如需要，请在该商店购买/恢复 Pro。

如何将一个密码发送到局域网上的另一台设备？

配对后（Pro），在条目上使用 发送到设备，或从 Nearby 对等方操作发送。这会在局域网会话中推送单个条目，无需等待完整保险库同步。详情：Nearby → 发送条目。

自动填充 / 通行密钥未出现

在 设置 → 自动填充 下将 OpenKey 启用为系统密码与通行密钥提供方，然后解锁保险库。在 iOS/macOS 上授予系统权限提示。更改提供方后重启浏览器或目标应用。

扩展填充快捷键是什么？

Windows/Linux 上为 Ctrl+Shift+L，macOS 上为 ⌘⇧L。可在浏览器的扩展键盘快捷键中重新映射。参见浏览器扩展。

导入成功但导出被锁定

导入免费；导出需要 Pro（加密 .okbak 备份同理）。步骤：导入与导出。

附件如何工作？

Pro。 打开登录 → 添加加密附件（约最大 20 MB）。附件作为密文通过您的服务器同步。OpenKey JSON 导出仅包含元数据 — 包含附件 blob 的完整保险库请使用 .okbak。

如何添加 TOTP / 验证器代码？

在条目上添加验证器密钥或 otpauth URI，或从网站的 2FA 设置中扫描二维码。保险库解锁时显示代码；系统自动填充 / 扩展可在支持处填充。

集合可以嵌套吗？

可以 — 文件夹可以包含其他文件夹（parent 关系）。嵌套登录包含在自动填充与桌面桥接中。

已删除的条目会立即在其他设备上消失吗？

软删除的条目作为**墓碑（tombstones）**同步，直到对等方赶上。Last-write-wins 使用每条目的 revision — 并发编辑仍可能覆盖。

Web 构建需要 Pro 吗？

暂不。 Web 构建目前不强制 Pro 限额。移动与桌面商店/桌面构建会强制。

组织与共享如何工作？

Pro + 同一自托管服务器。发布身份密钥，然后邀请加入组织或共享条目快照。详情：共享与组织。

生物识别 / 自动锁定如何工作？

在 设置 → 安全 下可启用生物识别解锁（取决于平台）及相关锁定保护。在共享机器上建议空闲时锁定。生物识别在设备上封装保险库密钥 — 它们不能替代强主密码。

浏览器扩展

扩展无法与桌面应用通信

1. 解锁桌面保险库并保持解锁。
2. 打开 设置 → 自动填充（macOS 上还有 浏览器扩展），以便注册原生主机。
3. Chromium：将未打包扩展 ID 写入平台文件（见浏览器扩展），然后重新打开自动填充。
4. 在扩展中选择 使用桌面应用。
5. macOS 需要 PATH 上的 Python 3 以运行主机脚本。

针对我的服务器的独立解锁失败

确认 prelogin 可用：邮箱必须已注册。与应用相同的主密码。浏览器必须能访问服务器 URL（CORS / HTTPS）。在选项页检查 URL，并在普通标签页中尝试 /health。

通行密钥回退到浏览器验证器

当您在确认对话框中选择 使用浏览器，或扩展保险库已锁定时，这是预期行为。解锁扩展（独立模式）以存储/使用 OpenKey 通行密钥。

CLI

openkey secret … 提示解锁应用

保险库命令需要已解锁的桌面应用（原生桥接）或在 login 之后执行 eval $(openkey unlock)。运行 openkey status 查看桥接 / 会话状态。

会话已过期

默认锁定为 15 分钟（openkey config set-lock）。再次运行 eval $(openkey unlock)。在个人机器上优先使用交互式密码提示，而非 OPENKEY_PASSWORD。

安全 / 隐私

密码健康会把我的密码发送到互联网吗？

本地弱密码/重复检查留在设备上。可选的 Have I Been Pwned 仅使用 SHA-1 前缀 k-匿名 — 从不发送完整密码。参见安全。

Nearby 是备份吗？

不是。它在已配对、已链接保险库的设备之间于局域网上同步密文。请同时保留离线 Pro 备份。

仍然卡住？

1. 记录失败的客户端（应用 / 扩展 / CLI）与大致时间。
2. 检查服务器日志（docker compose logs -f api）与 /health。
3. 私下报告安全问题 — [email protected] 或 OpenSelfHosting 下的私有公告。参见安全。
4. 对于产品缺陷，在 OpenSelfHosting 下开 issue，并注明软件包名称与版本。

下一步：Nearby · 服务器安装 · 安全 · 下载