1797 字
9 分钟

Pocket ID 在 Dokploy 上的部署教程

2026-01-05
教程
Pocket ID
/
Dokploy
/
Docker
/
OIDC
/
Passkey
/
认证

在自建服务越来越多的今天,管理众多账号密码成了一大痛点。Pocket ID 提供了一个优雅的解决方案<基于> Passkey 的无密码认证系统,支持标准的 OIDC 协议,可以为你的所有自托管应用提供统一的单点登录(SSO)能力。

本文将详细介绍如何在 Dokploy 上部署 Pocket ID,并以 Linkding 为例演示如何接入应用。

pocket-id
/
pocket-id
Waiting for api.github.com...
00K
0K
0K
Waiting...

什么是 Pocket ID?#

Pocket ID 是一个现代化的 OpenID Connect (OIDC) 身份提供商,专注于使用 Passkey 进行无密码认证。

核心特性#

  • 完全无密码: 采用 Passkey 技术(WebAuthn),告别传统密码的安全隐患
  • OIDC 标准支持: 兼容所有支持 OIDC 的应用,如 Immich、Nextcloud、Grafana 等
  • 自托管友好: 轻量级设计,使用 SQLite 或 PostgreSQL 存储数据
  • 硬件密钥支持: 支持 YubiKey 等 FIDO2 硬件安全密钥
  • 简洁高效: 相比 Keycloak、Authelia 等企业级方案更轻量、配置更简单

技术栈#

  • 后端: Go (高性能、低资源占用)
  • 前端: Svelte + TypeScript
  • 数据库: SQLite(默认)或 PostgreSQL

在 Dokploy 上部署#

前置要求#

  • 已安装 Dokploy 的服务器
  • 一个域名(用于 HTTPS 访问,Passkey 必须在 HTTPS 环境下使用)
  • 至少 512MB 可用内存

创建 Compose 服务#

  1. 登录 Dokploy 管理面板
  2. 选择对应的项目(或新建一个)
  3. 点击 “Create Service” → 选择 “Template”
  4. 搜索 Pocket ID 模板并选择

image-20260105111215504

Docker Compose 配置#

CAUTION

Dokploy 的默认模板可能使用的是 v1 版本,但该版本已过时。必须修改镜像为 ghcr.io/pocket-id/pocket-id:v2,否则可能遇到兼容性问题和功能缺失。

在 Compose 配置中,粘贴以下内容:

services:
  pocket-id:
    image: ghcr.io/pocket-id/pocket-id:v2  #也就这里要修改，因为模板没更新是v1版本
    restart: unless-stopped
    environment:
      - APP_URL
      - TRUST_PROXY
      - ENCRYPTION_KEY
    volumes:
      - pocket-id-data:/app/data
    healthcheck:
      test: [ "CMD", "/app/pocket-id", "healthcheck" ]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s


volumes:
  pocket-id-data:

image-20260105111350098

环境变量配置#

在 Dokploy 的 “Environment” 标签页中,添加以下环境变量:

APP_URL#

应用的完整访问地址,必须使用 HTTPS。

Terminal window
APP_URL=https://pocketid.your.domain

示例:

  • 使用自定义域名: https://pocketid.example.com
  • 使用 Dokploy 自动生成的域名: https://berohost-pocketid-0da961-5-175-220-72.traefik.me
TIP

如果使用 Dokploy 自动生成的域名,可以在 Domains 标签页查看完整的 URL。

ENCRYPTION_KEY#

用于加密敏感数据的密钥,首次部署时设置为 CHANGEME,系统会自动生成。

Terminal window
ENCRYPTION_KEY=CHANGEME

如果需要手动生成密钥(可选),可以使用以下命令:

Terminal window
openssl rand -base64 32

TRUST_PROXY#

启用反向代理支持,Dokploy 默认使用 Traefik 作为反向代理,需设置为 true。

Terminal window
TRUST_PROXY=true

image-20260105111447700

部署与初始化#

