这是「Docker 好项目」系列的第 20 期。前 19 期我们把监控、密码库、照片、音乐、代码、文档、记账……一个个搬回了自己服务器,但不知道你发现没有:每搬回来一个服务,就要多记一套账号密码。Vaultwarden(第 3 期)帮你把密码存好,可登录这件事本身还是散落在十几个服务里——Uptime Kuma 一套、Gitea 一套、Miniflux 一套,改个密码要挨个登进去改,谁离职了、谁手机丢了,你得自己想起来去关哪个。这期介绍 Pocket ID:一个只做一件事的自托管 OIDC 认证服务——让所有服务都用同一把 passkey 登录。它最讨喜的地方是官方文档里躺着一百个现成的接入教程,其中九个正是这个系列写过的项目,抄作业就行。

Pocket ID 效果图

痛点开场

自托管玩到第十个服务,账号密码就开始失控了:

  • 一套服务一套密码。Immich 一套、Jellyfin 一套、Paperless-ngx 一套。为了省事很多人干脆全用同一个弱密码——那第 3 期 Vaultwarden 存的密码库就白搭了
  • 关停一个账号要靠脑子记。家里人、朋友的临时账号散在各个服务里,人走了你根本不记得要去哪个后台把人禁用
  • 每个服务都要单独开两步验证。有的支持 TOTP,有的只支持邮件,有的压根没有,安全水位参差不齐
  • 想统一入口,一看 Keycloak 就劝退。Keycloak、Authentik 这类全家桶确实什么都有:SAML、LDAP、Kerberos、用户联邦……代价是 Java 内存的启动配置和一眼望不到头的管理台。家庭服务器跑这个,属于开挖掘机去取快递

Pocket ID 的定位就是卡在这个空档上:它只做 OIDC(外加 OAuth 2.0),只支持 passkey 登录,一个 Go 二进制 + 内置 SQLite,一个容器就跑完。不是"功能少",是"故意不多做"——README 原话是给"觉得 Keycloak 或 Authentik 太重"的小团队和 homelab 用的。它通过了 OpenID 官方的 Certified 认证,这个认证在自托管圈子里并不多见。我写这篇时它的最新版本是 v2.17.0(2026-10-01 发布),前一天仓库还在推代码,9.4k star,BSD-2-Clause——注意这个协议是货真价实的开源,比第 19 期 n8n 的 fair-code 宽松得多,想拿它做什么都行。

能力边界

能干什么

  • 统一登录:任何支持"OIDC / SSO / OAuth 登录"的应用都能接, Pocket ID 负责"这人是谁",应用自己管"这人能干什么"
  • Passkey 优先:指纹、面容、PIN、YubiKey 都行;passkey 绑定域名,钓鱼网站偷不走。也支持从另一台设备扫码授权登录(手机审批,5 分钟有效)
  • 用户与用户组:组可以决定"谁能登录哪个应用",并且随 token 下发给应用,应用可以直接拿组做角色判断
  • 三种备用登录:管理员生成的登录码(一次性链接/口令)、扫码跨设备登录、配好 SMTP 后的邮箱验证码登录(这个有安全代价,后面细说)
  • 审计日志:每次登录记录 IP 和地理位置(MaxMind GeoLite2 或 Cloudflare 头),默认保留 90 天
  • API 完整:管理端 REST API + API Key,可以写脚本批量建客户端;静态 API Key 还能做声明式部署
  • LDAP 同步:把已有 LDAP/AD 的用户和组同步进来,管理员组映射成 Pocket ID 管理员
  • SCIM:给接进来的企业级应用做用户/组的自动开通与回收(v2.17.0 源码里已有 scimsync 模块和配套 UI 表单)
  • 中文界面:v2.17.0 的语言包里带 zh-CN.json,管理界面直接切中文,不用啃英文
  • PostgreSQL / S3 可选:SQLite 默认够用;附件(logo、头像)可以放本地、数据库或 S3 兼容存储(MinIO、R2 都行)

