自托管统一认证：Pocket ID + Tinyauth 完整部署指南


阅读数: 0次   
字数：2.5k字 | 预计阅读时长：10分钟

前言

目前大多数网站仍采用账号密码登录，注重安全性的平台会在登录时增加二次验证，从最基础的图形验证码，到交互式人机验证，再到发送至手机或邮箱的验证码、2FA等。但这些方式本质上仍未脱离账号密码的框架——只要登录依赖密码，就始终面临账号被盗或字典爆破的风险，安全性始终存在隐患。

那么，是否存在一种彻底告别密码、同时兼顾安全与便捷的登录方式？答案是肯定的。通行密钥（Passkeys）正是这样一种全新的认证方式，它与硬件设备绑定，完全无需密码即可完成登录。借助设备内置的安全功能（如Touch ID、Face ID等），通行密钥在安全性和易用性上均优于密码及现有双因素认证。

随着技术与设备的发展，如今绝大多数主流设备都已支持通行密钥，并达到了真正“好用”的程度。

Pocket ID + Tinyauth这套轻量化方案，可以将所有自托管的服务统一纳入无密码认证体系。借助Pocket ID提供的用户与用户组权限管理，还能灵活满足小型组织中按权限控制访问的需求。

Pocket ID

Pocket ID是一个轻量化的OIDC提供商，支持且仅允许用户用通行密钥认证自定义服务，因此支持自定义OIDC供应商的服务可以直接使用它，实现无密码登录。

对于不支持自定义OIDC单点登录的服务，可以使用Tinyauth作为身份验证中间件，调用Pocket ID进行验证，最终实现一站式统一认证。

Tinyauth

Tinyauth是一个轻量化的认证和授权中间件，可以与Nginx、Traefik和Caddy等流行代理无缝集成。支持使用GItHub、Google、Pocket ID等作为OIDC认证提供商，为自定义服务提供现代化的认证界面。

注意

不能将Pocket ID或Tinyauth部署在根域名下，例如https://example.com。两者必须是同一个主域名，且使用不同的子域名，认证信息才能正确传递。

例如，Pocket ID部署在https://id.example.com，Tinyauth部署在https://auth.example.com。

值得注意的是，Pocket ID和Tinyauth都可以独立部署使用，以实现不同的功能，并非完全绑定。部署时可以根据需求自行选择。

Pocket ID部署

建议使用Docker Compose部署，创建PocketID文件夹，新建docker-compose.yml文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
services:
  pocket-id:
    image: ghcr.io/pocket-id/pocket-id:v2
    container_name: PocketID
    restart: unless-stopped
    env_file: .env
    ports:
      - xxxx:1411
    volumes:
      - "./data:/app/data"
    # Optional healthcheck
    healthcheck:
      test: ["CMD", "/app/pocket-id", "healthcheck"]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s
  • 修改端口号为自定义端口号

新建.env文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# See the documentation for more information: https://pocket-id.org/docs/configuration/environment-variables

# These variables must be configured for your deployment:
APP_URL=https://id.example.com

# Encryption key (choose one method):
# Method 1: Direct key (simple but less secure)
# Generate with: openssl rand -base64 32
ENCRYPTION_KEY=
# Method 2: File-based key (recommended)
# Put the base64 key in a file and point to it here.
# ENCRYPTION_KEY_FILE=/path/to/encryption_key

# These variables are optional but recommended to review:
TRUST_PROXY=true
MAXMIND_LICENSE_KEY=
PUID=1000
PGID=1000
ANALYTICS_DISABLED=true
  • 修改APP_URL为自定义域名
  • 使用openssl rand -base64 32生成加密密钥，填入ENCRYPTION_KEY，用于加密本地文件；或在ENCRYPTION_KEY_FILE中填写密钥文件所在位置。
  • TRUST_PROXY：如果准备使用后端代理，建议保持开启
  • MAXMIND_LICENSE_KEY：MaxMind密钥，用于下载GeoLite2数据库，以支持获取日志中IP地址的地理位置。如果未提供，IP地址位置将被标记为“未知”，密钥可以在MaxMind官网免费获取。国内下载请参考下面的详细说明
  • PUID、PGID改为当前用户和用户组的ID号，可以运行命令id查看
  • ANALYTICS_DISABLED：是否允许官方分析统计，实例每24小时向官方发送一次心跳，用于统计正在运行的实例数量，默认为“false”，可选关闭。

