Galette 1.3.1 配置参数详解

目标：逐一讲清 Galette 1.3.1 的全部配置入口与核心参数——文件层的数据库连接参数（config.inc.php）、行为覆写参数（behavior.inc.php）、数据库层的 144 项实例偏好（Settings 页与高级配置页）、特性开关（feature flags），并给出可直接落地的生产配置模板。所有参数值与文件内容均在实际部署的 Galette 1.3.1 站点上逐项读取回显（安装与站点部署过程见《Ubuntu 22.04 安装 Galette 1.3.1 指南》）。

一、环境信息

本文实测环境（与前篇安装指南同一站点）：

• 操作系统：Ubuntu 22.04；Apache 2.4.52；PHP 8.3.36；MariaDB 10.6.23
• Galette：1.3.1（官方 tarball 部署），安装路径 /var/www/galette-1.3.1，Web 入口 galette/webroot/
• 配置目录：/var/www/galette-1.3.1/galette/config/
• 数据目录：/var/www/galette-1.3.1/galette/data/
• 数据库：galette 库，表前缀 galette_，偏好参数存于 galette_preferences 表
• 后台管理账号：admin（超级管理员）

二、前置条件

阅读与操作本文需要：

• 已完成 Galette 1.3.1 安装（未装请先看《Ubuntu 22.04 安装 Galette 1.3.1 指南》）；
• 服务器上的文件编辑权限（config/ 目录两个文件的读改）与数据库查询权限（mariadb 客户端可连）；
• 一个超级管理员后台账号（本文用 admin），用于查看 Settings 与高级配置页。

三、参数查看与修改方式

Galette 1.3.x 的参数分布在三个层级，各自有不同的查看与修改方式。这一分层在 1.3.0 中明确化：原先只能写文件的部分参数被迁入数据库，文件层退化为"强制覆写"。

三种后台查看途径的实测入口：

• Settings 页：登录后访问 http://<站点>/preferences（实测页面标题 Settings - Galette），表单含 111 个 pref_* 输入项，覆盖绝大多数日常参数；
• 高级配置页（1.3.0 新增）：访问 http://<站点>/advanced-config（实测页面标题 Advanced configuration - Galette），以列表形式展示全部偏好参数（包括 Settings 表单不显示的），并标注每项处于默认值/已修改/被 behavior.inc.php 锁定三种状态之一；该页参数表由前端脚本异步加载；
• 数据库直查：偏好参数的最终事实在 galette_preferences 表（字段为 nom_pref/val_pref），文件层与页面之外的一切以它为准，例如查询会籍参数：

mariadb -ugalette -pq1w2e3r4 galette \
  -e "SELECT nom_pref, val_pref FROM galette_preferences WHERE nom_pref IN ('pref_membership_ext','pref_numrows');"

实测回显：

nom_pref                val_pref
pref_membership_ext     12
pref_numrows            30

⚠️ 注意：修改文件层参数（config.inc.php / behavior.inc.php）不需要重启 Web 服务，PHP 每次请求都会重新加载；在 behavior.inc.php 覆写数据库偏好时，高级配置页会把对应项显示为锁定并写一条告警日志（官方注释原文："the advanced page will show it as locked and Galette will log a warning"）。

四、参数总览

按层级汇总本文覆盖的参数规模：

💡 说明：Settings 页 111 项 < 数据库 144 项，差值包括 UUID 类标识（pref_registration_uuid 等）、遥测时间戳等只读或极少改动项——它们只在高级配置页可见，这正是 1.3.0 引入该页的理由（官方公告原文："A new page lists every preference of the instance, including those no form displays"）。

五、核心参数分类详解

5.1 数据库连接参数（config.inc.php）

本站安装器生成的 galette/config/config.inc.php 全文实测：

<?php
define('TYPE_DB', 'mysql');
define('HOST_DB', 'localhost');
define('PORT_DB', '3306');
define('USER_DB', 'galette');
define('PWD_DB', 'q1w2e3r4');
define('NAME_DB', 'galette');
define('PREFIX_DB', 'galette_');

