Huginn 2026.10.14 配置参数详解

目标：逐参数讲解 Huginn v2026.10.14 的全量 .env 配置——必填项、数据库、安全策略、邮件、调度、网络行为、OAuth 扩展与镜像部署的 HUGINN_ 变量映射，全部默认值经实测核对。已在 Ubuntu 22.04 实测通过。

Huginn 的配置集中在 .env 文件（dotenv 机制，源码部署与镜像部署通用）。本文按 .env.example（65 个变量）逐段讲解，全部默认值取自 v2026.10.14 实测源码，标注了实测验证方式。修改后必须重启 Web 与 Worker 进程才生效。

一、环境信息

• Huginn 版本：v2026.10.14，全部参数默认值取自该版本实测源码；
• 配置载体：.env（dotenv 机制，源码部署与镜像部署通用），逐段讲解依据 .env.example（65 个变量）；
• 部署形态：源码部署（.env 位于源码目录，修改后重启 Web 与 Worker systemd 服务生效）与镜像部署（HUGINN_* 前缀容器环境变量注入，入口脚本生成容器内 .env）；
• 依赖数据库：MySQL 系（DATABASE_ADAPTER=mysql2），Web 对外端口默认 3000（PORT）；
• 实测主机：Ubuntu 22.04（Ubuntu 源码部署场景实测）。

二、配置系统与加载顺序

2.1 三层配置来源

镜像部署时无需写 .env，入口脚本把 HUGINN_DATABASE_HOST 等环境变量转写进容器内 .env，实测其映射逻辑（docker/scripts/setup_env 摘录）：

DATABASE_HOST=${HUGINN_DATABASE_HOST:-${DATABASE_HOST:-localhost}}
DATABASE_PORT=${HUGINN_DATABASE_PORT:-${DATABASE_PORT}}
DATABASE_ENCODING=${HUGINN_DATABASE_ENCODING:-${DATABASE_ENCODING:-utf8mb4}}
DATABASE_USERNAME=${HUGINN_DATABASE_USERNAME:-${DATABASE_USERNAME}}
DATABASE_PASSWORD=${HUGINN_DATABASE_PASSWORD:-${DATABASE_PASSWORD:-password}}
DATABASE_NAME=${HUGINN_DATABASE_NAME:-${DATABASE_NAME:-huginn_production}}

即优先级：HUGINN_ 前缀变量 → 无前缀同名变量 → 内置默认值。

💡 技术拓展：rake secret 与密钥来源。APP_SECRET_TOKEN 可用 rake secret 生成，也可用 openssl rand -hex 64，两者都是随机十六进制串。注意 v2026.10.14 上 rake secret 在 .env 未就位前执行可能因依赖加载报错，实测用 openssl rand -hex 64 更省心（安装指南 5.1 节即用此法）。

2.2 修改生效方式

• 源码部署：改 .env 后 systemctl restart huginn-web.service 与 systemctl restart huginn-worker.service（两个单元都要重启）；
• 镜像部署：改 compose 的 environment 后 docker compose up -d（会重建容器）。

三、必填核心项

3.1 APP_SECRET_TOKEN（必填）

APP_SECRET_TOKEN=beac26b240576cf9f06634a0cf1aefdaf8906de6170bb4ec6b6071dddd4e2ab8c75defcb594e0772b856588bbab7e4abebc6c2c10515c19950571ac0a8523154

Rails 会话加密与敏感字段加密的根密钥。更换后所有用户会话失效，已加密数据不可恢复——生成后妥善备份，禁止使用模板占位值。

3.2 DOMAIN 与 PORT

DOMAIN=your-domain-here.com
PORT=3000

对外访问域名（含端口），用于拼邮件里的激活/重置链接与 Webhook 文档提示。实测默认 localhost:3000，上生产必须改，否则邮件链接全部指向 localhost。

3.3 RAILS_ENV

RAILS_ENV=production

源码部署必须在 .env 里显式设置（模板里默认注释），否则按 development 启动（资产不预编译、代码热加载、性能差且暴露调试信息）。

四、数据库参数（DATABASE_*）

• utf8mb4：模板注释明确 MySQL 需 utf8mb4 才能存 emoji 等 4 字节字符，实测安装指南按 utf8mb4 建库；
• DATABASE_HOST=127.0.0.1：Ubuntu 源码部署实测，默认走 socket 时 Rails 应用用户无权进入 /var/run/mysqld（目录 700 属 mysql），报 Permission denied，改 TCP 绕开；
• NATIVE_JSON_COLUMNS=true（可选）：迁移时把序列化字段转原生 JSON 列。模板警告：MySQL 8 上开它之后 JSON 列排序可能报 Out of sort memory，需同步把 sort_buffer_size 调到 4M 以上。默认不开；
• DATABASE_POOL：Puma 默认 2 worker（WEB_CONCURRENCY）× 1 线程（RAILS_MAX_THREADS，实测默认 1）+ Worker 线程都要占连接，20 是稳妥值；连接报 Pool timeout 时调大。

4.1 database.yml 与 .env 的关系

config/database.yml 是从 ENV 读值的桥接（实测模板片段）：

# And be sure to use new-style password hashing:
#   https://dev.mysql.com/doc/refman/8.0/en/set-password.html

它引用 DATABASE_* 环境变量，因此只改 .env 即可，不需要动 database.yml。

五、用户注册与安全策略

公网实例推荐组合（实测语法均支持 N.days/N.hours/N.minutes 格式）：

INVITATION_CODE=换成长随机串
REQUIRE_CONFIRMED_EMAIL=true
MIN_PASSWORD_LENGTH=12
MAX_FAILED_LOGIN_ATTEMPTS=5
UNLOCK_STRATEGY=both

