warning

本教程由社区贡献，不属于 Open WebUI 官方团队的支持范围。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要贡献吗？请查看贡献教程。

使用 Nginx 配置 HTTPS

确保用户与 Open WebUI 之间的通信安全至关重要。HTTPS（超文本传输安全协议）对传输的数据进行加密，防止被窃听和篡改。通过将 Nginx 配置为反向代理，您可以无缝地为 Open WebUI 部署添加 HTTPS，从而提高安全性和可信度。

本指南提供了三种设置 HTTPS 的方法：

自签名证书 (Self-Signed Certificates)：适用于开发和内部使用，使用 Docker。
Let's Encrypt：适用于需要受信任 SSL 证书的生产环境，使用 Docker。
Windows + 自签名证书：适用于 Windows 上的开发和内部使用，无需 Docker。

关键：为 WebSocket 连接配置 CORS

WebSocket 连接中一个非常常见且难以调试的问题是跨源资源共享 (CORS) 策略配置不当。当在 Nginx Proxy Manager 等反向代理后面运行 Open WebUI 时，您必须在 Open WebUI 配置中设置 CORS_ALLOW_ORIGIN 环境变量。

如果不这样做，即使您在 Nginx Proxy Manager 中启用了 "Websockets support"，WebSocket 连接也会失败。

选择最适合您部署需求的方法。

Nginx Proxy Manager
Let's Encrypt
自签名证书
Windows

Nginx Proxy Manager

Nginx Proxy Manager (NPM) 允许您轻松管理反向代理，并使用来自 Let's Encrypt 的有效 SSL 证书保护您的本地应用程序（如 Open WebUI）。此设置可实现 HTTPS 访问，这对于许多移动浏览器由于安全要求而使用语音输入功能是必需的，且无需将应用程序的特定端口直接暴露给互联网。

先决条件

一台运行 Docker 且 open-webui 容器正在运行的家用服务器。
一个域名（免费选项如 DuckDNS，或付费选项如 Namecheap/GoDaddy）。
Docker 和 DNS 配置的基础知识。

Nginx Proxy Manager 步骤

创建 Nginx 文件目录：
```
mkdir ~/nginx_config
cd ~/nginx_config
```
使用 Docker 设置 Nginx Proxy Manager：
```
nano docker-compose.yml
```

services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

运行容器：

docker-compose up -d

配置 DNS 和域名：
- 登录您的域名提供商（例如 DuckDNS）并创建一个域名。
- 将域名指向代理服务器的局域网 IP（例如 192.168.0.6）。
- 如果使用 DuckDNS，请从其仪表板获取 API 令牌。

这里有一个关于在 https://www.duckdns.org/domains 中如何操作的简单示例

设置 SSL 证书：

访问 Nginx Proxy Manager，地址为 http://server_ip:81。例如：192.168.0.6:81
使用默认凭据（admin@example.com / changeme）登录。根据提示更改凭据。
转到 SSL Certificates → Add SSL Certificate → Let's Encrypt。
填写您的电子邮件以及从 DuckDNS 获取的域名。一个域名包含星号，另一个不包含。示例：*.hello.duckdns.org 和 hello.duckdns.org。
选择 Use a DNS challenge，选择 DuckDNS，然后粘贴您的 API 令牌。示例： dns_duckdns_token=f4e2a1b9-c78d-e593-b0d7-67f2e1c9a5b8
同意 Let’s Encrypt 条款并保存。如果需要，可以更改传播时间（120 秒）。

创建代理主机 (Proxy Hosts)：

对于每个服务（例如 openwebui、nextcloud），转到 Hosts → Proxy Hosts → Add Proxy Host。
填写域名（例如 openwebui.hello.duckdns.org）。
将方案 (Scheme) 设置为 HTTP（默认），启用 Websockets support 并指向您的 Docker IP（如果运行 open-webui 的 Docker 与 NGINX 管理器在同一台计算机上运行，则此 IP 将与之前的相同，例如：192.168.0.6）。
选择之前生成的 SSL 证书，启用 Force SSL 和 HTTP/2。

