环境变量

核心配置

以业务仓库 .env.example 和所用部署定义为准，环境文件不进入版本控制。

变量	用途与注意事项
DATABASE_URL	数据库连接串；本地运行必须指向已准备好的项目数据库
POSTGRES_PASSWORD	项目 Compose 中 PostgreSQL 服务及连接串使用的密码
JWT_SECRET	至少 32 个字符的随机认证密钥，不能使用可猜测短语
ADMIN_USERNAME	初始管理员登录名，默认 admin
ADMIN_INITIAL_PASSWORD	初始管理员密码，至少 12 个字符；仅用于账号不存在时的初始化
APP_ENV	运行环境标识
REDIS_URL	可选 Redis 连接；使用时采用项目专用凭据

不要把管理员级数据库或 Redis 凭据发给业务应用。多实例部署需要审查共享缓存与会话相关约束，不能简单复制单实例配置。

域名路由

变量	用途
ADMIN_HOSTS	允许作为管理端入口的域名列表
MOBILE_HOSTS	允许作为移动端入口的域名列表
CANONICAL_ADMIN_HOST	管理端规范域名
CANONICAL_MOBILE_HOST	移动端规范域名
COOKIE_DOMAIN	需要跨子域共享会话时使用的 Cookie 域

将这些变量与反向代理、TLS 证书和实际入口同时核对。不要把官网域名填为业务入口，除非确实设计并验证了对应路由。

Cookie 边界

优先采用满足业务需要的最小 Cookie 范围。不要为了省事把 Cookie 域设为包含官网和所有其他项目的共同父域；这可能让会话 Cookie 被发送到不需要接收它的服务。

变更配置后

1. 核对值是否通过实际使用的启动方式传入应用；Compose、进程环境与 .env 文件不是自动等价的。
2. 按发布方案重新创建或重启相关应用实例。
3. 验证管理端、移动端登录与跳转是否正确。
4. 核查日志和健康检查，不输出完整凭据。

更换 JWT 密钥可能影响现有登录会话，安排合适窗口并通知使用者重新登录。

相关：部署指南 · 维护与排障