⚠️ 实测排障：IMPORT_DEFAULT_SCENARIO_FOR_ALL_USERS=true 时，每个新注册用户都会复制一份示例 Agent；内网专用实例想要干净列表就设 false。该开关只影响新用户，已有用户不受影响。

六、邮件参数（SMTP_*）

实测组合样例（本文 3.4 节全链路验证所用的本机 SMTP）：

SMTP_DOMAIN=local.test
SMTP_SERVER=127.0.0.1
SMTP_PORT=2525
SMTP_ENABLE_STARTTLS_AUTO=false
SMTP_AUTHENTICATION=none
EMAIL_FROM_ADDRESS=huginn@local.test

无认证本地 Postfix/中继用 SMTP_AUTHENTICATION=none；Gmail 587 报错时按模板提示改 SMTP_AUTHENTICATION=login 与 SMTP_PORT=465。

七、调度与后台任务参数

实测要点：

• Agent 不按时跑优先查 SCHEDULER_FREQUENCY 与 Worker 进程是否存活（The Agent job scheduler is not running 横幅）；
• 任务被杀（日志 Delayed::Worker::MaxRunTimeError）是 DELAYED_JOB_MAX_RUNTIME 到点，按任务性质调大（单位分钟）；
• AGENT_EXECUTION_LOCK_TIMEOUT 防同一个 Agent 被并发执行，30 秒等不到锁即失败重试，这是重复事件排障的常见根因。

八、Agent 网络行为参数

实测要点：

• 网站抓取被 403/429 时，除改 UA 外，OUTBOUND_NETWORK_TIMEOUT 太小也会让慢站点的抓取批量超时；
• ENABLE_INSECURE_AGENTS=true 允许任意用户跑 Shell 命令，等于把服务器交给所有注册用户，仅单人可信实例可开；
• 公网开放注册的实例，官方强烈建议把 OUTBOUND_PROXY 指向 Smokescreen 类出口代理（拒绝内网/链路本地地址），否则注册用户可借 WebsiteAgent/PostAgent 探测你的内网。

九、第三方 OAuth 与扩展

TWITTER_OAUTH_KEY=
TWITTER_OAUTH_SECRET=
GITHUB_OAUTH_KEY=
GITHUB_OAUTH_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
DROPBOX_OAUTH_KEY=
DROPBOX_OAUTH_SECRET=
EVERNOTE_OAUTH_KEY=
EVERNOTE_OAUTH_SECRET=
USE_EVERNOTE_SANDBOX=true
THIRTY_SEVEN_SIGNALS_OAUTH_KEY=
THIRTY_SEVEN_SIGNALS_OAUTH_SECRET=
TUMBLR_OAUTH_KEY=
TUMBLR_OAUTH_SECRET=
THREADS_APP_ID=
THREADS_APP_SECRET=

对应同名 Agent 的应用凭据；不用的留空即可，对应 Agent 在 UI 上会提示未配置。v2026.10.14 新增 LLM 段：

# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com/v1

OPENAI_BASE_URL 可指向 Ollama（http://localhost:11434/v1）、Azure OpenAI、Groq、vLLM 等兼容端点，未配置时使用各 Agent 的独立 key。

扩展 Agent gem（ADDITIONAL_GEMS）支持逗号分隔多值与版本约束，实测模板示例：

ADDITIONAL_GEMS=huginn_nlp_agents(~> 0.2.1),test_agent

十、时区与杂项

TIMEZONE=Asia/Shanghai

调度器按此时区解释 Agent 的 schedule 与 SchedulerAgent 的 cron。模板默认 Pacific Time (US & Canada)，中文环境必改，否则午夜任务、Digest 邮件时间全部错位。可选值可用 bundle exec rake time:zones:all 列出。

其余图示参数（实测默认关闭）：

• USE_JQ=jq：启用 jq 查询 Agent（官方注明有无限循环风险，仅可信实例）；
• USE_GRAPHVIZ_DOT=dot：用 Graphviz 渲染 Agent 流程图替代 Google Charts；
• DIAGRAM_DEFAULT_LAYOUT=dot：Graphviz 布局算法（circo/fdp/neato 等可选）；
• ASSET_HOST：静态资源 CDN 前缀；
• CAPISTRANO_DEPLOY_*：Capistrano 部署参数，源码部署进阶可选项。

十一、镜像部署的 HUGINN_ 前缀速查

容器环境变量与 .env 的对应关系（HUGINN_ 前缀优先，实测映射）：

实测映射机制是通用的：入口脚本遍历 .env.example 的每个变量，统一按 HUGINN_<原名> → <原名> → 模板默认值取值，因此任何 .env 参数都可加 HUGINN_ 前缀注入。另有两个镜像专用开关：START_MYSQL=true 让全功能镜像启用内置数据库（并自动追加 DATABASE_SOCKET=/app/tmp/sockets/mysqld.sock）；ENABLE_SMOKESCREEN=true 启用内置出站过滤代理并自动设置 OUTBOUND_PROXY。

APP_SECRET_TOKEN 未提供时的实测行为：入口脚本自动用 dd if=/dev/urandom 生成随机密钥并写入容器内 /tmp/secret 持久化——密钥随容器生命周期有效，容器删除后重建会换新密钥，会话全部失效；要跨重建保持会话，显式传 HUGINN_APP_SECRET_TOKEN。

⚠️ 实测排障：SEED_PASSWORD 只在数据库首次初始化时生效；之后改它不会改密码（重置密码走 UI 的 Forgot password 或 rails console）。想重建初始账号，需清空数据库重新初始化——生产环境先用 docker compose down（保留数据卷）再决定。

十二、参考链接

• Huginn GitHub 仓库
• Huginn 官方 .env.example 模板
• Huginn 官方 Wiki
• MySQL 8.0 官方文档
• dotenv（dotenv-rails）