Teampass 3.2.3.2 配置参数详解

目标：把 Teampass 3.2.3.2 安装后散落在三个层面的配置（数据库 teampass_misc 表的站点参数全集、settings.php 数据库连接层、PHP_* 运行时层）一次讲清：参数存在哪里、怎么查看、怎么修改才生效、每类核心参数的实测行为与生产推荐值。已在 Ubuntu 宿主机（Docker 29.8.1）部署的 Teampass 3.2.3.2 实例上实测通过，全部参数值、修改回执与验证查询均为真实执行记录。

一、环境信息

• 实例版本：Teampass 3.2.3.2（teampass_misc 表 teampass_version=3.2.3、镜像常量 TP_VERSION_MINOR=2 实查一致）
• 部署形态：应用 + MySQL 8.0 双服务（服务端 8.0.46），部署过程见《Teampass 3.2.3.2 Docker Compose 部署指南》
• 应用内 PHP：8.3.35；站点 URL：http://192.168.146.128:8144/（安装向导写入）
• 参数存储位置（本文三大层）：
  1. 数据库表 teampass_misc（站点参数全集，type=admin 共 294 项，另 type=complex 2 项、cron 1 项、timestamp 1 项）；
  2. 文件 /var/www/html/storage/config/settings.php（数据库连接常量，1192 字节配置树中的 1048 字节文件）；
  3. PHP 运行时 /usr/local/etc/php/conf.d/teampass-env.ini（由镜像 entrypoint 按 PHP_* 环境变量生成）。

二、前置条件

1. 已完成 3.2.3.2 安装向导并能以管理员登录（维护模式已关闭）；
2. 具备数据库只读查询能力（直连 MySQL 或容器内 mysql 客户端），用于核对参数落库值；
3. 管理员后台设置页面可用（参数修改的首选通道）；
4. 了解基础加密事实：teampass_misc 中标记 is_encrypted=1 的参数值为密文（如 bck_script_passkey、duo_skey、ldap_password、email_auth_pwd），不可手改。

三、参数查看与修改方式

3.1 查看：后台界面与数据库直查

后台「管理 → 设置」按功能分页展示全部参数，适合日常查看。需要全景或核对落库值时直查数据库（实测命令）：

docker exec teampass-3.2.3.2-db mysql -uteampass -pq1w2e3r4 teampass \
  -e "SELECT type, COUNT(*) FROM teampass_misc GROUP BY type;"

docker exec teampass-3.2.3.2-db mysql -uteampass -pq1w2e3r4 teampass \
  -e "SELECT intitule, IF(is_encrypted=1,'<enc>',valeur) AS v
      FROM teampass_misc WHERE type='admin' ORDER BY intitule;"

实测回显（节选）：

admin      294
complex      2
cron         1
timestamp    1

3.2 修改：后台设置界面（推荐）

管理员在后台修改任意参数，保存即写库生效。实测样例：把剪贴板清空时长 clipboard_life_duration 从 30 改为 60，保存后直查数据库：

intitule                 valeur   updated_at
clipboard_life_duration  60       1792835759

updated_at 同步刷新，无需重启任何服务。

3.3 修改：程序化接口（同写库路径）

后台保存走的是同一个后端接口（admin.queries.php 的 save_option_change），自动化场景可程序化调用。实测（关闭维护模式）：

• 请求载荷 {field: "maintenance_mode", value: "0"}
• 实测回执 {"error":false,"misc":"1 ; 0","message":""}（回显变更痕迹，库里 1 改 0）
• 随后普通用户登录立即不再被维护模式拦截

接口对个别字段有服务端校验（实测可见：nb_bad_authentication、bruteforce_lock_duration、api_rate_limit_per_minute 强制非负整数；bruteforce_lock_duration 传 0 会被纠正为 10）。

3.4 修改：直接改数据库（仅限非加密项，慎用）