不干什么

  • 没有密码登录。这不是缺功能是产品立场:没有密码就没有密码可泄露、可撞库。代价是没带任何 passkey 设备的人进不来,只能靠登录码救急。家里有完全不会折腾的长辈要权衡
  • 不做 SAML / 不对外提供 LDAP。老应用不支持 OIDC 的话,官方给的路子是前面加一层认证代理(oauth2-proxy 之类),Pocket ID 本身不管这个
  • 不是密码管理器。它管"登录",密码该存哪还归第 3 期 Vaultwarden 管,两者是邻居不是竞争
  • 单实例。一个数据库同一时间只能被一个 Pocket ID 用(源码里 HA 模式的注释写得很直白:还没做完)。个人服务器单实例足够,但别想着一主一备
  • 注册默认关闭。ALLOW_USER_SIGNUPS 默认 disabled,用户都得管理员建——这本来就不是给陌生人注册用的产品

部署前准备

准备项 说明
一个专属域名 比如 id.example.com。passkey 和域名绑定,APP_URL 必须和浏览器地址栏一字不差,中途换域名等于所有 passkey 作废重录,所以一开始就定好
HTTPS 浏览器只在 HTTPS(或 localhost)下允许创建/使用 passkey。反代或 Cloudflare 套一层都行
加密密钥 openssl rand -base64 32 生成。必填,不设或短于 16 字节,容器直接启动失败退出
本地磁盘目录 数据目录别放 NFS/SMB 挂载上,SQLite 在网络文件系统上有损坏风险,程序检测到会在管理台报警
端口 1411 空闲 Web 端口。另外它内部还有个 1414/udp 的任务运行时,只在容器内部用,不需要映射,别照着某些教程瞎映射

先生成密钥(生成一次就够,后面 compose 和备份都靠它):

# 在准备放 Pocket ID 的目录里执行
openssl rand -base64 32

docker run 一行版

先跑起来感受一下(正式用推荐下面的 compose):

mkdir -p ~/pocket-id && cd ~/pocket-id

# 密钥落盘一次,容器重启也不会变(printf '%s' 是故意的:避免末尾换行符被算进密钥)
printf '%s' "$(openssl rand -base64 32)" > encryption_key

docker run -d \
  --name pocket-id \
  --restart unless-stopped \
  -p 1411:1411 \
  -v "$PWD/data:/app/data" \
  -v "$PWD/encryption_key:/app/encryption_key:ro" \
  -e APP_URL=https://id.example.com \
  -e ENCRYPTION_KEY_FILE=/app/encryption_key \
  pocketid/pocket-id:v2.17

三个细节别抄错:

  • tag 必须带 v。官方只发 v2.17.0、v2.17、v2、latest 这几种写法,不带 v 的 2.17 实测是 404。我比对过 manifest digest:v2 == v2.17 == v2.17.0 == latest,v2.6 == v2.6.2——次版本 tag 是跟着补丁滚动的,所以钉 v2.17 就行,补丁版本会自动跟进
  • 镜像有两个源:Docker Hub 的 pocketid/pocket-id 和 GHCR 的 ghcr.io/pocket-id/pocket-id,同一套构建,Docker Hub 拉不动就换 GHCR
  • 为什么用 ENCRYPTION_KEY_FILE:-e ENCRYPTION_KEY=$(openssl rand -base64 32) 这种写法每次重建容器都会生成新密钥,旧密钥一换,里面加密的签名密钥全部解不开,所有客户端的 secret 作废。落成文件挂进去才是对的做法。所有敏感变量都有 _FILE 变体(DB_CONNECTION_STRING_FILE、STATIC_API_KEY_FILE、S3_SECRET_ACCESS_KEY_FILE、MAXMIND_LICENSE_KEY_FILE)

docker-compose 推荐版

mkdir -p ~/pocket-id && cd ~/pocket-id

docker-compose.yml:

services:
  pocket-id:
    image: pocketid/pocket-id:v2.17        # 或 ghcr.io/pocket-id/pocket-id:v2.17
    container_name: pocket-id
    restart: unless-stopped
    env_file: .env
    ports:
      - "1411:1411"                        # 宿主机端口按需改,容器内固定 1411
    volumes:
      - "./data:/app/data"                 # 唯一的数据卷:SQLite 库 + 上传文件全在这
    healthcheck:                           # 镜像已内置同款检查,写出来是为了自己能调参数
      test: ["CMD", "/app/pocket-id", "healthcheck"]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

.env:

# 必填:浏览器打开 Pocket ID 用的地址,不带路径、不带末尾斜杠
APP_URL=https://id.example.com

# 必填:openssl rand -base64 32 的输出,丢了等于全部加密数据作废
ENCRYPTION_KEY=把上面生成的密钥粘这里

