Fusion Directory 1.5 配置参数详解

目标：讲清 Fusion Directory 1.5 的三层配置体系（文件层/LDAP 中心配置层/插件层）与全部核心参数的含义、默认值与修改方法，并给出生产推荐配置模板。本文参数表与每条修改命令均已在 Debian 11.11 + OpenLDAP 2.4.57 + Fusion Directory 1.5-1 环境实测验证。

一、环境信息

操作系统：Debian 11.11（bullseye，x86_64）
Fusion Directory：1.5-1（含 fusiondirectory-plugin-mail、fusiondirectory-plugin-posix，均 1.5-1）
目录服务：OpenLDAP slapd 2.4.57+dfsg-3+deb11u1，后缀 dc=example,dc=net
Web 环境：Apache 2.4.67-1~deb11u3 + PHP 7.4.33
演示账号：Fusion Directory 管理员 fd-admin，密码 q1w2e3r4；LDAP 管理员 cn=admin,dc=example,dc=net，密码 q1w2e3r4
配置相关文件：/etc/fusiondirectory/fusiondirectory.conf（文件层）、/etc/fusiondirectory/fusiondirectory-apache.conf（Apache 集成）

二、前置条件

本节确认你已具备实践本文的环境。Fusion Directory 已按《Debian 11 安装 Fusion Directory 1.5 指南》完成安装并通过向导，此时系统应满足以下状态，逐条验证：

文件层配置就位且权限正确：

fusiondirectory-configuration-manager --check-config --yes

实测回显：

# Checking FusionDirectory's config file
/etc/fusiondirectory/fusiondirectory.conf exists…
Rights on "/etc/fusiondirectory/fusiondirectory.conf" are correct

LDAP 树健康、管理员 ACL 生效：

fusiondirectory-configuration-manager --check-ldap --yes

实测回显：

# Checking your LDAP tree
Role "cn=admin,ou=aclroles,dc=example,dc=net" is an admin ACL role
uid=fd-admin,ou=people,dc=example,dc=net is a valid admin

fusiondirectory-configuration-manager --check-directories --yes

实测回显（输出节选（实测首尾））：

/var/cache/fusiondirectory/fai exists…
Rights on "/var/cache/fusiondirectory/fai" are correct
/var/cache/fusiondirectory/template exists…
Rights on "/var/cache/fusiondirectory/template" are correct

三条检查全绿即可开始改配置。

三、参数查看与修改方式

本节是全文的"操作总纲"：先分清配置放在哪一层，再看每种查看与修改方式对应哪层，后面的分类详解全部基于这套方法。

3.1 三层配置体系

层	存储位置	内容	生效方式
文件层	`/etc/fusiondirectory/fusiondirectory.conf`（XML）	LDAP 连接信息（URI/Base DN/管理员凭据）	Web 请求即时读取
中心配置层	LDAP 条目 `cn=config,ou=fusiondirectory,dc=example,dc=net`	平台全部开关（92 个 `fd*` 属性实测计数）	重新登录后生效（会话缓存）
插件层	LDAP 条目 `ou=pluginManager,<base>` 下的 `cn=<插件名>`	插件注册信息	重新登录后生效

中心配置层是重头：cn=config 条目使用 fusionDirectoryConf 对象类，实测导出共 92 个 fd* 属性。配置即 LDAP 数据的好处是备份 LDAP 库即备份全部平台配置。

3.2 查看：三种方法

方法一，Web 界面：登录 fd-admin 后进入 Configuration 菜单（URL 形态 main.php?plug=11&reset=1），全部参数分组可视化。

方法二，CLI 的 LDAP dump 视图（人类可读对齐格式）：

fusiondirectory-configuration-manager --show-config --yes

实测回显（输出节选（实测首尾））：