逐项说明：

官方样例 config.inc.php.dist 另示范一个可选常量 SCRIPT_AUTH_TOKEN（样例取值 change_this_value_with_a_very_strong_password）：这是"缴费后置脚本"（post contribution script，收到缴费后回调外部 HTTP 接口）的鉴权令牌，启用该功能时必须换成强口令。

💡 说明：换数据库服务器（迁移）时只改本文件的 HOST_DB/PORT_DB/USER_DB/PWD_DB 即可，无需重装；换引擎（mysql↔pgsql）则需配合官方导出工具重新初始化，属于跨库迁移话题。

5.2 行为覆写参数（behavior.inc.php）

behavior.inc.php 默认不存在（需从 behavior.inc.php.dist 复制改造），它是数据库连接之前的最早加载层，全部为 PHP 常量。官方样例文件中的 8 个参数逐项实录与解读：

（1）GALETTE_DEBUG——调试模式（样例默认注释掉，即关闭）：

//define('GALETTE_DEBUG', true);

开启后日志级别自动降到 DEBUG 并输出详细错误。生产环境保持关闭；排障时临时打开，用完注释回去。

（2）GALETTE_MODE——运行模式（样例默认注释掉，即 PROD）：

//define('GALETTE_MODE', 'MAINT');

可用值四种（样例注释原文）：PROD 正常运行（不设置时的默认）；DEV 已废弃（1.1.0 起用 GALETTE_DEBUG 替代）；MAINT 维护模式——只有超级管理员能登录；DEMO 演示模式——超级管理员凭据与邮件设置被锁定。把站点交给外部演示时用 DEMO，升级维护窗口用 MAINT。

（3）GALETTE_LOG_LVL——日志级别：

//define('GALETTE_LOG_LVL', \Analog\Analog::INFO);

取 Analog 日志库的级别常量；默认 WARNING，调试模式下自动为 DEBUG。设为 INFO 可看到更多运行轨迹（本站实测安装日志即为 INFO 级输出）。

（4）GALETTE_SQL_DEBUG——SQL 调试：

//define('GALETTE_SQL_DEBUG', true);

开启后每条 SQL 都追加写入 data/logs/galette_sql.log（样例注释原文），慢查询/异常语句排查专用，同样属于"临时打开"类开关。

（5）GALETTE_FEATURE_FLAGS——特性开关强制声明：

//define('GALETTE_FEATURE_FLAGS', ['acls', 'oauth2']);

以数组强制开启特性开关（见 5.10 节 registry），声明的优先级高于后台高级配置页的开关（样例注释原文："takes precedence over the features turned on from the advanced configuration page"）。

（6）GALETTE_URI——实例 URI（1.3.0 起迁入偏好 pref_galette_url）：

//define('GALETTE_URI', 'https://galette.example.com');

本实例对外完整 URL，cron 脚本等无 HTTP 请求上下文的场景需要它。文件里定义仍有效且优先，但高级配置页会显示锁定并告警，官方建议改用后台设置（样例注释原文："Prefer removing it from this file"）。本站实测数据库值为空串：

nom_pref             val_pref
pref_galette_url     (空)

生产模板里应填上真实 URL（见第六章）。

（7）GALETTE_X_FORWARDED_FOR_INDEX——反代下取真实 IP（迁入 pref_x_forwarded_for_index）：

//define('GALETTE_X_FORWARDED_FOR_INDEX', 1);

站点在反向代理之后时，从 X-Forwarded-For 头解析客户端真实 IP；值 = 从头部末尾起数的索引（最简单单反代场景取 1），0 表示禁用。官方注释同时警告：不在代理之后就不要设——否则客户端可伪造该头隐匿来源。本站（无反代）实测值为 0。

（8）GALETTE_TIMEOUT——会话时长（迁入 pref_session_timeout）：