# 容器降权运行(默认就是 1000:1000,写出来是提醒你别用 root 的 uid)
PUID=1000
PGID=1000

# 收紧:默认允许应用用 http:// 回调地址(官方注释写明 v3 会改成默认 false),现在就手动关掉
ALLOW_INSECURE_CALLBACK_URLS=false

# 反代场景二选一:直连 OpenResty 用 TRUST_PROXY,套了 Cloudflare 用 TRUSTED_PLATFORM
# TRUST_PROXY=172.18.0.0/16
# TRUSTED_PLATFORM=CF-Connecting-IP
docker compose up -d

镜像配置我拉了 config blob 逐项核过:端口 1411,入口 /app/docker/entrypoint.sh,启动后 entrypoint 按 PUID/PGID 建用户、把 /app/data 属主改过来,再用 su-exec 降权——和 Navidrome、changedetection.io 那两期"设了也没用"不一样,Pocket ID 的 PUID/PGID 是真生效的。镜像自带 HEALTHCHECK(/app/pocket-id healthcheck,90 秒一次),基础镜像 alpine:3.24.1,amd64 和 arm64 都有。

配置项逐项解释

高频项都在这,完整清单见官方文档(文末有链接):

变量 默认值 为什么这么写
APP_URL http://localhost:1411 整个系统里最重要的一行。Passkey 绑定它的域名,发给应用的回调、发现文档、token 端点全部由它拼出来;它还必须不含路径,https://id.example.com/id/ 这种写法启动时直接报错
ENCRYPTION_KEY 无(必填) 加密 token 签名密钥、客户端 secret 这些敏感数据。≥16 字节,推荐 32 字节。换 key 要走 encryption-key-rotate 命令重加密,不能直接改
PUID / PGID 1000 数据目录属主。默认镜像以 root 起步、降权到这个 uid 跑主进程;如果你用 user: 或 distroless 镜像,这两个变量失效,要自己 chown
TRUST_PROXY false 告诉它谁的反代头可以信(取真实客户端 IP 用于审计日志和限流)。支持 IP 或 CIDR 逗号分隔,true 是信任所有来源——只在"不经过反代就根本访问不到"时才用
TRUSTED_PLATFORM 空 在 Cloudflare 后面比 TRUST_PROXY 更省心:直接读 CF-Connecting-IP 头。Fly.io、GAE 也有各自对应的头
INTERNAL_APP_URL 同 APP_URL 浏览器走 https://id.example.com,但同机的应用容器去取 token 时走内网地址(如 http://pocket-id:1411)时设这个。不设就全部用 APP_URL,要求应用容器也能解析公网域名
DB_CONNECTION_STRING data/pocket-id.db 以 postgres:// 开头就走 PostgreSQL,否则当 SQLite 文件路径。SQLite 别放网络盘;非要放就加 _journal_mode=DELETE 并自己担风险
ALLOW_INSECURE_CALLBACK_URLS true 默认允许应用拿 http:// 回调(localhost 除外)。这是官方为了兼容老部署留的口子,源码注释写明 v3 要改成默认 false——现在就手动设 false
AUDIT_LOG_RETENTION_DAYS 90 审计日志保留天数,登录记录里带 IP 和城市
MAXMIND_LICENSE_KEY 空 免费 MaxMind key,用于在审计日志里显示登录地点。套 Cloudflare 的话可以用 CLOUDFLARE_LOCATION_HEADERS=true 替代,连 key 都不用申请
ACTORS_PORT 1414 内部任务运行时的 UDP 端口,容器内部自用,不要映射到宿主机,只有撞端口才需要改
ANALYTICS_DISABLED false 每天一次的心跳统计(统计有多少实例在跑)。介意就设 true,还有个 VERSION_CHECK_DISABLED=true 关掉 GitHub 版本检查,内网机两个都建议关
LOG_LEVEL info debug/info/warn/error。排障时临时开 debug,注意 LOG_QUERY_ARGS=true 会把 SQL 参数打进日志,含个人信息,别常开
UI_CONFIG_DISABLED false 设 true 后"应用配置"页的全部设置改由环境变量管理(APP_NAME、SESSION_DURATION、SMTP_*、LDAP_*、WEBAUTHN_*、ALLOW_USER_SIGNUPS 等),适合想把配置放进 git 的人

