Automatisch 配置参数详解

目标：系统梳理 Automatisch v0.15.0 的环境变量配置体系——服务监听与对外地址、安全密钥三元组、PostgreSQL/Redis 连接、BullMQ 队列仪表盘、日志遥测、SMTP 邮件与界面开关，讲清参数优先级机制与 main/worker 双服务同步修改纪律。变量清单以官方配置文档为准（automatisch.io/docs/advanced/configuration，查询日期 2026-10-28），优先级机制经源码核实，关键参数行为经实测验证。

一、配置体系总览

Automatisch 0.15.0 的全部服务端配置通过环境变量注入，没有配置文件。配置来源分三层：

1. 官方文档环境变量表（权威口径）：https://automatisch.io/docs/advanced/configuration，2026-10-28 查询，共 34 个变量；
2. 源码配置层（packages/backend/src/config/app.js）：定义变量读取与默认值回落逻辑，本文关键机制的判定依据；
3. 部署载体：Docker Compose 编排中 main 与 worker 两个服务的 environment 段。

一条官方反复强调的纪律（配置文档原文）：「Please do not forget to change in main and worker services of docker-compose since the following variables might be used in both.」——除 WORKER=true 外，两个服务的环境变量必须保持完全一致。本文部署篇实测中 WEB_APP_URL/WEBHOOK_URL 的修改验证也遵循了这一纪律。

💡 技术拓展：Automatisch 的 main/worker 拆分是「无状态入口 + 有状态消费者」的经典形态。环境变量在两个进程间承担双职责——既是服务监听配置（main 用）也是执行环境配置（worker 用），因此安全密钥、数据库、Redis 连接参数在两侧必须字节级一致，否则会出现「main 加密、worker 解不开」的凭据错乱或队列消费异常。对比同类：n8n 单进程时代无此烦恼，拆分执行器（queue 模式）后同样引入了一致性纪律。

二、服务监听与对外地址参数

优先级机制（源码 config/app.js 核实，伪代码转写）：

apiUrl     = API_URL || `${PROTOCOL}://${HOST}:${PORT}`     // 默认 http://localhost:3000
webAppUrl  = WEB_APP_URL || apiUrl
webhookUrl = WEBHOOK_URL || apiUrl

三个地址各自独立回落：只设 WEB_APP_URL 不会改变 webhookUrl；要让 flow 触发器拿到对外可达的回调地址，必须设置 WEBHOOK_URL。部署篇第六章记录了这一行为的完整实测：仅加 WEB_APP_URL=http://192.168.146.128:8140 时 webhookUrl 仍为 http://localhost:3000/...，补设 WEBHOOK_URL 后方变为 http://192.168.146.128:8140/webhooks/flows/<flowId>/sync。

生产建议：HOST/PORT/PROTOCOL 保持官方默认（服务监听地址），对外地址全部交给 WEB_APP_URL 与 WEBHOOK_URL 两个显式变量表达，语义最清晰。

三、安全密钥三元组

三条硬约束：

1. 生成方式：官方建议 openssl rand -base64 36（安装文档原文），部署篇 3.1 节给出了实测生成回显；
2. 不可更换：官方 DANGER 警示「If you change them, your existing connections and flows will not continue to work」——凭据密文与密钥绑死，换钥即全部失效，且无官方在线轮换工具；
3. 来源随部署方式而异：官方仓库源码编排（方案 B）由 compose-entrypoint 在首启时自动生成并写入存储卷 .env；官方镜像方式（方案 A）不会落盘（部署篇第五章实测存储卷为空），密钥完全由环境变量注入，必须自行纳入密管。

社区版三把密钥全量必配：缺省时镜像入口不报错，但凭据加密与 webhook 验签将处于未初始化状态，首次保存连接即可能产生不可逆问题。安全密钥之外的关联变量 WORKER=true 仅 worker 侧设置，用于区分进程角色（官方文档明示的唯一天然差异项）。

四、PostgreSQL 数据库参数

官方默认值即官方仓库编排的配套值（库名 automatisch、用户 automatisch_user）。生产强化建议：

1. POSTGRES_PASSWORD 默认编排中的示例密码（automatisch_password）只应存在于隔离网络；跨网段生产部署务必改为强密码，且 main/worker/postgres 三处一致；
2. 数据库位于独立主机或托管 RDS 时，把 POSTGRES_HOST 指向真实地址并开启 POSTGRES_ENABLE_SSL=true（托管数据库通常强制 TLS）；
3. POSTGRES_SCHEMA 保持 public 默认，多系统共用一个库时才需要独立 schema 隔离。

数据库是 Automatisch 唯一的持久化层（用户/flow/凭据/执行历史都在这里），备份策略围绕它展开——运维篇给出 pg_dump 实测（46353 字节全量导出）与卷快照两种方法。

五、Redis 队列参数

Redis 在架构中承载 BullMQ 任务队列（main 投递、worker 消费），不持久化业务数据。要点：

