企业官网建设流程全解析

Automatisch 环境变量配置完全指南：docker-compose 部署中的参数详解与源码级原理

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch

Automatisch 是一款开源的工作流自动化平台（Zapier 的开源替代品），其行为几乎完全由环境变量驱动。本文以官方配置文档为骨架，完整解析 Automatisch 在 docker-compose 部署方式下的全部环境变量——包括 Web 服务、PostgreSQL 数据库、Redis、安全密钥、SMTP 邮件、BullMQ 看板等功能开关，并深入仓库源码，说明每个参数如何被读取、校验与生效。读完本文，你将能独立完成 Automatisch 的部署调优、安全密钥管理、HTTPS 反代场景配置与故障排查。

一、如何设置环境变量：docker-compose 双服务同步原则

Automatisch 的后端由main（API/Web 服务）与worker（后台任务队列消费者）两个服务组成，官方文档明确指出：修改环境变量时必须同时修改 docker-compose 中的main和worker两个服务，因为大多数变量（数据库、Redis、密钥等）会在两者中被同时使用。

在仓库根目录的 docker-compose.yml 中，可以看到两个服务各自声明的环境变量：

• main服务：HOST、PROTOCOL、PORT、APP_ENV、REDIS_HOST、POSTGRES_HOST、POSTGRES_DATABASE、POSTGRES_USERNAME、POSTGRES_PASSWORD，以及ENCRYPTION_KEY、WEBHOOK_SECRET_KEY、APP_SECRET_KEY三个密钥变量（注意这三个变量在 compose 文件中只写了变量名、没有默认值，说明其值必须来自宿主机环境或.env文件）；
• worker服务：与main几乎相同的数据库、Redis 与密钥变量，并额外设置了WORKER=true，用于在 docker/entrypoint.sh 中区分启动模式（WORKER非空则执行yarn start:worker，否则执行yarn db:migrate、yarn db:seed:user与yarn start）。

修改方式示例：在docker-compose.yml的main与worker两个environment:段中同步添加或覆盖变量，然后执行docker compose up -d重启服务。如果你不希望在 compose 文件中写死敏感值，也可以把密钥放在宿主机环境中（compose 会透传同名变量），或使用独立的.env文件配合 compose 的变量替换机制。

二、核心安全密钥：ENCRYPTION_KEY 与 WEBHOOK_SECRET_KEY

官方文档对这两个变量给出了最高级别的警告（:::danger）：ENCRYPTION_KEY与WEBHOOK_SECRET_KEY一旦修改，已有的第三方服务连接（connections）和流程（flows）将无法继续工作。原因如下：

• ENCRYPTION_KEY：用于加密第三方服务的凭据。若更换该密钥，此前用旧密钥加密存储的凭据将无法解密，所有已建立的应用连接都会失效；
• WEBHOOK_SECRET_KEY：用于校验 webhook 请求的真实性。更换后，依赖该密钥签名验证的 webhook 触发流程将无法通过校验。

另一个容易被忽略的细节是：这两个变量并非可选。在 packages/backend/src/config/app.js 中，服务启动时会做强制校验：

if (!appConfig.encryptionKey) { throw new Error('ENCRYPTION_KEY environment variable needs to be set!'); } if (!appConfig.webhookSecretKey) { throw new Error('WEBHOOK_SECRET_KEY environment variable needs to be set!'); }

即缺少任意一个，后端都会直接抛错拒绝启动。因此首次部署时，必须保证这两个变量被正确注入。

首次启动的自动密钥生成机制

如果你使用的是官方 compose 镜像，无需手动生成密钥：容器入口脚本 docker/compose-entrypoint.sh 会在存储卷/automatisch/storage/.env不存在时，用openssl rand -base64 36自动生成ENCRYPTION_KEY、WEBHOOK_SECRET_KEY、APP_SECRET_KEY三个随机密钥并持久化到该文件，后续启动再从该文件导入。这保证了容器重启后密钥不变，连接与流程得以持续有效。这也解释了为什么 docker-compose 卷定义中包含automatisch_storage:/automatisch/storage（见 docker-compose.yml）——删除该卷等同于更换全部密钥。

APP_SECRET_KEY用于用户会话认证（源码中注释为 "Secret Key to authenticate the user"），同样建议保持稳定。

三、完整环境变量参考表

以下表格完整覆盖官方配置文档的全部变量（默认值针对docker-compose 部署方式）。官方文档同时提示：开发环境（development setup）下部分变量的默认值可能与此不同——从源码看，例如 packages/backend/src/config/app.js 中数据库名与用户名在开发模式下默认分别为automatisch_development与automatisch_development_user。

四、源码级解析：环境变量如何被读取与生效

1. 配置聚合入口：config/app.js

所有环境变量的读取与默认值注入都集中在 packages/backend/src/config/app.js 中，其余模块（数据库、Redis、BullMQ、邮件等）都从这份appConfig对象取值。要点包括：

• URL 推导逻辑（L15-L39）：API URL 默认由${PROTOCOL}://${HOST}:${PORT}拼接而成；前端 URLwebAppUrl优先取WEB_APP_URL，未设置时回退到 API URL；若SERVE_WEB_APP_SEPARATELY=true（开发模式特征）则回退到http://localhost:3001。webhook URL 则取WEBHOOK_URL，未设置时回退到 API URL。
• 布尔值解析约定：项目统一使用字符串与'true'比较来解析布尔变量，例如process.env.POSTGRES_ENABLE_SSL === 'true'、process.env.REDIS_TLS === 'true'、process.env.TELEMETRY_ENABLED === 'false' ? false : true（即遥测默认开启，只有显式写false才关闭）。
• 数字解析：PORT、POSTGRES_PORT、REDIS_PORT、REDIS_DB、SMTP_PORT均通过parseInt转换为数字。
• 环境判定：APP_ENV决定isDev/isTest/isProd，进而影响日志、测试数据库（.env.test加载）等行为。注意APP_ENV未设置时源码默认是development，而 docker-compose 中显式设置为production。

