supertokens/supertokens-postgresql

SuperTokens PostgreSQL Docker镜像文档

镜像概述

本镜像为SuperTokens身份验证服务的Docker部署版本，集成PostgreSQL数据库支持，用于快速部署安全可靠的用户身份验证和管理系统。支持通过环境变量或自定义配置文件进行灵活配置，适用于各类需要用户认证功能的应用场景。

核心功能与特性

• 支持PostgreSQL数据库存储用户认证数据，同时提供内存数据库作为默认选项
• 丰富的核心配置项：API密钥管理、令牌有效期设置、密码哈希算法配置等
• 完整的PostgreSQL连接参数：支持连接URI、用户名/密码、连接池大小等配置
• 灵活的日志管理：支持日志路径自定义及容器日志集成
• 支持只读根文件系统部署，增强安全性
• 自动等待PostgreSQL服务可用（最长等待约1小时）

使用场景

适用于需要集成用户认证系统的Web应用、移动应用后端、API服务等场景，尤其适合需要PostgreSQL数据库支持的生产环境部署。

快速启动

使用内存数据库快速启动容器：

bash
docker run -p 3567:3567 -d registry.supertokens.io/supertokens/supertokens-postgresql

配置说明

环境变量配置

可通过环境变量配置服务参数，优先级低于自定义配置文件。

核心配置项

• API_KEYS: API密钥，用于服务间通信认证
• SUPERTOKENS_HOST: 服务绑定主机地址
• SUPERTOKENS_PORT: 服务监听端口（默认3567）
• ACCESS_TOKEN_VALIDITY: 访问令牌有效期
• ACCESS_TOKEN_BLACKLISTING: 是否启用访问令牌黑名单
• ACCESS_TOKEN_SIGNING_KEY_DYNAMIC: 是否启用动态签名密钥
• REFRESH_TOKEN_VALIDITY: 刷新令牌有效期
• PASSWORD_RESET_TOKEN_LIFETIME: 密码重置令牌有效期
• EMAIL_VERIFICATION_TOKEN_LIFETIME: ***验证令牌有效期
• INFO_LOG_PATH: 信息日志路径
• ERROR_LOG_PATH: 错误日志路径
• MAX_SERVER_POOL_SIZE: 服务器连接池最大大小
• PASSWORDLESS_MAX_CODE_INPUT_ATTEMPTS: 无密码登录验证码最大尝试次数
• PASSWORDLESS_CODE_LIFETIME: 无密码登录验证码有效期
• DISABLE_TELEMETRY: 是否禁用遥测
• BASE_PATH: API基础路径
• PASSWORD_HASHING_ALG: 密码哈希算法
• ARGON2_ITERATIONS: Argon2迭代次数
• ARGON2_MEMORY_KB: Argon2内存使用量（KB）
• ARGON2_PARALLELISM: Argon2并行度
• ARGON2_HASHING_POOL_SIZE: Argon2哈希池大小
• BCRYPT_LOG_ROUNDS: Bcrypt日志轮数
• LOG_LEVEL: 日志级别
• FIREBASE_PASSWORD_HASHING_POOL_SIZE: Firebase密码哈希池大小
• FIREBASE_PASSWORD_HASHING_SIGNER_KEY: Firebase密码哈希签名密钥
• IP_ALLOW_REGEX: 允许访问的IP正则表达式
• IP_DENY_REGEX: 拒绝访问的IP正则表达式
• TOTP_MAX_ATTEMPTS: TOTP最大尝试次数
• TOTP_RATE_LIMIT_COOLDOWN_SEC: TOTP速率限制冷却时间（秒）
• SUPERTOKENS_SAAS_LOAD_ONLY_CUD: 是否仅加载CUD操作（SaaS环境）
• OAUTH_PROVIDER_PUBLIC_SERVICE_URL: OAuth提供商公共服务URL
• OAUTH_PROVIDER_ADMIN_SERVICE_URL: OAuth提供商管理服务URL
• OAUTH_PROVIDER_CONSENT_LOGIN_BASE_URL: OAuth提供商 consent登录基础URL
• OAUTH_PROVIDER_URL_CONFIGURED_IN_OAUTH_PROVIDER: OAuth提供商配置的URL
• OAUTH_CLIENT_SECRET_ENCRYPTION_KEY: OAuth客户端密钥加密密钥
• BULK_MIGRATION_PARALLELISM: 批量迁移并行度

PostgreSQL配置项

• POSTGRESQL_CONNECTION_URI: PostgreSQL连接URI
• POSTGRESQL_USER: PostgreSQL用户名
• POSTGRESQL_PASSWORD: PostgreSQL密码
• POSTGRESQL_PASSWORD_FILE: 存储PostgreSQL密码的文件路径
• POSTGRESQL_CONNECTION_POOL_SIZE: PostgreSQL连接池大小
• POSTGRESQL_HOST: PostgreSQL主机地址
• POSTGRESQL_PORT: PostgreSQL端口
• POSTGRESQL_DATABASE_NAME: PostgreSQL数据库名
• POSTGRESQL_TABLE_NAMES_PREFIX: PostgreSQL表名前缀
• POSTGRESQL_TABLE_SCHEMA: PostgreSQL表模式
• POSTGRESQL_IDLE_CONNECTION_TIMEOUT: PostgreSQL空闲连接超时时间
• POSTGRESQL_MINIMUM_IDLE_CONNECTIONS: PostgreSQL最小空闲连接数

环境变量配置示例:

bash
docker run \
    -p 3567:3567 \
    -e POSTGRESQL_CONNECTION_URI="postgresql://username:password@host:port/dbName" \
    -d registry.supertokens.io/supertokens/supertokens-postgresql

或

bash
docker run \
    -p 3567:3567 \
    -e POSTGRESQL_USER="postgresqlUser" \
    -e POSTGRESQL_HOST="192.168.1.2" \
    -e POSTGRESQL_PORT="5432" \
    -e POSTGRESQL_PASSWORD="password" \
    -d registry.supertokens.io/supertokens/supertokens-postgresql

自定义配置文件

通过挂载自定义config.yaml文件进行配置（优先级高于环境变量）。

config.yaml必需键值:

• core_config_version: 0
• host: "0.0.0.0"
• postgresql_config_version: 0
• info_log_path: null（日志输出到容器日志）
• error_log_path: null（日志输出到容器日志）

挂载配置文件示例:

bash
docker run \
    -p 3567:3567 \
    -v /path/to/config.yaml:/usr/lib/supertokens/config.yaml \
    -d registry.supertokens.io/supertokens/supertokens-postgresql

日志管理

• 默认日志通过docker logs <container-name>命令查看
• 可配置日志路径到共享卷，示例如下：

bash
docker run \
    -p 3567:3567 \
    -v /path/to/logsFolder:/home/logsFolder \
    -e INFO_LOG_PATH="/home/logsFolder/info.log" \
    -e ERROR_LOG_PATH="/home/logsFolder/error.log" \
    -e POSTGRESQL_USER="postgresqlUser" \
    -e POSTGRESQL_PASSWORD="password" \
    -d registry.supertokens.io/supertokens/supertokens-postgresql

数据库设置

• 启动容器前需初始化PostgreSQL数据库
• 容器启动时会等待PostgreSQL服务可用，最长等待约1小时
• 未提供PostgreSQL连接信息（如POSTGRESQL_USER、POSTGRESQL_PASSWORD等）时，自动使用内存数据库

只读根文件系统配置

如需以只读根文件系统运行容器，需挂载临时目录：

方法1：挂载主机目录

bash
docker run \
    -p 3567:3567 \
    --mount source=/path/on/host/machine,destination=/lib/supertokens/temp/,type=bind \
    --read-only \
    -d registry.supertokens.io/supertokens/supertokens-postgresql

方法2：使用tmpfs

bash
docker run \
    -p 3567:3567 \
    --tmpfs=/lib/supertokens/temp/:exec \
    --read-only \
    -d registry.supertokens.io/supertokens/supertokens-postgresql