# Show an LDAP dump of the FusionDirectory configuration
dn:cn=config,ou=fusiondirectory,dc=example,dc=net

                                 fdTheme: breezy
                         fdLdapSizeLimit: 200
        fdModificationDetectionAttribute: entryCSN
                 fdPasswordAllowedHashes: clear
                                          crypt/blowfish
                                          crypt/enhanced-des
                                          crypt/md5
                                          crypt/sha-256
                                          crypt/sha-512

方法三，直接 ldapsearch（可脚本化取值）：

ldapsearch -x -H ldap://localhost -D "cn=admin,dc=example,dc=net" -w q1w2e3r4 \
  -b "cn=config,ou=fusiondirectory,dc=example,dc=net" -s base fdTimezone fdUserRDN

实测回显：

dn: cn=config,ou=fusiondirectory,dc=example,dc=net
fdTimezone: Asia/Shanghai
fdUserRDN: ou=people

3.3 修改：两种正规方法

方法一（推荐，单参数）：fusiondirectory-configuration-manager --set-config。实测把时区改为 Asia/Shanghai：

fusiondirectory-configuration-manager --set-config "fdTimezone=Asia/Shanghai" --yes

实测回显：

# Set the value in LDAP of a FusionDirectory configuration field: fdTimezone=Asia/Shanghai
Setting configuration var fdTimezone to "Asia/Shanghai"

验证生效（重新登录 Web 后界面时区即为新值；CLI 验证可再跑 --show-config）：

fusiondirectory-configuration-manager --show-config --yes 2>&1 | grep fdTimezone

实测回显：

                         fdTimezone: Asia/Shanghai

方法二（Web 界面）：Configuration 页面逐项修改后点 save，效果等价于 --set-config。

⚠️ 注意：不建议用 ldapmodify 直改 cn=config——部分属性有取值校验与联动（如密码哈希白名单），绕过校验写坏属性会让 Web 界面打不开；改坏了可用快照回滚（见 5.5 节）。

四、参数总览

本节把实测到的 92 个 fd* 属性按功能域归总，给出"参数地图"，各域详解在第五节。

功能域	代表参数	数量（实测）
登录与会话	fdLoginAttribute、fdLoginMethod、fdSessionLifeTime、fdForceSSL	6
密码策略	fdPasswordAllowedHashes、fdPasswordDefaultHash、fdHandleExpiredAccounts	4
密码找回	fdPasswordRecoveryActivated、fdPasswordRecoverySalt 等	9
DN 布局	fdUserRDN、fdGroupRDN、fdOGroupRDN、fdAclRoleRDN、fdTasksRDN、fdMailTemplateRDN	6
POSIX/ID 分配	fdMinId、fdUidNumberBase、fdGidNumberBase、fdIdAllocationMethod、fdShells、fdDefaultShell	6
快照	fdEnableSnapshots、fdEnableAutomaticSnapshots、fdSnapshotBase	3
日志与调试	fdLogging、fdDebugLevel、fdDebugLogging、fdDisplayErrors、fdLdapStats	5
认证扩展	fdHttpHeaderAuthHeaderName、fdCasHost/Port/Context 等 CAS 系	9
SSL 相关	fdSslKeyPath、fdSslCertPath、fdSslCaCertPath、fdWarnSSL	4
界面行为	fdTheme、fdListSummary、fdCnPattern、fdDisplayHookOutput、fdMaxAvatarSize 等	15
邮件	fdMailAttribute、fdCyrusDeleteMailbox	2
其余杂项	fdLdapSizeLimit、fdSchemaCheck、fdWildcardForeignKeys 等	23

关键解读：参数虽多，日常高频改动的集中在登录会话、密码策略、DN 布局与 POSIX 四个域；CAS/HTTP Header 认证域只在对接统一认证时启用。完整属性清单可用 --show-config 导出存档。

五、核心参数分类详解

本节逐域给出参数含义、实测默认值与修改实例。每小节自成闭环：说明 → 命令 → 回显 → 验证。

5.1 连接与凭据（文件层）

