Heimdall 2.8.4 配置参数详解

Heimdall 2.8.4 三层配置体系(.env 环境层、settings 数据表层、nginx/PHP 服务层)的边界、逐键语义、生效方式与生产加固模板详解。

Heimdall面板Docker部署自托管2026/11/03

Heimdall 2.8.4 配置参数详解

目标:讲清 Heimdall 2.8.4 的三层配置体系——.env 环境层、settings 数据表层(Web 设置页读写)、nginx/PHP 服务层文件——的边界、逐键语义与生效方式,并给出可直接落地的生产加固模板。本文所有参数值与命令回显均在真实部署环境实测取得(部署过程见《Heimdall Docker Compose 部署指南》)。

一、环境信息

项目值说明
组件版本Heimdall 2.8.4settings 表 version 键实测值 2.8.4
运行期PHP 8.5.12(NTS)+ nginx 1.30.6 + Laravel Framework 13.39.0 + SQLite 3.53.4php artisan about 与版本实测回显
应用根目录/app/www程序代码与默认配置所在
数据根目录/config全部持久化配置与数据所在
环境文件/config/www/.env配置体系第一层
数据库/config/www/app.sqlitesettings/items/users 等全部表收敛于此单文件
搜索提供方配置/config/www/searchproviders.yaml885 字节实测,详见 5.4 节
PHP 定制文件/config/php/php-local.ini覆盖 php.ini 指令
nginx 定制目录/config/nginx/ssl.conf、site-confs/default.conf 等
监听端口80(HTTP)/ 443(HTTPS)服务自身视角;宿主侧访问端口由部署层映射决定
目录视角约定全文路径均为服务自身视角若按《Heimdall Docker Compose 部署指南》部署,/config 对应宿主挂载的 config 目录;/app/www 为运行环境内置的应用代码目录

二、前置条件

  1. 已按《Heimdall Docker Compose 部署指南》完成部署,Web 入口可达,首启自动安装(迁移、密钥生成)已完成。
  2. /config 目录对服务运行账号可写(.env、app.sqlite、php-local.ini 等都在其内)。
  3. 具备任一修改通道的访问条件:浏览器(Web 设置页)、文件编辑(/config 内文件)、或命令行(php artisan,命令矩阵见《Heimdall 2.8.4 常用 CLI 命令与工具详解》)。

三、参数查看与修改方式

Heimdall 的配置分散在三层载体上,各层职责互不重叠:

层载体读写方式生效特点
环境层/config/www/.env编辑文件进程重启后读取;若执行过 config:cache,改文件不会读回(FAQ 7.1)
应用层app.sqlite 的 settings 表Web 设置页(推荐)或直查数据库保存即生效,无需重启
服务层/config/nginx/、/config/php/编辑文件nginx 需 nginx -t 校验后重载;PHP 需重启服务进程

3.1 环境层查看

$ cat /config/www/.env

全文键位见 4.1 节总览。该文件由首启安装流程生成(APP_KEY 为自动生成值),文件属性实测 -rwxr-xr-x,属主为服务运行账号。

3.2 应用层查看

settings 表共 15 行(实测计数),每行含 key/type/options/label/value/group_id/system 字段。命令行直查方法(PDO 方式)见 CLI 篇 4.3 节;日常维护首选浏览器打开 /settings 设置页读写,四个分组对应关系见 5.3 节。

3.3 运行态核对

php artisan about 一次拿到环境层生效值与驱动选择(实测回显节选):

$ php artisan about

  Environment ................................................................  
  Application Name .................................................. Heimdall  
  Laravel Version .................................................... 13.39.0  
  PHP Version ......................................................... 8.5.12  
  Composer Version .................................................... 2.11.0  
  Environment .......................................................... local  
  Debug Mode ............................................................. OFF  
  URL .............................................................. localhost  
  Maintenance Mode ....................................................... OFF  
  Timezone ............................................................... UTC  
  Locale .................................................................. en  

  Cache ......................................................................  
  Config .......................................................... NOT CACHED  
  Events .......................................................... NOT CACHED  
  Routes .......................................................... NOT CACHED  
  Views ............................................................... CACHED  

  Drivers ....................................................................  
  Broadcasting ........................................................... log  
  Cache ................................................................. file  
  Database ............................................................ sqlite  
  Logs ................................................................. daily  
  Mail .................................................................. smtp  
  Queue ................................................................. sync  
  Session ............................................................... file  