//define('GALETTE_TIMEOUT', 0);

会话 Cookie 生命周期（秒），0 = 关浏览器即失效（PHP session.cookie_lifetime 语义）。本站实测值为 0。

💡 技术拓展：Web 应用的"会话保持时长"有两种常见策略——滑动过期（每次活动刷新过期时间，适合管理后台）与绝对过期（登录后固定时长强制重登，适合高安全场景）。Galette 的 GALETTE_TIMEOUT 语义对应 PHP 会话 Cookie 生命周期，0 即"浏览器会话级"，属于滑动类；需要绝对过期可在反代或 PHP 层另设 session.gc_maxlifetime。本站实际保持默认 0。

5.3 实例信息与站点参数（偏好层）

数据库 galette_preferences 表中的基础站点参数，本站实测值（mariadb 直查回显）：

nom_pref                      val_pref
pref_lang                     en_US
pref_theme                    default
pref_nom                      Galette
pref_slogan                   (空)
pref_session_timeout          0
pref_x_forwarded_for_index    0
pref_galette_url              (空)
pref_footer                   (空)

逐项说明：pref_lang 站点默认语言（本站安装时选 en_US，可改 zh-CN 等已安装语言包）；pref_theme 界面主题；pref_nom/pref_slogan 组织名称与口号（页面标题、PDF 单据抬头来源）；pref_footer 页脚文本；pref_session_timeout/pref_x_forwarded_for_index/pref_galette_url 即 5.2 节三个"迁入"参数的数据库侧真身。修改入口：Settings 页顶部区块。

5.4 邮件参数

Galette 1.3.0 起邮件发送方式收敛为 4 种（QMAIL 与 Gmail 方式被移除）。Settings 页 pref_mail_method 单选项实测（HTML 表单原文）：

value=0  Emailing disabled            （默认选中）
value=1  PHP mail() function
value=2  Using a SMTP server (slower)
value=5  Using Sendmail server

本站实测数据库当前值 pref_mail_method = 0（禁用群发）。配套参数组（Settings 页表单字段名）：

1.3.1 新增了保存前连接测试（官网公告原文："Email settings can be tested before being saved, with a connection check"），SMTP 参数填完可先测连通再落库。1.3.0 的分批发送配额参数（两信间隔、时/日配额）位于高级配置页（官网公告将其截图标注为 "Batch sending settings in the advanced configuration"）。

💡 技术拓展：服务器发信的四种路径对比——PHP mail()（值 1）调用本地 MTA 的 sendmail 包装器，零配置但依赖本机邮件栈；Sendmail（值 5）直接走本地 sendmail 二进制，语义与 1 接近；SMTP（值 2）直连远程邮件服务器，可认证可加密，是中继到专业邮件服务商的正路，速度慢一点（页面原话 slower）但可控性最好；disabled（值 0）关闭全部出站邮件。生产自托管推荐值 2 + 独立 SMTP 账号；本站隔离实验环境保持默认 0。本方案实际采用默认禁用（0），理由是实验环境无外发需求，避免误发。

5.5 会员与会籍参数

会籍与会员列表相关的核心偏好，本站实测值：

nom_pref                       val_pref
pref_membership_ext            12
pref_membership_offermonths    0
pref_beg_membership            (空)
pref_statut                    9
pref_numrows                   30
pref_default_paymenttype       3

逐项说明：pref_membership_ext=12——标准会籍时长 12 个月（缴费到期日按它推算）；pref_membership_offermonths=0——赠送月数（年中入会优惠类政策），0 不赠送；pref_beg_membership——固定会籍起始日（如全体会员统一 1 月 1 日过期则填该日，留空则按各自缴费日推算）；pref_statut=9——新会员默认身份（9 对应默认成员状态枚举）；pref_numrows=30——列表每页行数；pref_default_paymenttype=3——默认缴费方式，枚举实测（Settings 页下拉原文）：1=Cash、2=Credit card、3=Check、4=Transfer、5=Paypal、6=Other、8=Stripe、9=HelloAsso。

