为 Supabase Studio 添加 Nginx HTTP Basic Auth 认证

概述

Supabase 本地开发环境的 Studio 默认不需要登录，这在本地开发时很方便，但如果需要在局域网或远程环境中使用，就需要添加访问控制。本文介绍如何使用 Nginx 反向代理为 Supabase Studio 添加 HTTP Basic Auth 认证。

环境要求

macOS 系统（本文基于 macOS，其他系统类似）
已安装 Nginx（通过 Homebrew 安装）
已安装 Supabase CLI 并配置本地开发环境
htpasswd 工具（macOS 自带）

实现原理

通过 Nginx 反向代理，在访问 Supabase Studio 之前添加 HTTP Basic Auth 认证层：

用户浏览器 → Nginx (8888端口) → HTTP Basic Auth → Supabase Studio (54323端口)

配置步骤

1. 检查 Nginx 是否已安装

which nginx
输出: /opt/homebrew/bin/nginx

如果未安装，使用 Homebrew 安装：

brew install nginx

2. 创建密码文件

使用 htpasswd 工具创建密码文件。注意：必须使用 -b 参数直接在命令行中指定密码，避免交互式输入导致的问题。

创建密码文件（-c 表示创建新文件，-b 表示从命令行读取密码）
htpasswd -cb /Users/你的用户名/soft/supabase/.htpasswd admin your_secure_password

验证密码是否正确：

printf "your_secure_password" | htpasswd -vi /Users/你的用户名/soft/supabase/.htpasswd admin
输出: Password for user admin correct.

重要提示： 如果密码包含特殊字符（如 !），建议使用简单密码或确保正确转义。

3. 创建 Nginx 配置文件

在 Nginx 的 servers 目录下创建配置文件：

配置文件路径
/opt/homebrew/etc/nginx/servers/supabase-studio-auth.conf

配置文件内容：

server {
    listen 8888;
    server_name localhost;
    location / {
        auth_basic "Supabase Studio";
        auth_basic_user_file /Users/你的用户名/soft/supabase/.htpasswd;
        proxy_pass http://127.0.0.1:54323;
        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;
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

配置说明：

listen 8888: Nginx 监听的端口（避免与其他服务冲突）
auth_basic: 认证提示信息
auth_basic_user_file: 密码文件路径（必须使用绝对路径）
proxy_pass: 代理到 Supabase Studio 的实际端口
WebSocket 支持：确保 Studio 的实时功能正常工作

4. 测试并重载 Nginx 配置

测试配置文件语法：

nginx -t
输出:
nginx: the configuration file /opt/homebrew/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /opt/homebrew/etc/nginx/nginx.conf test is successful

重新加载 Nginx 配置：

nginx -s reload

如果 Nginx 未启动，先启动它：

nginx

5. 验证配置

检查 Nginx 是否在监听 8888 端口：

lsof -i :8888
输出:
COMMAND   PID      USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
nginx     756 your_user   10u  IPv4 0x...      0t0  TCP *:ddi-tcp-1 (LISTEN)

使用方法

启动 Supabase

cd /Users/你的用户名/soft/supabase
supabase start

访问 Studio

在浏览器中访问：http://localhost:8888
浏览器会弹出登录框
输入用户名：admin
输入密码：your_secure_password（你在创建密码文件时设置的密码）
登录成功后即可使用 Supabase Studio

远程访问（可选）

如果需要从局域网其他设备访问，使用服务器的 IP 地址：

http://你的服务器IP:8888

用户管理

添加新用户

添加新用户（不使用 -c 参数，避免覆盖现有文件）
htpasswd -b /Users/你的用户名/soft/supabase/.htpasswd 新用户名 新密码
重新加载 Nginx
nginx -s reload

修改密码

修改现有用户密码
htpasswd -b /Users/你的用户名/soft/supabase/.htpasswd admin 新密码
重新加载 Nginx
nginx -s reload

删除用户

删除用户
htpasswd -D /Users/你的用户名/soft/supabase/.htpasswd 用户名
重新加载 Nginx
nginx -s reload

常见问题

1. 密码验证失败

症状： 输入正确的密码仍然无法登录，Nginx 错误日志显示 "password mismatch" 原因： 密码文件创建时使用了错误的方法，或密码中的特殊字符未正确处理 解决方法：

删除旧的密码文件
rm -f /Users/你的用户名/soft/supabase/.htpasswd
使用 -b 参数重新创建
htpasswd -cb /Users/你的用户名/soft/supabase/.htpasswd admin your_secure_password
验证密码
printf "your_secure_password" | htpasswd -vi /Users/你的用户名/soft/supabase/.htpasswd admin
重新加载 Nginx
nginx -s reload

2. 端口冲突

症状： Nginx 启动失败，提示 "Address already in use" 解决方法： 修改配置文件中的 listen 端口为其他未使用的端口

3. 查看 Nginx 日志

错误日志
tail -f /opt/homebrew/var/log/nginx/error.log
访问日志
tail -f /opt/homebrew/var/log/nginx/access.log

4. Nginx 管理命令

测试配置
nginx -t
启动 Nginx
nginx
重新加载配置
nginx -s reload
停止 Nginx
nginx -s stop
查看 Nginx 进程
ps aux | grep nginx

安全建议

使用强密码： 避免使用简单密码，建议使用包含大小写字母、数字和特殊字符的复杂密码（至少12位）
定期更换密码： 定期修改访问密码
限制访问 IP： 如果只需要特定 IP 访问，可以在 Nginx 配置中添加 IP 白名单
使用 HTTPS： 生产环境建议配置 SSL 证书，使用 HTTPS 加密传输
防火墙规则： 配置防火墙只允许必要的端口访问

IP 白名单配置（可选）

如果需要限制只有特定 IP 可以访问，可以在 Nginx 配置中添加：

server {
    listen 8888;
    server_name localhost;
    # 只允许特定 IP 访问
    allow 192.168.1.100;
    allow 192.168.1.0/24;
    deny all;
    location / {
        auth_basic "Supabase Studio";
        auth_basic_user_file /Users/你的用户名/soft/supabase/.htpasswd;
        proxy_pass http://127.0.0.1:54323;
        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_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

总结

通过 Nginx 反向代理和 HTTP Basic Auth，我们为 Supabase Studio 添加了简单有效的访问控制。这种方法的优点是：

配置简单，易于维护
不需要修改 Supabase 本身的配置
支持多用户管理
可以轻松扩展（如添加 IP 白名单、SSL 等）

适用于本地开发、团队协作或小规模部署场景。对于生产环境，建议使用 Supabase 的云服务或自托管版本，它们提供了更完善的认证和权限管理功能。

参考资料

[Nginx 官方文档](http://nginx.org/en/docs/)
[Supabase 本地开发文档](https://supabase.com/docs/guides/local-development)
[Apache htpasswd 文档](https://httpd.apache.org/docs/current/programs/htpasswd.html)