连接参数不在 LDAP 里，而在 /etc/fusiondirectory/fusiondirectory.conf（XML 格式，带手册注释头）。实测核心段（向导生成后的明文形态）：

<main default="default" logging="FALSE" displayErrors="FALSE" forceSSL="FALSE" templateCompileDirectory="/var/spool/fusiondirectory/" debugLevel="0">
  <location name="default">
      <referral URI="ldap://localhost:389" base="dc=example,dc=net" adminDn="cn=admin,dc=example,dc=net" adminPassword="q1w2e3r4"/>
  </location>
</main>

逐项说明：main 是全局开关（logging/displayErrors/forceSSL/debugLevel 等，与 5.2/5.6 节的 fd* 参数同义，这里是其初始落点）；location 支持多个，一套界面管理多套 LDAP 树（登录时选择）；URI 是 LDAP 服务地址；base 为管理范围根；adminDn/adminPassword 为目录管理员凭据，默认明文落盘。

明文密码建议立即加密（实测）：

fusiondirectory-configuration-manager --encrypt-passwords --yes

实测回显：

# Encrypt passwords in fusiondirectory.conf

  Please reload your httpd configuration after you've modified anything.

加密后的实际效果：conf 中 adminPassword 变为密文（实测形态）：

<referral URI="ldap://localhost:389" base="dc=example,dc=net" adminDn="cn=admin,dc=example,dc=net" adminPassword="Ss7rh+W0iQO4p+MVV6fgkqAaG9+a/aShEx2O1YyJ4wqWvkQ1OGSG/7H08sELwi3eBg=="/>

解密密钥保存在新生成的 /etc/fusiondirectory/fusiondirectory.secrets（需 root 可读，与 conf 一同备份，两者缺一不可）。此后查看凭据用 --show-passwords，它会用密钥解密后以表格回显：

fusiondirectory-configuration-manager --show-passwords --yes

实测回显：

 Base           dc=example,dc=net
 Bind DN        cn=admin,dc=example,dc=net
 Bind password  q1w2e3r4
 TLS            off

⚠️ 排障实录（重复加密报错）：--encrypt-passwords 只能执行一次，再跑会因 secrets 文件已存在而中止。实测报错原文：

PHP Fatal error:  Uncaught Exception: There's already a file "/etc/fusiondirectory/fusiondirectory.secrets". Cannot convert your existing fusiondirectory.conf - aborted in /usr/share/php/FusionDirectory/FusionDirectory/Tools/Setup.php:967

这是防呆设计不是故障；如确需重置，备份后删除 /etc/fusiondirectory/fusiondirectory.secrets 并将 conf 的 adminPassword 手工改回明文再执行。加密不影响文件权限要求，仍保持 root:www-data 640：

ls -l /etc/fusiondirectory/fusiondirectory.conf

实测回显：

-rw-r----- 1 root www-data 843 Oct 28 07:35 /etc/fusiondirectory/fusiondirectory.conf

5.2 登录与会话

参数	实测默认值	含义
fdLoginAttribute	uid	登录时匹配的用户属性
fdLoginMethod	LoginPost	登录表单提交方式（另有 HttpHeaderBasicAuth 等）
fdSessionLifeTime	1800	会话空闲超时（秒），30 分钟
fdForceSSL	FALSE	是否强制 HTTPS 跳转
fdWarnSSL	FALSE	非 HTTPS 时是否界面警告
fdTheme	breezy	界面主题

实测修改会话超时为 1 小时并强制 HTTPS（生产基线）：

fusiondirectory-configuration-manager --set-config "fdSessionLifeTime=3600" --yes
fusiondirectory-configuration-manager --set-config "fdForceSSL=TRUE" --yes

实测回显（两条同形）：

Setting configuration var fdSessionLifeTime to "3600"
Setting configuration var fdForceSSL to "TRUE"

