Movim 0.35.4 配置参数详解

目标：逐项讲清 Movim v0.35.4 的全部配置面——.env 环境变量键、config/*.php 默认值、数据库 configuration 表的 20 个字段与 CLI 可改的 15 键，并实测验证「三级配置来源」「--timezone 静默忽略陷阱」「loglevel 0/1/2 语义」等关键行为。已在 Debian 13 (trixie) + PHP 8.4.15 + PostgreSQL 15 + Prosody 13.0.1、安装路径 /var/www/movim（运行用户 www-data）环境实测通过。

一、环境信息

本文所有命令与回显均在以下环境实测采集：

• 操作系统：Debian 13 (trixie)（x86_64），PHP 8.4.15
• Movim：v0.35.4（源码 VERSION 文件实测 = v0.35.4），安装路径 /var/www/movim，运行用户 www-data
• 数据库：PostgreSQL 15（库/用户均为 movim，演示口令 q1w2e3r4）
• XMPP 服务器：Prosody 13.0.1，域 movim.local
• 配置入口：项目根 .env、config/*.php、php daemon.php config 命令、Web 管理面板
• 验证工具：psql -U movim -d movim（\d configuration 取表结构）

💡 说明：本文以源码安装形态书写；若采用编排文件方式部署，同样的键通过环境变量注入，逐项解释见 《Movim 0.35.4 Docker Compose 部署指南》第六章。

二、前置条件

1. 代码已放置到 /var/www/movim 并完成 composer install --no-dev（安装主线见 《Movim 0.35.4 Docker Compose 部署指南》第四章）；
2. 数据库迁移已执行（composer movim:migrate），configuration 表存在；
3. 项目根已有 .env（可从 .env.example 复制）；
4. 以 www-data 用户执行 CLI（su -s /bin/bash www-data 或等效方式），避免缓存/日志目录权限错位（该坑实测见第七章 Q5）。

三、参数查看与修改方式

Movim 的配置分布在三个层面，修改方式与生效条件各不相同：

3.1 三级来源与优先级

config/*.php 的每个键都按「.env 文件 → 同名环境变量 → config/*.php 默认值」三级取值（DotEnv 加载，环境变量可覆盖 .env）。查看某项当前生效值最直接的办法是看守护进程行为或查库：

cd /var/www/movim && grep -E '^(DB_|DAEMON_|GALENER_)' .env

3.2 CLI 修改（daemon.php config）

实例级参数（存 configuration 表）用 php daemon.php config --键=值 修改，实测回显：

php daemon.php config --info="Movim 演示实例（quzuo.net 实测）" --xmppdomain=movim.local
# The configuration key info has been updated from Demo instance by CLI to Movim 演示实例（quzuo.net 实测）
# The configuration key xmppdomain has been updated from movim.local to movim.local

可改的键以 --help 为准（共 12 个选项，见 5.5 的 fillable 对照），不在白名单内的选项会被静默忽略（实测陷阱见 5.7）。

3.3 Web 管理面板与直接改库

管理后台「实例」页可改同一批参数（含 CLI 改不了的 banner、maxsessions，以及「日志详细度」下拉）。兜底方式是直接 UPDATE configuration——该表恒为一行（id=1）：

update configuration set loglevel='1' where id=1;

⚠️ 注意：官方 INSTALL.md 明示「部分配置需重启守护进程生效」——改完 .env 或 configuration 表后，systemctl restart movim-daemon（或等效重启）再验证。

四、参数总览

configuration 表 20 列实测（\d configuration）：id, description, info, unregister, restrictsuggestions, locale, loglevel, xmppdomain, xmppdescription, xmppwhitelist, created_at, updated_at, chatonly, gifapikey, disableregistration, banner, maxsessions, ssrfwhitelist（另有 id/时间戳共 20 列，业务键 18 个）。

五、核心参数分类详解

5.1 数据库连接组（.env 键 DB_*，默认值见 config/database.php）

官方强烈推荐 PostgreSQL：部分特性仅 PG 可用（README/INSTALL.md 原文），本文全部取证基于 PG 15。

5.2 守护进程组（.env 键 DAEMON_*，默认值见 config/daemon.php）

daemon 启动检查链实测顺序（源码 DaemonCommand.php）：phinx 迁移状态（缺则提示 composer movim:migrate）→ 必需 PHP 扩展 → DAEMON_URL → cache/log 目录可建（不可写报 Can’t create ... directory）→ admin 存在（无则提示 php daemon.php setAdmin {jid}）。

5.3 音视频组件组（.env 键 GALENER_*，默认值见 config/galener.php）

不部署音视频可全部留空；worker 生命周期用 daemon.php galener <start|stop|restart> 管理（galener status 实测回显 🔴 Not running）。

5.4 路径与缓存组（config/paths.php）

三个目录 cache/、log/、public/cache/ 必须对运行用户可写（INSTALL.md 要求 chown -R www-data: 对应目录），daemon 启动时若不可建会直接报错退出（见 5.2 检查链）。

5.5 实例参数（configuration 表，CLI 可改 15 键）

源码 Configuration.php 的 fillable 白名单共 15 键，默认值实测如下：

CLI config --help 实测暴露 12 个选项（全部 VALUE_REQUIRED）：--info / --description / --timezone / --restrictsuggestions / --chatonly / --disableregistration / --loglevel / --locale / --xmppdomain / --xmppdescription / --xmppwhitelist / --gifapikey。configuration 表首行由第一次 config 命令自动创建（实测 id=1、locale=en、loglevel=0、maxsessions=0）。

5.6 loglevel 语义（实测源码 AdminMain.php:36）

管理面板「日志详细度」下拉即此三档。排障期建议 2（文件日志便于 tail），稳定运行降回 0 或 1。

5.7 --timezone 静默忽略陷阱（v0.35.4 实测）

config --help 列出了 --timezone 选项，但 timezone 不在 Configuration fillable 白名单——源码 ConfigCommand.php 只对「在 fillable 且 isset」的选项落库，因此：

php daemon.php config --timezone=Asia/Shanghai
# （无任何回显，配置未写入——静默忽略）

对比同一条命令里带 --info/--xmppdomain 时正常输出 The configuration key info has been updated from ... to ... 两行落库回显（见 3.2 实测）。时区应在 PHP 层（php.ini date.timezone）解决，不要指望该 CLI 选项。

六、生产配置模板

适用画像：2–4 人家庭/小团队自建实例，2 核 4GB 内存、20GB SSD，PostgreSQL 与 XMPP 服务器同机或内网可达。

/var/www/movim/.env：

DB_DRIVER=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=movim
DB_USERNAME=movim
DB_PASSWORD=q1w2e3r4
DAEMON_URL=https://movim.example.com/
DAEMON_INTERFACE=127.0.0.1
DAEMON_PORT=8080
DAEMON_DEBUG=false
DAEMON_VERBOSE=false

实例参数（初始化脚本，改完重启 daemon）：

php daemon.php config --xmppdomain=example.org --disableregistration=true --restrictsuggestions=true --loglevel=1 --locale=zh

解读：disableregistration=true 关闭自助注册防滥用（账号由管理员在 XMPP 服务器侧开通）；loglevel=1 走 syslog 纳入集中日志；DAEMON_DEBUG/VERBOSE 生产关闭。banner/maxsessions/ssrfwhitelist 无 CLI 入口，经管理面板或 SQL 设置（见 3.3）。演示口令 q1w2e3r4 仅限文档示例，上线必须更换并同步 DB_PASSWORD。

七、常见问题

Q1：config --timezone 执行后毫无反应？ 设计如此：该选项不在 fillable 白名单，被静默忽略（实测，见 5.7）。时区改 php.ini。

Q2：改了 .env 或 configuration 表但行为没变？ INSTALL.md 明示部分配置需重启守护进程生效。重启 daemon 后再验证；改 .env 必须重启（Dotenv 只在进程启动时读一次）。

Q3：daemon 启动即退出，提示 Please configure DAEMON_URL in .env？ DAEMON_URL 是启动硬检查（5.2）。配置公网 URL 后重启；URL 无 scheme 会被自动补 https://。

Q4：MariaDB 建库后迁移失败？ Movim 强制 utf8mb4 + utf8mb4_bin（MySQL 直接不支持）。建库：CREATE DATABASE movim CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;。建议直接上 PostgreSQL（5.1）。

Q5：Can’t create ... directory 或日志/缓存写入失败？ cache/、log/、public/cache/ 对运行用户不可写（5.4）。chown -R www-data: /var/www/movim/cache /var/www/movim/log /var/www/movim/public/cache。另注意：用 root 跑过 daemon.php 后目录属主会漂移，再切回 www-data 就写不进（实测 emojisToJson 曾因权限报 Failed to open stream: Permission denied，完整回显见 《Movim 0.35.4 常用 CLI 命令与工具详解》注意事项章）。

Q6：configuration 表是空的，CLI 改不动？ 首次执行 php daemon.php config 任一选项即自动创建 id=1 行（实测默认 locale=en、loglevel=0、maxsessions=0），无需手工插行。

Q7：banner、maxsessions 想设置但 CLI 没有选项？ 二者是表列但不在 CLI fillable 通路（5.5 表）。用管理面板或 SQL（如 update configuration set maxsessions=100 where id=1;），改完重启 daemon。

八、参考链接

• 官方安装与配置说明：仓库根 INSTALL.md（.env、目录权限、迁移、systemd/虚拟主机模板 etc/）
• 默认值源码：config/daemon.php、config/database.php、config/galener.php、config/paths.php；白名单源码：src/Movim/Configuration.php、src/Movim/Console/ConfigCommand.php
• 官网与文档：https://movim.pub/doc/
• GitHub：https://github.com/movim/movim
• 本专栏姊妹篇：《Movim 0.35.4 介绍与选型指南》、《Movim 0.35.4 Docker Compose 部署指南》、《Movim 0.35.4 常用 CLI 命令与工具详解》