LimeSurvey 配置参数详解

版本基线：LimeSurvey Community Edition 7.7.0（martialblog/limesurvey:7.7.0-261020-apache，2026-10-27 构建），参数均从该版本实际文件摘录 实测环境：按 《LimeSurvey 7.7 Docker Compose 部署实战》 完成部署的 7.7 实例，应用根目录 /var/www/html 读者前置：已完成部署安装；涉及数据库/URL/安全等运维主题

一、配置体系总览

LimeSurvey 的配置是「PHP 数组分层覆盖」体系：全部可调参数都有内置默认值，站点级覆盖写在 config.php，密钥类写在 security.php，邮件默认值单独放在 email.php。7.7.0 版本实际文件的布局如下（实测 application/config/ 目录清单）：

覆盖规则写在 config-defaults.php 文件头（实测原文）：copy the lines corresponding to the parameter you want to change from this file to the config.php file——要改哪个参数，就把那一行拷贝到 config.php 的 config 数组里改值，config.php 中的同名键优先生效，未覆盖的参数回落到默认值。邮件参数同理：把 email.php 中的行拷到 config.php 覆盖。

💡 技术拓展：这类「defaults 文件 + 站点覆盖文件」是 PHP 应用的经典配置分层，WordPress（wp-config.php）、Drupal（settings.php）、Nextcloud（config/config.php）同属此列。优点是升级不丢配置、默认值有单一事实源；代价是改参数必须理解「覆盖发生在哪一层」——在 config-defaults.php 里直接改，升级即失效，这是最常见的误操作。

二、config.php 结构解剖

config.php 返回一个两层 PHP 数组：components（框架组件配置：数据库/路由/会话）与 config（应用级参数）。以下是本文实测实例（Docker 静默安装由镜像 entrypoint 生成）的完整内容：

<?php if (!defined('BASEPATH')) exit('No direct script access allowed');
return array(
  'components' => array(
    'db' => array(
      'connectionString' => 'mysql:host=db;port=3306;dbname=limesurvey;',
      'emulatePrepare' => true,
      'username' => 'limesurvey',
      'password' => 'q1w2e3r4',
      'charset' => 'utf8mb4',
      'tablePrefix' => 'lime_',
    ),
    //'session' => array (
    //   'class' => 'application.core.web.DbHttpSession',
    //   'connectionID' => 'db',
    //   'sessionTableName' => '{{sessions}}',
    //),
    'urlManager' => array(
      'urlFormat' => 'path',
      'rules' => array(),
      'showScriptName' => true,
    ),
  ),
  'config'=>array(
    'publicurl'=>'',
    'debug'=>0,
    'debugsql'=>0,
    'mysqlEngine' => 'InnoDB',
  )
);