UPDATE teampass_misc SET valeur='...' WHERE type='admin' AND intitule='...' 技术上可行（参数即普通行），但要注意：加密项（is_encrypted=1）写入明文后应用无法解密使用；直接改库绕过接口的取值校验。除批量初始化场景外建议走 3.2/3.3 通道。

3.5 数据库连接层与运行时层的修改边界

settings.php 中的数据库连接常量由安装向导生成，其中 DB_PASSWD 是 Defuse 密文（实测值形态 def50200...，与 secrets/ 主密钥文件配套），不能手写明文口令进去；变更数据库口令无法通过手改该文件完成。PHP_* 运行时参数通过 compose 环境变量修改后需重建应用服务（entrypoint 重新生成 teampass-env.ini）。

四、参数总览

294 项站点参数按存储与加密属性总览（实测统计）：

另有一批参数不在 teampass_misc 而在文件/环境层，统一口径见第五、十四节与第五、十三节。

五、核心参数分类详解

5.1 站点与路径

5.2 会话与登录安全

5.3 双因素认证

启用 TOTP 后 admin_2fa_required=1 即对管理员生效；独立的 TOTP 管理可配合 《2FAuth 8.0.3 介绍与选型指南》自托管验证器。

5.4 密码与复杂度

• 复杂度档位为固定枚举：0 / 20 / 38 / 48 / 60 五档（对应后台五档描述）。实测给文件夹传 64 直接报 Undefined array key 64；teampass_misc 中 type=complex 两行记录了实测文件夹的档位（均 48）。
• security_dashboard_min_password_length=12：安全仪表盘的最小口令长度评分基线（注意与安装向导的 10 位硬性策略是两回事）。
• use_md5_password_as_salt=0：保持关闭（旧版兼容项）。
• enable_local_password_recovery=1：本地密码找回，无邮件服务器时会受影响。

5.5 条目与文件夹行为

5.6 个人空间与知识库

5.7 API

5.8 邮件与通知

email_smtp_server/email_smtp_auth/email_auth_username/email_auth_pwd（后两者密文）/email_from/email_security/email_smtp_verify_certificate=1 组成 SMTP 配置组；emails_templates_enabled=1 启用模板；enable_send_email_on_user_login=0 控制登录通知；sending_emails_job_frequency=2 为发信任务频率。未配置 SMTP 时用户创建流程仍可用（实测创建用户后接口直接回传自动生成口令），但找回密码、邮件通知类功能不可用。

5.9 LDAP 目录认证

ldap_mode=0（本地认证）、ldap_port=389、ldap_ssl=0、ldap_tls=0、ldap_and_local_authentication=0；启用时需配 ldap_hosts/ldap_password/ldap_bdn（三项均密文存储）、ldap_user_attribute、ldap_group_objectclasses_attibute（实测默认值 top,groupofuniquenames，注意该参数名拼写即为官方原样）等。AD/LDAP 组到角色的映射经 ldap_groups_roles 表落地。

5.10 附件与上传

5.11 任务与后台处理

5.12 加密与密钥治理

5.13 数据库连接层（settings.php）

安装向导生成的 /var/www/html/storage/config/settings.php 实测全文（口令密文截断展示）：

<?php
define("DB_HOST", "db");
define("DB_USER", "teampass");
define("DB_PASSWD", "def502000a853d76eb93aa454e37c43ed363974eadc03a8578f8a…");
define("DB_NAME", "teampass");
define("DB_PREFIX", "teampass_");
define("DB_PORT", "3306");
define("DB_ENCODING", "utf8mb4");
define("DB_SSL", false); // if DB over SSL then comment this line
define("DB_CONNECT_OPTIONS", array(
    MYSQLI_OPT_CONNECT_TIMEOUT => 10
));
define("SECUREFILE", "ge6zX3sOqVEuhZoai9jeANbBcTxogTQgcu5KbfYT");
if (isset($_SESSION['settings']['timezone']) === true) {
    date_default_timezone_set($_SESSION['settings']['timezone']);
}

