用 Pocket ID 给自托管应用接入 Passkey：Docker 部署与 OIDC 登录验证

自托管应用一多，账号就容易各管一套。换设备时重复登录，成员离开时逐个检查权限，也会遗漏。Pocket ID 提供 OIDC 与 OAuth 2.0 身份入口，以 Passkey 登录，适合已经支持这类协议的应用集中接入。

接入之前先选一个普通测试应用，不把所有管理员入口同时改掉。身份服务暂时不可用时，至少要能通过受控的恢复方式处理应用；否则一次域名、证书或数据库问题，会同时挡住多个服务的维护入口。

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 KuZhuJi。

它负责登录身份，应用仍负责访问权限

登录成功说明身份流程完成，用户是否能看某个项目、删除文件或进入管理员页面，仍要由目标应用的授权规则决定。只有登录按钮接上了，不能视为所有应用权限已经统一。

Pocket ID 官方界面示例

官方图展示通过 Pocket ID 登录 Pangolin 的确认界面。具体应用需要根据自己的 OIDC 实现填写发行者、客户端和回调地址，不能把一个应用的配置直接复制给另一应用。

Passkey 需要支持的浏览器、设备或安全密钥，并依赖正确的站点来源。先确定长期使用的域名，配置 HTTPS；不要先用一个临时域名录入全部凭据，随后随意换域名。设备同步的 Passkey 和独立硬件密钥，也应按自己的恢复需求安排。

当前镜像与有效文档一起使用

项目当前 Docker 示例使用主版本 v2，持久目录为 /app/data。安装参数应与当前主版本对应，迁移旧实例时另外核对该版本的安装与环境变量说明。

mkdir -p ~/services/pocket-id/data
cd ~/services/pocket-id
umask 077
printf 'APP_URL=https://id.example.com\n' > .env
printf 'ENCRYPTION_KEY=%s\n' "$(openssl rand -base64 32)" >> .env
chmod 600 .env

把域名换成实际地址。ENCRYPTION_KEY 用于加密包含私钥在内的数据，恢复需要保留相应密钥，不把它当作可以随时重新生成的临时密码。轮换按官方流程处理，不通过简单改环境变量代替。

保存 compose.yaml：

services:
  pocket-id:
    image: ghcr.io/pocket-id/pocket-id:v2
    env_file:
      - .env
    ports:
      - "127.0.0.1:1411:1411"
    volumes:
      - ./data:/app/data
    healthcheck:
      test: ["CMD", "/app/pocket-id", "healthcheck"]
      interval: 90s
      timeout: 5s
      retries: 2
      start_period: 10s
    restart: unless-stopped

主版本标签仍会获得该系列内的更新。第一次验收后记录实际镜像摘要，长期维护时按发行说明升级，不让身份服务在无人验收的时间自动跨版本改变。

docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 pocket-id

HTTPS 正常后再建立管理员

反向代理连接宿主机 127.0.0.1:1411，使用有效证书和 .env 中相同域名。初始化阶段限制入口到维护者能访问的范围，在 https://id.example.com/setup 建立首个管理员并录入 Passkey。

不要只测试首页加载。实际完成一次 Passkey 注册、退出和再次登录，再从预期使用的另一设备验证。浏览器出现站点来源、凭据或安全上下文错误时，检查域名、HTTPS 和代理，不通过放宽浏览器安全条件来维持正式使用。

TRUST_PROXY 用于指定可信代理地址或网段，按当前版本说明设置实际代理来源；不要为了“可能有用”直接信任所有来源。默认不信任代理时，日志或限流可能把流量归到代理地址，开放前应核对实际效果。

Pocket ID 与 OIDC 应用的登录和授权关系

身份服务提供登录信息，目标应用继续执行自己的成员和角色规则。恢复材料保存在身份服务之外，避免需要登录这个服务才能找到它的备份。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 KuZhuJi。配置按实际任务选择，数据库和附件另做备份。

为一个测试应用建立独立客户端

在 Pocket ID 中建立 OIDC 客户端，根据目标应用的官方说明填写允许的回调 URL。回调地址应精确对应协议、域名和路径，不使用泛化通配来掩盖拼写错误。客户端 ID 与密钥属于这一项应用，多个应用分别建立，便于撤销和检查。

目标应用填写 Pocket ID 的发行者或发现入口、客户端 ID、必要的密钥及所需范围。不同应用的字段名和支持方式不同，采用它自己的文档，不在这里编造一个能通用于所有服务的回调路径。

测试流程包括从目标应用发起登录、跳转到 Pocket ID、完成 Passkey、返回应用。接着退出并重新进入，确认身份对应预期账号。只在身份服务自己页面登录成功，不能证明客户端配置已经完整。

管理员和普通成员分别验收

使用普通测试用户接入目标应用，核对它不会自动获得管理员权限。再测试未被允许的用户是否被拒绝或限制，确认分组及角色映射按自己的预期生效。应用不支持所需映射时，应保留该应用自己的权限管理，而不是假设身份组会自动同步过去。

账号合并同样需要谨慎。已有用户使用相同邮箱登录，目标应用可能有不同的绑定行为；先在测试账号上核对，不让首次接入直接覆盖所有现有成员。邮箱相同也不应在没有验证流程时被当作充分的身份依据。

成员离开后，禁用身份入口并检查目标应用中的既有会话、API 令牌和其他登录方式。阻止新的 OIDC 登录，不一定立即撤销每个应用已经颁发的会话。按应用当前支持的方式处理，保留操作记录。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 KuZhuJi；迁移前保留数据与原有部署配置。

提前准备第二种可用凭据

管理员至少应有另一枚可用的 Passkey 或安全密钥，并验证它确实能够登录。设备损坏时，靠一条“以后再恢复”的说明并不足够。凭据丢失后的临时恢复使用官方支持的命令和流程，输出的一次性访问链接应当作为凭据保护，不贴进日志分享。

将服务器访问、备份位置和必要密钥的获取方式保存在独立受保护的位置。不要把这些信息只放在一个必须先通过 Pocket ID 才能打开的应用里。恢复路径可以定期演练，但不在正式用户仍活跃时随便删除全部凭据。

数据与加密密钥一起恢复

暂停身份服务后保存数据、环境文件与部署配置：

mkdir -p backups
docker compose stop pocket-id
tar -czf "backups/pocket-id-$(date +%F-%H%M%S).tar.gz" data .env compose.yaml
docker compose start pocket-id

备份转移到外部受保护的存储。恢复测试不仅看容器健康，还要核对管理员能登录、客户端信息和密钥可用，以及一个测试应用能够完成 OIDC 回调。

域名与 Passkey 来源相关，恢复演练的访问方式应按照官方支持的方案安排，不能把测试副本随意改到另一域名就认为旧凭据一定可用。演练不与正式实例共用数据，也不把正式客户端无意指向测试副本。升级后若迁移了数据库，回退需使用升级前的数据和对应密钥。