Skip to main content

环境变量说明

羽忆的环境变量不只是“把服务跑起来”的参数，其中有一部分直接决定了认证、安全、检索和 Judge 的行为边界。部署时优先确认下面这几组配置。

管理员初始化​

MEMORY_BOOTSTRAP_ADMIN_USERNAME=admin
MEMORY_BOOTSTRAP_ADMIN_PASSWORD=change-me-now

这组配置只在数据库里还没有任何用户时生效，用于初始化首个管理员账号。

浏览器来源与跨域​

MEMORY_CORS_ALLOWED_ORIGIN_PATTERNS=http://localhost:3000,https://memory.example.com

本地前后端分离开发或分域部署时，需要显式配置允许的浏览器来源，避免浏览器工作台无法正常访问管理接口。

Token 默认配置​

memory.security.token-expire-days=90

它影响控制台创建 API Token 时的默认有效期，是接入层长期访问能力的基础参数之一。

Embedding Provider 主密钥与默认配置​

MEMORY_EMBEDDING_MASTER_KEY=replace-with-strong-key
memory.embedding.base-url=https://...
memory.embedding.api-key=...
memory.embedding.model=...

要点：

  • 主密钥用于加密保存到数据库中的 provider 密钥
  • 环境变量 provider 是控制台未激活 provider 时的默认兜底
  • 两者都不可用时，系统应退化为纯词法检索

LLM Judge 主密钥与默认配置​

MEMORY_LLM_MASTER_KEY=replace-with-strong-key
memory.llm.base-url=https://...
memory.llm.api-key=...
memory.llm.model=gpt-4o-mini
memory.judge.llm-confidence-threshold=0.7

要点：

  • 控制台保存的 LLM provider 密钥同样需要主密钥保护
  • 低置信、超时、解析失败都应回退到规则兜底
  • 即使未配置 LLM，写入链路也不应不可用

开发模式相关​

memory.dev.mode-enabled=true

只建议在开发环境开启。生产环境应避免保留任何便捷但会弱化安全边界的开发态开关。

部署时的最小检查清单​

  • 管理员初始化账号已设置
  • 数据库连接与密码已配置
  • CORS 来源符合实际访问域名
  • Embedding / LLM 主密钥是否需要开启已明确
  • 生产环境是否启用 HTTPS 已明确

环境变量文档单独成页的目的，是帮助部署者先把“决定系统行为边界的配置”理清楚，而不是在 .env.example 里盲填一大串参数。