Mindwendel v0.4.9 配置参数详解
Mindwendel 全部环境变量完整手册：数据库连接（DB_HOST/DB_USER/SSL 等 11 项）、Phoenix Endpoint（SECRET_KEY_BASE/URL_HOST/PORT 等 8 项）、功能开关（清理天数/附件上传/隐私链接）、S3 文件存储（OBJECT_STORAGE_* 7 项）、AI 集成（MW_AI_* 8 项）、libcluster 集群模式，含启动校验速查表和典型配置组合。
MindwendelMindwendelElixirPhoenix2026/10/27
Mindwendel v0.4.9 配置参数详解
目标：完整梳理 Mindwendel 的全部可配置参数（数据库、应用端点、功能开关、文件存储、AI 集成、集群模式），按模块分组说明每个参数的作用、默认值、取值范围、是否必填、修改生效条件与生产建议。覆盖环境变量配置体系与典型配置组合。
一、配置体系总览
Mindwendel 使用 环境变量 作为唯一的运行时配置源，所有参数通过 Elixir 的 System.get_env/2 读取，配置集中在 config/runtime.exs 中。不支持 config 文件热加载，修改后必须重启应用。
配置生效机制
系统环境变量 → Mindwendel.EnvHelper.trimmed_env()
→ config/runtime.exs 中读取
→ 编译进 Elixir Release（运行时只读）
→ 需要重启 /app/bin/mindwendel restart 生效
默认值策略
- 大部分参数有合理默认值（如
DATABASE_PORT=5432、POOL_SIZE=10） - 三个参数必须显式设置，否则启动时 raise：
SECRET_KEY_BASE（Phoenix session 加密）DATABASE_HOST/DATABASE_NAME/DATABASE_USER/DATABASE_USER_PASSWORD（数据库连接）URL_HOST（应用对外访问的主机名）
- 文件附件开启时还必须设置
VAULT_ENCRYPTION_KEY_BASE64和所有OBJECT_STORAGE_*参数
二、数据库连接参数
| 变量名 | 默认值 | 必填 | 说明 | 生产建议 |
|---|---|---|---|---|
DATABASE_HOST | — | ✅ | PostgreSQL 主机名/IP | 远程 DB 用 IP 或域名，同 compose 网络用服务名 db |
DATABASE_PORT | 5432 | ❌ | PostgreSQL 端口 | 默认 5432，远程 DB 用实际端口 |
DATABASE_NAME | — | ✅ | 数据库名 | 如 mindwendel_prod |
DATABASE_USER | — | ✅ | 数据库用户名 | 应用专用账号，只授予 mindwendel_prod 的全部权限 |
DATABASE_USER_PASSWORD | — | ✅ | 数据库用户密码 | 强随机密码，≥ 32 字符 |
DATABASE_SSL | "true" | ❌ | 是否启用 SSL 连接 PostgreSQL | 远程 DB 必须设 "true"（⚠️ YAML 中加引号），同宿主机可 "false" |
DATABASE_CERT_FILE | — | ❌ | 自定义 CA 证书文件路径（SSL 启用时） | 留空则用系统证书 |
DATABASE_URL | — | ❌ | 完整 PostgreSQL URL（覆盖上述单独参数） | 格式 postgres://user:pass@host:port/dbname，不推荐，分散参数更清晰 |
POOL_SIZE | 10 | ❌ | Ecto 连接池大小 | 生产推荐 50；公式 ≈ 2 × LiveView 并发数 + 10 |
DATABASE_TIMEOUT | 15000 | ❌ | 查询超时时间（毫秒） | 高延迟场景可设 30000 |
示例：本地 PostgreSQL（compose 场景）
environment:
DATABASE_HOST: db
DATABASE_PORT: "5432"
DATABASE_NAME: mindwendel_prod
DATABASE_USER: mindwendel
DATABASE_USER_PASSWORD: "q1w2e3r4"
DATABASE_SSL: "false"
POOL_SIZE: "50"
DATABASE_TIMEOUT: "15000"
示例：远程 AWS RDS PostgreSQL（SSL 必需）
environment:
DATABASE_HOST: mindwendel-db.xxx.rds.amazonaws.com
DATABASE_PORT: "5432"
DATABASE_NAME: mindwendel
DATABASE_USER: mindwendel_user
DATABASE_USER_PASSWORD: "<strong-password>"
DATABASE_SSL: "true"
三、Phoenix Endpoint 与 URL 参数
| 变量名 | 默认值 | 必填 | 说明 | 生产建议 |
|---|---|---|---|---|
SECRET_KEY_BASE | — | ✅ | Phoenix session + cookie 加密密钥 | 64 字符随机值，妥善保管，变更会使现有 session 全部失效 |
URL_HOST | — | ✅ | 应用对外访问的主机名（不含协议和端口） | 如 mindwendel.example.com，用于生成 URL |
URL_PORT | 443 | ❌ | 对外 URL 端口 | HTTPS 用 443，HTTP 用 80 或 8080 |
URL_SCHEME | "https" | ❌ | 对外 URL 协议 | 反向代理做 SSL 终止时用 "https"，无反代直接暴露用 "http" |
MW_ENDPOINT_URL_PORT | URL_PORT 同值 | ❌ | Phoenix URL 配置中的端口 | 通常不需要单独设置 |
MW_ENDPOINT_URL_SCHEME | URL_SCHEME 同值 | ❌ | Phoenix URL 配置中的协议 | 通常不需要单独设置 |
MW_ENDPOINT_HTTP_PORT | 4000 | ❌ | Phoenix Cowboy 监听的 HTTP 端口 | 容器化部署时注意端口映射 |
SECRET_KEY_BASE 生成方式
# 方式 1: openssl
openssl rand -base64 48 | tr -d '\n'
# 方式 2: shell /proc
head -c 48 /dev/urandom | base64 -w0
# 方式 3: Elixir release（已安装 Mindwendel 时）
/app/bin/mindwendel eval 'Phoenix.gen.secret()'
典型配置组合
| 场景 | URL_HOST | URL_PORT | URL_SCHEME | MW_ENDPOINT_HTTP_PORT |
|---|---|---|---|---|
| 本地开发（无域名） | localhost | 8134 | http | 4000 |
| 生产反代 Nginx SSL | mindwendel.example.com | 443 | https | 4000 |
| 直接暴露（内网） | 10.0.0.10 | 8080 | http | 4000 |
四、功能开关参数
| 变量名 | 默认值 | 说明 | 生产建议 |
|---|---|---|---|
MW_DEFAULT_LOCALE | "en" | 界面默认语言 | "en" 英文，"de" 德语。暂不支持中文 |
MW_FEATURE_BRAINSTORMING_REMOVAL_AFTER_DAYS | "30" | 头脑风暴自动清理天数 | GDPR 合规设计。设为 "-1" 关闭自动清理（⚠️ 需自行数据备份策略） |
MW_FEATURE_IDEA_FILE_UPLOAD | "true" | 是否启用便签附件上传 | 生产建议先关闭 "false"，确认 S3 存储稳定后再开启 |
MW_FEATURE_LEGAL_PRIVACY_LINKS | "false" | 是否在页脚显示隐私声明/法律链接 | 公共部署建议开启 "true" 并自定义内容 |
MW_FILE_UPLOAD_MAX_FILE_SIZE | "2666666" | 单个附件最大字节数 | 默认约 2.5 MB，可按需调大，但会增加存储压力 |
自动清理 cron 配置
# 清理计划由 Oban Cron Worker 执行，默认 "@midnight"（UTC 时间）
MW_FEATURE_BRAINSTORMING_REMOVAL_CRON="@midnight"
修改 cron 表达式的注意事项：
- Cron 时区跟随系统时区（容器默认 UTC）
- 格式同标准 cron：分 时 日 月 周
- 清理逻辑：找到
updated_at < (now - N days)且无活跃用户连接的头脑风暴 → 删除
五、文件存储参数（附件上传）
当 MW_FEATURE_IDEA_FILE_UPLOAD=true 时，以下参数全部必填。Mindwendel 使用 S3 兼容对象存储后端，附件在上传前用 AES-GCM 加密。
| 变量名 | 默认值 | 必填 | 说明 |
|---|---|---|---|
OBJECT_STORAGE_SCHEME | — | ✅ | 存储协议 |
OBJECT_STORAGE_HOST | — | ✅ | 存储服务主机 |
OBJECT_STORAGE_PORT | — | ✅ | 存储服务端口 |
OBJECT_STORAGE_REGION | — | ✅ | S3 区域 |
OBJECT_STORAGE_BUCKET | — | ❌ | 存储桶名称 |
OBJECT_STORAGE_USER | — | ✅ | 存储访问密钥（Access Key） |
OBJECT_STORAGE_PASSWORD | — | ✅ | 存储秘钥（Secret Key） |
加密密钥参数
| 变量名 | 默认值 | 必填 | 说明 |
|---|---|---|---|
VAULT_ENCRYPTION_KEY_BASE64 | — | ✅（文件上传开启时） | 32 字节密钥的 base64 编码 |
⚠️ 安全红线：
VAULT_ENCRYPTION_KEY_BASE64丢失 = 所有已加密附件永久不可恢复。建议多副本备份（密码管理器 + 加密离线备份）。
对象存储后端选择
| 后端 | 场景 | 优缺点 |
|---|---|---|
| rustfs（compose 内置） | 开发/测试/最小部署 | ✅ 零依赖；❌ 数据卷在 compose 中，容器删除会丢数据 |
| MinIO 自建 | 生产环境 | ✅ 成熟稳定；❌ 需额外维护组件 |
| AWS S3 | 公有云部署 | ✅ 托管式免运维；❌ 有费用，网络延迟 |
六、AI 功能参数
Mindwendel 内置 AI 辅助生成功能（如基于已有想法生成新想法），默认关闭。
| 变量名 | 默认值 | 必填 | 说明 |
|---|---|---|---|
MW_AI_ENABLED | "false" | ❌ | 是否启用 AI 功能 |
MW_AI_API_KEY | — | ✅（AI 开启时） | OpenAI/兼容 API 的密钥 |
MW_AI_API_MODEL | "gpt-4o-mini" | ❌ | 使用的模型名称 |
MW_AI_API_BASE_URL | — | ❌ | OpenAI 兼容 API 的基础 URL |
MW_AI_REQUEST_TIMEOUT | 60000 | ❌ | 单次 AI 请求超时（毫秒） |
MW_AI_TOKEN_LIMIT_DAILY | 1000000 | ❌ | 每日总 token 上限 |
MW_AI_TOKEN_LIMIT_HOURLY | 100000 | ❌ | 每小时 token 上限 |
MW_AI_TOKEN_RESET_HOUR | 0 | ❌ | 每日重置时间（UTC 小时） |
AI 供应商配置模板
# OpenAI 官方
MW_AI_ENABLED: "true"
MW_AI_API_KEY: "${OPENAI_API_KEY}"
MW_AI_API_MODEL: "gpt-4o-mini"
# MW_AI_API_BASE_URL 留空，默认 https://api.openai.com/v1
# DeepSeek / 其他 OpenAI 兼容
MW_AI_ENABLED: "true"
MW_AI_API_KEY: "${DEEPSEEK_API_KEY}"
MW_AI_API_MODEL: "deepseek-chat"
MW_AI_API_BASE_URL: "https://api.deepseek.com/v1"
七、集群模式参数
Mindwendel 支持通过 libcluster 实现多节点集群，主要用于高可用扩展。
| 变量名 | 默认值 | 说明 |
|---|---|---|
MW_ENABLE_LIBCLUSTER | "false" | 是否启用 libcluster 节点发现 |
启用后，配置会自动加载 Kubernetes.DNS 策略：
# runtime.exs 中的配置片段
if System.get_env("MW_ENABLE_LIBCLUSTER") == "true" do
config :libcluster,
topologies: [
k8s_mindwendel: [
strategy: Elixir.Cluster.Strategy.Kubernetes.DNS,
config: [
service: "mindwendel-cluster",
application_name: "mindwendel"
]
]
]
end
💡 技术拓展：BEAM 的集群机制基于 Erlang Distribution——节点间通过 TCP 直接通信（默认 4369 端口 + 动态 EPMD 端口），所有进程可以跨节点调用。libcluster 只是自动化了节点发现。Phoenix LiveView 的 pub/sub 在多节点模式下需要
Phoenix.PubSub.Adapter（如 Redis 适配器）来跨节点广播事件，否则只有同一节点的用户能实时看到更新。Mindwendel 默认使用本地 PubSub Adapter——多节点部署必须评估 pub/sub 跨节点广播方案。
八、日志与运维参数
Mindwendel 在生产环境使用 LoggerJSON 格式化日志，敏感字段自动脱敏。
自动脱敏的字段（runtime.exs 已硬编码）
password, key, token, ERLANG_COOKIE, gcp_credentials,
secret_access_key, access_key_id, api_key, private_key,
private_key_id, service_account, authorization
系统 Elixir 环境变量参考
| 变量 | 说明 |
|---|---|
MIX_ENV | 环境标识，Mindwendel 生产部署固定为 prod |
PHX_SERVER | 是否启动 Phoenix Cowboy 服务器，Release 部署时固定 true |
九、典型配置组合
组合 1：最小验证（本地单机，无附件）
environment:
# DB
DATABASE_HOST: db
DATABASE_NAME: mindwendel_prod
DATABASE_USER: mindwendel
DATABASE_USER_PASSWORD: "minimal123"
DATABASE_SSL: "false"
# Phoenix
SECRET_KEY_BASE: "<64-char-random>"
URL_HOST: localhost
URL_PORT: "8134"
URL_SCHEME: "http"
MW_ENDPOINT_HTTP_PORT: "4000"
# 功能开关
MW_DEFAULT_LOCALE: "en"
MW_FEATURE_IDEA_FILE_UPLOAD: "false"
MW_FEATURE_BRAINSTORMING_REMOVAL_AFTER_DAYS: "30"
MW_AI_ENABLED: "false"
组合 2：生产推荐（HTTPS + 附件 + S3 + GDPR）
environment:
# DB (远程 Postgres)
DATABASE_HOST: pg.example.com
DATABASE_PORT: "5432"
DATABASE_NAME: mindwendel
DATABASE_USER: mw_user
DATABASE_USER_PASSWORD: "<strong-password>"
DATABASE_SSL: "true"
POOL_SIZE: "50"
# Phoenix (反代 + SSL)
SECRET_KEY_BASE: "<64-char-random>"
URL_HOST: mindwendel.example.com
URL_PORT: "443"
URL_SCHEME: "https"
MW_ENDPOINT_HTTP_PORT: "4000"
# 功能
MW_DEFAULT_LOCALE: "en"
MW_FEATURE_BRAINSTORMING_REMOVAL_AFTER_DAYS: "90"
MW_FEATURE_LEGAL_PRIVACY_LINKS: "true"
# 文件上传 (MinIO)
MW_FEATURE_IDEA_FILE_UPLOAD: "true"
OBJECT_STORAGE_SCHEME: "https://"
OBJECT_STORAGE_HOST: minio.example.com
OBJECT_STORAGE_PORT: "9000"
OBJECT_STORAGE_REGION: "us-east-1"
OBJECT_STORAGE_BUCKET: mindwendel-prod
OBJECT_STORAGE_USER: "${MINIO_ACCESS_KEY}"
OBJECT_STORAGE_PASSWORD: "${MINIO_SECRET_KEY}"
VAULT_ENCRYPTION_KEY_BASE64: "<32-byte-base64>"
# AI (谨慎开启)
MW_AI_ENABLED: "true"
MW_AI_API_KEY: "${AI_API_KEY}"
MW_AI_API_MODEL: "gpt-4o-mini"
MW_AI_TOKEN_LIMIT_DAILY: "100000"
MW_AI_TOKEN_LIMIT_HOURLY: "10000"
十、参数校验速查表
启动时以下校验不通过会立即 raise 或打 warning：
| 校验项 | 级别 | 触发条件 |
|---|---|---|
SECRET_KEY_BASE 缺失 | 🔴 raise | 生产环境未设置 |
URL_HOST / HOST 缺失 | 🔴 raise | 生产环境未设置 |
DATABASE_HOST 缺失 | 🟡 warning | 生产环境未设置（不会 raise） |
DATABASE_NAME 缺失 | 🟡 warning | 生产环境未设置 |
DATABASE_USER 缺失 | 🟡 warning | 生产环境未设置 |
DATABASE_USER_PASSWORD 缺失 | 🟡 warning | 生产环境未设置 |
AI 开启但 MW_AI_API_KEY 缺失 | 🔴 raise | MW_AI_ENABLED=true 时 |
AI 兼容模式开启但 MW_AI_API_BASE_URL 缺失 | 🔴 raise | 设置了自定义 base URL 但缺 endpoint |
| 文件上传开启但存储参数缺失 | 🔴 raise | runtime.exs 中 System.fetch_env! 会抛 KeyError |
VAULT_ENCRYPTION_KEY_BASE64 无效 base64 | 🔴 raise | Base.decode64! 解码失败 |
十一、配置变更后的影响
| 参数变更 | 影响范围 | 生效方式 |
|---|---|---|
DATABASE_HOST / DATABASE_USER_* | 数据库连接 | 重启服务。迁移不会自动执行 |
SECRET_KEY_BASE | 所有用户 session | 重启服务。⚠️ 所有现有登录 session 失效 |
POOL_SIZE | 数据库连接数 | 重启服务 |
MW_FEATURE_BRAINSTORMING_REMOVAL_AFTER_DAYS | 清理 Worker | 重启服务生效 |
MW_AI_ENABLED | AI 功能 | 重启服务生效 |
OBJECT_STORAGE_* | 文件存储 | 重启服务。⚠️ 已有附件仍在原存储位置 |
MW_DEFAULT_LOCALE | 界面语言 | 重启服务生效 |
URL_HOST / URL_PORT | 外部 URL 生成 | 重启服务生效。⚠️ 已生成的头脑风暴邀请链接包含旧 URL |
关于 SECRET_KEY_BASE：Phoenix 用它签名 session cookie 和验证 CSRF token。变更后所有浏览器的 session cookie 会立即失效，用户需重新打开头脑风暴链接（链接本身不失效，只是用户状态重置为游客）。
章节目录