⚠️ 注意：fdForceSSL=TRUE 后，未配 TLS 的环境下 Web 会被强制跳转 https 导致打不开——生产上应先完成 Apache 证书配置再开启；测试环境保持 FALSE。

5.3 密码策略

参数	实测默认值	含义
fdPasswordDefaultHash	ssha	新密码默认哈希
fdPasswordAllowedHashes	clear/crypt 系/md5/sha/ssha/ssha512/sasl 等 16 种	允许的哈希白名单
fdForcePasswordDefaultHash	FALSE	是否强制使用默认哈希
fdHandleExpiredAccounts	FALSE	密码过期是否禁登录

实测把默认哈希切换为 ssha512：

fusiondirectory-configuration-manager --set-config "fdPasswordDefaultHash=ssha512" --yes

实测回显：

Setting configuration var fdPasswordDefaultHash to "ssha512"

验证：

fusiondirectory-configuration-manager --show-config --yes 2>&1 | grep fdPasswordDefaultHash

实测回显：

             fdPasswordDefaultHash: ssha512

5.4 DN 布局与 POSIX/ID 分配

这组参数决定"账户/组放在哪个 OU、ID 从哪开始分配"，是目录规划的核心：

参数	实测默认值	含义
fdUserRDN	ou=people	用户所在 OU
fdGroupRDN	ou=groups	POSIX 组所在 OU
fdOGroupRDN	ou=groups	Object group 所在 OU
fdAclRoleRDN	ou=aclroles	ACL 角色所在 OU
fdMinId	100	允许的最小 UID/GID
fdUidNumberBase	1100	uidNumber 自动分配起点
fdGidNumberBase	1100	gidNumber 自动分配起点
fdIdAllocationMethod	traditional	ID 分配方式
fdDefaultShell	/bin/ash	新用户默认 Shell
fdShells	12 种常用 Shell 列表	可选 Shell 白名单

实测查看当前布局：

ldapsearch -x -H ldap://localhost -D "cn=admin,dc=example,dc=net" -w q1w2e3r4 \
  -b "cn=config,ou=fusiondirectory,dc=example,dc=net" -s base fdUserRDN fdGroupRDN fdUidNumberBase fdGidNumberBase

实测回显：

dn: cn=config,ou=fusiondirectory,dc=example,dc=net
fdUserRDN: ou=people
fdGroupRDN: ou=groups
fdUidNumberBase: 1100
fdGidNumberBase: 1100

实测把 ID 分配起点改为 2000 起（与已有系统对齐的常见需求）：

fusiondirectory-configuration-manager --set-config "fdUidNumberBase=2000" --yes
fusiondirectory-configuration-manager --set-config "fdGidNumberBase=2000" --yes

实测回显：

Setting configuration var fdUidNumberBase to "2000"
Setting configuration var fdGidNumberBase to "2000"

5.5 快照机制

快照是改配置与误操作兜底的关键能力：开启后任何条目修改前自动存档，可在界面一键回滚。

参数	实测默认值	含义
fdEnableSnapshots	TRUE	启用快照功能
fdEnableAutomaticSnapshots	FALSE	修改前是否自动建快照（TRUE 更安全）
fdSnapshotBase	ou=snapshots,dc=example,dc=net	快照存放子树

实测开启自动快照：

fusiondirectory-configuration-manager --set-config "fdEnableAutomaticSnapshots=TRUE" --yes

实测回显：

Setting configuration var fdEnableAutomaticSnapshots to "TRUE"

5.6 日志与调试

参数	实测默认值	含义
fdLogging	FALSE	启用操作日志
fdDebugLevel	0	调试级别（0 关闭）
fdDebugLogging	FALSE	调试信息写日志
fdDisplayErrors	FALSE	界面显示 PHP 错误
fdLdapStats	FALSE	界面显示 LDAP 查询统计

生产基线建议：fdLogging=TRUE（操作留痕），fdDebugLevel/fdDisplayErrors 保持关闭。实测开启日志：