值得注意的是，国内IP地址即使填写了MaxMind密钥也无法正常下载GeoLite2数据库，手动下载提示：“Downloads of this database from CN are forbidden due to US bulk sensitive data transfer rules”，实测使用全局代理也无法正常下载。

解决办法是，先在文件夹中新建data文件夹，手动下载数据库文件GeoLite2-City.mmdb并放在data下，Pocket ID会自动读取。

数据库开源仓库：P3TERX/GeoLite.mmdb: MaxMind’s GeoIP2 GeoLite2 Country, City, and ASN databases

数据库文件默认的路径是data/GeoLite2-City.mmdb，可以通过环境变量GEOLITE_DB_PATH自定义修改。

由于数据库文件更新频繁，正常情况下，Pocket ID会自动下载更新，但默认是从MaxMind下载。通过配置环境变量GEOLITE_DB_URL为Github链接https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb可以实现数据库自动更新。

但由于数据库文件较大，一般来说不需要配置数据库为自动更新，在需要更新时手动下载，替换更新即可。

其他环境变量可以参考官方文档：Environment Variables

启动服务：

1
sudo docker compose up -d

修改docker compose文件或环境变量之后，需要删除并重建容器使其生效：

1
2
sudo docker compose down
sudo docker compose up -d

在Nginx中配置自定义本地端口的反向代理后，即可完成部署。Nginx中的SSL证书配置，各种参数配置模板可自行搜索。

更新容器镜像：

1
2
sudo docker compose pull
sudo docker compose up -d

Pocket ID配置与使用

访问https://id.example.com/setup进行管理员账户的注册。

在管理员面板，可以注册新的通行密钥、管理用户与用户组、配置SMTP邮箱通知、设置应用图标等。

个人使用，建议禁用用户注册，小团队使用，建议开启使用令牌注册，并配置用户组，方便权限管理。

在OIDC客户端中，可以添加支持自定义OIDC认证服务器的应用，具体配置方法可参考对应服务的官方文档，如果不确定回调URL，可以先留空，让Pocket ID自动获取。

对于不支持OIDC认证的服务，可以部署Tinyauth进行认证转发。

Tinyauth部署

建议使用Docker Compose部署，创建Tinyauth文件夹，新建docker-compose.yml文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
services:
  pocket-id:
    image: ghcr.io/steveiliop56/tinyauth:v5
    container_name: Tinyauth
    restart: unless-stopped
    env_file: .env
    ports:
      - xxxx:3000
    volumes:
      - ./data:/data
    # Optional healthcheck
    healthcheck:
      test: ["CMD", "tinyauth", "healthcheck"]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s
  • 修改端口号为自定义端口号

建立临时的docker容器初始用户，获取加密的用户名密码（如果不需要账号密码登录可以跳过这一步）：

1
docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 user create --interactive

输入用户名密码，使用上下键在“Format the output for Docker?”中选择“Yes”，复制生成的用户名密码Hash，填入下面的环境变量TINYAUTH_AUTH_USERS中。