而走 Web 图形向导安装的第二实例生成的 config.php（实测）结构相同，但有两点差异：向导版保留了 Yii 标准注释头（数据库连接说明），且会话段生成随机 sessionName：

 'session' => array (
    'sessionName'=>'LS-ZPPJOIUAZOPENULW',
    // Uncomment the following lines if you need table-based sessions.
    // Note: Table-based sessions are currently not supported on MSSQL server.
    // 'class' => 'application.core.web.DbHttpSession',
    // 'connectionID' => 'db',

sessionName 前缀 LS- + 随机串用于多实例同域名下会话隔离；两份文件可直接对照出「自动化生成」与「向导生成」的差别。

三、数据库参数（components.db）

配套的表引擎由 config 层的 mysqlEngine 决定：

• 默认 MyISAM（历史默认值）；
• 本文实例设为 InnoDB（事务、行锁、崩溃恢复）。官方文件对该开关有一句历史性警告：MyISAM 的表行数上限更高，「Using InnoDB instead of MyISAM will reduce the possible maximum number of questions in your surveys」（InnoDB 下单问卷可建题数会变少）——超大规模题库场景才需要权衡，一般部署选 InnoDB。

数据库连接类的排障手段：临时把 config.php 的 debug 设为 2（见第五章）后访问站点，PDO 连接异常会以完整堆栈展示；生产定位完务必改回 0。

四、URL 与路由参数（components.urlManager）

反向代理场景（Docker 镜像的对应环境变量为 BASE_URL/HOST_INFO/PUBLIC_URL）会在 components 里额外生成 request 段（baseUrl + hostInfo），用于代理终止 TLS 或路径前缀转发时修正生成的链接。新实例登录后台后如果跳转域名不对，优先检查这三个值与代理的 X-Forwarded-* 头。

五、全局核心参数（config 层常用覆盖项）

以下参数全部实测摘录自 7.7.0 的 config-defaults.php（行号对应实际文件），按运维主题分组：

站点与展示

安全与登录

调试与升级

令牌与参与者黑名单

上传与附件白名单（主题/资源/插件三组）

插件管控

六、security.php：应用加密密钥

security.php 存放 LimeSurvey 数据加密体系的根密钥，7.7.0 实际文件包含五个键（默认值形态见 config-defaults）：

$config['encryptionkeypair'] = '';
$config['encryptionpublickey'] = '';
$config['encryptionsecretkey'] = '';
$config['encryptionnonce'] = '';
$config['encryptionsecretboxkey'] = '';

应用首次运行时自动生成实际密钥并写入该文件（本文实例自动生成后含 encryptionnonce 与 encryptionsecretboxkey 等项）。文件头部的警告必须原文照录：

WARNING!!!
ONCE SET, ENCRYPTION KEYS SHOULD NEVER BE CHANGED, OTHERWISE ALL ENCRYPTED DATA COULD BE LOST !!!

即密钥一旦生成严禁更换：问卷令牌、SMTP 密码等加密字段的解密都系于这套密钥，丢失/更换等于密文报废。运维要求：

1. security.php 必须纳入备份（与数据库成对，见运维实战篇）；
2. 容器形态下该文件默认落在可写层——重建容器前先拷出，或用镜像的 ENCRYPT_* 环境变量在首次启动时注入固定密钥（支持 ENCRYPT_KEYPAIR/ENCRYPT_PUBLIC_KEY/ENCRYPT_SECRET_KEY/ENCRYPT_NONCE/ENCRYPT_SECRET_BOX_KEY，且均提供 _FILE 形态从文件注入）；
3. 未提供密钥时 entrypoint 会打印三行 Warning 并交由应用自建，属预期行为。

七、Docker 形态的环境变量覆盖

容器形态下，config.php 不必手写——镜像 entrypoint 在首启时用环境变量拼装生成。7.7.0 镜像 README 与 entrypoint.sh 实测对照的完整变量表：

所有「普通值」变量都有对应的 <VAR>_FILE 文件注入形态（entrypoint 的 file_env 函数实现）：同时给值与文件会报 exclusive 错误退出——密钥类变量建议统一走 _FILE。

环境变量与 config.php 的关系是「首启生成、此后不回写」：entrypoint 只在 config.php 不存在时生成；改环境变量后想让配置生效，需要删除容器内已生成的 config.php（或改用手写挂载），因此生产推荐直接挂载 config 目录做配置管理，环境变量只负责数据库连接这类引导参数。

八、邮件参数（email.php 专题）

7.7.0 把邮件默认值独立在 email.php（文件头同样标注 DO NOT EDIT，覆盖写 config.php）。实测全量参数：

生产建议：emailmethod 置 smtp 并指向独立邮件网关；发不出信先在后台「全局设置→邮件」发测试邮件，仍失败再把 emailsmtpdebug 提到 2 看完整 SMTP 会话。

九、主题与插件配置实务

• 主题查找路径：问卷主题安装目标为 upload/themes/survey/（admin 主题在 admintheme 参数，默认 Sea_Green）。部署时 upload 目录必须保留该骨架（实测：骨架缺失导致全站 500，见部署篇排障实录①）；
• 主题开发调试：force_xmlsettings_for_survey_rendering 置 true 后主题改动即时生效，免卸载重装（官方注释：仅开发场景用）；
• 主题可上传类型：受第五章三组白名单约束；允许 SVG 需同时扩 allowedthemeimageformats 与 imagemimetypes 映射（默认映射表实测含 gif/ico/jpg/jpeg/png 五类，官方注释明确警示 SVG 的 XSS 风险）；
• 插件安装：5.x 起 支持 ZIP 上传安装（依赖 disablePluginUpload=false）；安全敏感环境开 usePluginWhitelist 只放行指定插件，pluginWhitelist 列名即可，核心插件隐式放行、可用 corePluginBlacklist 排除。

十、缓存、会话与资产

• 会话存储：默认 PHP 文件会话；置 TABLE_SESSION 环境变量（或手工取消 config.php 中 session 段注释）切换到数据库表会话（DbHttpSession，表 {{sessions}}）。官方注释的坑：大型问卷的参与者会话可增长到 15 MB 以上，表会话必须保证 MySQL max_allowed_packet 足够（建议 ≥64M），否则会话静默丢失不报错；
• 资产缓存：前端合并产物在 tmp/assets/（customassetversionnumber 参与生成路径），twig_cache、cache、HTML 目录同在 tmp/runtime 下；改了主题/JS 却不生效时，清 tmp 资产目录或执行 console.php flushassets（见运维实战篇）即可；
• 上传体积：maximum_unzipped_size（解压上限，默认 5 亿字节）之外，真实上限还受 PHP post_max_size/upload_max_filesize 约束——完整性检查页（showserverconfigurationcheck=true）会并列展示这四项。

十一、常见配置任务实例

任务 1：站点改中文 + 上海时区（在 config.php 的 config 数组追加）：

  'config'=>array(
    'sitename'=>'青柠问卷平台',
    'defaultlang'=>'zh-Hans',
    'displayTimezone'=>'Asia/Shanghai',
    // ... 原有项
  )

任务 2：临时开排错模式：

    'debug'=>2,
    'debugsql'=>1,

排障完成后必须回 0——debug=2 会向受访者暴露堆栈与 SQL。

任务 3：强制 HTTPS（确认证书可用后再做，留好逃生开关）：

    'force_ssl'=>'on',

锁死后的恢复路径：数据库直改全局设置，或临时置 ssl_emergency_override=>true。

任务 4：管理员登录防爆破收紧：

    'maxLoginAttempt'=>5,
    'timeOutTime'=>60*30,

任务 5：会话入库（config.php 取消注释 + 数据库参数核对）：

    'session' => array (
       'class' => 'application.core.web.DbHttpSession',
       'connectionID' => 'db',
       'sessionTableName' => '{{sessions}}',
    ),

同时确认 MySQL max_allowed_packet ≥ 64M（官方口径，理由见第十章）。

十二、排障实录（实测沉淀）

1. 「改了参数不生效」：先确认改动写的是 config.php 而不是 config-defaults.php（后者升级即被覆盖）；主题/前端类改动还要清资产缓存（第十章）。
2. config.php 语法错误导致整站白屏：config.php 是被 require 的 PHP 文件，语法错（漏逗号/引号）会让整个应用无法启动；改动前 php -l application/config/config.php 校验语法是零成本习惯。
3. 7.x 实例复用旧 config.php 后 URL 全 404：旧文件里 'urlFormat'=>'get'，7.x 已不支持 get 路由（官方安装手册明确），改回 'path' 即恢复。
4. 容器重建后管理员被「重置」的错觉：ADMIN_* 只在首次安装生效（第七章），重建容器不会重跑安装、也不会改密码；以为密码丢失时先确认是不是连接到了另一套数据库（DB_NAME/DB_HOST 指向变化）。
5. 加密字段解不开：security.php 与数据库不同步（恢复时只恢复了库没恢复密钥文件）。两者必须成对备份/恢复。

十三、参考链接

• LimeSurvey 官方手册 · Optional settings（config.php 参数全集）：https://manual.limesurvey.org/Optional_settings
• LimeSurvey 官方手册 · Installation - LimeSurvey CE（URL 格式与数据库要求）：https://manual.limesurvey.org/Installation_-_LimeSurvey_CE
• LimeSurvey 官方手册 · Encryption（security.php 加密体系）：https://manual.limesurvey.org/Encryption
• 镜像 README（环境变量表与生成机制）：https://hub.docker.com/r/martialblog/limesurvey
• 本专栏关联篇目：《LimeSurvey 介绍与选型指南》、《LimeSurvey 7.7 Docker Compose 部署实战》、运维实战篇（console.php、RemoteControl API 与备份恢复）