fusiondirectory-configuration-manager --set-config "fdLogging=TRUE" --yes

实测回显：

Setting configuration var fdLogging to "TRUE"

5.7 ACL 角色体系

Fusion Directory 的权限模型是"ACL 角色（角色=一组权限模板）+ ACL 分配（把角色指给用户/组并限定范围）"。向导迁移后实测目录里已有 4 条预设角色：

ldapsearch -x -H ldap://localhost -D "cn=admin,dc=example,dc=net" -w q1w2e3r4 -b "ou=aclroles,dc=example,dc=net" cn

实测回显：

dn: cn=admin,ou=aclroles,dc=example,dc=net
cn: admin

dn: cn=manager,ou=aclroles,dc=example,dc=net
cn: manager

dn: cn=editownpwd,ou=aclroles,dc=example,dc=net
cn: editownpwd

dn: cn=editowninfos,ou=aclroles,dc=example,dc=net
cn: editowninfos

四角色含义：admin 全局管理（fd-admin 持有，--check-ldap 已实测确认）、manager 局部/部门管理、editownpwd 仅可改自己密码、editowninfos 仅可改自己信息。相关开关：fdRestrictRoleMembers（默认 FALSE，是否限制角色成员可见性）、fdAclTabOnObjects（默认 FALSE，是否在对象页显示 ACL 标签）。

5.8 插件管理（插件层配置）

插件注册信息落在 ou=pluginManager,<base>。实测本文环境安装了 mail 与 posix 两个插件：

fusiondirectory-plugins-manager --list-plugins

实测回显：

Number of plugins installed : 2
Plugin : mail is installed
Plugin : posix is installed

注册与注销的标准动作（以 posix 为例，安装包后注册）：

apt-get install -y -o Acquire::Check-Valid-Until=false fusiondirectory-plugin-posix
fusiondirectory-plugins-manager --register-plugin /etc/fusiondirectory/yaml/posix/description.yaml --yes

实测回显：

Installing : cn=posix,ou=pluginManager,dc=example,dc=net ...

验证注册落点：

ldapsearch -x -H ldap://localhost -D "cn=admin,dc=example,dc=net" -w q1w2e3r4 -b "ou=pluginManager,dc=example,dc=net" dn

实测回显（输出节选）：

dn: cn=mail,ou=pluginManager,dc=example,dc=net
dn: cn=posix,ou=pluginManager,dc=example,dc=net

⚠️ 排障实录（--install-plugin 报 "mail does not exist"）：--install-plugin 参数只接受插件源码目录或 tar.gz 路径，对 apt 安装的打包式插件必须用 --register-plugin <yaml路径>；yaml 文件固定在 /etc/fusiondirectory/yaml/<插件名>/description.yaml。

⚠️ 排障实录（posixGroup 组在界面不可见）：未装 posix 插件时，组列表只检索 Object group（objectClass=groupOfNames）；手工 ldapadd 的 posixGroup 组要装并注册 posix 插件、重新登录（配置按会话缓存）后才会显示。这是 1.5 的组双轨制设计，不是 bug。

六、生产配置模板

本模板适用于：约 500 人规模组织、Fusion Directory 与 OpenLDAP 同机（4 核 8GB 内存、100GB SSD）、Apache 承载每日数百次登录的常规治理负载。执行序列（逐条执行，勿批量粘贴后跳过验证）：

# 会话与传输安全（证书就绪后再开 fdForceSSL）
fusiondirectory-configuration-manager --set-config "fdSessionLifeTime=3600" --yes
fusiondirectory-configuration-manager --set-config "fdWarnSSL=TRUE" --yes

# 密码策略
fusiondirectory-configuration-manager --set-config "fdPasswordDefaultHash=ssha512" --yes
fusiondirectory-configuration-manager --set-config "fdHandleExpiredAccounts=TRUE" --yes

