Hasura Backend Plus环境变量配置指南：从基础到高级的完整清单
Hasura Backend Plus环境变量配置指南：从基础到高级的完整清单
【免费下载链接】hasura-backend-plus🔑Auth and 📦Storage for Hasura. The quickest way to get Auth and Storage working for your next app based on Hasura.项目地址: https://gitcode.com/gh_mirrors/ha/hasura-backend-plus
Hasura Backend Plus是为Hasura提供身份验证和存储功能的快速解决方案，通过环境变量配置可以灵活定制其行为。本文将详细介绍从基础到高级的环境变量设置方法，帮助新手和普通用户轻松完成配置。
快速开始：基础环境变量设置
核心配置项
Hasura Backend Plus的基础运行依赖以下核心环境变量，建议在部署前优先配置：
PORT：服务器端口，默认值为Express.js的默认端口HOST：服务器主机地址，详细配置可参考Express文档HASURA_ENDPOINT：Hasura GraphQL端点地址，必填项HASURA_GRAPHQL_ADMIN_SECRET：Hasura管理员密钥，用于执行管理员操作SERVER_URL：Hasura Backend Plus运行的服务器URL，用于生成邮件模板链接和OAuth回调地址
基础配置示例
PORT=3000 HOST=0.0.0.0 HASURA_ENDPOINT=http://hasura:8080/v1/graphql HASURA_GRAPHQL_ADMIN_SECRET=your-admin-secret SERVER_URL=https://your-domain.com身份验证配置：保护你的应用
用户认证基础设置
身份验证模块的核心环境变量控制用户注册、登录和权限管理：
AUTH_ENABLED：是否启用所有身份验证路由，默认值trueAUTH_LOCAL_USERS_ENABLED：是否允许使用邮箱密码或魔法链接注册登录，默认值trueVERIFY_EMAILS：是否要求用户验证邮箱，默认值falseAUTO_ACTIVATE_NEW_USERS：新用户是否自动激活，默认值true。设为false时需通过邮件验证激活
密码安全设置
增强账户安全性的关键配置：
MIN_PASSWORD_LENGTH：密码最小长度，默认值3，建议生产环境设置为8以上HIBP_ENABLED：是否检查密码是否在Pwned Passwords数据库中，默认值falseLOST_PASSWORD_ENABLED：是否启用密码找回功能，默认值false
角色与权限控制
DEFAULT_USER_ROLE：注册用户的默认角色，默认值userDEFAULT_ANONYMOUS_ROLE：匿名用户的默认角色，默认值anonymousALLOWED_EMAIL_DOMAINS：限制注册邮箱域名，默认允许所有域名。示例：tesla.com,ikea.se
JWT配置：安全的身份验证令牌
JWT设置控制身份验证令牌的生成和验证：
JWT_KEY：JWT签名密钥，建议使用长随机字符串。示例：some-long-random-string-uh8ga7sgd8asgd7asgd89asijduyvtasfd789ujioasdubvtf76a8ys9udiojuauvytdf768audJWT_ALGORITHM：加密算法，可选RS256、HS256等，推荐HS512JWT_EXPIRES_IN：访问令牌过期时间（分钟），默认值15JWT_REFRESH_EXPIRES_IN：刷新令牌过期时间（分钟），默认值43200（30天）JWT_CLAIMS_NAMESPACE：Hasura声明命名空间，默认值https://hasura.io/jwt/claims
自定义JWT字段
通过JWT_CUSTOM_FIELDS可以将用户表中的自定义字段添加到JWT令牌中：
JWT_CUSTOM_FIELDS=company_id,department配置后，JWT将包含这些自定义字段作为Hasura会话变量，如x-hasura-company-id。
存储配置：管理文件上传
存储模块配置控制文件上传和S3集成：
STORAGE_ENABLED：是否启用存储功能，默认值trueS3_BUCKET：S3存储桶名称，必填项S3_ACCESS_KEY_ID：S3访问密钥IDS3_SECRET_ACCESS_KEY：S3密钥S3_ENDPOINT：S3服务端点，适用于兼容S3的存储服务S3_SSL_ENABLED：是否启用SSL连接，默认值true
邮件配置：启用事务性邮件
要启用账户激活、密码重置等邮件功能，需配置SMTP参数：
EMAILS_ENABLED：是否启用邮件功能，默认值falseSMTP_HOST：SMTP服务器主机名SMTP_PORT：SMTP端口，默认值587SMTP_USER：SMTP用户名SMTP_PASS：SMTP密码SMTP_SENDER：发件人邮箱地址SMTP_AUTH_METHOD：认证方式，默认值PLAINSMTP_SECURE：是否使用安全连接，默认值true
OAuth集成：第三方登录配置
Hasura Backend Plus支持多种OAuth提供商，以Google为例：
GOOGLE_ENABLED：是否启用Google登录，默认值falseGOOGLE_CLIENT_ID：Google应用客户端IDGOOGLE_CLIENT_SECRET：Google应用客户端密钥
类似配置适用于GitHub、Facebook、Twitter、LinkedIn等其他提供商，只需将前缀替换为对应提供商名称（如GITHUB_、FACEBOOK_）。
高级配置：安全与性能优化
安全增强
COOKIE_SECRET：用于加密Cookie的密钥COOKIE_SECURE：是否仅通过HTTPS发送CookieCOOKIE_SAME_SITE：Cookie SameSite策略，可选lax、strict或none，默认值laxMFA_ENABLED：是否启用多因素认证，默认值falseOTP_ISSUER：OTP发行者名称，默认值HBP
速率限制
MAX_REQUESTS：时间窗口内的最大请求数，默认值1000TIME_FRAME：时间窗口（毫秒），默认值900000（15分钟）
配置文件管理
推荐使用.env文件管理环境变量，项目中可参考以下文件结构组织配置：
- 开发环境：
docker/dev/.env - 生产环境：
docker/prod/.env
配置变更后需重启服务使设置生效。完整的环境变量列表可参考官方文档docs/docs/environment-variables.md。
常见问题解决
配置不生效
- 确保环境变量名称拼写正确（区分大小写）
- 检查是否使用了正确的文件路径
- 确认服务已重启以应用新配置
邮件发送失败
- 验证SMTP服务器信息是否正确
- 检查防火墙设置是否阻止了SMTP连接
- 尝试禁用
SMTP_SECURE（设为false）测试连接
权限问题
- 检查JWT配置是否正确包含所需的角色信息
- 确认
HASURA_GRAPHQL_ADMIN_SECRET是否正确设置 - 验证
ALLOWED_USER_ROLES是否包含所需角色
通过合理配置这些环境变量，你可以充分发挥Hasura Backend Plus的功能，构建安全、高效的应用后端。如需进一步定制，可参考项目中的配置文件src/shared/config/获取更多细节。
【免费下载链接】hasura-backend-plus🔑Auth and 📦Storage for Hasura. The quickest way to get Auth and Storage working for your next app based on Hasura.项目地址: https://gitcode.com/gh_mirrors/ha/hasura-backend-plus
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考