新建.env文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
TINYAUTH_ANALYTICS_ENABLED=false
TINYAUTH_APPURL=https://auth.example.com
TINYAUTH_AUTH_USERS=xxxxxx
TINYAUTH_UI_TITLE=Tinyauth
TINYAUTH_UI_FORGOTPASSWORDMESSAGE=
TINYAUTH_UI_BACKGROUNDIMAGE=
TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID=your-pocket-id-client-id
TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET=your-pocket-id-client-secret
TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL=https://id.example.com/authorize
TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL=https://id.example.com/api/oidc/token
TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL=https://id.example.com/api/oidc/userinfo
TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL=https://auth.example.com/api/oauth/callback/pocketid
TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES=openid email profile groups
TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME=Pocket ID
  • TINYAUTH_ANALYTICS_ENABLED：是否启用定期版本信息收集，默认为true，可选改为false
  • TINYAUTH_APPURL：反向代理的目标域名
  • TINYAUTH_AUTH_USERS：用户名密码设置，配置Pocket ID后，如果不需要用户名密码登录，可以直接将此环境变量删除
  • TINYAUTH_UI_TITLE：自定义界面标题，可自行修改
  • TINYAUTH_UI_FORGOTPASSWORDMESSAGE：忘记密码时显示的信息，可以自行修改，如果没有设置密码登录，则不会显示
  • TINYAUTH_UI_BACKGROUNDIMAGE：自定义背景图片路径，默认是“/background.jpg”，可以是本地路径，也可以直接填写图片URL
  • TINYAUTH_OAUTH_xxxxx：连接Pocket ID的OIDC服务器配置，可以参考官方文档进行配置（Pocket ID OAuth | Tinyauth）

其他环境变量可以参考官方文档：Configuration | Tinyauth

启动服务：

1
sudo docker compose up -d

修改docker compose文件或环境变量之后，需要删除并重建容器使其生效：

1
2
sudo docker compose down
sudo docker compose up -d

在Nginx中配置自定义本地端口的反向代理后，即可完成部署。Nginx中的SSL证书配置，各种参数配置模板可自行搜索。

更新容器镜像：

1
2
sudo docker compose pull
sudo docker compose up -d

Tinyauth配置与使用

对于不支持OIDC的服务，可以通过Tinyauth作为中间件的方式，来调用Pocket ID做登录验证。

以Nginx反代的应用为例，下面是配置认证的模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
location / {
	# Pass the request to the app
	proxy_pass $forward_scheme://$server:$port;

	# Add other app-specific config here

	# Tinyauth auth request
	auth_request /tinyauth;
}

# Tinyauth auth request
location /tinyauth {
	# Pass request to Tinyauth
	proxy_pass http://localhost:xxxx/api/auth/nginx;

	# Pass the request headers
	proxy_set_header x-forwarded-proto $scheme;
	proxy_set_header x-forwarded-host $http_host;
	proxy_set_header x-forwarded-uri $request_uri;
}

# Tinyauth login redirect

location @tinyauth_login {
	return 302 https://auth.example.com/login?redirect_uri=$scheme://$http_host$request_uri; # Replace with your app URL
}

error_page 401 = @tinyauth_login;

对于特定的服务，如果只想要给域名的某一个子路径例如/admin添加Tinyauth鉴权，可以参考下面的模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
location /admin {
	# Pass the request to the app
	proxy_pass $forward_scheme://$server:$port/admin;

	# Add other app-specific config here

	# Tinyauth auth request
	auth_request /tinyauth;
}

location / {
	# Pass the request to the app
	proxy_pass $forward_scheme://$server:$port;

	# Add other app-specific config here
}

# Tinyauth auth request
location /tinyauth {
	# Pass request to Tinyauth
	proxy_pass http://localhost:xxxx/api/auth/nginx;

	# Pass the request headers
	proxy_set_header x-forwarded-proto $scheme;
	proxy_set_header x-forwarded-host $http_host;
	proxy_set_header x-forwarded-uri $request_uri;
}

# Tinyauth login redirect

location @tinyauth_login {
	return 302 https://auth.example.com/login?redirect_uri=$scheme://$http_host$request_uri; # Replace with your app URL
}

error_page 401 = @tinyauth_login;

需要将localhost:xxxx修改为本地Tinyauth服务的地址加端口号，修改auth.example.com为自定义域名。

在Docker中使用Traefik代理认证的设置可以参考官方文档：Getting Started | Tinyauth

至此，恭喜！部署和配置完成，尽情享受便捷的无密码一站式认证吧！

参考链接

本文来源： 青江的个人站
本文链接： https://hanqingjiang.com/2026/03/24/20260324_selfhostedPocketIdTinyauth/
版权声明： 本作品采用 CC BY-NC-SA 4.0 进行许可。转载请注明出处！
知识共享许可协议
赏

谢谢你请我喝可乐~

支付宝
微信

扫一扫，分享到微信

微信分享二维码

tag: