supertokens/supertokens-mysql

SuperTokens MySQL Docker 镜像文档

镜像概述和主要用途

SuperTokens MySQL Docker 镜像是集成了 MySQL 数据库的 SuperTokens 服务镜像。SuperTokens 是一个开源身份验证解决方案，提供用户登录、会话管理、密码重置、电子邮件验证等核心功能。该镜像专为需要与 MySQL 数据库集成的身份验证服务场景设计，支持灵活配置、日志管理和安全部署。

核心功能和特性

• MySQL 集成：原生支持 MySQL 数据库存储用户数据和会话信息，同时支持内存数据库作为默认回退方案。
• 多方式配置：支持通过环境变量或自定义 config.yaml 文件配置服务参数，满足不同部署需求。
• 日志管理：默认日志输出至 Docker 日志系统，支持配置日志文件路径并挂载至共享卷。
• 安全部署：支持只读根文件系统（Read-only root fs），通过临时目录挂载保障运行安全。
• 灵活扩展：支持连接池大小、密码哈希算法（如 Argon2、BCrypt）、IP 访问控制等高级配置。

使用场景和适用范围

• 需要集成 MySQL 数据库的身份验证服务（如用户注册、登录、会话管理）。
• 需自定义身份验证流程（如密码策略、TOTP 双因素认证、无密码登录）的应用。
• 对安全性有要求的生产环境（如只读文件系统、IP 访问限制）。
• 需要可配置日志和监控的企业级应用。

详细的使用方法和配置说明

快速启动

默认情况下，未指定 MySQL 连接参数时，镜像将使用内存数据库运行。启动命令如下：

bash
# 使用内存数据库启动 SuperTokens
docker run -p 3567:3567 -d registry.supertokens.io/supertokens/supertokens-mysql

配置方式

支持通过环境变量或自定义 config.yaml 文件配置服务。若同时指定两种方式，仅 config.yaml 文件会生效。

使用环境变量配置

通过 -e 参数传递环境变量，支持 Core（核心服务）和 MySQL（数据库）两类参数。

Core 核心配置参数

MySQL 数据库配置参数

环境变量配置示例：
通过环境变量连接 MySQL 数据库：

bash
docker run \
  -p 3567:3567 \
  -e MYSQL_CONNECTION_URI="mysql://user:password@mysql-host:3306/supertokens_db" \
  -e ACCESS_TOKEN_VALIDITY=7200 \
  -e LOG_LEVEL="warn" \
  -d registry.supertokens.io/supertokens/supertokens-mysql

若未提供 MYSQL_CONNECTION_URI，可通过独立参数配置：

bash
docker run \
  -p 3567:3567 \
  -e MYSQL_USER="admin" \
  -e MYSQL_PASSWORD="secure-pass" \
  -e MYSQL_HOST="192.168.1.100" \
  -e MYSQL_PORT="3306" \
  -d registry.supertokens.io/supertokens/supertokens-mysql

使用自定义配置文件

通过挂载自定义 config.yaml 文件覆盖默认配置。配置文件需包含以下必填项：

yaml
core_config_version: 0
host: "0.0.0.0"
mysql_config_version: 0
info_log_path: null  # 输出至 Docker 日志
error_log_path: null  # 输出至 Docker 日志

自定义配置文件示例：

1. 本地创建 config.yaml：

yaml
core_config_version: 0
host: "0.0.0.0"
port: 3567
access_token_validity: 7200
mysql_config_version: 0
mysql:
  user: "admin"
  password: "secure-pass"
  host: "mysql-host"
  port: 3306
  database_name: "supertokens_db"

2. 挂载配置文件启动容器：

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

日志配置

默认日志

服务日志默认输出至 Docker 日志系统，可通过 docker logs <container-id> 查看：

bash
docker logs <container-id>  # 查看所有日志
docker logs <container-id> --tail 100  # 查看最近 100 行日志

日志文件挂载

若需将日志输出至文件并持久化，需配置日志路径并挂载共享卷：

bash
docker run \
  -p 3567:3567 \
  -v /path/to/host/logs:/home/supertokens/logs \  # 挂载主机日志目录
  -e INFO_LOG_PATH="/home/supertokens/logs/info.log" \  # 信息日志路径
  -e ERROR_LOG_PATH="/home/supertokens/logs/error.log" \  # 错误日志路径
  -e MYSQL_USER="admin" \
  -e MYSQL_PASSWORD="secure-pass" \
  -d registry.supertokens.io/supertokens/supertokens-mysql

数据库设置

前置要求

启动容器前，需确保 MySQL 数据库已初始化（无需提前创建表，SuperTokens 会自动初始化表结构）。

连接等待机制

若 MySQL 服务未就绪，SuperTokens 会在启动时等待约 1 小时，直至数据库可用，无需手动协调容器启动顺序。

内存数据库回退

若未配置 MYSQL_CONNECTION_URI、MYSQL_USER 和 MYSQL_PASSWORD，服务将自动使用内存数据库（仅适用于开发环境，生产环境需使用 MySQL）。

只读根文件系统支持

为增强安全性，可通过只读根文件系统运行容器。需挂载临时目录 /lib/supertokens/temp/ 用于服务运行时写入临时文件。

方式 1：绑定主机目录

bash
docker run \
  -p 3567:3567 \
  --mount source=/path/to/host/temp,destination=/lib/supertokens/temp/,type=bind \  # 挂载主机临时目录
  --read-only \  # 启用只读根文件系统
  -e MYSQL_CONNECTION_URI="mysql://user:password@mysql-host:3306/db" \
  -d registry.supertokens.io/supertokens/supertokens-mysql

方式 2：使用 tmpfs 临时文件系统

bash
docker run \
  -p 3567:3567 \
  --tmpfs=/lib/supertokens/temp/:exec \  # 挂载 tmpfs 临时目录（带执行权限）
  --read-only \
  -e MYSQL_CONNECTION_URI="mysql://user:password@mysql-host:3306/db" \
  -d registry.supertokens.io/supertokens/supertokens-mysql

Docker Compose 部署示例

以下是 SuperTokens 与 MySQL 数据库的 Docker Compose 配置示例，适用于本地开发或测试环境：

yaml
version: '3.8'

services:
  mysql:
    image: docker.xuanyuan.run/mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: "root-pass"
      MYSQL_DATABASE: "supertokens_db"
      MYSQL_USER: "supertokens_user"
      MYSQL_PASSWORD: "supertokens-pass"
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql  # 持久化 MySQL 数据

  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-mysql
    depends_on:
      - mysql
    ports:
      - "3567:3567"
    environment:
      MYSQL_HOST: "mysql"
      MYSQL_PORT: "3306"
      MYSQL_USER: "supertokens_user"
      MYSQL_PASSWORD: "supertokens-pass"
      MYSQL_DATABASE_NAME: "supertokens_db"
      ACCESS_TOKEN_VALIDITY: 7200
      LOG_LEVEL: "info"
    volumes:
      - ./logs:/home/supertokens/logs  # 挂载日志目录
    restart: unless-stopped

volumes:
  mysql-data:  # MySQL 数据卷

启动命令：

bash
docker-compose up -d