关键：为 WebSocket 连接配置 CORS

如果不这样做，即使您在 Nginx Proxy Manager 中启用了 "Websockets support"，WebSocket 连接也会失败。

缓存最佳实践

虽然 Nginx Proxy Manager 会自动处理大部分配置，但请注意：

静态资源（CSS、JS、图像）默认会被缓存以获得更好的性能。
身份验证端点 绝不应该被缓存。
如果您在 NPM 的 "Advanced" 选项卡中添加自定义缓存规则，请确保排除以下路径：/api/、/auth/、/signup/、/signin/、/sso/、/admin/、/signout/、/oauth/、/login/ 和 /logout/。

默认的 NPM 配置已正确处理此问题 —— 除非您非常清楚自己在做什么，否则请勿修改缓存设置。

示例： 如果您通过 https://openwebui.hello.duckdns.org 访问 UI，您必须设置：

CORS_ALLOW_ORIGIN="https://openwebui.hello.duckdns.org"

Let's Encrypt

Let's Encrypt 提供被大多数浏览器信任的免费 SSL 证书，是保护您的生产环境的理想选择。🔐

本指南采用分两阶段的方法：

第一阶段：临时运行 Nginx 以证明您拥有该域名并从 Let's Encrypt 获取证书。
第二阶段：重新配置 Nginx 以使用新证书建立安全的 HTTPS 连接。

先决条件

一个域名（例如 my-webui.com），并具有指向您服务器公共 IP 地址的 DNS A 记录。
您的服务器上已安装 Docker 和 Docker Compose。
具备在终端中运行命令的基础知识。

info

注意！ Let's Encrypt 无法为 IP 地址颁发证书。您必须使用域名。

第 1 步：证书验证的初始设置

首先，我们将设置必要的文件和临时 Nginx 配置，以便 Let's Encrypt 的服务器验证您的域名。

确保您已完成上述先决条件。
创建目录结构

在您的项目根目录下，运行此命令为 Nginx 配置和 Let's Encrypt 证书创建文件夹：
```
mkdir -p nginx/conf.d ssl/certbot/conf ssl/certbot/www
```

创建临时 Nginx 配置

创建文件 nginx/conf.d/open-webui.conf。此初始配置仅监听 80 端口，并为 Certbot 提供验证文件。

⚠️ 请记住将 <YOUR_DOMAIN_NAME> 替换为您的实际域名。

# nginx/conf.d/open-webui.conf

server {
    listen 80;
    listen [::]:80;
    server_name <YOUR_DOMAIN_NAME>;

    # 用于 Let's Encrypt 验证挑战的路由
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    # 目前将忽略所有其他请求
    location / {
        return 404;
    }
}

更新您的 docker-compose.yml

将 nginx 服务添加到您的 docker-compose.yml 中，并确保您的 open-webui 服务配置为使用共享的 Docker 网络。

services:
  nginx:
    image: nginx:alpine
    restart: always
    ports:
      # 将 HTTP 和 HTTPS 端口暴露给宿主机
      - "80:80"
      - "443:443"
    volumes:
      # 挂载 Nginx 配置和 SSL 证书数据
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./ssl/certbot/conf:/etc/letsencrypt
      - ./ssl/certbot/www:/var/www/certbot
    depends_on:
      - open-webui
    networks:
      - open-webui-network

  open-webui:
    # 您现有的 open-webui 配置...
    # ...
    # 确保它在同一个网络上
    networks:
      - open-webui-network
    # 将端口内部暴露给 Docker 网络。
    # 您不需要将其发布到宿主机（例如，这里不需要 `ports` 部分）。
    expose:
      - 8080

networks:
    open-webui-network:
        driver: bridge

第 2 步：获取 SSL 证书

现在我们将运行一个使用 Docker 获取证书的脚本。

创建证书请求脚本

在项目根目录下创建一个名为 enable_letsencrypt.sh 的可执行脚本。

⚠️ 请记住将 <YOUR_DOMAIN_NAME> 和 <YOUR_EMAIL_ADDRESS> 替换为您的实际信息。

#!/bin/bash
# enable_letsencrypt.sh

DOMAIN="<YOUR_DOMAIN_NAME>"
EMAIL="<YOUR_EMAIL_ADDRESS>"

echo "### 正在为 $DOMAIN 获取 SSL 证书 ###"

# 启动 Nginx 以提供挑战验证
docker compose up -d nginx

# 在容器中运行 Certbot 以获取证书
docker run --rm \
  -v "./ssl/certbot/conf:/etc/letsencrypt" \
  -v "./ssl/certbot/www:/var/www/certbot" \
  certbot/certbot certonly \
  --webroot \
  --webroot-path=/var/www/certbot \
  --email "$EMAIL" \
  --agree-tos \
  --no-eff-email \
  --force-renewal \
  -d "$DOMAIN"

if [[ $? != 0 ]]; then
    echo "错误：获取 SSL 证书失败。"
    docker compose stop nginx
    exit 1
fi

# 在应用最终配置之前停止 Nginx
docker compose stop nginx
echo "### 证书获取成功！ ###"

使脚本可执行
```
chmod +x enable_letsencrypt.sh
```
运行脚本

执行脚本。它将自动启动 Nginx，请求证书，然后停止 Nginx。
```
./enable_letsencrypt.sh
```

重要提示：缓存配置

在使用 Nginx 与 Open WebUI 时，合理的缓存对于性能至关重要，同时要确保身份验证保持安全。以下配置包括：

已缓存：静态资源（CSS、JS、字体、图像）以获得更好的性能。
未缓存：身份验证端点、API 调用、SSO/OAuth 回调和会话数据。
结果：更快的页面加载速度，且不会破坏登录功能。

下面的配置会自动实现这些规则。

第 3 步：完成 HTTPS 的 Nginx 配置

证书保存到 ssl 目录后，您现在可以更新 Nginx 配置以启用 HTTPS。

更新 Nginx 的 SSL 配置

使用下面的最终配置替换 nginx/conf.d/open-webui.conf 的全部内容。

⚠️ 请将所有 4 处 <YOUR_DOMAIN_NAME> 替换为您的域名。

# nginx/conf.d/open-webui.conf

# 将所有 HTTP 流量重定向到 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name <YOUR_DOMAIN_NAME>;

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name <YOUR_DOMAIN_NAME>;

    ssl_certificate /etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers off;

    location ~* ^/(auth|api|oauth|admin|signin|signup|signout|login|logout|sso)/ {
        proxy_pass http://open-webui:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 $scheme;
        proxy_read_timeout 10m;
        proxy_buffering off;
        client_max_body_size 20M;

        proxy_no_cache 1;
        proxy_cache_bypass 1;
        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
        add_header Pragma "no-cache" always;
        expires -1;
    }

    location ~* \.(css|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot)$ {
        proxy_pass http://open-webui:8080;
        proxy_http_version 1.1;
        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 $scheme;

        # 缓存静态资源 7 天
        expires 7d;
        add_header Cache-Control "public, immutable";
    }

    location / {
        proxy_pass http://open-webui:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 $scheme;
        proxy_read_timeout 10m;
        proxy_buffering off;
        client_max_body_size 20M;

        add_header Cache-Control "public, max-age=300, must-revalidate";
    }
}

启动所有服务

使用最终的安全配置同时启动 Nginx 和 Open WebUI。
```
docker compose up -d
```

第 4 步：访问您的安全 WebUI

您现在可以通过 HTTPS 安全地访问您的 Open WebUI 实例了。

➡️ https://<YOUR_DOMAIN_NAME>

(可选) 第 5 步：设置自动续期

Let's Encrypt 证书每 90 天过期一次。您应该设置一个 cron 任务来自动续期。

打开 crontab 编辑器：
```
sudo crontab -e
```

添加以下行，以便每天凌晨 3:30 运行续期检查。只有在证书即将过期时才会进行续期。

30 3 * * * /usr/bin/docker run --rm -v "<absolute_path>/ssl/certbot/conf:/etc/letsencrypt" -v "<absolute_path>/ssl/certbot/www:/var/www/certbot" certbot/certbot renew --quiet --webroot --webroot-path=/var/www/certbot --deploy-hook "/usr/bin/docker compose -f <absolute_path>/docker-compose.yml restart nginx"

自签名证书 (Self-Signed Certificate)

使用自签名证书适用于开发或内部使用，在这些场景下，信任验证不是首要关注点。

自签名证书设置步骤

创建 Nginx 文件目录：
```
mkdir -p conf.d ssl
```

创建 Nginx 配置文件：

conf.d/open-webui.conf：

server {
    listen 443 ssl;
    server_name your_domain_or_IP;

    ssl_certificate /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key /etc/nginx/ssl/nginx.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    location ~* ^/(auth|api|oauth|admin|signin|signup|signout|login|logout|sso)/ {
        proxy_pass http://host.docker.internal:3000;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        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 $scheme;

        proxy_buffering off;
        client_max_body_size 20M;
        proxy_read_timeout 10m;

        # 禁用身份验证端点的缓存
        proxy_no_cache 1;
        proxy_cache_bypass 1;
        add_header Cache-Control "no-store, no-cache, must-revalidate" always;
        expires -1;
    }

    location ~* \.(css|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot)$ {
        proxy_pass http://host.docker.internal:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;

        expires 7d;
        add_header Cache-Control "public, immutable";
    }

    location / {
        proxy_pass http://host.docker.internal:3000;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        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 $scheme;

        proxy_buffering off;

        client_max_body_size 20M;
        proxy_read_timeout 10m;

        add_header Cache-Control "public, max-age=300, must-revalidate";
    }
}

生成自签名 SSL 证书：

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout ssl/nginx.key \
-out ssl/nginx.crt \
-subj "/CN=your_domain_or_IP"

更新 Docker Compose 配置：

将 Nginx 服务添加到您的 docker-compose.yml 中：

services:
  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./conf.d:/etc/nginx/conf.d
      - ./ssl:/etc/nginx/ssl

运行 Docker Compose：
```
docker-compose up -d
```

在 Windows 上不使用 Docker 使用自签名证书和 Nginx

对于基础的内部/开发安装，您可以使用 nginx 和自签名证书将 Open WebUI 代理到 https，从而允许在局域网（LAN）上使用麦克风输入等功能。（默认情况下，大多数浏览器不允许在不安全的非 localhost url 上进行麦克风输入）

本指南假设您使用 pip 安装了 Open WebUI，并且正在运行 open-webui serve

步骤 1：安装 openssl 以生成证书

您首先需要安装 openssl

您可以从 Shining Light Productions (SLP) 网站下载并安装预编译的二进制文件。

或者，如果您安装了 Chocolatey，可以使用它快速安装 OpenSSL：

打开命令提示符或 PowerShell。
运行以下命令安装 OpenSSL：
```
choco install openssl -y
```

验证安装

安装完成后，打开命令提示符并输入：

openssl version

如果显示 OpenSSL 版本（例如 OpenSSL 3.x.x ...），则说明安装正确。

步骤 2：安装 nginx

从 nginx.org 下载官方的 Windows 版 Nginx，或使用 Chocolatey 等包管理器。将下载的 ZIP 文件解压到一个目录（例如 C:\nginx）。

步骤 3：生成证书

运行以下命令：

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout nginx.key -out nginx.crt

将生成的 nginx.key 和 nginx.crt 文件移动到您选择的文件夹中，或移动到 C:\nginx 目录。

步骤 4：配置 nginx

在文本编辑器中打开 C:\nginx\conf\nginx.conf

如果您希望在本地局域网上访问 Open WebUI，请务必使用 ipconfig 记录您的局域网 IP 地址，例如 192.168.1.15

按如下方式进行设置：

#user  nobody;
worker_processes  1;

#error_log  logs/error.log;

#error_log  logs/error.log  notice;

#error_log  logs/error.log  info;

#pid        logs/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  120;

    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    server {
        listen 80;
        server_name 192.168.1.15;

        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl;
        server_name 192.168.1.15;

        ssl_certificate C:\\nginx\\nginx.crt;
        ssl_certificate_key C:\\nginx\\nginx.key;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
        ssl_prefer_server_ciphers on;

        location ~* ^/(auth|api|oauth|admin|signin|signup|signout|login|logout|sso)/ {
            proxy_pass http://localhost:8080;

            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;

            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 $scheme;

            proxy_buffering off;
            client_max_body_size 20M;
            proxy_read_timeout 10m;

            add_header Cache-Control "no-store, no-cache, must-revalidate" always;
            expires -1;
        }

        location ~* \.(css|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot)$ {
            proxy_pass http://localhost:8080;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            
            expires 7d;
            add_header Cache-Control "public, immutable";
        }

        location / {
            proxy_pass http://localhost:8080;

            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;

            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 $scheme;

            proxy_buffering off;
            client_max_body_size 20M;
            proxy_read_timeout 10m;

            add_header Cache-Control "public, max-age=300, must-revalidate";
        }
    }
}

保存文件，并运行 nginx -t 检查配置是否存在错误或语法问题。根据您的安装方式，您可能需要先 cd C:\nginx。

运行 nginx 来启动 nginx。如果 nginx 服务已经启动，您可以运行 nginx -s reload 来重新加载新配置。

您现在应该可以通过 https://192.168.1.15（或您适当的局域网 IP）访问 Open WebUI。请确保根据需要允许 Windows 防火墙访问。

下一步

设置 HTTPS 后，通过以下方式安全访问 Open WebUI：

https://localhost

如果您使用的是域名，请确保您的 DNS 记录已正确配置。对于生产环境，建议使用 Let's Encrypt 以获得受信任的 SSL 证书。

Nginx Proxy Manager​

先决条件​

Nginx Proxy Manager 步骤​

这里有一个关于在 https://www.duckdns.org/domains 中如何操作的简单示例​

Let's Encrypt​

先决条件​

第 1 步：证书验证的初始设置​

第 2 步：获取 SSL 证书​

重要提示：缓存配置​

第 3 步：完成 HTTPS 的 Nginx 配置​

第 4 步：访问您的安全 WebUI​

(可选) 第 5 步：设置自动续期​

自签名证书 (Self-Signed Certificate)​

自签名证书设置步骤​

在 Windows 上不使用 Docker 使用自签名证书和 Nginx​

步骤 1：安装 openssl 以生成证书​

验证安装​

步骤 2：安装 nginx​

步骤 3：生成证书​

步骤 4：配置 nginx​

下一步​

Nginx Proxy Manager

先决条件

Nginx Proxy Manager 步骤

这里有一个关于在 https://www.duckdns.org/domains 中如何操作的简单示例

Let's Encrypt

先决条件

第 1 步：证书验证的初始设置

第 2 步：获取 SSL 证书

重要提示：缓存配置

第 3 步：完成 HTTPS 的 Nginx 配置

第 4 步：访问您的安全 WebUI

(可选) 第 5 步：设置自动续期

自签名证书 (Self-Signed Certificate)

自签名证书设置步骤

在 Windows 上不使用 Docker 使用自签名证书和 Nginx

步骤 1：安装 openssl 以生成证书

验证安装

步骤 2：安装 nginx

步骤 3：生成证书

步骤 4：配置 nginx

下一步