要点：DB_PASSWD 为 Defuse 密文（def50200 前缀），解密主密钥在 secrets/<SECUREFILE> 指向的随机名文件（实测 136 字节，目录 0700、文件 0600，属主 nginx:nginx）；DB_SSL 改 true 并配套证书可启用数据库传输加密。该文件经符号链接持久化到 storage/config/（机制详见部署指南持久化章节）。

5.14 运行时 PHP 层（环境变量）

entrypoint 按环境变量生成 teampass-env.ini，实测默认：memory_limit=512M、upload_max_filesize=100M、post_max_size=100M、max_execution_time=120。调整方式为改 compose 环境变量后重建应用服务，变量清单见部署指南环境变量表。

六、生产配置模板

两档按团队规模划分的推荐基线（均基于 5.x 实测语义；磁盘按 5 年附件与日志增量估算）：

小团队（≤50 人、2 条目/人/周；4GB 内存 / 40GB 磁盘）

中型团队（200 人、附件重度使用；8GB 内存 / 200GB 磁盘，PHP 内存可提至 512M 默认不变）

在小型基线上追加：

七、常见问题

Q1：后台改了参数，数据库里查到的还是旧值？ 确认改的是同一参数名（intitule 区分大小写）；确认没有第二个写入口在覆盖（如安装向导重跑会把 cpassman_url 等重写）。程序化修改走 save_option_change 与后台同路径，实测即时落库（回执 {"error":false,"misc":"1 ; 60"}、直查 valeur=60）。

Q2：<enc> 参数（如 ldap_password、duo_skey、email_auth_pwd）在数据库里看到乱码/密文，能直接 UPDATE 吗？ 不能。这些行 is_encrypted=1，应用读取时按密文解密，写入明文会导致功能异常。修改唯一正道是后台设置界面重新录入。

Q3：为什么管理员没配 2FA 也能登录，admin_2fa_required 不是 1 吗？ 该参数只在至少一种双因素提供者（google_authentication/yubico_authentication/duo）启用时生效，这是实测确认的代码语义。要强制管理员 2FA，先启用 TOTP 提供者。

Q4：文件夹复杂度设成 64 报错？ 复杂度是固定五档枚举（0/20/38/48/60），传 64 后端报 Undefined array key 64。已建文件夹可通过后台编辑修正档位（实测 64→48 修正成功）。

Q5：手改 settings.php 把 DB_PASSWD 写成明文会怎样？ 应用按 Defuse 密文解密该字段，明文会导致数据库连接失败。数据库口令变更不能手写此文件；部署时应把数据库口令视为随安装固化的稳定值（配合卷持久化），变更需按官方升级/迁移流程处理。

Q6：安装后普通用户登录报 maintenance_mode_enabled？ 全新安装默认维护模式开启，后台关闭即可（实测 1 → 0 后普通用户立即可登录），详见部署指南 FAQ。

Q7：删除的用户名重建报 User already exists？ 软删除设计：删除即改名保留记录，重名校验覆盖软删除行。需走「恢复用户」；测试环境彻底重建的数据库清理方法见部署指南 FAQ Q5。

八、参考链接

• 《Teampass 3.2.3.2 介绍与选型指南》（同专栏，版本背景）
• 《Teampass 3.2.3.2 Docker Compose 部署指南》（同专栏，参数的载体——卷、settings.php 与环境变量的落点机制）
• Teampass 官方文档站（Settings 章节组）：https://documentation.teampass.net
• Teampass 官方代码仓库（app/sources/admin.queries.php、app/sources/core.php 参数处理实现）：https://github.com/nilsteampassnet/TeamPass
• 独立 TOTP 验证器选型参考：《2FAuth 8.0.3 介绍与选型指南》
• 同类密码库对比：《PassIt 1.25.0 介绍与选型指南》、《Psono v7.5.3 介绍与选型指南》