Leantime 3.12.0 配置参数详解

目标：把 Leantime 3.12.0 的配置面讲清——三层配置谁覆盖谁、哪些 LEAN_* 变量是必填、限流与邮件怎么调，以及每次改动后如何用可观测结果确认真的生效。本文所有「改参数 → 重启 → 观测」均在 Ubuntu 22.04.5 LTS + Leantime 3.12.0 + PHP 8.3.36 + MariaDB 10.11.19 的服务上执行，命令与回显于 2026-10-28 照抄。

一、环境信息

配置文件只有一个：/var/www/leantime/config/.env。样例文件 config/sample.env 是官方全量参数清单（约 14 KB，逐项带注释），config/configuration.sample.php 是旧版 PHP 配置，官方已标注 deprecated，不要再用。

二、配置体系：三层，优先级从低到高

Leantime 的配置不是「一个文件说了算」，而是三层叠在一起，排障时必须先判断某个值来自哪层：

第 1、2 层本质是同一套 LEAN_* 变量，作用域不同：写进 .env 的是「文件里的默认值」，写进进程环境的是「运行时的最终值」。第 3 层只覆盖「展示类与业务设置」，不覆盖数据库凭据这类启动参数。

2.1 实测：数据库设置优先于环境变量

先确认当前站点名来自数据库：

mysql -uleantime -pq1w2e3r4 leantime -e \
  "select \`key\`, value from zp_settings where \`key\`='companysettings.sitename';"

实测回显：

key	value
companysettings.sitename	去作项目管理

在 .env 末尾追加同名环境变量并重启：

printf '\nLEAN_SITENAME = "EnvOverride"\n' >> /var/www/leantime/config/.env
systemctl restart php8.3-fpm
curl -s http://192.168.1.71:8141/auth/login | grep -oE '<title>[^<]*</title>'

实测回显：

<title>去作 Leantime 配置实验</title>

标题没有变成 EnvOverride，说明 LEAN_SITENAME 只在安装时作为初始值写入数据库，之后数据库里的 companysettings.sitename 才是唯一事实。反过来，用 CLI 直接改数据库设置则立即生效、无需重启：

cd /var/www/leantime && php bin/leantime setting:save \
  --key=companysettings.sitename --value="去作 Leantime 配置实验"

实测回显：

 [OK] Saved Successfully

随后刷新登录页，<title> 立刻变为 去作 Leantime 配置实验。这条规律可以直接推广：凡是后台「公司设置」「外观」里能改的项，改 .env 不会生效，只能改数据库设置或走 UI。

2.2 哪些参数必须走 .env

• 数据库连接（LEAN_DB_*）：应用启动前就要连库，不可能存在库里；
• 会话盐（LEAN_SESSION_PASSWORD）：决定 cookie 签名；
• SMTP / S3 / LDAP 凭据：属于启动期读取的服务端配置；
• 限流阈值（LEAN_RATELIMIT_*）：中间件在请求早期读取。

三、最小必填项

一个能启动的实例至少要这 6 个变量，缺任意一个都会在安装向导或首访时报错：

LEAN_APP_URL = 'http://192.168.1.71:8141'
LEAN_DB_HOST = '127.0.0.1'
LEAN_DB_USER = 'leantime'
LEAN_DB_PASSWORD = 'q1w2e3r4'
LEAN_DB_DATABASE = 'leantime'
LEAN_SESSION_PASSWORD = 'K7pQ2mX9vR4tL8wZ3nC6bF1hJ5sD0gY2'

要点：

• LEAN_APP_URL 决定邮件里链接的域名，不填会导致密码重置、邀请邮件不发送（官方在 sample.env 里已注明）。已在数据库里记录过的地址可用 php bin/leantime setting:save --key=system.trustedAppUrl --value=https://pm.example.com 修正。
• LEAN_SESSION_PASSWORD 必须换成随机长串；它一旦变更，所有已登录用户的会话立即失效。
• 数据库密码里若含 #、空格等字符，必须加单引号，否则 Dotenv 会把 # 之后当注释截断。