启动服务#

  1. 在 Compose 服务页面,点击 “Deploy” 按钮
  2. 等待镜像拉取和容器启动
  3. 检查 “Logs” 标签页,确认服务正常启动 image-20260105111610271

访问 Setup 页面#

服务启动后,访问:

https://pocketid.your.domain/setup

image-20260105110038267

创建管理员账户#

  1. Username: 输入管理员用户名(建议使用邮箱格式,如 admin@example.com)
  2. Display Name: 显示名称
  3. Create Passkey: 点击后按照浏览器提示创建 Passkey
NOTE

Passkey 创建方式

  • 桌面浏览器: 可选择使用系统密码管理器(如 Windows Hello、macOS Touch ID)或硬件密钥
  • 移动设备: 可使用生物识别(指纹/面容)
  • 跨设备: 使用 1Password、Bitwarden 等密码管理器同步 Passkey

完成后,你将自动登录到管理面板。

接入通行密钥#

访问 https://pocketid.your.domain/settings/account

点击下方的增加通行密钥

一般建议多选一个，以备不时之需。

image-20260105111937578

分配用户组#

image-20260105114640534

应用集成<以> Linkding 为例#

在 Pocket ID 中创建 OIDC 客户端#

  1. 登录 Pocket ID 管理面板
  2. 进入 “Clients” 页面
  3. 点击 “Create Client”

填写以下信息:

Client Name: Linkding
Redirect URIs: https://linkding.your.domain/oidc/callback/
TIP
  • 回调 URL 也可以留空,首次登录时会自动填充
  • 可选上传 Logo 图标,用于登录页面展示

创建完成后,复制并保存以下凭证信息:

  • Client ID: 例如 abc123def456
  • Client Secret: 例如 secret_xyz789

在 Linkding 中配置 OIDC#

假设你使用 Docker Compose 部署 Linkding,在服务的环境变量(.env 文件或 Dokploy 的 Environment 标签页)中添加:

Terminal window
# 启用 OIDC 登录
LD_ENABLE_OIDC=True


# Pocket ID 客户端凭证
OIDC_RP_CLIENT_ID=<从 Pocket ID 复制的 Client ID>
OIDC_RP_CLIENT_SECRET=<从 Pocket ID 复制的 Client Secret>


# OIDC 端点配置
OIDC_OP_AUTHORIZATION_ENDPOINT=https://pocketid.your.domain/authorize
OIDC_OP_TOKEN_ENDPOINT=https://pocketid.your.domain/api/oidc/token
OIDC_OP_USER_ENDPOINT=https://pocketid.your.domain/api/oidc/userinfo
OIDC_OP_JWKS_ENDPOINT=https://pocketid.your.domain/.well-known/jwks.json


# PKCE 支持(根据实际需求调整,默认为 True)
OIDC_USE_PKCE=False


# SSL 证书验证(自签名证书时设为 False)
OIDC_VERIFY_SSL=True


# 可选:自定义用户名字段(默认使用 email)
# OIDC_USERNAME_CLAIM=preferred_username

完整参数说明:

环境变量说明示例值
LD_ENABLE_OIDC启用 OIDC 登录True
OIDC_RP_CLIENT_IDPocket ID 客户端 ID从 Pocket ID 复制
OIDC_RP_CLIENT_SECRETPocket ID 客户端密钥从 Pocket ID 复制
OIDC_OP_AUTHORIZATION_ENDPOINT授权端点https://pocketid.your.domain/authorize
OIDC_OP_TOKEN_ENDPOINTToken 端点https://pocketid.your.domain/api/oidc/token
OIDC_OP_USER_ENDPOINT用户信息端点https://pocketid.your.domain/api/oidc/userinfo
OIDC_OP_JWKS_ENDPOINTJWKS 端点https://pocketid.your.domain/.well-known/jwks.json
OIDC_USE_PKCE启用 PKCE 验证False(Pocket ID 暂不需要)
OIDC_VERIFY_SSL验证 SSL 证书True(生产环境推荐)
OIDC_USERNAME_CLAIM用户名字段(可选)email 或 preferred_username

重新部署 Linkding#

保存环境变量后,在 Dokploy 中点击 “Redeploy” 重新部署 Linkding 服务。

部署完成后,访问 Linkding 登录页面,你将看到 “Sign in with OIDC” 按钮。

image-20260105114128831

image-20260105114152444

通用集成说明#

对于其他支持 OIDC 的应用,通常需要以下信息:

Issuer / Discovery URL: https://pocketid.your.domain
Authorization Endpoint: https://pocketid.your.domain/authorize
Token Endpoint: https://pocketid.your.domain/api/oidc/token
UserInfo Endpoint: https://pocketid.your.domain/api/oidc/userinfo
JWKS Endpoint: https://pocketid.your.domain/.well-known/jwks.json
Client ID: 从 Pocket ID 获取
Client Secret: 从 Pocket ID 获取
Scopes: openid profile email
NOTE

大部分 OIDC 应用支持自动发现配置,只需填写 Issuer URL (https://pocketid.your.domain) 即可。如果需要手动配置,请使用上述完整端点路径。

TIP
  • Immich: 支持 OIDC,配置路径在 Settings → OAuth
  • Grafana: 配置文件中的 [auth.generic_oauth] 部分
  • Nextcloud: 安装 “OpenID Connect user backend” 插件
  • Portainer: Business Edition 支持 OIDC

更多接入可以见 https://pocket-id.org/docs/client-examples#

备份策略#

数据持久化#

Pocket ID 的所有数据保存在 pocket-id-data 数据卷中,包括:

  • SQLite 数据库(用户、客户端、Passkey 信息)
  • 配置文件
  • 会话数据

备份方法#

** 使用 Dokploy 内置备份**

  1. 进入服务的 “Backups” 标签页
  2. 配置备份目标(如 S3、本地路径)
  3. 设置备份计划(建议每日备份)

image-20260105115339189

image-20260105115402992

WARNING
  • 备份文件包含加密密钥和用户认证信息,务必妥善保管
  • 定期测试备份恢复流程,确保数据可用
  • 如果使用 PostgreSQL,额外备份数据库

安全加固建议#

1. 强制 HTTPS#

确保 APP_URL 使用 HTTPS,Passkey 在非 HTTPS 环境下无法使用。

2. 限制管理面板访问#

如果只有特定 IP 需要访问管理面板,可以在 Traefik 中配置 IP 白名单。

常见问题#

Q: Passkey 创建失败怎么办?#

A: 检查以下几点:

  1. 确认访问地址使用 HTTPS
  2. 浏览器是否支持 WebAuthn(Chrome 67+、Firefox 60+、Safari 14+)
  3. 检查浏览器控制台是否有错误信息

Q: 忘记管理员账户怎么办?#

A: 如果无法登录,可以通过数据库重置:

详情见 https://pocket-id.org/docs/troubleshooting/account-recovery

CAUTION

建议为管理员账户配置多个 Passkey,避免单点故障。

总结#

Pocket ID 为自托管用户提供了一个轻量级、现代化的身份认证解决方案。

再也不需要记密码了。

下一步,你可以:

  1. 将更多自托管应用接入 Pocket ID
  2. 配置多因素认证(MFA)增强安全性
  3. 探索 Pocket ID 官方文档了解高级功能

如果在部署过程中遇到问题,可以查阅:

祝你使用愉快!

Pocket ID 在 Dokploy 上的部署教程
https://catcat.blog/2026/01/pocket-id-dokploy
作者
猫猫博客
发布于
2026-01-05
许可协议
CC BY-NC-SA 4.0
Icons Gallery - 自托管图标 CDN 加速服务
清华大学校园网国际带宽基准测试
© 2026 猫猫博客. All Rights Reserved. / RSS / Sitemap
Powered by Astro & Fuwari