其中 Cache/Config 区块直接暴露"是否处于配置缓存态",是排查 .env 改动不生效的第一现场。

四、参数总览

4.1 .env 环境层键位总览(实测文件全键,注释键以「默认注释」标注)

键实测值作用
APP_NAMEHeimdall应用名(页面标题、邮件署名)
APP_ENVlocal运行环境标识
APP_KEYbase64:…(44 字符密钥体)Laravel 加密根密钥,首启自动生成,丢失即会话/加密数据作废
APP_DEBUGfalse调试开关,生产必须 false
APP_URLhttp://localhost生成绝对 URL 的基准,反代场景建议改为实际地址
TRUSTED_PROXIES默认注释(内置私网段)允许设置 X-Forwarded-* 头的反向代理 CIDR/IP(CVE-2025-50578 加固)
TRUSTED_HOSTS默认注释(不限制)允许服务的域名白名单,防 Host 头注入/开放重定向
APP_LOCALE / APP_FALLBACK_LOCALEen / en界面语言(用户级语言在 settings 表 language 键)
BCRYPT_ROUNDS12口令散列强度
LOG_CHANNELdaily应用日志按日滚动
DB_CONNECTION / DB_DATABASEsqlite / app.sqlite数据库连接与库文件(相对 database_path,实测软链到 /config/www/app.sqlite)
(注释块)DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD—切换 MySQL/PostgreSQL 的键位模板
CACHE_STOREfile缓存驱动
SESSION_DRIVER / SESSION_LIFETIMEfile / 120会话驱动与分钟数(响应 Cookie Max-Age=7200 即 120 分钟实测印证)
QUEUE_CONNECTIONsync队列驱动(运行期另有常驻 queue:work database 进程,见 CLI 篇)
MAIL_* / REDIS_* / AWS_* / PUSHER_*模板默认值Laravel 标准键位,Heimdall 本体基本用不到,留空即可
AUTH_ROLES_ENABLEfalse反向代理角色透传总开关
AUTH_ROLES_HEADER / AUTH_ROLES_HTTP_HEADERremote-groups / HTTP_REMOTE_GROUPS角色透传头名
AUTH_ROLES_ADMIN / AUTH_ROLES_DELIMITERadmin / ,管理员角色名与分隔符
ALLOW_INTERNAL_REQUESTSfalse是否允许服务端抓取用户提交的内网地址(SSRF 防护开关)

4.2 settings 应用层键位总览(15 键实测,分组取自 setting_groups 表)

键类型分组实测值系统键
versiontextsystem2.8.4是
supporttextsystemDiscord/Github/Blog 链接 HTML是
donatetextsystemPaypal 链接 HTML是
languageselect(27 选项)systemen否
background_imageimageappearance空(未设置)否
trianglifybooleanappearance空否
trianglify_seedtextappearanceheimdall否
treat_tags_asselectappearancefolders否
homepage_searchbooleanmiscellaneous空否
search_providerselect(6 选项)miscellaneous空否
window_targetselect(3 选项)miscellaneousheimdall否
custom_csstextareaadvanced空串否
custom_jstextareaadvanced空串否
default_tagselectadvanced空串否
skip_tls_verificationbooleanadvanced0否

4.3 服务层文件总览

文件作用
/config/nginx/site-confs/default.conf站点入口:监听、root、try_files、FastCGI
/config/nginx/ssl.confTLS 证书与协议参数
/config/nginx/resolver.confDNS resolver(自动生成)
/config/nginx/worker_processes.confnginx 工作进程数(按 CPU 核数自动生成)
/config/php/php-local.iniPHP 指令覆盖
/config/www/searchproviders.yaml搜索提供方清单
/config/keys/cert.crt、cert.keyHTTPS 证书对(首启自签生成)

五、核心参数分类详解

5.1 环境层:应用基础与日志会话

APP_KEY 是整套加密的根:首启安装流程自动生成并写入 .env(实测日志回显 INFO Application key set successfully.),会话 Cookie(XSRF-TOKEN、heimdall_session)都以它加密。备份 /config 时 .env 与 app.sqlite 必须同进同出——只恢复库文件而密钥不同,会话与加密字段会全部失效。

LOG_CHANNEL=daily 决定应用日志按日切分,实测落盘于 /config/www/logs/(文件名形如 laravel-2026-11-02.log)。SESSION_LIFETIME=120 与首页响应头 Set-Cookie: ... Max-Age=7200(秒)互为印证。

数据库默认值实测在 /app/www/config/database.php 中:

12:            'database' => env('DB_DATABASE', 'app.sqlite') === ':memory:'
14:                : database_path(env('DB_DATABASE', 'app.sqlite')),

即 DB_DATABASE 缺省为 app.sqlite,按 database_path 解析;实测 /app/www/database/app.sqlite 是指向 /config/www/app.sqlite 的软链,因此改 DB_DATABASE 为绝对路径即可换库,切换 MySQL/PostgreSQL 则按 .env 内注释模板填 DB_HOST 等五键。

5.2 环境层:安全加固三组键(重点)

TRUSTED_PROXIES / TRUSTED_HOSTS(CVE-2025-50578 修复项)。.env 内置注释原文(照抄):

# Security: Host Header Injection / Open Redirect hardening (CVE-2025-50578).
# TRUSTED_PROXIES: comma-separated CIDRs/IPs of reverse proxies allowed to set
#   X-Forwarded-* headers. Defaults to the private ranges below when unset. Use
#   "*" to trust all proxies (only behind a trusted network boundary).
#TRUSTED_PROXIES=192.168.0.0/16,172.16.0.0/12,10.0.0.0/8,127.0.0.1
# TRUSTED_HOSTS: comma-separated hostnames Heimdall is allowed to serve. Unset
#   means no restriction (default, backward compatible). Set this to your own
#   domain to fully prevent host-header injection / open redirects.
#TRUSTED_HOSTS=heimdall.example.com

要点三条:不设置 TRUSTED_PROXIES 时按内置私网段(上表注释行所列)信任;"*" 表示信任所有代理,仅在可信网络边界内使用;TRUSTED_HOSTS 默认不限制以兼容旧行为,反代暴露场景应显式设为自己的域名。中间件读取逻辑实测于 /app/www/app/Http/Middleware/TrustProxies.php:

/app/www/app/Http/Middleware/TrustProxies.php:11:     * The default trusted proxies used when the TRUSTED_PROXIES env var is unset.
/app/www/app/Http/Middleware/TrustProxies.php:38:     * The set of trusted proxies is read from the TRUSTED_PROXIES env var
/app/www/app/Http/Middleware/TrustProxies.php:46:        $trustedProxies = env('TRUSTED_PROXIES');

ALLOW_INTERNAL_REQUESTS(SSRF 防护)。.env 内置注释原文(照抄):

# Set to true if you host Heimdall on a LAN and need website lookups or icon
# URLs to reach internal addresses (e.g. http://192.168.1.10:8080/favicon.png).
# When false (the default), server-side fetches of user-supplied URLs are
# refused when the host, or any redirect it returns, resolves to a private or
# reserved address (loopback, RFC1918, link-local metadata, etc.).
ALLOW_INTERNAL_REQUESTS=false

默认 false 时,"网站查找"(自动抓标题/图标)与增强应用 API 调用若目标解析到回环、RFC1918、链路本地(云元数据)等私网地址会被拒绝。局域网自建场景(卡片指向内网 IP)必须显式置 true,否则图标与标题自动填充静默失败。

AUTH_ROLES_*(反向代理角色透传)。五键在 /app/www/config/app.php 的映射实测:

/app/www/config/app.php:22:    'auth_roles_enable' =>  (bool) env('AUTH_ROLES_ENABLE', false),
/app/www/config/app.php:24:    'auth_roles_header' =>  env('AUTH_ROLES_HEADER', 'remote-groups'),
/app/www/config/app.php:26:    'auth_roles_http_header' =>  env('AUTH_ROLES_HTTP_HEADER', 'HTTP_REMOTE_GROUPS'),
/app/www/config/app.php:28:    'auth_roles_admin' =>  env('AUTH_ROLES_ADMIN', 'admin'),
/app/www/config/app.php:30:    'auth_roles_delimiter' =>  env('AUTH_ROLES_DELIMITER', ','),

启用后 Heimdall 从前置认证代理注入的 remote-groups 头读取用户角色组,含 admin(AUTH_ROLES_ADMIN 值)即获得管理权限。该功能必须与 TRUSTED_PROXIES 配合——只有来自可信代理的该头才被采信,否则任何客户端都能伪造管理员身份。

5.3 应用层:settings 表与 Web 设置页

表结构实测(app.sqlite):

CREATE TABLE "settings" ("id" integer primary key autoincrement not null, "group_id" integer not null default '0', "key" varchar not null, "type" varchar not null default 'text', "options" text, "label" varchar not null, "value" varchar, "order" varchar not null default '0', "system" tinyint(1) not null default '0')

分组表 setting_groups 实测四行:

{"id":1,"title":"app.settings.system","order":0}
{"id":2,"title":"app.settings.appearance","order":1}
{"id":3,"title":"app.settings.miscellaneous","order":2}
{"id":4,"title":"app.settings.advanced","order":3}

即 Web 设置页的四个分区:系统(system)、外观(appearance)、杂项(miscellaneous)、高级(advanced)。另有 setting_user 表(实测结构:setting_id+user_id 复合主键、uservalue 列)支持按用户覆盖某项设置值。

逐键语义(值列为实测环境值):

  • version / support / donate:system=1 的系统键。version 由升级流程维护;support/donate 是页脚链接的 HTML 串,可改成自己的支持渠道。
  • language:界面语言,27 个选项(含 zh、zh_TW),实测值 en。与 .env 的 APP_LOCALE 分层:这里管前端展示语言。
  • background_image / trianglify / trianglify_seed:外观三件套。背景图上传受 PHP 上传限制(5.6 节);不开背景图时可启用 trianglify 程序化背景,trianglify_seed 决定图案(实测种子 heimdall)。
  • treat_tags_as:标签语义呈现,实测值 folders(可选 folders/tags/categories)。
  • homepage_search / search_provider:搜索条开关与默认引擎;search_provider 的选项集为 none/google/ddg/qwant/bing/startpage,与 searchproviders.yaml(5.4 节)联动。
  • window_target:卡片打开方式,实测值 heimdall(可选 current 当前页 / heimdall 应用内新标签 / _blank 新窗口)。
  • custom_css / custom_js:全局注入的自定义样式/脚本(textarea),进阶美化的入口。
  • default_tag:新建卡片的默认标签,实测空。
  • skip_tls_verification:实测值 0。置 1 后增强应用请求 HTTPS 目标时跳过证书校验,读取点实测位于 /app/www/app/SupportedApps.php:89(if (Setting::fetch('skip_tls_verification')) {)。更安全的替代方案是把自建 CA 束指给 PHP(openssl.cafile,见 5.6 节),而不是全局关校验。

5.4 应用层:searchproviders.yaml

单文件定义搜索条的全部提供方,实测全文(/config/www/searchproviders.yaml,885 字节):

tiles:
   id: tiles
   name: Tiles
   target: _blank

baidu:
   id: baidu
   url: https://www.baidu.com/s
   name: Baidu
   method: get
   target: _blank
   query: wd

bing:
   id: bing
   url: https://www.bing.com/search
   name: Bing
   method: get
   target: _blank
   query: q
   autocomplete: https://api.bing.com/osjson.aspx?query={query}

ddg:
   id: ddg
   url: https://duckduckgo.com/
   name: DuckDuckGo
   method: get
   target: _blank
   query: q
   autocomplete: https://duckduckgo.com/ac/?q={query}&type=list

google:
   id: google
   url: https://www.google.com/search
   name: Google
   method: get
   target: _blank
   query: q
   autocomplete: https://suggestqueries.google.com/complete/search?output=toolbar&hl=en&q={query}

startpage:
   id: startpage
   url: https://www.startpage.com/do/dsearch
   name: Startpage
   method: get
   target: _blank
   query: query

字段语义:url 为检索端点、query 为关键词参数名(百度是 wd、Startpage 是 query)、autocomplete 为建议接口模板({query} 占位)、target 为打开方式。tiles 条目没有 url——它是本地搜索,按名称匹配仪表盘内卡片,列表首位即生效。

文件位置机制实测:应用读写的是 storage 层路径,而该文件是指向数据根目录的软链——

lrwxrwxrwx 1 root root 32 Nov  3 00:47 searchproviders.yaml -> /config/www/searchproviders.yaml

同目录另有出厂备份 searchproviders.yaml.orig。改配置直接编辑 /config/www/searchproviders.yaml 即可(增删、重排、自定义新引擎),改完刷新页面由搜索条重新读取;恢复出厂可复制 .orig。

5.5 服务层:nginx

站点入口 /config/nginx/site-confs/default.conf 实测关键段(全文照抄核心块):

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    listen 443 quic reuseport default_server;
    listen [::]:443 quic reuseport default_server;

    server_name _;

    include /config/nginx/ssl.conf;

    set $root /app/www/public;
    if (!-d /app/www/public) {
        set $root /config/www;
    }
    root $root;
    index index.html index.htm index.php;

    location / {
        try_files $uri $uri/ /index.html /index.htm /index.php$is_args$args;
    }

    location ~ ^(.+\.php)(.*)$ {
        fastcgi_split_path_info ^(.+\.php)(.*)$;
        if (!-f $document_root$fastcgi_script_name) { return 404; }
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include /etc/nginx/fastcgi_params;
    }

    # deny access to .htaccess/.htpasswd files
    location ~ /\.ht {
        deny all;
    }
}

三个要点:root 有 /app/www/public 优先、回退 /config/www 的双态逻辑;PHP 请求经 fastcgi_pass 127.0.0.1:9000 交给应用进程;文件内保留了两处 Basic Auth 注释块(auth_basic "Restricted" / auth_basic_user_file /config/nginx/.htpasswd,实测位于第 23-25、31-33 行),给服务加口令墙只需取消注释并准备 .htpasswd。

TLS /config/nginx/ssl.conf 实测要点(文件头标注 2026-06-27 版、TLSRef v6.0 intermediate 生成):

ssl_certificate /config/keys/cert.crt;
ssl_certificate_key /config/keys/cert.key;

# HSTS (ngx_http_headers_module is required) (63072000 seconds)
add_header Strict-Transport-Security "max-age=63072000";

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ecdh_curve X25519MLKEM768:X25519:prime256v1:secp384r1;
ssl_prefer_server_ciphers off;
ssl_session_timeout 1d;
ssl_session_cache shared:MozSSL:10m; # about 40000 sessions

证书对默认是首启自签(/config/keys/,实测 cert.crt 1371 字节、cert.key 权限 -rw-------),换正式证书即替换这两个文件。HSTS 一年+(63072000 秒)默认开启——纯 HTTP 部署访问过一次 HTTPS 后浏览器会强制跳转,排障时别忘了这点。

自动生成件:resolver.conf 实测 resolver 127.0.0.11 valid=30s;(首启按运行环境 DNS 生成,可手改);worker_processes.conf 实测 worker_processes 6;(按检测到的 CPU 核数生成,可改数字或 auto)。

改完任何 nginx 文件,先跑语法校验再重载,实测回显:

$ nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

5.6 服务层:PHP

/config/php/php-local.ini 是 PHP 指令的唯一持久覆盖点(实测内容):

; Edit this file to override php.ini directives

date.timezone = Asia/Shanghai
upload_max_filesize = 30M
post_max_size = 30M

背景图上传失败的最常见根因就在这里:默认上传限制 2M,超过即"背景图设置不上"(官方 README 专节说明),把 upload_max_filesize/post_max_size 提到 30M 后生效。自签/本地 CA 场景的推荐写法也加在此文件:openssl.cafile = /config/heimdall.pem(把自建 CA 与目标站点证书合并成一个 .pem 束,确保证书文件对运行账号可读),比打开 skip_tls_verification 安全得多。

应用进程侧实测(fpm 池配置):

[www]
user = abc
group = abc
listen = 127.0.0.1:9000
pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3
clear_env = no

listen 与 default.conf 的 fastcgi_pass 成对出现(改一侧必改另一侧);clear_env = no 保证 .env 相关环境变量能透传给应用。关键扩展实测在位:curl fileinfo mbstring openssl pdo_sqlite zip——其中 fileinfo 缺失正是"背景图改不了"的另一种故障形态(README 提醒确认 php_fileinfo 已启用)。

六、生产配置模板

6.1 .env 加固段(反代 + 局域网场景,基于内置注释口径):

APP_DEBUG=false
APP_URL=https://heimdall.example.com

# 反向代理所在网段(按实际改);只信任它设置 X-Forwarded-*
TRUSTED_PROXIES=10.89.62.0/24
# 域名白名单,杜绝 Host 头注入/开放重定向
TRUSTED_HOSTS=heimdall.example.com

# 卡片指向内网地址(图标/标题自动抓取、增强应用 API)
ALLOW_INTERNAL_REQUESTS=true

# 若前置认证代理透传角色,才启用:
#AUTH_ROLES_ENABLE=true
#AUTH_ROLES_HEADER=remote-groups
#AUTH_ROLES_ADMIN=admin

6.2 php-local.ini:

date.timezone = Asia/Shanghai
upload_max_filesize = 30M
post_max_size = 30M
; 自签/本地 CA 增强应用(二选一,优先此项而非全局跳过校验)
;openssl.cafile = /config/heimdall.pem

6.3 settings 推荐值:skip_tls_verification 保持 0;window_target 按习惯选(内网自用推荐 heimdall);treat_tags_as 按组织习惯选 folders/tags;language 可设 zh。

6.4 备份清单:/config/www/.env(含 APP_KEY)、/config/www/app.sqlite、/config/www/searchproviders.yaml、/config/keys/、/config/nginx/、/config/php/——与部署篇第五节的持久化目录表一致,打包 /config 即全覆盖。

七、常见问题

7.1 改了 .env 但值不生效

执行过 php artisan config:cache 后,配置被固化进缓存文件,.env 改动不再被读取。实测确认方法:php artisan about 的 Cache 区块显示 Config ... CACHED(对照未缓存态 NOT CACHED)。恢复实测:

$ php artisan config:clear

   INFO  Configuration cache cleared successfully.  

之后重启应用进程让新值进入内存。原则:改 .env → config:clear → 重启,三步连做。

7.2 背景图上传后没有变化

两个根因按序排查:图片超过 PHP 上传限制(默认 2M,改 php-local.ini 的 upload_max_filesize/post_max_size,见 5.6);fileinfo 扩展缺失(实测 php -m 应有 fileinfo)。

7.3 增强应用报证书错误(自签/本地 CA)

把 CA 束写入 openssl.cafile(6.2 模板);确实需要省事才用 skip_tls_verification=1,它是全局跳过校验,内网之外不建议。

7.4 反代后部分链接跳转异常

HTTPS 反代必须走服务的 443 端口(官方 README 明示,否则链接会断);同时确认 TRUSTED_PROXIES 覆盖了代理地址,否则 X-Forwarded-Proto 不被采信、生成 URL 回退 http。子目录反代不被支持,换根路径或子域名。

7.5 卡片图标/标题自动抓取失败(内网目标)

默认 ALLOW_INTERNAL_REQUESTS=false 会拒绝解析到私网地址的抓取(含重定向后落私网的情况),局域网部署显式置 true(5.2 节)。

7.6 设置页保存后页面 500 / 权限类报错

多为数据目录属主错位:app.sqlite、.env 等必须归属服务运行账号(实测属主为 abc,与 PUID/PGID 对齐)。修复与排障实录见部署篇 FAQ 11.3。

八、参考链接