Friendica 2026.05 配置参数详解

目标：把 Friendica 2026.05 的「静态默认 → 本地文件 → 环境变量映射 → 数据库 config 表」四层配置模型讲透，逐项解释 database/config/system/storage 核心参数的含义与真实默认值，并沉淀 URL 序列化损坏、日志 0 字节、垃圾配置行等 6 类实测配置故障。已在 Friendica 2026.05（DB build 1595，Apache/2.4.69 + PHP 8.4.27，MariaDB 11）单节点与双节点联邦环境实测通过；部署形态见 《Friendica Docker Compose 部署指南》。

一、环境信息

本文命令均在部署完成的编排内执行（docker compose exec web bin/console ...，形态见部署篇）；选型背景见 《Friendica 介绍与选型指南》。

二、前置条件

1. 已按 《Friendica Docker Compose 部署指南》 完成部署并通过验证（bin/console --version 回显 Friendica Console version 2026.05）；
2. 能在 web 服务内执行 bin/console（注意：php bin/console 只会 cat 脚本原文——bin/console 是 bash 包装，必须直接执行 /var/www/html/bin/console 或编排内 bin/console）；
3. 能访问数据库（docker compose exec db mariadb -ufriendica -pq1w2e3r4 friendica）；
4. 修改任何配置后，daemon 侧生效需重启 cron 服务（docker compose restart cron），Web 侧配置缓存随请求刷新。

三、参数查看与修改方式

3.1 四层配置模型（先读这一节）

Friendica 的配置值按以下顺序合并，后层覆盖前层：

环境变量映射表实测（cat static/env.config.php，节选，完整文件即映射清单）：

return [
	'MYSQL_HOST'     => ['database', 'hostname'],
	'MYSQL_USER'     => ['database', 'username'],
	'MYSQL_PORT'     => ['database', 'port'],
	'MYSQL_PASSWORD' => ['database', 'password'],
	'MYSQL_DATABASE' => ['database', 'database'],

	// Core variables
	'FRIENDICA_ADMIN_MAIL' => ['config', 'admin_email'],
	'FRIENDICA_URL'        => ['system', 'url'],
	'FRIENDICA_TZ'         => ['config', 'timezone'],
	'FRIENDICA_LANG'       => ['config', 'language'],
	'FRIENDICA_SITENAME'   => ['config', 'sitename'],

	// Storage
	'FRIENDICA_DATA'     => ['storage', 'name'],
	'FRIENDICA_DATA_DIR' => ['storage', 'filesystem_path'],

	// Debugging/Profiling
	'FRIENDICA_DEBUGGING'       => ['system', 'debugging'],
	'FRIENDICA_LOGFILE'         => ['system', 'logfile'],
	'FRIENDICA_LOGLEVEL'        => ['system', 'loglevel'],

	// Caching
	'FRIENDICA_CACHE_DRIVER'             => ['system', 'cache_driver'],
	'FRIENDICA_SESSION_HANDLER'          => ['system', 'session_handler'],
	'FRIENDICA_DISTRIBUTED_CACHE_DRIVER' => ['system', 'distributed_cache_driver'],
	'FRIENDICA_LOCK_DRIVER'              => ['system', 'lock_driver'],

	// Redis Config
	'REDIS_HOST' => ['system', 'redis_host'],
	'REDIS_PORT' => ['system', 'redis_port'],
	'REDIS_PW'   => ['system', 'redis_password'],
	'REDIS_DB'   => ['system', 'redis_db'],

	// Proxy Config
	'FRIENDICA_FORWARDED_HEADERS' => ['proxy', 'forwarded_for_headers'],
	'FRIENDICA_TRUSTED_PROXIES'   => ['proxy', 'trusted_proxies'],
];

实测验证第 3 层覆盖第 2 层：config/local.config.php 文件里 'sitename' => 'Friendica Social Network'（出厂默认），但编排环境变量 FRIENDICA_SITENAME: quzuo Friendica 生效：

docker compose exec web bin/console config config sitename

config.sitename => quzuo Friendica

💡 技术拓展：配置载体不止这四层可选——