5.6 自助服务与公开页开关

控制"会员能自助做什么、访客能看什么"的布尔开关，本站实测值：

nom_pref                        val_pref
pref_bool_selfsubscribe         1
pref_bool_publicpages           1

说明：pref_bool_selfsubscribe=1 开启自助注册（注册页含邮箱、登录名与验证码，1.3.1 官网公告明确这三项始终显示）；pref_bool_publicpages=1 开启公开页路由；pref_publicpages_visibility_* 组（memberslist/stafflist/membersgallery/staffgallery/documents/generic 六项，Settings 页表单实测字段）按页面粒度控制公开可见性。1.3.1 起 pref_disable_members_socials 可整体关闭会员社交链接字段。

5.7 群组管理员授权矩阵

Galette 的群组管理员（groups managers）默认只能管本群成员，1.3.1 将其权限细粒度化。Settings 页实测表单字段共 9 个开关（字段名即授权项）：

pref_bool_groupsmanagers_are_staff            群管视同工作人员
pref_bool_groupsmanagers_create_member        允许群管新建会员
pref_bool_groupsmanagers_edit_member          允许群管编辑会员
pref_bool_groupsmanagers_create_contributions 允许群管录入缴费
pref_bool_groupsmanagers_see_contributions    允许群管查看缴费
pref_bool_groupsmanagers_create_transactions  允许群管录入交易
pref_bool_groupsmanagers_see_transactions     允许群管查看交易
pref_bool_groupsmanagers_mailings             允许群管发群邮件
pref_bool_groupsmanagers_exports              允许群管使用导出

这些开关是全局性的授权上限；群管实际权力始终还受"其名下群组"约束。1.3.1 补齐了两项能力（官网公告原文）：群管可编辑自己的档案、可获取其成员的收据与发票。

5.8 密码策略参数

会员密码强度策略三件套，本站实测值：

nom_pref                    val_pref
pref_password_length        6
pref_password_strength      0
pref_password_blacklist     0

说明：pref_password_length=6 最短 6 位（与安装器对超管密码的 6 位下限一致）；pref_password_strength=0 强度档位（0 弱，档位越高要求的字符类别越多，1.3.1 的密码强度指示器会逐条列出规则与达标情况——官网公告原文："The password strength indicator lists the rules, and which ones are met"）；pref_password_blacklist=0 是否启用弱口令黑名单校验。1.3.1 起该指示器也出现在会员表单上。

5.9 会员卡与标签打印参数

PDF 会员卡（pref_card_* 13 项）与通信标签（pref_etiq_* 9 项）两组几何/样式参数，Settings 页实测字段：

卡片：pref_card_abrev（组织缩写）, pref_card_address, pref_card_strip, pref_card_year,
      pref_card_hsize/vsize（卡尺寸）, pref_card_hspace/vspace（间距）,
      pref_card_marges_h/v（页边距）, pref_card_tcol/bcol/hcol/scol（四区配色）
标签：pref_etiq_cols/rows（行列数）, pref_etiq_hsize/vsize（标签尺寸）,
      pref_etiq_hspace/vspace（间距）, pref_etiq_marges_h/v（页边距）, pref_etiq_corps（字号）, pref_etiq_border（边框）

1.3.0 起"自适应会员卡"成为默认模板（官网公告原文："The adaptive PDF member card is now the default one"），自适应模式下几何参数的作用弱化；Settings 页还实测到配套项 pref_force_picture_ratio/pref_member_picture_ratio（头像纵横比控制），1.3.0 同时把最大上传尺寸改为按文件类型分别设置（官网公告原文）。

5.10 特性开关（feature flags）

特性开关是 1.3.x 引入的实验特性门控机制，注册表在 includes/sys_config/feature_flags.inc.php。用官方命令实测当前状态：

cd /var/www/galette-1.3.1
sudo -u www-data php bin/console galette:feature:status

实测回显：

Galette Feature Flags Status
===================================


All Feature Flags
-----------------

 --------------------- ------------ -------- ---------------------------------------------- -------------- ------------- -------------
  Flag Name             Status       Source   Description                                    Dependencies   State         Note
 --------------------- ------------ -------- ---------------------------------------------- -------------- ------------- -------------
  two-factor-required   ✗ DISABLED   -        Mandatory two-factor authentication policies                  [available]   not enabled
 --------------------- ------------ -------- ---------------------------------------------- -------------- ------------- -------------

Statistics:
  - Total registered flags: 1
  - Enabled flags: 0
  - Declared (config, environment, database): 0
  - Used in code: 0

 ! [NOTE] No flags are currently enabled. Turn them on from the advanced
 !        configuration page or with galette:feature:enable.

解读：1.3.1 只注册了一个可用开关 two-factor-required（强制两步验证策略，状态 Testing，目标版本 1.4.0——源码注释原文）；两步验证本身在 1.3.0 已内置但默认关闭。开关三种修改途径：后台高级配置页的 feature 区块、命令行 galette:feature:enable two-factor-required / galette:feature:disable two-factor-required、或在 behavior.inc.php 用 GALETTE_FEATURE_FLAGS 强制声明（优先级最高）。源码注释中另有三个规划中未注册的 flag：acls（RBAC 权限系统重做，In Development）、oauth2（API 认证，Planning）、api-v2（REST API v2，Planning，依赖前两者）——它们预示了 Galette 的 API 化方向。

5.11 只读与系统标识参数

高级配置页可见、无需人工改动的系统参数（本站实测值）：

nom_pref                    val_pref
pref_instance_uuid          (空)
pref_registration_uuid      Q8Q56jrHjv2typeV3HCFSOasgtwgMvA58NqDPnNd
pref_telemetry_date         (空)
pref_admin_login            admin
pref_admin_pass             $2y$10$aURExh2xFfUHxIYHCIXdhuQobXHxfa2pFsm/b/ddryOizcqj4dMzO

说明：pref_registration_uuid 实例注册标识（遥测与官方统计用）；pref_admin_pass 为 bcrypt 哈希（$2y$10$ 前缀），不存明文——忘记超管密码用命令行重置 galette:superadmin:password，禁止直接改表；1.3.0 起超管凭据也可在后台"我的信息"（My information）页修改（官网公告原文）。

六、生产配置模板

适用场景：中小型协会（数百至数千会员）的自托管生产实例，2C4G 起、NVMe 磁盘、站点位于反代之后、邮件走外部 SMTP 中继。逐文件给出推荐配置：

（1）config/config.inc.php（连接层，安装器生成后按需微调）：

<?php
define('TYPE_DB', 'mysql');
define('HOST_DB', 'localhost');
define('PORT_DB', '3306');
define('USER_DB', 'galette');
define('PWD_DB', 'q1w2e3r4');
define('NAME_DB', 'galette');
define('PREFIX_DB', 'galette_');

说明：单机部署保持 localhost；数据库独立部署时改 HOST_DB 并确认远程账号只授予六项权限；本文件含明文口令，属主必须为 Web 运行用户（安装器生成的实际属主即 www-data:www-data，实测 ls -la 回显 -rw-r--r-- 1 www-data www-data 216）。

（2）config/behavior.inc.php（覆写层，从 dist 复制后建议只保留以下常量）：

<?php
/**
 * 生产覆写：站点位于单层反代之后，取 X-Forwarded-For 末位真实 IP
 */
define('GALETTE_X_FORWARDED_FOR_INDEX', 1);

/**
 * 生产覆写：会话 2 小时过期（秒）
 */
define('GALETTE_TIMEOUT', 7200);

/**
 * 生产覆写：cron 场景的实例 URI（与后台 pref_galette_url 保持一致更佳）
 */
define('GALETTE_URI', 'https://galette.example.com');

