使用文档
PassDock 是面向个人的自托管密码管理器。第一次使用时,先部署服务端,再通过浏览器初始化密码库。已经有实例的用户可直接前往连接设备。
部署服务端
准备 PassDock 源码、Go 1.26+、Node.js 22.12+、独立的 MySQL 数据库及其账号。开发集成测试使用 MySQL 8.4。非本地部署需要设备可访问、证书受信任的 HTTPS 地址。
从仓库根目录执行以下命令,生成 Web 静态资源与 Go 服务端。
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。
./bin/passdock bootstrap
./bin/passdock servebootstrap 签发 15 分钟内有效的一次性初始化凭据。保持服务运行,访问配置好的实例地址,继续首次设置。
首次设置
- 在浏览器打开自己的实例地址,输入初始化凭据并注册 Passkey。
- 设置一个足够长且独立的主密码,用于在设备本地解锁密码库。
- 按界面提示离线保存恢复密钥并验证。妥善保存恢复密钥,后续重设主密码及恢复加密备份会用到它。
- 新建一条演示数据,试一次搜索、打开详情、复制和锁定。可在「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 构建产物。桌面授权完成后,请切回客户端继续解锁。