2. PostgreSQL：knex 连接与连接失败即退出

数据库连接由 packages/backend/src/config/database.js 基于 knex 建立，实际连接参数在 packages/backend/knexfile.js 中组装：

connection: { host: appConfig.postgresHost, port: appConfig.postgresPort, user: appConfig.postgresUsername, password: appConfig.postgresPassword, database: appConfig.postgresDatabase, ssl: appConfig.postgresEnableSsl, }, searchPath: [appConfig.postgresSchema], pool: { min: 0, max: 20 },

POSTGRES_SCHEMA通过 knex 的searchPath生效；连接池上限为 20。同时 packages/backend/src/config/database.js 会启动时执行SELECT 1探活，若遇到ECONNREFUSED（连接被拒绝）会打印错误提示并直接process.exit()，确保配置错误能第一时间暴露。

3. Redis：单机、TLS 与 Sentinel 三种形态

packages/backend/src/config/redis.js 展示了对 Redis 的完整配置逻辑：

• 默认读取REDIS_HOST/REDIS_PORT/REDIS_USERNAME/REDIS_PASSWORD/REDIS_DB；
• 当设置REDIS_SENTINEL_HOST（源码支持的变量，可配合REDIS_NAME、REDIS_ROLE、REDIS_SENTINEL_PORT等）时，会切换为 Sentinel 模式并忽略普通 host/port；
• REDIS_TLS=true时为连接附加tls: {}选项；
• 测试环境（isTest）下强制使用db = 1，避免污染开发库。

Redis 是 Automatisch 队列系统（BullMQ，基于 Redis 的任务队列）的底层依赖，因此REDIS_*系列变量与ENABLE_BULLMQ_DASHBOARD、BULLMQ_DASHBOARD_USERNAME、BULLMQ_DASHBOARD_PASSWORD配合，即可在ENABLE_BULLMQ_DASHBOARD=true时开启可视化看板并设置登录凭据。

4. Web 前端：通知页与 favicon 开关

DISABLE_NOTIFICATIONS_PAGE与DISABLE_FAVICON会由后端经配置接口下发到 Web 前端。在 packages/web/src/routes.jsx 中可以看到!config?.disableNotificationsPage && (...)的条件渲染逻辑——设为true时通知相关路由/页面不再渲染。

五、典型部署场景配置示例

场景 1：通过反向代理提供 HTTPS 访问

将PROTOCOL改为https或显式设置WEB_APP_URL/WEBHOOK_URL，使前端调用、回调 URL 与 webhook 地址指向你的公网域名：

environment: - PROTOCOL=https - HOST=your-domain.example.com - WEB_APP_URL=https://your-domain.example.com - WEBHOOK_URL=https://your-domain.example.com/webhooks # 若使用外部托管数据库/Redis： - POSTGRES_HOST=db.internal - POSTGRES_ENABLE_SSL=true - REDIS_HOST=cache.internal - REDIS_PASSWORD=your-redis-password

场景 2：启用邮件通知（SMTP）

SMTP_*与FROM_EMAIL是 Automatisch 发送邀请邮件、通知邮件的基础配置。常见组合为：

environment: - SMTP_HOST=smtp.example.com - SMTP_PORT=465 - SMTP_SECURE=true - SMTP_USER=no-reply@example.com - SMTP_PASSWORD=your-smtp-password - FROM_EMAIL=no-reply@example.com

场景 3：日志调优与功能裁剪

environment: - LOG_LEVEL=debug # 排障时调高日志详细度 - TELEMETRY_ENABLED=false # 关闭遥测 - DISABLE_NOTIFICATIONS_PAGE=true - DISABLE_FAVICON=true - ENABLE_BULLMQ_DASHBOARD=true - BULLMQ_DASHBOARD_USERNAME=admin - BULLMQ_DASHBOARD_PASSWORD=strong-password

六、配置变更与排查提示

• 修改后必须重启两个服务：仅重启main而 worker 仍使用旧配置，会导致队列处理与 API 行为不一致；建议docker compose down && docker compose up -d或至少docker compose up -d --force-recreate main worker。
• 密钥类变量修改的代价：改动ENCRYPTION_KEY、WEBHOOK_SECRET_KEY意味着既有连接与 webhook 流程失效（详见第二节），生产环境务必提前规划密钥轮换策略（例如先备份storage卷中的.env）。
• 连接失败类故障：若日志中出现数据库ECONNREFUSED提示，请核对POSTGRES_HOST、POSTGRES_PORT、POSTGRES_PASSWORD以及POSTGRES_ENABLE_SSL是否与你的数据库实例匹配；Redis 异常则重点检查REDIS_HOST、REDIS_PASSWORD、REDIS_TLS。
• URL 类故障：若前端页面回调、OAuth 连接回调或 webhook 触发异常，优先检查WEB_APP_URL、WEBHOOK_URL是否与外部实际可达的地址一致（结合 config/app.js 的 URL 回退逻辑排查）。

以上配置项均可在仓库中的 docker-compose.yml、packages/backend/src/config/app.js 以及官方配置文档 packages/docs/pages/advanced/configuration.md 中交叉验证，按需调整即可稳定运行 Automatisch 的完整工作流自动化能力。

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch