farmOS 4.0.9 配置参数详解

目标：逐项讲清 farmOS 4.0.9（Drupal 11.3.19 内核）的配置体系——settings.php 核心参数、services.yml 服务参数、PHP 运行参数与 farmOS 专属配置（私有文件、OAuth2 密钥、地图 API Key），并给出生产可用的配置模板。全部文件内容与命令回显取自 Ubuntu 22.04 实测安装的 farmOS 4.0.9 站点（实测日期：2026-10-23，安装过程见《Ubuntu 22.04 安装 farmOS 4.0.9 指南》）。

一、环境信息

• farmOS 4.0.9（farmos/project 预打包发行，farm profile，81 个已启用模块）
• Drupal 11.3.19 / PHP 8.4.27 / PostgreSQL 16.15 / Apache 2.4.52
• 代码库 /opt/drupal，站点配置目录 /opt/drupal/web/sites/default/
• 关键文件清单（实测 ls /opt/drupal/web/sites/default/）：

default.services.yml
default.settings.php
files
settings.php

• 配置文件分工：settings.php（运行时参数：数据库、加密盐、文件路径、反向代理等）、services.yml（Symfony 容器参数：Twig 调试、会话等）、settings.local.php（本机覆盖，需手工启用）、php.ini/conf.d（PHP 引擎参数）。数据库中的活动配置（站点名、日志级别等）属于 Drupal 配置系统，用 drush 或后台 UI 管理。

二、前置条件

• 已按安装指南完成 farmOS 4.0.9 安装并可登录后台；
• drush 可用（tarball/Composer 方案在代码库内 vendor/bin/drush，Docker 方案用 docker compose exec www drush ...，见《farmOS 4.0.9 Docker Compose 部署指南》第九节）；
• 修改 settings.php 前先备份；Drupal 出于安全会在某些操作后对 settings.php 做只读硬化，改回前先 chmod u+w。

三、参数查看与修改方式

farmOS 没有 .env 之类的环境文件机制（这一点与 Go/PHP 框架类应用不同），参数分布在四处，查看与修改方式各不相同：

实测：用 drush 读取活动配置（回显为 farmOS 安装后的真实默认值）：

cd /opt/drupal && vendor/bin/drush config:get system.logging error_level

'system.logging:error_level': hide

💡 说明：error_level 默认就是 hide——farmOS 出厂即隐藏错误详情，生产可以少改一项；开发环境可改为 verbose。

四、参数总览

安装器写好的 settings.php 尾部（实测摘录，这是每台 farmOS 装完后都有的两行）：

$settings['hash_salt'] = 'h7PrNTacRCO29wunGa2Ibl0cXXPJLTL218MqWDRKT79omxotL5duvqGXklI8kJml8Jf85Ap4XA';
$settings['config_sync_directory'] = 'sites/default/files/config_w2RH6iHvSaYa2GVI9U6iQghro9LHZpTCK0bM25tvtwD77GQ1y6S_yEpfbg51CQKMdhSsYv7oyw/sync';

加上数据库连接块，安装器实际写入 3 组参数；其余参数（文件路径、反向代理、受信主机等）都在 default.settings.php 注释模板中等待启用（实测行号：反向代理 388 行、公共文件 515 行、私有文件 589 行、临时文件 602 行、受信主机 753 行）。下表为本文详解的核心参数总览：

五、核心参数分类详解

5.1 数据库连接：$databases

安装向导写入的实测值（PostgreSQL）：

$databases['default']['default'] = array (
  'database' => 'farm',
  'username' => 'farm',
  'password' => 'q1w2e3r4',
  'prefix' => '',
  'host' => '127.0.0.1',
  'port' => '5432',
  'driver' => 'pgsql',
  'namespace' => 'Drupal\\pgsql\\Driver\\Database\\pgsql',
  'autoload' => 'core/modules/pgsql/src/Driver/Database/pgsql/',
);

逐项说明：driver 支持 pgsql/mysql/sqlite（mariadb 走 mysql 驱动）；namespace 与 autoload 是 Drupal 11 多驱动架构的必配项，指明驱动类与 autoload 路径，换数据库时两者同步换（mysql 的 namespace 为 Drupal\\mysql\\Driver\\Database\\mysql）；prefix 为表前缀，多站共库时才需要；host 裸机装库用 127.0.0.1，Docker Compose 栈里是服务名 db。换库或改密码后必须 drush cr 并跑一次 drush sqlq "select 1" 验证连通。

多连接语法（只读副本示例，同一 $databases 数组里加 key）：

$databases['default']['replica'] = [
  'database' => 'farm',
  'username' => 'farm_reader',
  'password' => 'q1w2e3r4',
  'host' => '10.0.0.8',
  'port' => '5432',
  'driver' => 'pgsql',
  'namespace' => 'Drupal\\pgsql\\Driver\\Database\\pgsql',
  'autoload' => 'core/modules/pgsql/src/Driver/Database/pgsql/',
];

5.2 安全参数：hash_salt 与 trusted_host_patterns

$settings['hash_salt']：安装器生成的 64 位随机串，用于会话与密码重置令牌的加密盐。实测已自动写入（见第四节摘录）。要点：换库迁移站点时应保留原值，否则全部会话失效；泄露后轮换会导致用户重新登录（数据无损）。

$settings['trusted_host_patterns']：防 Host 头注入。默认注释未启用，生产必须按真实域名设置（default.settings.php 753 行模板）：

$settings['trusted_host_patterns'] = [
  '^www\.myfarm\.example\.com$',
  '^myfarm\.example\.com$',
];

逐项说明：数组元素是正则（锚点 ^/$ 要写全）；不启用时任意 Host 头都能命中站点（缓存投毒风险）；设错会让站点直接报 "The provided host name is not valid for this server"，改回即可恢复。

5.3 文件系统参数：public/private/temp

// 公共文件（可匿名访问），默认即 sites/default/files，一般无需显式设置
$settings['file_public_path'] = 'sites/default/files';
// 私有文件（必须登录才能下载），farmOS 官方要求安装后必须配置
$settings['file_private_path'] = '/opt/drupal/web/sites/default/private/files';
// PHP 临时目录（上传中间态），默认 /tmp
$settings['file_temp_path'] = '/tmp';

实测配置 private 的完整动作（官方安装文档同款）：

mkdir -p /opt/drupal/web/sites/default/private/files
chown -R www-data:www-data /opt/drupal/web/sites/default/private
chmod -R 770 /opt/drupal/web/sites/default/private
echo '$settings["file_private_path"] = "/opt/drupal/web/sites/default/private/files";' >> /opt/drupal/web/sites/default/settings.php
cd /opt/drupal && vendor/bin/drush cr

实测回显：

 [success] Cache rebuild complete.

逐项说明：目录属主必须 www-data、权限 770（其他用户禁入）；私有文件通过 /system/files/... 签名 URL 下载而非直链；Docker 部署时该路径在 sites bind mount 内（/opt/drupal/web/sites/default/private/files），天然持久化。

5.4 配置同步目录：config_sync_directory

安装器把配置导出目录放在了 sites/default/files/config_<随机串>/sync（见第四节摘录）。它接受绝对路径，生产建议移到 Web 根之外并纳入 git/备份：

$settings['config_sync_directory'] = '/etc/farmos/config/sync';

配套的 drush 用法（实测）：

cd /opt/drupal && vendor/bin/drush config:status | tail -3

  views.view.who_s_new                    Only in DB
  views.view.who_s_online                 Only in DB
 --------------------------------------- ------------

config:status 列出文件系统与数据库配置的差异（farmOS 大量视图配置只在数据库中，属正常初始状态）；config:export 全量导出到 sync 目录、config:import 反向导入，是环境间搬运配置的标准通道。

5.5 反向代理参数

farmOS 前置 Nginx/负载均衡做 TLS 终结时必须启用（default.settings.php 364–388 行模板）：

$settings['reverse_proxy'] = TRUE;
$settings['reverse_proxy_addresses'] = ['10.0.0.2', '10.0.0.3/24'];
$settings['reverse_proxy_trusted_headers'] = \Symfony\Component\HttpFoundation\Request::HEADER_X_FORWARDED_FOR | \Symfony\Component\HttpFoundation\Request::HEADER_X_FORWARDED_PROTO;

逐项说明：reverse_proxy_addresses 填代理服务器 IP/CIDR 白名单，Drupal 只信任来自这些地址的 X-Forwarded-* 头，防止伪造 IP；reverse_proxy_trusted_headers 指明读取哪些头（Drupal 11 推荐显式声明 FOR 与 PROTO）；不配置时后台看到的访客 IP 全是代理 IP，限流与审计都会失真。

5.6 日志与错误参数

活动配置方式（drush 实测）：

cd /opt/drupal && vendor/bin/drush config:set system.logging error_level verbose -y

 active store was saved with new value(s).

取值说明：hide（默认，生产）/all/some/verbose（开发，页面直接打印堆栈）。另一个相关项 $settings['error_level'] 已在新版中由活动配置取代。日志查看走 watchdog（drush 命令见《farmOS 4.0.9 常用 CLI 命令与工具详解》第九章）。

5.7 services.yml 服务参数

从模板拷贝后编辑（文件不存在时 Drupal 用内核默认值）：

cp /opt/drupal/web/sites/default/default.services.yml /opt/drupal/web/sites/default/services.yml

常用片段：

parameters:
  twig.config:
    debug: false          # Twig 调试注释，生产必须 false
    auto_reload: true     # 模板变更自动重编译（开发 true）
  session.storage.options:
    gc_probability: 1     # 会话 GC 分子
    gc_divisor: 100       # 会话 GC 分母（1/100 概率触发）
    cookie_lifetime: 2000000  # 会话 Cookie 生命周期（秒）
    ini_set.cache_limiter: ''   # 禁用 PHP 缓存头，避免缓存冲突

逐项说明：twig.config.debug 开启后页面 HTML 会出现 Twig 调试注释（暴露模板路径，生产禁用）；cookie_lifetime 默认 2000000 秒（约 23 天），农场平板场景可按需调短；改完 drush cr 生效。

5.8 PHP 运行参数

官方推荐 6 项（Requirements 页）：memory_limit=256M、max_execution_time=240、max_input_time=240、max_input_vars=5000、realpath_cache_size=4096K、realpath_cache_ttl=3600。裸机写入 /etc/php/8.4/apache2/conf.d/90-farmos.ini（完整步骤与前后对比实测见《Ubuntu 22.04 安装 farmOS 4.0.9 指南》6.1 节）；Docker 部署挂 php.ini 进 /usr/local/etc/php/conf.d/farmos.ini（实测 upload_max_filesize => 50M 生效，见《farmOS 4.0.9 Docker Compose 部署指南》第七节）。

5.9 farmOS 专属配置

• OAuth2 API 密钥：启用 farmOS API 后，在后台 Configuration > Web Services > Consumers 的 Settings 页把 Public/Private Key 路径设为 ../keys/public.key、../keys/private.key 并点击 Generate keys。keys 目录必须在 Web 根之外且对 www-data 可写（生成后建议改为只写保护）；Docker 方案里就是 compose 的 ./keys:/opt/drupal/keys 挂载。
• 地图图层 API Key：Mapbox / Google Maps 卫星图层在后台 Setup > Settings > Map 中填 Key（Key 需向 Mapbox/Google 申请），图层模块在 Setup > Modules 安装。
• 私有文件路径：见 5.3，这是 farmOS 文件上传功能的前置条件（官方安装文档 File uploads 一节）。
• cron：farmOS 依赖外部触发例行维护（drush cron 或密钥 URL https://站点/cron/<key>），后者在 Configuration > System > Cron 页查看，密钥型 URL 便于无登录的宿主 crontab 用 wget 触发。

