使用文档 ​

PassDock 是面向个人的自托管密码管理器。第一次使用时,先部署服务端,再通过浏览器初始化密码库。已经有实例的用户可直接前往连接设备。

部署服务端 ​

准备 PassDock 源码、Go 1.26+、Node.js 22.12+、独立的 MySQL 数据库及其账号。开发集成测试使用 MySQL 8.4。非本地部署需要设备可访问、证书受信任的 HTTPS 地址。

从仓库根目录执行以下命令,生成 Web 静态资源与 Go 服务端。

sh
npm --prefix web ci
npm --prefix web run build
go build -o bin/passdock ./cmd/passdock

在服务的运行环境中设置 PASSDOCK_MYSQL_DSN,让它指向 PassDock 使用的数据库。数据库账号需要创建和升级本库表结构的权限。把 PASSDOCK_ORIGIN 设置为用户实际访问的来源,例如 https://vault.example.com。Go 默认监听 127.0.0.1:8090,可由同机反向代理终止 TLS 并保留请求的 Host,也可设置 PASSDOCK_TLS_CERT 和 PASSDOCK_TLS_KEY 由 Go 提供 HTTPS。

从仓库根目录启动时,程序从 web/dist 读取 Web 构建产物。若部署目录不同,请设置 PASSDOCK_WEB_DIST。

sh
./bin/passdock bootstrap
./bin/passdock serve

bootstrap 签发 15 分钟内有效的一次性初始化凭据。保持服务运行,访问配置好的实例地址,继续首次设置。

首次设置 ​

  1. 在浏览器打开自己的实例地址,输入初始化凭据并注册 Passkey。
  2. 设置一个足够长且独立的主密码,用于在设备本地解锁密码库。
  3. 按界面提示离线保存恢复密钥并验证。妥善保存恢复密钥,后续重设主密码及恢复加密备份会用到它。
  4. 新建一条演示数据,试一次搜索、打开详情、复制和锁定。可在「Passkey 管理」中添加一个备用 Passkey。

连接设备 ​

使用网页版 ​

直接在电脑或手机浏览器打开自己的实例地址,通过 Passkey 登录并输入主密码。登录与解锁均在你的自托管实例地址进行。

使用原生客户端 ​

更新 Go 服务与 Web 构建产物,在客户端填写已初始化实例的 HTTPS 地址。点击「使用 Passkey 登录」,在浏览器完成验证并返回 PassDock,再输入主密码。等待首次同步完成后,可以搜索和查看条目。

构建原生客户端 ​

四端共用仓库中的 mobile/ Flutter 工程。准备 Flutter 3.47 和 Dart 3.13。在仓库的 mobile/ 目录运行 flutter pub get,再按平台选择对应命令。

macOS ​

配置 Xcode 后运行 flutter build macos。开发调试可以使用 flutter run -d macos。

Windows ​

安装 Visual Studio 并启用「使用 C++ 的桌面开发」,运行 flutter build windows。

iPhone ​

在 Xcode 的 Runner target 选择签名团队,连接测试 iPhone。运行 flutter devices 查看设备 ID,再用 flutter run -d DEVICE_ID 安装到设备。仅测试模拟器时,可运行 flutter build ios --simulator --debug。

Android ​

安装 Android SDK,运行 flutter build apk --debug 生成开发测试包,或连接测试设备后用 flutter run -d DEVICE_ID 运行。完成安装后按连接设备连接自己的实例。

日常使用 ​

在条目列表用标题、账号或站点搜索。打开条目详情后可以复制密码。条目可按分类整理,编辑保存后能在其他已连接设备同步。网页版可查看历史版本及管理回收站。在桌面客户端,可用 ⌘F 或 Ctrl+F 聚焦搜索。

离线使用 ​

联网登录并解锁,等待首次同步完成。希望断网后查看或复制的条目,先在线打开一次详情。断网重新打开 PassDock 时,可用主密码解锁和搜索缓存。联网后可以在「待提交」中检查和重试未确认的编辑。主动退出网页版会清除本机缓存及待提交密文。

备份与恢复 ​

联网解锁网页版,进入「设置」→「设备与恢复」,下载 .passdock 备份。备份文件和对应恢复密钥应分开保管。

在已经初始化并解锁的目标实例中,选择备份文件,输入对应的恢复密钥,核对条目数量后选择「恢复为副本」。可以恢复到新的实例,原服务器无需在线。

旧库迁移 ​

在可信机器上构建迁移工具 go build -o bin/passdock-migrate ./cmd/passdock-migrate。将 PASSDOCK_LEGACY_MYSQL_DSN 指向已还原的旧版 MySQL 备份,并使用只读账户。将 PASSDOCK_MYSQL_DSN 指向完成首次设置的 V2 目标库。

在隔离库先演练。用 -user-id 指定旧账号,以 -source-id 为本次源快照指定固定的小写 UUID v4,并通过标准输入传入 V2 目标库的恢复密钥。默认只预检。核对数量并处理异常后用 -apply 导入。中断后使用同一源快照、标识、目标库和历史密钥映射重跑。

常见问题 ​

为什么客户端需要服务器地址?

PassDock 把服务端部署在用户自己的环境中。客户端需要你的实例地址,才能登录并同步密码库的密文。

有 Passkey 还需要主密码吗?

需要。Passkey 用于登录服务器,主密码用于在设备本地解锁密码库。两者的用途见安全设计。

为什么离线可以搜索,却打不开某条详情?

列表摘要和详情分别缓存。联网打开一次该条目的详情,后续才能离线查看和复制。

原生客户端授权完成后无法连接怎么办?

确认实例的 HTTPS 证书受该设备信任,域名与 PASSDOCK_ORIGIN 一致,并同时更新 Go 服务和 Web 构建产物。桌面授权完成后,请切回客户端继续解锁。