1. 官方默认编排未给 Redis 设密码，生产环境建议启用 REDIS_PASSWORD（Redis 6+ ACL）并配 requirepass；
2. REDIS_DB 留空即默认 0 号库；多套环境共用一个 Redis 实例时用不同 DB 编号隔离；
3. Redis 不可用时 main 照常提供界面但 flow 无法执行（队列断供），监控上把 Redis 可用性纳入 Automatisch 的前置探针；
4. REDIS_TLS=true 用于托管 Redis 强制 TLS 的场景。

六、BullMQ 队列仪表盘参数

生效条件（源码核实）：shouldEnableBullDashboard() 要求三个变量同时非空/为 true，缺一即静默不启用。启用后仪表盘挂载在 /admin/queues，以 HTTP Basic 认证保护；仪表盘展示的队列列表源码固定为 flow、email、delete-user 三个（云环境追加订阅扣费队列）。

实测验证（admin/q1w2e3r4 为实测演示账号）：未认证访问返回 401，带 Basic 认证访问返回 200：

$ curl -s -o /dev/null -w 'no-auth: %{http_code}\n' http://127.0.0.1:8140/admin/queues
no-auth: 401
$ curl -s -u admin:q1w2e3r4 http://127.0.0.1:8140/admin/queues -o /dev/null -w 'with-auth: %{http_code}\n'
with-auth: 200

安全提示：仪表盘暴露了队列与任务明细，公网部署务必置于反代之后并收紧访问，或干脆保持默认关闭、排障时临时开启。

七、日志与遥测参数

LOG_LEVEL 排障时临时调到 debug 可看到任务派发与消费细节（默认 info 下 worker 日志只有 Workers are ready! 一行启动信息，本专栏运维篇有实测对比）；TELEMETRY_ENABLED 默认开启，向官方上报匿名使用统计，内网合规要求严格的部署显式置 false。

八、SMTP 邮件参数

SMTP 配置供密码找回、邮件通知类队列（email 队列）使用；不配置时相关功能静默降级。本组变量为官方文档溯源内容（本文实测环境未接入真实邮件服务，未做收发验证，实施时请以官方文档与自有 SMTP 服务商参数为准）。

九、界面开关参数

两个开关均面向「把 Automatisch 作为内部平台交付」的场景：通知页不可用时隐藏入口减少困惑，favicon 开关配合企业版白标（White labeling）完成品牌替换的第一步。

十、典型配置场景与建议

最小生产配置清单（官方镜像方式，逐项给出建议值）：

反向代理场景：Automatisch 服务监听 3000（服务侧），前置 Nginx/Caddy 做 TLS 终结与域名路由时——WEB_APP_URL=https://auto.example.com、WEBHOOK_URL=https://auto.example.com（回调地址由反代统一对外），PROTOCOL/HOST/PORT 保持服务侧默认值不动。这套组合已在部署篇实测（HTTP 形态），HTTPS 形态差异仅在两个 URL 变量的 scheme。

worker 扩容场景：执行吞吐不足时复制 worker 服务定义、以独立实例名横向加副本（BullMQ 天然多消费者竞争），密钥与连接参数与原 worker 完全一致；main 侧无需变更。

十一、常见问题（FAQ）

Q1：WEB_APP_URL 设了为什么 webhook 地址还是 localhost？ 变量职责不同：webhook 回调地址只认 WEBHOOK_URL（见第二章优先级表）。这是本文实测踩过的真实坑，反代与外呼场景两个变量都要设。

Q2：main 和 worker 配置不一致会怎样？ 轻则 worker 日志报连接失败（Redis/PostgreSQL 参数漂移），重则凭据解密失败（密钥漂移）。官方文档明确要求除 WORKER 外全部一致，变更时一次改两处再重启。

Q3：BullMQ 仪表盘开了但 401？ 确认三个变量全部就位（ENABLE_BULLMQ_DASHBOARD=true + 用户名 + 密码），且访问的是 Basic 认证（curl -u user:pass 或浏览器弹窗输入）。只开了开关不设账号同样不生效（源码生效条件为三者同时非空）。

Q4：LOG_LEVEL=debug 会不会影响性能？ debug 级别日志量显著放大（每个任务派发/消费都有明细），仅建议排障期临时开启，定位后回 info。

Q5：遥测能不能关？ 能，TELEMETRY_ENABLED=false。官方默认 true 上报匿名统计，合规敏感部署显式关闭即可。

十二、参考链接

1. 官方配置文档（34 个环境变量权威表）：https://automatisch.io/docs/advanced/configuration （查询日期 2026-10-28）
2. 官方安装文档（密钥生成建议与双服务同步警示）：https://automatisch.io/docs/guide/installation （查询日期 2026-10-28）
3. 配置层源码（优先级机制判定依据）：https://github.com/automatisch/automatisch/blob/main/packages/backend/src/config/app.js
4. 队列仪表盘源码（生效条件与挂载路径）：https://github.com/automatisch/automatisch/blob/main/packages/backend/src/helpers/inject-bull-board-handler.js