5.10 settings.local.php 机制

default.settings.php 尾部有一段被注释的本地覆盖加载块，启用后可把开发期参数（Twig 调试、跳过权限硬化）隔离到不入库的本地文件：

# if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
#   include $app_root . '/' . $site_path . '/settings.local.php';
# }

启用步骤：去掉注释，cp default.settings.local.php settings.local.php（模板同目录），常用覆盖：

$settings['skip_permissions_hardening'] = TRUE; // 允许 settings.php 保持可写（仅开发）
$config['system.logging']['error_level'] = 'verbose';

六、生产配置模板

适用于「1 台 4GB 内存服务器 + Nginx TLS 反代 + PostgreSQL 同机」的单农场生产场景，settings.php 增量段（数据库块沿用安装器写入值）：

// ===== 生产加固段（单农场，4GB 内存，反代后）=====
// 受信主机：换成你的真实域名
$settings['trusted_host_patterns'] = [
  '^farm\.example\.com$',
];
// 反向代理（Nginx 所在机器）
$settings['reverse_proxy'] = TRUE;
$settings['reverse_proxy_addresses'] = ['127.0.0.1'];
$settings['reverse_proxy_trusted_headers'] = \Symfony\Component\HttpFoundation\Request::HEADER_X_FORWARDED_FOR | \Symfony\Component\HttpFoundation\Request::HEADER_X_FORWARDED_PROTO;
// 私有文件（farmOS 必需）
$settings['file_private_path'] = '/opt/drupal/web/sites/default/private/files';
// 配置同步目录移出 Web 根
$settings['config_sync_directory'] = '/etc/farmos/config/sync';
// 错误详情关闭（活动配置默认已是 hide，此处仅示例覆盖本地文件场景）

配套 PHP conf.d（90-farmos.ini）：官方推荐 6 项原值（5.8 节）。磁盘方面：站点数据与私有文件与系统盘分离时，file_private_path 指向挂载点即可；数据库建议预留 20GB 起（含 watchdog 增长）。

七、常见问题（FAQ）

Q1：改了 settings.php 不生效？ 三步排查：确认编辑的是当前站点的 sites/default/settings.php（多站点目录时容易改错）；文件末尾的 settings.local.php 加载块是否被启用且 local 里覆盖了同参数；最后 drush cr 清缓存。

Q2：访问报 "The provided host name is not valid for this server"？ trusted_host_patterns 正则没覆盖当前 Host。把该域名按 PHP 正则语法加入数组（注意转义点号），或在测试环境临时清空该配置定位问题。

Q3：hash_salt 可以删除吗？ 不可以。缺省会话/令牌校验直接报错。迁移站点时从旧 settings.php 带过来即可。

Q4：file_private_path 配了但上传仍失败？ 确认目录属主 www-data、权限 770、路径指向的目录存在；Docker 场景还要确认它在 sites 挂载内（宿主目录属主 33:33）。改完必须 drush cr。

Q5：Docker 部署能用环境变量改数据库连接吗？ 不能。官方镜像没有 FARMOS_* 类环境变量，数据库连接由安装向导一次性写入 sites/default/settings.php（随 sites 挂载持久化），后续修改直接编辑该文件。

八、参考链接

• 默认参数模板：https://github.com/farmOS/farmOS/blob/4.x/web/sites/default/default.settings.php
• 官方安装文档（File uploads / Cron / OAuth2 keys）：https://farmos.org/hosting/install
• 服务器要求（PHP 参数）：https://farmos.org/hosting/requirements
• Docker 定制（php.ini 挂载）：https://farmos.org/hosting/docker
• Drupal 设置参数参考：https://www.drupal.org/docs/administering-a-site/configuration-management