说明：调试、SQL 调试、日志级别三件不要在生产设置（保持默认 WARNING）；MAINT/DEMO 模式仅维护窗口临时启用；覆写型常量优先用后台偏好（高级配置页不显示锁定告警），文件覆写只在偏好层无法生效时使用（如数据库不可达时的实例 URI）。

（3）偏好层（后台 Settings 页 + 高级配置页）推荐基线：

pref_galette_url             https://galette.example.com     # cron 与邮件里的绝对链接
pref_session_timeout         7200                             # 与覆写层一致（二选一即可）
pref_x_forwarded_for_index   1                                # 反代后取真实 IP
pref_membership_ext          12                               # 年度会籍
pref_numrows                 30                               # 列表每页行数
pref_password_length         10                               # 提升最短长度
pref_password_strength       2                                # 提高强度档位
pref_password_blacklist      1                                # 启用弱口令黑名单
pref_bool_selfsubscribe      1                                # 开自助注册（按需）
pref_mail_method             2                                # SMTP 中继
pref_mail_smtp_host / port / auth / user / password / secure  # SMTP 三件套按服务商填
pref_email / pref_email_nom / pref_email_reply_to               # 发件三要素

💡 说明：SMTP 方式（值 2）虽标注 slower，但生产外发可交付性与可追溯性最好；1.3.1 的保存前连接测试可先验证参数再落库。两步验证在 1.3.x 是实验特性：先给超管个人开启试用，全站强制需要 two-factor-required flag（目标 1.4.0 转正）。

七、常见问题（FAQ）

Q1：后台改了参数没生效？

按层级排查：行为覆写层（behavior.inc.php）优先级最高，若其中定义了同名常量，后台改动会被文件值压制且高级配置页显示该项锁定——删除文件中对应 define 即恢复偏好层控制；文件层改动无需重启，但 PHP 的 OPcache 可能缓存少量引导文件，极端情况 systemctl reload apache2 刷新。

Q2：改数据库偏好直接 UPDATE 表可以吗？

可以但不推荐：偏好层有格式与联动校验（如布尔项只收 0/1、邮件方式与 SMTP 参数组联动），Settings 页会做完整校验；直改表绕过校验，适合只读排查与批量审计，常规变更走后台。

Q3：pref_galette_url 不配会怎样？

浏览器访问时 Galette 能从请求推断 URI，日常页面无感；但 cron 脚本、命令行任务与部分邮件里的绝对链接拿不到请求上下文，官方注释明确 GALETTE_URI/pref_galette_url 就是给这类场景用的（"needed by cron scripts which have no incoming request to guess it from"）。生产必配。

Q4：密码策略调严后老会员会被锁吗？

不会。pref_password_* 只约束新密码（注册、改密、找回重置），已有口令不追溯；会员下次改密时才按新策略校验。

Q5：如何确认某参数的"文件值"还是"数据库值"在生效？

高级配置页每项都标注三态（默认值/已修改/锁定，官网公告原文）——显示锁定即被 behavior.inc.php 覆写；命令行侧可用 galette:feature:status 看 flags 的 Source 列（config/environment/database 三个来源）。数据库终值随时可用第三节的 SQL 复核。

八、参考链接

• 官方样例配置（config.inc.php.dist / behavior.inc.php.dist，随安装包分发）：galette-1.3.1.tar.bz2 内 galette/config/ 目录
• 特性开关注册表源码：galette/includes/sys_config/feature_flags.inc.php
• 官网 1.3.0 发布公告（高级配置页、分批发送、行为参数迁移说明）：https://galette.eu/site/post/2026/10/03/galette-1-3-0/
• 官网 1.3.1 发布公告（密码指示器、群组管理改进）：https://galette.eu/
• 官方变更日志：https://doc.galette.eu/en/develop/changelog.html
• 本专栏选型背景：《Galette 1.3.1 介绍与选型指南》
• 本专栏安装过程：《Ubuntu 22.04 安装 Galette 1.3.1 指南》