跳到主要内容

部署与配置

在上一篇文章中，我们介绍了快速开始使用 Logto 的基础知识。本文将深入探讨，重点介绍在生产环境中部署 Logto 的最佳实践和详细配置步骤。

环境变量​

我们在演示中（docker-compose.yml）使用了生成的环境变量预设，你应该用你自己的变量替换，并在多个 Logto 实例之间保持一致性。

你可以直接设置环境变量，或者将 .env 文件放在 Logto 项目的根目录下。如果你在使用 Docker 进行测试，请查看镜像在 /etc/logto 生成的 .env 文件。

基本项​

  • DB_URL Logto 数据库的 Postgres DSN。
  • PORT Logto 监听的端口。默认 3001。
  • ENDPOINT 你可以为生产环境指定带有自定义域名的 URL（例如：ENDPOINT=https://logto.domain.com）。这也会影响 OIDC 发行者 (Issuer) 标识符 的值。

启用管理控制台

  • ADMIN_PORT Logto 管理控制台监听的端口。默认 3002。
  • ADMIN_ENDPOINT 你可以为生产环境指定带有自定义域名的 URL（例如：ADMIN_ENDPOINT=https://admin.domain.com）。这也会影响管理控制台重定向 URI 的值。

禁用管理控制台

  • ADMIN_DISABLE_LOCALHOST 设置为 1 或 true 可关闭管理控制台端口。如果未设置 ADMIN_ENDPOINT，则会完全禁用管理控制台。

有关环境变量的更多详情，请参阅 配置。

启用 Secret Vault

  • 若要使用 Secret Vault，你需要将 SECRET_VAULT_KEK 设置为你的密钥加密密钥（KEK）的 base64 编码字符串。该密钥用于加密 Secret Vault 中的数据加密密钥（DEK）。推荐使用 AES-256（32 字节）。示例：crypto.randomBytes(32).toString('base64')。

HTTPS​

你可以直接使用 Node.js 提供 HTTPS 服务，或在 Node.js 前面设置 HTTPS 代理 / 负载均衡器。详情见 启用 HTTPS。

反向代理​

如果你想在服务器上使用反向代理，例如 Nginx 或 Apache，你需要在代理转发设置中分别映射 3001 和 3002 端口。假设你使用 Nginx，Logto 认证 (Authentication) 端点运行在 3001 端口，Logto 管理控制台运行在 3002 端口，请在 nginx.conf 中加入如下配置：

server {
  listen 443 ssl;
  server_name <your_endpoint_url>; // 例如 auth.your-domain.com
  ...

  location / {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;

    proxy_pass http://127.0.0.1:3001;
  }

  ssl_certificate <path-to-your-certificate-for-auth-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-auth-endpoint>
  ...
}

然后为你的管理控制台添加类似的配置：

server {
  listen 443 ssl;
  server_name <your_admin_endpoint_url>; // 例如 admin.your-domain.com
  ...

  location / {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;

    proxy_pass http://127.0.0.1:3002;
  }

  ssl_certificate <path-to-your-certificate-for-admin-endpoint>;
  ssl_certificate_key <path-to-your-certificate-key-for-admin-endpoint>
  ...
}

重新加载 Nginx 配置以应用最新更改：

nginx -s reload

一切就绪。打开浏览器访问 https://admin.your-domain.com，你应该可以看到 Logto 欢迎页面。

容器化​

在生产环境中，你可以使用 Docker 对 Logto 进行容器化。你可以在项目根目录找到 Dockerfile。如果你想运行多个 Logto 实例，例如在 Kubernetes 集群中部署 Logto，还需要额外的步骤。

共享连接器 (Connectors) 文件夹​

默认情况下，Logto 会在 core 文件夹的根目录下创建一个 connectors 文件夹。我们建议在多个 Logto 实例之间共享该文件夹，你需要将 packages/core/connectors 文件夹挂载到容器，并运行 npm run cli connector add -- --official 来部署连接器 (Connectors)。

以下是 Kubernetes 的最小示例 deployment：

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: logto
  namespace: default
spec:
  template:
    spec:
      volumes:
        - name: connectors
          emptyDir: {}
      initContainers:
        - image: ghcr.io/logto-io/logto
          command:
            - /bin/sh
          args:
            - '-c'
            - 'npm run cli connector add -- --official'
          name: init
          volumeMounts:
            - name: connectors
              mountPath: /etc/logto/packages/core/connectors
      containers:
        - image: ghcr.io/logto-io/logto
          name: logto
          volumeMounts:
            - name: connectors
              mountPath: /etc/logto/packages/core/connectors

在此示例中，我们创建了一个空目录作为卷并挂载到容器。然后在 init 容器中运行 npm run cli connector add -- --official 下载连接器 (Connectors)。最后，每个容器都将共享同一个包含官方连接器 (Connectors) 的文件夹。

备注:

这是一个示例 yaml，实际运行 Logto 时需要正确设置环境变量。

在生产环境中，你可以将 "empty dir" 卷替换为持久卷，并用你自己的方式完成 "init" 操作，你知道你在做什么！

数据库变更​

与连接器 (Connectors) 类似，数据库变更需要在单个实例中运行。你可以使用 job 来运行变更脚本。

当以非交互方式运行变更时，必须设置 CI=true 环境变量。

apiVersion: batch/v1
kind: Job
metadata:
  name: alteration
spec:
  template:
    spec:
      containers:
        - name: alteration
          image: ghcr.io/logto-io/logto
          imagePullPolicy: Always
          env:
            - name: CI
              value: 'true'
            - name: DB_URL
              value: postgresql://user:password@localhost:5432/logto
          command:
            - /bin/sh
          args:
            - '-c'
            - 'npm run alteration deploy latest'
      restartPolicy: Never

关于变更命令的详细信息，请参阅 数据库变更。