有两个 UI 里的策略项值得单独说,因为它们直接影响日常体验:

  • WEBAUTHN_USER_VERIFICATION:默认 required,每次登录都要求指纹/面容/PIN。用只有触摸没有 PIN 的老 YubiKey 会一直失败,要么给钥匙设 PIN,要么在应用配置里改成 preferred
  • WEBAUTHN_ALLOW_SYNCED_PASSKEYS:默认 true,允许 iCloud 钥匙串、1Password 这类"会跨设备同步的 passkey"。家里几台设备共用的人建议保持默认;追求最高安全(比如只认硬件钥匙)再关掉

数据目录与加密密钥:这一节最好背下来

/app/data 里就三样东西,挂载这一个目录就备份了全部:

内容 是什么
pocket-id.db SQLite 主库:用户、passkey 公钥、OIDC 客户端、审计日志全在这
uploads/ 上传文件:应用 logo、用户头像(默认 data/uploads,可用 UPLOAD_PATH 改)
GeoLite2-City.mmdb MaxMind 的 IP 地理库(配了 license key 才会有)

而 ENCRYPTION_KEY 不在数据目录里——它在环境变量或你挂的密钥文件里。这意味着:备份了 data 却丢了 key,恢复出来的库照样解不开签名密钥,所有 OIDC 客户端的 secret 全部作废,只能重建。密钥本身也要进备份,并且和 data 分开存(比如密码库里存一份)。改密钥别硬改环境变量,用官方命令原地重加密:

docker compose exec pocket-id /app/pocket-id encryption-key-rotate --new-key <新密钥>

1Panel 面板怎么搞

1Panel 应用商店(dev 分支 265 个应用)没有 Pocket ID——商店里的同类是 Keycloak、Logto、Zitadel、Casdoor,都是重量级全家桶,正好衬托出 Pocket ID 的定位。所以走"容器 → 编排"自己贴:

  1. 容器 → 编排 → 创建编排,把上面的 compose 和 .env 贴进去,工作目录建议 /opt/pocket-id
  2. 网站 → 创建网站 → 反向代理:域名填 id.example.com,代理地址 http://127.0.0.1:1411,然后在网站设置里给这个域名申请 Let's Encrypt 证书
  3. 别急着用,先处理两件 1Panel 环境特有的事,见下

第一件:OpenResty 的缓冲区。Pocket ID 某些页面返回的响应头比 nginx 默认缓冲大,会报 502(错误日志里是 upstream sent too big header)。这是官方文档点名的问题,1Panel 的反代底层就是 OpenResty,一样会中。编辑站点的反代配置(/opt/1panel/www/sites/<域名>/proxy/root.conf),在 location / 里加三行:

location / {
    proxy_pass http://127.0.0.1:1411;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Pocket ID 的响应头比 nginx 默认缓冲大,不加这三行会间歇性 502
    proxy_busy_buffers_size 512k;
    proxy_buffers 4 512k;
    proxy_buffer_size 256k;
}

改完 openresty -s reload(或在 1Panel 里重启 OpenResty)。

第二件:告诉 Pocket ID 谁是真实客户端 IP。1Panel 的 OpenResty 跑在容器里,Pocket ID 看到的来源 IP 是 OpenResty 容器的地址。先查一下实际网段再填:

docker network inspect 1panel-network | grep -i subnet

把查到的网段(常见是 172.18.0.0/16)填进 TRUST_PROXY,改完 docker compose up -d 重启。不设的话审计日志里全是反代的 IP,限流也会把所有用户算成同一个。

如果你的域名像本站一样套着 Cloudflare:TRUSTED_PLATFORM=CF-Connecting-IP 更简单,顺手可以加 CLOUDFLARE_LOCATION_HEADERS=true 用 CF 的头显示登录地点,MaxMind 的 key 都省了。另外务必给这个域名关掉 Cloudflare 的 Rocket Loader——它会往页面里注入自己的脚本,和 Pocket ID 的 CSP 冲突,症状是页面部分功能不加载。

首次访问

  1. 浏览器打开 https://id.example.com/setup,填用户名、邮箱、姓名,创建第一个账号。这个页面只在还没有任何账号时有效,第一个账号建完就永久关闭
  2. 创建完立刻去账号页点 Add Passkey 录入你的指纹/面容/YubiKey——这才是你以后的登录方式。如果建了账号但没来得及录 passkey,页面进不去了也别慌,用命令行救:
# 生成一个一次性登录链接,1 小时内有效
docker compose exec pocket-id /app/pocket-id one-time-access-token <用户名或邮箱>
# 输出形如:Use the following URL to sign in once: https://id.example.com/lc/YCvmQgrJbX0zEZbh
  1. 登录进去后到 管理 → 应用配置 里过一遍:界面语言切中文、按需开/关"允许同步 passkey"、把 WEBAUTHN_USER_VERIFICATION 改成适合你硬件的值
  2. 管理界面右上角还能改应用名和 logo——发给应用的授权页会带上这些,见下图这个样子:

Pocket ID 授权确认页

上图就是应用接入后的授权确认页:左边是 Pocket ID 和目标应用的图标,用户点一次"Sign in"就完成绑定,之后不再打扰(可以在客户端上勾选"跳过授权页")。右下角的 Alternative Sign In Methods 是备用登录入口,登录码、扫码、邮箱验证码都藏在这。

最小可用配置

Pocket ID 的"最小"真的小,压到三行也能跑:

APP_URL=https://id.example.com
ENCRYPTION_KEY=openssl rand -base64 32 的输出
ALLOW_INSECURE_CALLBACK_URLS=false
  • APP_URL:没有它,passkey 域名、回调地址、发现文档全是 localhost,只有本机能玩
  • ENCRYPTION_KEY:唯一强制项,缺了起不来
  • ALLOW_INSECURE_CALLBACK_URLS=false:不是必须,但默认值太宽,接进来的应用哪怕配错成 http:// 也能登录。关掉之后,回调地址必须是 https,配置错误会在接入时就暴露出来,而不是埋着

其余全部有合理默认。数据库 SQLite 开箱即用,附件存本地,审计日志 90 天——个人自托管这套默认就是官方推荐的形态,不需要一开始就上 Postgres。

接第一个应用(拿往期项目练手)

Pocket ID 这边:管理 → OIDC 客户端 → 添加,填名字和回调地址,建完立刻把 Client ID 和 Client Secret 抄下来(secret 只显示这一次),然后到客户端的 Access 标签页选允许登录的用户组——新客户端默认谁也进不去,忘了这步就会看到 "You are not allowed to access this service"。

应用那边要填的东西基本是这四样:

应用里叫什么 填什么
Issuer / 提供方 URL / 权限地址 https://id.example.com(你的 APP_URL)
发现地址 / well-known https://id.example.com/.well-known/openid-configuration
Client ID / Client Secret 客户端页面上那两个;纯前端/移动应用选"公共客户端",不用 secret(走 PKCE)
Scopes openid profile email,应用要按组分角色再加 groups

官方文档有 100 个应用的逐步接入教程,其中 9 个是本系列写过的:Vaultwarden(第 3 期)、Immich(第 4 期)、Memos(第 7 期)、Gitea(第 10 期)、Miniflux(第 12 期)、Paperless-ngx(第 14 期)、linkding(第 15 期)、Actual Budget(第 16 期)、Jellyfin(第 17 期)。第 16 期写 Actual Budget 时提过一句"多用户必须接 OIDC",当时没有现成的自建提供方,现在补上了。拿第 12 期的 Miniflux 举例,往它的环境变量里加:

OAUTH2_PROVIDER=oidc
OAUTH2_CLIENT_ID=<客户端ID>
OAUTH2_CLIENT_SECRET=<客户端密钥>
OAUTH2_REDIRECT_URL=https://miniflux.example.com/oauth2/oidc/callback
OAUTH2_OIDC_DISCOVERY_ENDPOINT=https://id.example.com
OAUTH2_OIDC_PROVIDER_NAME=PocketID
OAUTH2_USER_CREATION=1          # 首次登录自动创建 Miniflux 用户
DISABLE_LOCAL_AUTH=1            # 关掉本地密码登录,只留 OIDC

两个高频报错提前打预防针:

  • redirect_uri 不匹配:Pocket ID 只回调客户端里登记过的地址,一个字符都不能差。最常见原因是应用自己不知道在外面套了反代,把回调拼成了 http://——去把应用的对外地址配置改对,或者在客户端里把两个版本都登记上(官方也有回调地址通配符的文档)
  • 应用取不到 token:登录页跳过去又跳回来之后卡住,多半是应用容器自己访问不到 APP_URL——发现文档和 token 是应用的服务端直接找 Pocket ID 拿的,不是走你浏览器。路由器不开回环(hairpin NAT)或容器内 DNS 解析不了公网域名都会中招,这时设 INTERNAL_APP_URL=http://pocket-id:1411 让服务端走内网