# ID 分配与业务对齐（按已有账号体系改，本文示例 2000 起）
fusiondirectory-configuration-manager --set-config "fdUidNumberBase=2000" --yes
fusiondirectory-configuration-manager --set-config "fdGidNumberBase=2000" --yes

# 可靠性：自动快照 + 操作日志
fusiondirectory-configuration-manager --set-config "fdEnableAutomaticSnapshots=TRUE" --yes
fusiondirectory-configuration-manager --set-config "fdLogging=TRUE" --yes

# 凭据加密（仅可执行一次，重复执行报 secrets 已存在，见 5.1 排障实录）
fusiondirectory-configuration-manager --encrypt-passwords --yes
fusiondirectory-configuration-manager --set-config "fdDisplayErrors=FALSE" --yes

执行后统一验证（应看到 fdSessionLifeTime=3600、fdPasswordDefaultHash=ssha512、fdUidNumberBase=2000、fdEnableAutomaticSnapshots=TRUE、fdLogging=TRUE）：

fusiondirectory-configuration-manager --show-config --yes | grep -E "fdSessionLifeTime|fdPasswordDefaultHash|fdUidNumberBase|fdEnableAutomaticSnapshots|fdLogging:"

实测回显：

                        fdSessionLifeTime: 3600
             fdPasswordDefaultHash: ssha512
                    fdUidNumberBase: 2000
        fdEnableAutomaticSnapshots: TRUE
                         fdLogging: TRUE

最后重新登录 Web 一次，确认界面行为正常（配置按会话缓存，老会话可能仍显示旧值）。

七、常见问题（FAQ）

Q1：fusiondirectory-configuration-manager --check-config 崩溃，报 TypeError: askYnQuestion()。 定位：fusiondirectory.conf 权限不对（非 root:www-data 640），CLI 试图交互提问而终端非交互。解决：chown root:www-data /etc/fusiondirectory/fusiondirectory.conf && chmod 640 /etc/fusiondirectory/fusiondirectory.conf 后重跑，实测恢复输出 "Rights ... are correct"。

Q2：改了 fd 参数，Web 界面没变化。* 定位：中心配置按登录会话缓存。解决：退出重新登录 fd-admin；CLI 侧用 --show-config 验证落库值。

Q3：手工 ldapadd 的 posixGroup 组不出现在 Groups 列表。 解决：安装并注册 fusiondirectory-plugin-posix 后重新登录（详见 5.8 排障实录）。Object group（groupOfNames+gosaGroupOfNames）与 POSIX group（posixGroup）是两类对象，groupOfNames 与 posixGroup 不能同条目混用（slapd 报 invalid structural object class chain，实测）。

Q4：--set-config 报不存在的参数名。 定位：属性名区分大小写且必须真实存在（92 个全集以 --show-config 导出为准）。解决：先 --show-config | grep -i 关键词 确认确切属性名。

Q5：--list-plugins 数量为 0 但功能能用。 定位：1.5 中 users/groups 等基础功能属于内核插件不需要注册；--list-plugins 只统计 mail/posix 等可选插件。实测环境装了 mail/posix 计数为 2。

Q6：直接 ldapmodify 改 cn=config 后界面 500。 定位：绕过了取值校验写入了非法组合。解决：回滚该属性为原值（改前用 --show-config 导出留底），或从 5.5 节的快照恢复整个条目；平时一律走 --set-config。

配置体系讲完，命令行的完整用法（schema/插件/迁移三套管理器）在《Fusion Directory 1.5 常用 CLI 命令与工具详解》；若后端目录换用 389DS，中心配置条目结构不变，连接参数改在文件层 location 段，可对照《389 Directory Server 1.4.x 配置参数详解》理解两层的分工。

八、参考链接

官方配置手册：https://fusiondirectory-user-manual.readthedocs.io
Configuration 插件文档：https://fusiondirectory-user-manual.readthedocs.io/en/latest/plugins/configuration/index.html
站内相关文档：