在 Debian 12 上安装 Pocket ID 配置单点登录 SSO 教程

Pocket ID 是一个简单的 OIDC 提供程序，允许用户使用其服务的通行密钥进行身份验证。Pocket ID 的特别之处在于它仅支持 Passkey 身份验证，这意味着您不需要密码。您可能一开始并不赞同这个想法，但我相信 Passkey 是未来的新趋势，一旦你尝试过，你就会爱上它们。毕竟点一下就登录和输入一大堆密码才登录显然前者更省时间。

0x00 前情提要

为什么有 Pocket ID 这类项目？

作为开发者的您计划构建一个系列项目，通常情况下这个项目有很多跨网站的用户交互，为了提供统一的用户验证逻辑和体验，您可以选择使用 OIDC 或者对应的登录页面集成 —— 这样很明显，您无需为每一个站点开发一个用户系统，可以极大程度的缩短开发周期，有更多的时间来摸鱼。

为什么不选择 Casdoor 或者 Logto 或者 ZITADEL 等优秀的项目？

诚然，Casdoor 已经在一个月里坏两三次了，这个登录界面不能说很难看反正不太符合我的审美；Logto 是新一代的 IAM 验证解决方案，对于我来说，我并不需要他们的多租户功能，我只需要一个简单的使用案例。

Logto 是优秀的开源项目，支持多种登录方式，为什么不选择它呢？

真实原因是：手头没那么大资源的机器了，如果你想让我测测 Logto，请给我打钱，谢谢。

0x01 准备基础设施

XMSL Portal 实机演示

系统准备

准备一台不低于 1 Core 的机器，内存建议 512MB 起，硬盘建议 10G 起。

如果你要挂别的服务，我推荐使用各家 2C2G 的套餐，雨云优惠码：lz932，推荐使用云驰互联海外融合云。这里我使用十堰区域作为服务的主机，附带德国法兰克福（自有基础设施）作为一主一备。

Docker

如果你还没有安装 Docker，可以使用以下一键命令安装：

curl -fsSL https://get.docker.com | bash -s docker
# 对于中国大陆地区可选使用阿里云镜像
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

部分云主机厂商预装的 Docker 不含 docker-compose-plugin，实际使用的时候要多加注意（建议是手动安装）。

Docker compose

本部分内容因软件升级已过时，仅供参考，请以最新信息为准。

在这里我们假设您已经安装并熟练使用 docker compose 了，如果对此有疑问的请留言我以后加上详细的使用方法。

出于安全原因，或者不想让文件系统一团糟，我选择使用 Docker 部署 Pocket ID，方法也很简单，配置 docker-compose.yml 就好了：

services:
  pocket:
    image: ghcr.io/pocket-id/pocket-id
    container_name: pocket_id
    env_file: .env # 别忘了在这个文件里写上环境变量
    restart: unless-stopped
    ports:
      - 8888:80
    volumes:
      - "./data:/app/backend/data"
    healthcheck:
      test: "curl -f http://localhost/health"
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s

通常这是我的环境变量 .env，你既可以写进文件也可以直接在 compose 文件里编写：

# 详细配置教程: https://github.com/pocket-id/pocket-id?tab=readme-ov-file#environment-variables
PUBLIC_APP_URL=https://portal.example.com # 注意修改
TRUST_PROXY=true                          # 待会我要在前面套上 Cloudflare Tunnel，所以这里信任代理
MAXMIND_LICENSE_KEY=LowFo8_********_mmk   # 注意修改为你的 MAXMIND KEY，不然登录地址会显示未知
PUID=1000
PGID=1000
UPDATE_CHECK_DISABLED=true                # 由于是国内的机器，我习惯禁用检查新版本

很好，看起来我们已经配置好了，接下来我们使用 docker compose 命令启动容器看看能否正常运行：

docker compose up               # 先保持前台运行，方便修改配置
# 在稳定后...
docker compose up -d            # 这里可以正常丢到后台运行了
docker compose logs -f          # 这样可以持续的显示日志流，方便观察应用运行状态
docker compose down             # 优雅的关闭容器并移除相关网络等资源
docker compose kill             # 哦不是吧，好像出了什么事情！立即杀死所有容器，此时容器依然存在（只是变成停止状态）
docker compose restart          # 重启一下所有容器，注意这个通常只在修改了应用的配置时使用
# 如果你修改了 compose.yml，你应该再次使用：
docker compose up -d
# 这样会让所有修改了配置的容器 Recreate 并启动，并且遵循容器之间的依赖关系

现在，您可以在浏览器里使用 http://<YOUR_IP_HERE>:3000/login/setup admin 帐户登录。

管理员设置

0x02 访问 WebUI 添加新用户和新应用

一旦您设置好了管理员账户，你就可以在 Users 下添加更多账户。

设置新用户

我们也可以在 OIDC Client 处添加新 OIDC 客户端，具体参数要看具体应用怎么提供的，这里以 RSS 阅读器 Miniflux v2 举例：

设置新客户端

完成后你将获得 Client ID 和 Client secret，其中 Client secret 将仅展示一次，后续需要展示只能通过重置的方式。

牢记密钥，丢了可不好办

一旦您按照 Miniflux 文档填写好环境变量，您就可以通过 Portal 轻松登录到您的 Miniflux 了。

0x03 设置备用登录方式

如果真的发生了无法访问 Bitwarden 的问题（或者把数据库格式化了），你还有几种方法来补救：

设置「邮件一次性代码」恢复

设置「邮件一次性代码」恢复

多设置几个 Passkey，实现物理密钥和软件模拟密钥的多重备份
参见下一条。

0x04 我忘记了密码！怎么恢复？

很简单，你可以在管理面板的“用户”选项卡下为用户创建一次性访问链接，让用户通过代码登录随后修改自己的 Passkey 等信息。如果你丢了管理员密码（包括但不限于丢失了对 Bitwarden 的访问权限等小问题），请在终端运行以下命令恢复：

# 请将 pocket_id 改为您的容器名
docker compose exec pocket_id sh "sh scripts/create-one-time-access-token.sh <username or email>"

0x05 FAQ

无法添加 Passkey

这种情况通常是配置有误导致的，请确保 PUBLIC_APP_URL 设置为 Pocket ID 实例的公网 URL。

我该怎么为管理员用户设置 Passkey

要为初始用户 admin 设置 Passkey，请前往 https://portal.example.com/login/setup 设置。

我不会添加 OIDC 客户端

作者在文档中给出了一份非常详尽的 OIDC 常用配置，如果你实在不甚了解，可以去查看学习：Examples of how to setup Pocket ID with different clients

0x05 总结

Pocket ID 作为一款专注于 Passkey 身份验证的轻量级 OIDC 解决方案，以其无需密码、部署简单和资源占用低的特点，为开发者提供了高效便捷的用户认证管理体验。相较于 Casdoor 的稳定性问题、Logto 的多租户冗余功能或 ZITADEL 的复杂配置，Pocket ID 精准定位「极简主义」需求，仅需基础服务器资源即可运行，完美适配个人或小型项目的快速开发场景。

感谢你阅读到这里，对本文有任何问题欢迎留言！欢迎关注我的 Fediverse 账号接收最新的碎碎恋。