告警/通知配置

Pocket ID 自己不发"服务挂了"的告警——这类系统的告警一律外部化,和前 19 期一个思路:

  • 容器级:镜像自带 healthcheck(/app/pocket-id healthcheck,内部就是请求自己的 /healthz),Docker 会标记 unhealthy
  • 服务级:拿第 1 期的 Uptime Kuma 监控 https://id.example.com/healthz,这个端点无鉴权、极轻量;挂了走第 13 期的 ntfy 推手机。认证服务是所有服务的地基,它的监控优先级应该排在你所有监控里的第一位——它一挂,全家登录按钮一起转圈
  • 应用内的邮件通知(需要先在 应用配置 → 邮件 里配 SMTP,SMTP_TLS 可选 none/starttls/tls):
  • 新设备登录提醒(EMAIL_LOGIN_NOTIFICATION_ENABLED)——最值得开的一个,有人登你的号你立刻知道
  • API Key 即将到期提醒(EMAIL_API_KEY_EXPIRATION_ENABLED)
  • 管理员给用户发登录码(EMAIL_ONE_TIME_ACCESS_AS_ADMIN_ENABLED)——用户丢了 passkey 的标准救援通道
  • 用户自助申请邮箱登录码(EMAIL_ONE_TIME_ACCESS_AS_UNAUTHENTICATED_ENABLED)——官方明说这会削弱安全:能读用户邮箱的人就能登录成他。家里用建议不开,宁可用管理员发码
  • 审计日志:每次登录的 IP、地点、设备都有记录,保留 90 天(AUDIT_LOG_RETENTION_DAYS 可调),出事先看这里

反向代理与 HTTPS

Passkey 只在安全上下文里工作,所以反代这关躲不掉。核心就三条:

server {
    listen 443 ssl;
    server_name id.example.com;
    ssl_certificate     /etc/letsencrypt/live/id.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/id.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:1411;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_busy_buffers_size 512k;   # 响应头大于 nginx 默认缓冲,不加会 502
        proxy_buffers 4 512k;
        proxy_buffer_size 256k;
    }
}
  • APP_URL 和浏览器地址栏一字不差,多了个 www、少了个 https 都会导致 passkey 注册失败,报错文案是 "Passkeys are not configured correctly for this domain"
  • 反代透传全部路径到 1411,不要试图只代理 /authorize——OIDC 的端点散在 /.well-known/、/api/oidc/ 好几个前缀下
  • 后面有 CDN 就用 TRUSTED_PLATFORM,自建反代就用 TRUST_PROXY,二选一,别两个都设
  • Pocket ID 自己也能直接上 HTTPS(TLS_CERT_FILE/TLS_KEY_FILE,证书变化会自动重载),内网没有反代的场景可以走这条路,但公网还是建议专业反代管证书

踩坑清单

  • 镜像 tag 少了 v 直接 404。pocketid/pocket-id:2.17 拉不下来,正确写法 v2.17
  • 不设 ENCRYPTION_KEY 起不来。老教程很多还停留在"密钥可选"的年代(早期版本确实是自动生成的),v2.17 源码里启动第一个动作就是校验它,短于 16 字节直接退出。密钥生成后别动,要换必须走 encryption-key-rotate
  • 换域名 = 全部 passkey 作废。passkey 绑定域名,APP_URL 定下来就别改。真要迁域名,做好所有用户重新录 passkey 的心理准备
  • 新客户端默认没人能登录。建完客户端不去 Access 标签页选组或 All Users,用户登录时会看到 "You are not allowed to access this service"——这不是 bug,是默认拒绝
  • OpenResty/nginx 502。upstream sent too big header,加那三行 buffer 配置
  • 应用容器取不到 token。见上一节,INTERNAL_APP_URL 是解法;同时确认应用容器能解析你的公网域名
  • SQLite 放网络盘。NFS/SMB 上跑 SQLite 是经典数据损坏配方,程序检测到会在管理台挂出警告,DISMISS_SQLITE_STORAGE_WARNING=i accept the risks 能关掉警告——但关掉的是警告不是风险
  • 老安全钥匙 + required。没有 PIN 的触摸型钥匙在"必须生物验证"策略下永远失败,给钥匙设个 FIDO2 PIN,或把策略改成 preferred
  • Cloudflare Rocket Loader。往页面注脚本,和 CSP 冲突,部分界面不加载。给 Pocket ID 的域名关掉它
  • distroless 镜像没有 shell。pocketid/pocket-id:v2.17-distroless 更安全更小(非 root、无 shell),但 docker exec ... sh 进不去,PUID/PGID 也不生效,要用它就得自己把 /app/data 属主提前 chown 好。日常自托管用默认镜像 + PUID/PGID 就很好
  • 第一个账号建完 /setup 就没了。没录 passkey 就被关在门外,用 one-time-access-token 命令救回来,链接 1 小时有效