方式	特点	适用
环境变量映射（本文第 3 层）	编排友好，重建即生效	容器化部署（推荐）
本地文件 config/*.config.php	可版本化管理、分片按名序合并	裸机/共享主机
数据库 config 表	管理面板与 CLI 的写入层，运行时可改	站点运营期日常调整
Web 安装向导	首装一次性写入	首次部署

本文环境实际以「环境变量 + 数据库」两层为主，文件层仅承载 database 段——这正是官方镜像的设计取向。

3.2 console config 查看与设置

bin/console config 的官方语法（实测 bin/console help config 回显节选）：

	bin/console config
		Lists all config values

	bin/console config <category>
		Lists all config values in the provided category

	bin/console config <category> <key>
		Shows the value of the provided key in the category

	bin/console config <category> <key> <value>
		Sets the value of the provided key in the category

Notes:
	Setting config entries which are manually set in config/local.config.php may result in
	conflict between database settings and the manual startup settings.

要点（全部实测）：

• 没有 get/set 子命令：查看就是两参数 config system url，设置就是三参数 config system loglevel notice；
• 误用 config get system url 不报错，而是把 get 当类别、写入 cat='get' 垃圾行（见第七章 Q3）；
• 查看回显格式 system.url => http://friendica.local，写入回显格式 system.disable_password_exposed <= true。

实测样例：

docker compose exec web bin/console config system url
docker compose exec web bin/console config system build
docker compose exec web bin/console config config register_policy
docker compose exec web bin/console config storage

system.url => http://friendica.local
system.build => 1595
config.register_policy => 2
[storage]
name => Database
filesystem_path => /var/www/data

解读：register_policy => 2 是 \Friendica\Module\Register::OPEN 常量的数值形态（0=邀请/1=需批准/2=开放），管理面板与 CLI 都按数值存取。

3.3 管理面板

Admin → Site 表单保存即写数据库 config 表（第 4 层）。面板与 CLI 写同一层，可互相验证；面板改过的键再改文件不生效，属正常覆盖关系。

3.4 直接读写数据库 config 表

config 表结构：cat（类别）+ k（键）+ v（PHP serialize 字符串）。全新单节点安装后实测全表（8 行）：

docker compose exec db mariadb -ufriendica -pq1w2e3r4 friendica -e "SELECT cat,k,v FROM config ORDER BY cat,k;"

cat	k	v
system	allowed_themes	s:9:"frio,vier";
system	build	i:1595;
system	dbupdate	i:1;
system	disable_password_exposed	s:4:"true";
system	maintenance	b:0;
system	spoolpath	s:26:"/tmp/friendica.local/spool";
system	temppath	s:20:"/tmp/friendica.local";
system	update	i:0;

序列化格式对照（照抄实测行）：

⚠️ 注意：s: 的长度前缀必须等于值的真实字节数，手工 SQL 写错长度会让 unserialize 失败、配置静默失效（第七章 Q1 的 /.well-known 污染事故根因即此）。另外 bin/console config 写入一律按字符串存（disable_password_exposed 存成 s:4:"true"; 而非 b:1;），Friendica 读取时按 truthy 兼容处理。能用 CLI/面板就不要手工 SQL；必须手工时参照 INSERT INTO config (cat,k,v) VALUES ('system','debugging','b:1;') 的精确格式。

四、参数总览

bin/console config（不带参数）列出全部类别；核心类别与职责：

bin/console config system 实测输出节选（首 30 行，值即当前生效值）：

[system]
add_missing_posts => 
add_page_media => 
admin_inactivity_limit => 30
allowed_link_protocols[0] => ftp://
allowed_link_protocols[1] => ftps://
allowed_link_protocols[2] => mailto:
allowed_link_protocols[3] => cid:
allowed_link_protocols[4] => gopher://
always_show_preview => 
ap_always_bcc => 
auth_cookie_lifetime => 7
avatar_cache => 
basicauth => 1
big_emojis => 1
basepath => /var/www/html
bulk_delivery => 
contact_add_limit => 10
contact_discovery_limit => 10
contact_update_limit => 100
cache_driver => apcu
distributed_cache_driver => database
fetch_parents => 1
config_adapter => jit
crawl_permit_period => 60
db_loglimit => 10
dbclean_expire_conversation => 90
disable_password_exposed => true

空值即「取静态默认（多数为 false/空）」；非空值来自默认、文件或数据库层的合并结果。下面按主题挑核心参数逐项说明。

五、核心参数分类详解

5.1 database 段（连接）

config/local.config.php 实测（部署篇第八章生成内容）：

'database' => [
	'hostname' => 'db',
	'username' => 'friendica',
	'password' => 'q1w2e3r4',
	'database' => 'friendica',
	'charset' => 'utf8mb4',
],

• hostname：编排服务名 db；裸机填 127.0.0.1 或实际库地址；
• charset：必须 utf8mb4（emoji/多语言正文依赖，官方 requirements 的 InnoDB+Barracuda 也建在此之上）；
• 该段不受管理面板影响（文件/环境变量头注释：面板只覆盖 config/system 段），换库改这里并重启。

5.2 config 段（站点基础信息）

bin/console config config 实测：

[config]
admin_email => admin@friendica.local
admin_nickname => 
max_import_size => 200000
php_path => /usr/local/bin/php
register_policy => 2
sitename => quzuo Friendica
timezone => Asia/Shanghai
language => en

• admin_email：管理员邮箱，通知与 HIBP 相关操作回执地址；
• register_policy：2=开放注册（演示环境）；生产建议 0/1 并配合面板审批；
• max_import_size：导入（好友/帖子归档）体积上限，单位字节，默认 200000；
• php_path：CLI 进程派生 worker 用的 PHP 二进制路径，镜像内为 /usr/local/bin/php，错配表现为「worker 不启动」。

5.3 system 段——联邦身份（最重要）

5.4 system 段——日志与调试（2026.05 大坑区）

实测启用组合（双节点环境）：INSERT INTO config (cat,k,v) VALUES ('system','debugging','b:1;') + 重启 cron 后日志立即产出。

5.5 system 段——缓存与临时目录

Redis 接入点实测（镜像自带分片文件内容）：

// 01redis.config.php：仅当环境变量存在才生效
if (getenv('REDIS_HOST')) {
	return [
		'system' => [
			'session_handler' => 'cache',
			'distributed_cache_driver' => 'redis',
			'lock_driver' => 'redis',
			'redis_host' => getenv('REDIS_HOST'),
			...
		],
	];
} else {
	return [];
}

💡 技术拓展：cache_driver 可选后端对比——

后端	特点	适用
apcu	进程内、零网络开销、不跨进程共享	单实例（本文环境）
redis	跨进程/跨节点共享，可承载会话与锁	多 web 实例水平扩展
database	无依赖兜底	极小站点

官方镜像默认 apcu + distributed database；多节点联邦压测环境应加 REDIS_HOST 一并切走会话/缓存/锁。

5.6 system 段——联邦行为与限流（选摘）

bin/console config system 实测当前值：

5.7 storage 段（附件后端）

实测：

docker compose exec web bin/console config storage
docker compose exec web bin/console storage list

[storage]
name => Database
filesystem_path => /var/www/data

 Sel | Name                
-----------------------
     | Filesystem          
 *   | Database            

• name：附件后端选择，镜像默认 Database（帖子图片/头像进库，备份只导库即可）；
• filesystem_path：选 Filesystem 时的落盘根（镜像 zz-docker 固定 /var/www/data），切换后需保证该路径在编排卷内持久化；
• 切换用 bin/console storage 命令组（命令篇展开）。

5.8 proxy 段（反向代理）

生产 TLS 形态（nginx 反代 + 容器监听内网端口）必须配置，否则客户端 IP 全记成代理地址、URL 推导也可能错乱：

• proxy.forwarded_for_headers：环境变量 FRIENDICA_FORWARDED_HEADERS（如 X-Forwarded-For）；
• proxy.trusted_proxies：FRIENDICA_TRUSTED_PROXIES（反代所在网段/地址）。

六、生产配置模板

适用场景：4GB 内存、20GB SSD、单节点、真实域名 + 反代 TLS、百级注册用户。config/local.config.php：

<?php
return [
	'database' => [
		'hostname' => 'db',
		'username' => 'friendica',
		'password' => '<强密码>',
		'database' => 'friendica',
		'charset' => 'utf8mb4',
	],
	'config' => [
		'php_path' => '/usr/local/bin/php',
		'admin_email' => 'admin@example.com',
		'sitename' => 'Example Social',
		'register_policy' => \Friendica\Module\Register::APPROVE,
		'max_import_size' => 200000,
	],
	'system' => [
		'url' => 'https://social.example.com',   // 域名根路径，禁止路径前缀（联邦硬约束）
		'basepath' => '/var/www/html',
		'default_timezone' => 'Asia/Shanghai',
		'language' => 'en',
		'loglevel' => 'notice',                  // 生产级别；debug 会泄露私钥（见 5.4）
		'cache_driver' => 'apcu',
	],
];

编排环境变量同步要点：FRIENDICA_URL 与文件一致；反代场景加 FRIENDICA_TRUSTED_PROXIES；多实例才引入 REDIS_HOST（单实例 apcu 足够）。注册策略 Register::APPROVE（数值 1）需管理员审批新注册。数据库凭据属真实密钥，按你们密钥管理规范注入，勿提交仓库。

七、常见问题（FAQ）

以下均为双节点联邦环境实测复现并定位的配置故障。

Q1：WebFinger/Actor URL 变成 http://.../.well-known/...（/.well-known 污染）

现象：自联系人、Actor URL 全部带 /.well-known 段，对端无法解析。 根因：config 表 system.url 的序列化值手工 SQL 写坏——两种实测损坏形态：缺尾分号（s:22:"http://friendica.local"）与长度前缀不符（s:23: 实存 27 字符的 URL）。unserialize 失败后 Friendica 回退用请求 URI 推导站点地址，determineURLPath 恰好取到 /.well-known 目录段。 修复：不要补分号/改长度（实测补分号后长度前缀仍错、问题依旧），用官方迁移工具重写正确序列化并全库更新历史 URL：

docker compose exec web bin/console relocate http://web2.friendica.local

Q2：friendica.log 永远 0 字节

根因：2026.05 起 system.debugging=false 时日志管线直接返回 NullLogger（源码 LoggerManager::createLogger()），logfile/loglevel 正确存储也不写。 修复：INSERT INTO config (cat,k,v) VALUES ('system','debugging','b:1;');（或环境变量 FRIENDICA_DEBUGGING=true）+ 重启 cron，日志立即产出。排障完成后建议关回，且全程 loglevel 保持 notice（debug 级含 RSA 私钥，见 5.4）。

Q3：config 表出现 cat='get'/cat='config' 垃圾行

根因：console config 语法误用。bin/console config get system url 被解析为「类别=get、键=system、值=url」直接落库；把 system 类键写到 config 类别（如 config config disable_password_exposed true）同样产生不生效的垃圾行。 识别与清理：垃圾行的 v 序列化形态异常（如 s:4:"true"; 挂在错误 cat 下）；确认后 DELETE FROM config WHERE cat='get'; 并复查正确类别行存在。

Q4：改了 local.config.php 但值不生效

四层模型问题（3.1）：数据库 config 表已有同名键时优先于文件；或环境变量映射层（3.1 表）在覆盖文件。定位方法：bin/console config <cat> <key> 看生效值，再 SELECT * FROM config WHERE k='<key>'; 看库层有没有行——有行就改库（CLI/面板），没行就查环境变量。

Q5：bin/console config system logfile /var/www/html/friendica.log 存成了 /var/www/friendica.log

实测现象：console 写入带 /html 段的路径时存储值被剥离该段。处理：改用 SQL 写正确序列化值（s:27:"/var/www/html/friendica.log";），或直接把 FRIENDICA_LOGFILE 环境变量指到不带歧义的路径（如 /var/www/friendica.log）。

Q6：关注请求不投递——系统账户昵称为空

日志证据链（实测）：Could not find owner for uid 0 → User::getSystemAccount → WARNING No actor name was found. {"name":""}。根因：user 表 uid=0 系统账户行的 username/nickname 为空串，Application actor 创建失败，AP 出站请求无法签名。 修复（实测两节点）：

UPDATE user SET username='friendica', nickname='friendica' WHERE uid=0;

修复后重新关注，日志出现 System account to be created（addr friendica@friendica.local），Follow 带 HTTP Signature POST 到对端 /inbox/<nick> 返回 HTTP 202，联邦闭环恢复。

八、参考链接

• 配置静态默认文档：源码 static/defaults.config.php（每个键的注释即官方定义）
• 环境变量映射表：源码 static/env.config.php
• relocate 迁移工具：https://github.com/friendica/friendica（bin/console relocate）
• 官方系统要求：https://friendi.ca/requirements/
• 本专栏相关文档：部署形态与编排见 《Friendica Docker Compose 部署指南》；选型背景见 《Friendica 介绍与选型指南》；bin/console 命令全集见《Friendica 2026.05 常用 CLI 命令与工具详解》。