四、会话与安全

实测实例的 .env 里 LEAN_SESSION_EXPIRATION = 60，即 1 小时空闲登出：

grep SESSION_EXPIRATION /var/www/leantime/config/.env

LEAN_SESSION_EXPIRATION = 60

排障经验：LEAN_TRUSTED_PROXIES 设成具体 IP 段后，绕过反代直连该端口的请求会被拒绝，这是设计行为，不是故障；REMOTE_ADDR 会信任所有客户端，只在应用完全不可绕过反代时使用。

五、数据库连接与驱动

5.1 基础连接

当前实例为 MariaDB，实测版本：

mysql -uroot -p -e "select version();"

version()
10.11.19-MariaDB-ubu2204

切 PostgreSQL 时额外两个参数：LEAN_DB_SCHEMA（默认 public）与 LEAN_DB_SSLMODE（disable/allow/prefer/require/verify-ca/verify-full）。切驱动不能只改 LEAN_DB_DEFAULT_CONNECTION，还要在空库上重跑安装向导，否则旧库里的表结构与 SQL 方言不兼容。

5.2 连接池

容量估算：LEAN_DB_MAX_CONNECTIONS × PHP-FPM 子进程数 必须小于 MariaDB 的 max_connections 余量。多实例部署时尤其要算这笔账，否则表现为间歇性 SQLSTATE[HY000] [2002] 或 Too many connections。

六、日志

实测实例用 LEAN_LOG_CHANNELS = stderr，日志直接进服务标准输出，由 systemd/journal 收走：

journalctl -u leantime -n 4 --no-pager

127.0.0.1 -  27/Oct/2026:17:01:24 +0000 "POST /index.php" 200
127.0.0.1 -  27/Oct/2026:17:01:24 +0000 "POST /index.php" 401
127.0.0.1 -  27/Oct/2026:17:02:17 +0000 "GET /index.php" 200
127.0.0.1 -  27/Oct/2026:17:02:23 +0000 "GET /index.php" 429

最后一行 429 就是限流触发（见第九节）。把 single 与 stderr 同时写进 LEAN_LOG_CHANNELS 会导致同一错误出现两遍，排障时不要误判为「重复执行」。

七、邮件（SMTP）

Leantime 的找回密码、邀请、通知都依赖发信配置，缺一项就静默不发：

实测 .env 的邮件段：

grep -E 'LEAN_EMAIL_(USE_SMTP|SMTP_HOSTS|SMTP_PORT|SMTP_SECURE)' \
  /var/www/leantime/config/.env

LEAN_EMAIL_USE_SMTP = true
LEAN_EMAIL_SMTP_HOSTS = 'smtp.example.com'
LEAN_EMAIL_SMTP_PORT = '587'
LEAN_EMAIL_SMTP_SECURE = 'tls'

两类典型故障：LEAN_EMAIL_RETURN 写成 noreply（不带 @域名）导致全部拒信；587 端口用了 ssl 而不是 tls，握手阶段超时。改完这些参数必须重启 PHP-FPM，中间件不会热加载。

八、文件存储

8.1 本地存储

LEAN_USER_FILE_PATH = 'userfiles/'      # 附件目录（相对应用根目录）
LEAN_DB_BACKUP_PATH = 'backupdb/'       # 数据库备份目录

两个目录都要求 PHP-FPM 运行用户（www-data）可写。实测目录清单里 userfiles 与 backupdb 均存在；权限错误时的表现是上传返回 500、备份任务静默失败。

8.2 S3 / 兼容对象存储

MinIO 一类自建存储必须把 LEAN_S3_USE_PATH_STYLE_ENDPOINT 设为 true，否则域名解析不到 <bucket>.<endpoint>，表现为上传 403 或超时。切换存储后历史附件不会自动迁移，需要手工同步 userfiles/。

九、限流：LEAN_RATELIMIT_API 与 LEAN_RATELIMIT_AUTH

Leantime 有两道按 IP 计数的限流：

• LEAN_RATELIMIT_API：普通请求的每分钟上限；
• LEAN_RATELIMIT_AUTH：认证失败的每分钟上限（与登录表单共用）。

9.1 实测：阈值 5 的表现

.env 里把 API 限流设成 5，连续请求 7 次：

for i in $(seq 1 7); do
  curl -s -o /dev/null -w "call$i %{http_code}\n" \
    -X POST http://192.168.1.71:8141/api/jsonrpc \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TOKEN" \
    -d '{"jsonrpc":"2.0","method":"leantime.rpc.Api.Config.getSystemInfo","params":{},"id":1}'
done

实测回显：

call1 200
call2 200
call3 200
call4 200
call5 429
call6 429
call7 429

429 响应带完整限流元数据，可直接用来自动退避：

HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0
X-RateLimit-Retry-After: 9
X-RateLimit-Limit: 5
Retry-After: 9

{"error":"Too many requests. Please try again later."}

注意 429 是纯文本错误体，不是 JSON-RPC 错误对象——客户端不能用解析 error.code 的方式处理，必须按 HTTP 状态码分支。

9.2 实测：调高后恢复

把 .env 改为 LEAN_RATELIMIT_API = 120 并重启 PHP-FPM，同样连续请求 8 次：

call1 200
call2 200
...
call8 200

全部通过。这说明阈值是进程启动时读取的，改了不重启等于没改。

9.3 认证失败的限流

LEAN_RATELIMIT_AUTH = 2 时，用错误密钥请求两次，第三次开始返回：

{"error":"Too many failed authentication attempts. Try again later."}

这个计数按「客户端 IP + 1 分钟」衰减，即使随后换成正确密钥，也要等窗口过去才能恢复。在自动化脚本里硬编码错误密钥反复重试，会把自己锁死一分钟，这是实测中踩过的坑。

十、配置核实与排障

10.1 三个核实动作

# 1. 看文件里的值（去注释）
grep -vE '^\s*#|^\s*$' /var/www/leantime/config/.env

# 2. 看数据库里的展示类设置
mysql -uleantime -pq1w2e3r4 leantime -e \
  "select \`key\`, value from zp_settings order by \`key\` limit 12;"

# 3. 看运行时的最终能力
curl -s -X POST http://192.168.1.71:8141/api/jsonrpc \
  -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"leantime.rpc.Api.Config.getSystemInfo","params":{},"id":1}'

第三步实测回显（同时给出数据库版本号，可用作升级核对）：

{"jsonrpc":"2.0","result":{"version":"3.12.0","enabledPlugins":[]},"id":1}

10.2 五条常见故障

1. 改 .env 后行为没变：没重启 PHP-FPM。用 systemctl show php8.3-fpm -p ActiveEnterTimestamp 确认进程启动时间晚于文件修改时间。
2. 全站 429，连登录页都打不开：LEAN_RATELIMIT_API 设得过小（实测 5 就会在正常浏览时触发），调回 120 以上并重启。
3. 密码重置/邀请邮件不发：LEAN_APP_URL 为空且数据库没有 system.trustedAppUrl，邮件被安全策略丢弃。
4. 上传附件 500：LEAN_USER_FILE_PATH 目录属主不是 www-data，或 LEAN_USE_S3 已开启但 S3 参数不全。
5. 切换 PostgreSQL 后安装向导报错：只改了 LEAN_DB_DEFAULT_CONNECTION，没有在空库上重跑安装；旧 MySQL 库里的表不能直接复用。

十一、参考链接

• 官方全量配置样例：config/sample.env（随源码分发）
• 官方文档：https://docs.leantime.io
• 同专栏：《Leantime 介绍与选型指南》
• 同专栏：《Leantime 3.12.0 完整部署与实战指南》
• 同专栏：《Ubuntu 22.04 安装 Leantime 3.12.0 指南》
• 同专栏：《Leantime 3.12.0 常用 API 与运维命令详解》