备份

两条路,建议都做:

# 路线一:官方导出(把数据打成 zip,跨库迁移也能用,官方标注实验性)
cd ~/pocket-id
docker compose exec -T pocket-id ./pocket-id export --path - > pocket-id-backup-$(date +%F).zip

# 路线二:直接打包数据目录(最稳,先停写)
docker compose stop pocket-id
tar czf pocket-id-data-$(date +%F).tar.gz ./data ./encryption_key ./.env
docker compose start pocket-id

要点:

  • ENCRYPTION_KEY 必须进备份。上面说过:有 data 没 key,恢复出来的库是打不开的保险箱。我把密钥文件和 .env 一起打进了 tar,你抄走时按自己的目录调整
  • 官方 export 恢复时是先清空再导入,别拿它当增量备份用;import 前必须停实例,管道输入要加 --yes 和 -T(不开 TTY,否则二进制流会被弄脏)
  • 导入验证:恢复后先看 docker compose logs -f 里有没有报错,再开一次 /healthz
  • 提醒一句:这是身份中枢,备份策略要比普通服务更勤——它一丢,全家服务一起失去登录方式。丢过一次的人都会把备份周期从"想起来再说"改成 cron

小结

适合谁

  • 自托管了 5 个以上服务、开始被账号管理烦到的人——这是 Pocket ID 的甜蜜点。3 个服务以下,各登各的更省事
  • 家里有多个使用者的人。建账号、按组授权、人走了禁用,都在一个地方,这比"每个服务挨个处理"省一个数量级的精力
  • 在乎钓鱼和撞库的人。passkey 绑定域名,理论上没有"在假登录页输入密码"这回事
  • 觉得 Keycloak/Authentik 太重的人。一个 Go 二进制 + SQLite,内存占用几十 MB 级别,2G 小机器也带得动
  • 这个系列的读者。官方文档里躺着这个系列 9 期项目的现成接入教程,照抄就能把散落的登录收拢成一把钥匙

不适合谁

  • 使用者里有完全玩不转 passkey 的人。备用通道只有登录码和(安全性打折的)邮箱验证码,长辈用户多的环境要掂量,或者把登录码流程做成手把手的说明书
  • 需要 SAML、对外 LDAP 服务、多实例高可用的环境。这些是 Keycloak/Authentik 的主场,Pocket ID 明确不做
  • 把它当密码管理器的人。它管登录不管密码,密码柜还归第 3 期 Vaultwarden
  • 想给公网陌生人开放注册的人。默认注册关闭,产品设计上它就是给自己人用的

在这个系列里的位置:前 19 期解决的是"把服务搬回家",这一期解决的是"搬回家之后,人怎么进门"。Homepage(第 18 期)给了所有服务一个统一出口,Pocket ID 给所有入口一把统一钥匙——一个是门牌,一个是门锁。它也是这个系列目前最"地基"的一期:配好之后,以后每搬回来一个新服务,接上 OIDC 就完事,账号管理这件事从此不再新增待办。

项目地址

  • GitHub:https://github.com/pocket-id/pocket-id
  • 官网:https://pocket-id.org
  • 官方文档:https://pocket-id.org/docs
  • 环境变量总表:https://pocket-id.org/docs/configuration/environment-variables
  • 100 个应用的接入教程:https://pocket-id.org/docs/client-examples
  • 在线演示:https://demo.pocket-id.org
  • Docker 镜像:pocketid/pocket-id(Docker Hub)/ ghcr.io/pocket-id/pocket-id(GHCR)
  • 回调地址通配符:https://pocket-id.org/docs/advanced/callback-url-wildcards