Friendica 2026.05 常用 CLI 命令与工具详解

Friendica 2026.05 bin/console 命令族全景与常用子命令详解：config 读写回环、maintenance status 静默关闭陷阱、dbstructure 架构维护、user 管理闭环、daemon/worker/cron 后台机制、apcu 缓存进程级陷阱与 API Basic auth 实测实录（单节点实测）

FriendicaFriendicaCLIMariaDBPHP 应用2026/11/02

Friendica 2026.05 常用 CLI 命令与工具详解

目标：全景详解 Friendica 2026.05 的 bin/console 命令族（30 个命令、四个分组）与配套工具（mariadb 直查、API curl 验证），覆盖 config 读写、维护模式（含 maintenance status 静默关闭陷阱）、dbstructure 架构维护、user/contact/addon/cache/lock/serverblock/relay 管理、daemon/worker/cron 后台机制与 API Basic auth 实测路径。已在 Friendica 2026.05（DB build 1595，Apache/2.4.69 + PHP 8.4.27，MariaDB 11）单节点环境实测通过；部署形态见 《Friendica 2026.05 Docker Compose 部署指南》，选型背景见 《Friendica 2026.05 介绍与选型指南》，四层配置模型与参数含义见 《Friendica 2026.05 配置参数详解》。

一、环境信息

项目实测值
Friendica2026.05 "Blutwurz"（DB build 1595）
运行时Apache/2.4.69 (Debian) + PHP 8.4.27（官方 friendica:2026.05 发行包内置）
数据库MariaDB 11，业务库 friendica
控制台入口/var/www/html/bin/console（bash 包装）+ bin/console.php（PHP 实现）
站点 URLhttp://friendica.local
后台进程cron 角色：/cron.sh → php bin/console.php daemon start -f 前台运行
演示账号admin / q1w2e3r4（admin@friendica.local，UID 2；口令重置实录见 5.1）

本文命令按真实服务器视角书写：bin/console ... 于站点根 /var/www/html 执行（本专栏编排形态为 docker compose exec web bin/console ...）；SQL 经 mariadb -ufriendica -pq1w2e3r4 friendica 执行（编排形态 docker compose exec db mariadb ...）。

二、工具概览

2.1 控制台版本与命令族全景

bin/console --version

Friendica Console version 2026.05

bin/console 不带参数即打印命令族全景（实测回显，四个分组共 30 个命令）：

Usage: bin/console [--version] [-h|--help|-?] <command> [<args>] [-v]

Commands:
	daemon                 Interact with the Friendica daemon
	help                   Show help about a command, e.g (bin/console help config)
	jetstream              Interact with the Jetstream daemon
	worker                 Start worker process

	node management
		archivecontact         Archive a contact when you know that it isn't existing anymore
		cache                  Manage node cache
		contact                Contact management
		globalcommunityblock   Block remote profile from interacting with this node
		globalcommunitysilence Silence a profile from the global community page
		lock                   Edit site locks
		mergecontacts          Merge duplicated contact entries
		serverblock            Manage blocked servers
		relay                  Manage ActivityPub relay servers
		user                   User management

	node configuration
		addon                  Addon management
		autoinstall            Starts automatic installation of friendica based on values from htconfig.php
		clearavatarcache       Clear the file based avatar cache
		config                 Edit site config
		dbstructure            Do database updates
		maintenance            Set maintenance mode for this node
		movetoavatarcache      Move cached avatars to the file based avatar cache
		postupdate             Execute pending post update scripts (can last days)
		relocate               Update node base URL
		storage                Manage storage backend

	developer
		createdoxygen          Generate Doxygen headers
		docbloxerrorchecker    Check the file tree for DocBlox errors
		extract                Generate translation string file for the Friendica project (deprecated)
		php2po                 Generate a messages.po file from a strings.php file
		po2php                 Generate a strings.php file from a messages.po file
		typo                   Checks for parse errors in Friendica files

Options:
	-h|--help|-? Show help information
	-v           Show more debug information.

分组职责与本文覆盖度：

分组命令数定位本文详解
顶层4（daemon/jetstream/worker/help）后台进程与帮助第六章
node management10用户/联系人/缓存/封锁治理第五章
node configuration10配置、架构、安装、存储第四章
developer6源码开发辅助（翻译文件、文档生成、语法检查）4.6 简述

2.2 配套工具

工具用途实测入口
mariadb 客户端直查 config / workerqueue 表，验证 CLI 写入落库结果mariadb -ufriendica -pq1w2e3r4 friendica -e "..."
curlAPI（Basic auth）、nodeinfo、webfinger 端点验证curl -s -u admin:q1w2e3r4 http://friendica.local/api/...
ps / 日志 tail前台 daemon 的真实运行验证（见 6.1）ps aux | grep [c]onsole.php

2.3 不存在的「常用命令」（避坑）

实测：Friendica 控制台没有独立的 cron、db、theme 命令。bin/console help cron 回显：

[Warning] Command cron doesn't exist

随后照常打印上方全景命令列表。三个「以为有、实际没有」的能力由以下机制承载：定时任务由 daemon 派生 Cron worker（6.4），数据库架构由 dbstructure（4.3），主题切换由 config system theme（4.1）。

三、前置条件

  1. 已完成部署并通过验证：bin/console --version 回显 Friendica Console version 2026.05（安装全流程见 《Friendica 2026.05 Docker Compose 部署指南》）；
  2. bin/console 是 bash 包装脚本，必须直接执行 bin/console ...；php bin/console 只会 cat 脚本原文不执行（部署篇实测结论）；
  3. 能连上业务库：mariadb -ufriendica -pq1w2e3r4 friendica -e "SELECT 1;" 返回 1；
  4. 经 bin/console config 改配置后，daemon/worker 侧生效需重启 cron 角色（docker compose restart cron），Web 侧随请求刷新（四层配置模型见 《Friendica 2026.05 配置参数详解》 3.1 节）。

四、节点配置命令详解

4.1 config——站点配置读写

config 是日常运维最高频命令，读写数据库 config 表（第 4 层，运行时生效值）。官方语法（实测 bin/console help config 回显节选）：

Synopsis
	bin/console config [-h|--help|-?] [-v]
	bin/console config <category> [-h|--help|-?] [-v]
	bin/console config <category> <key> [-h|--help|-?] [-v]
	bin/console config <category> <key> <value> [-h|--help|-?] [-v]

Description
	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 子命令——0 参数列全部、1 参数按类别列、2 参数读、3 参数写；回显方向区分读写（读 =>、写 <=）。误用 config get system url 不报错，而是把 get 当类别名写库产生垃圾行（事故实录见 《配置参数详解》 Q3）。

单键读取实测：

bin/console config system url
bin/console config system build
bin/console config config sitename
bin/console config system logfile
bin/console config system cron_interval

system.url => http://friendica.local
system.build => 1595
config.sitename => quzuo Friendica
system.logfile => /var/www/html/friendica.log
system.cron_interval => 5

读写回环实测（把 crawl_permit_period 从 60 改 90 再改回）：

bin/console config system crawl_permit_period
bin/console config system crawl_permit_period 90
bin/console config system crawl_permit_period
bin/console config system crawl_permit_period 60

system.crawl_permit_period => 60
system.crawl_permit_period <= 90
system.crawl_permit_period => 90
system.crawl_permit_period <= 60

写入结果 SQL 直查验证（实测 config 表仅 9 行，全新单节点量级）：

SELECT COUNT(*) FROM config;
SELECT cat,k,v FROM config ORDER BY cat,k;

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

注意 crawl_permit_period 存成 s:2:"60";（字符串）——console 写入一律按字符串序列化，不区分数值类型；PHP serialize 格式对照与手工 SQL 的长度前缀风险见 《配置参数详解》 3.4 节。

按类别列表 bin/console config system（实测约 200 行，输出节选（实测首尾））：

[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 => 
avatar_cache_path => 
avatar_cache_url => 
basicauth => 1
big_emojis => 1
basepath => /var/www/html
bulk_delivery => 
channel_cache => 
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
...
poco_requery_days => 30
worker_defer_limit => 15
worker_fetch_limit => 1
worker_load_cooldown => 0
build => 1595
maintenance => 0
update => 0
dbupdate => 1
spoolpath => /tmp/friendica.local/spool

空值即「取静态默认（多数为 false/空）」；末尾 build/maintenance/update/dbupdate 是 schema 升级与维护模式四状态键。

全量列表 bin/console config（所有类别合并，实测约 270 行，输出节选（实测首尾））：

database.hostname => db
database.socket => 
database.username => friendica
database.password => q1w2e3r4
database.database => friendica
database.charset => utf8mb4
database.pdo_emulate_prepares => 1
database.disable_pdo => 
database.persistent => 
database.port => 3306
config.admin_email => admin@friendica.local
config.admin_nickname => 
config.max_import_size => 200000
config.php_path => /usr/local/bin/php
config.info => 
config.register_policy => 2
config.register_text => 
config.sitename => quzuo Friendica
config.timezone => Asia/Shanghai
config.language => en
...
atprotocol.jetstream => jetstream1.us-west.bsky.network
atprotocol.plc_directory => https://plc.directory
atprotocol.web => https://bsky.app
channel.engagement_hours => 24
channel.engagement_post_limit => 20000
channel.interaction_score_days => 30
channel.max_posts_per_author => 2
channel.sharer_interaction_days => 90
storage.name => Database
storage.filesystem_path => /var/www/data

解读：全量列表把 database/config/system/performance/proxy/experimental/debug/jetstream/atprotocol/channel/storage 等类别以 <cat>.<key> 平铺；database 段回显的是连接参数生效值（来自环境变量映射层），说明 config 命令展示的是四层合并后的运行时视图，而非 config 表原始行。

4.2 maintenance——维护模式（⚠️ 最大陷阱）

官方语法（实测 bin/console help maintenance 回显，cen be 为官方原文拼写，照抄）：

Usage
	bin/console maintenance <enable> [<reason>] [-h|--help|-?] [-v]

Description
	<enable> cen be either 0 or 1 to disabled or enable the maintenance mode on this node.

	<reason> is a quote-enclosed string with the optional reason for the maintenance mode.

Examples
	bin/console maintenance 1
		Enables the maintenance mode without setting a reason message

	bin/console maintenance 1 "SSL certification update"
		Enables the maintenance mode with setting a reason message

	bin/console maintenance 0
		Disables the maintenance mode

启用带原因（实测）：

bin/console maintenance 1 "schema upgrade window"

System set in maintenance mode
Maintenance reason: schema upgrade window

正确查法是查配置键，不是 maintenance 命令（实测）：

bin/console config system maintenance
bin/console config system maintenance_reason

system.maintenance => 1
system.maintenance_reason => schema upgrade window

SELECT cat,k,v FROM config WHERE k LIKE 'maintenance%';

cat	k	v
system	maintenance	i:1;
system	maintenance_reason	s:21:"schema upgrade window";

维护期站点行为（实测）：HTTP 状态码仍是 200，页面正文替换为维护文案；API 请求同样返回 200 + HTML（非 JSON）：

HTTP 200
maintenance.
maintenance mode, either automatically because it is self-updating or manually by the node administrator. This condition should be temporary, please come back in a few minutes.

陷阱：maintenance status 不是查询命令。 官方 Usage 只有 maintenance <enable> [<reason>]，第一个参数直接进 intval()。源码 src/Console/Maintenance.php doExecute()（实测节选）：

$enabled = intval($this->getArgument(0));

$transactionConfig = $this->config->beginTransaction();

intval('status') 等于 0，因此执行 bin/console maintenance status 等价于静默关闭维护模式并回显 normal。实测证据链（四步闭环）：

bin/console maintenance 1 "CLI 维护演练"
bin/console config system maintenance
bin/console maintenance status
bin/console config system maintenance

System set in maintenance mode
Maintenance reason: CLI 维护演练
system.maintenance => 1
System set in normal mode
system.maintenance => 0

第 4 行 maintenance status 打印 "System set in normal mode" 的同时把维护模式关掉了——第 5 行直查确认 system.maintenance => 0。用法小结：

操作命令实测回显
启用bin/console maintenance 1 "原因"System set in maintenance mode + reason 行
关闭bin/console maintenance 0System set in normal mode
查询bin/console config system maintenancesystem.maintenance => 0/1
❌ 勿用bin/console maintenance status显示 normal 且静默关闭维护模式

💡 消歧：system.maintenance_start / maintenance_end（默认 01:00 +00:00 / 03:00 +00:00，static/defaults.config.php 375-383 行实测 grep）是每日维护任务时间窗（数据库清理类），与本节站点维护模式无关。

4.3 dbstructure——数据库架构

官方语法（实测 bin/console dbstructure 回显）：

Usage
	bin/console dbstructure <command> [options]

Commands
    drop     Show tables that aren't in use by Friendica anymore and can be dropped
       -e|--execute    Execute the removal

    update   Update database schema
       -f|--force      Force the update command (Even if the database structure matches)
       -o|--override   Override running or stalling updates

    dryrun   Show database update schema queries without running them
    dumpsql  Dump database schema
    toinnodb Convert all tables from MyISAM or InnoDB in the Antelope file format to InnoDB in the Barracuda file format
    initial  Set needed initial values in the tables
    version  Set the database to a given number

实测（本环境 build 1595 已最新）：

bin/console dbstructure update
bin/console dbstructure dryrun
bin/console dbstructure drop

(update 与 dryrun 均空输出、exit 0)
These tables are not used for friendica and will be deleted when you execute "dbstructure drop -e":

解读：schema 最新时 update/dryrun 静默且 exit 0（空输出即正常，不是失败）；drop 只打印表头行、下面无表名，即无废弃表可清理（drop -e 才真正执行删除）。toinnodb 用于 MyISAM/Antelope 旧表迁移，本环境 MariaDB 11 已是 InnoDB Barracuda，无需执行。

架构导出（实测 4150 行，输出节选（实测首尾））：

bin/console dbstructure dumpsql | wc -l
bin/console dbstructure dumpsql

4150
-- ------------------------------------------
-- Friendica 2026.05 (Blutwurz)
-- DB_UPDATE_VERSION 1595
-- ------------------------------------------


--
-- TABLE gserver
--
CREATE TABLE IF NOT EXISTS `gserver` (
	`id` int unsigned NOT NULL auto_increment COMMENT 'sequential ID',
	`url` varbinary(383) NOT NULL DEFAULT '' COMMENT '',
	`nurl` varbinary(383) NOT NULL DEFAULT '' COMMENT '',
	`version` varchar(255) NOT NULL DEFAULT '' COMMENT 'The version of this server software.',
	`site_name` varchar(255) NOT NULL DEFAULT '' COMMENT '',
...
			INNER JOIN `item-uri` ON `item-uri`.`id` = `diaspora-contact`.`uri-id`
			LEFT JOIN `gserver` ON `gserver`.`id` = `diaspora-contact`.`gsid`;

头部三行注释即版本与 DB_UPDATE_VERSION 自述，可作架构基线存档（升级前留底对照）。

4.4 postupdate——升级后数据脚本

实测 bin/console postupdate 回显：

Check for pending update actions.
Done.
Execute pending post updates.

All pending post updates are done.

解读：schema 升级（build 递增）后的数据迁移脚本由它执行，顶层 help 标注 "can last days"（大站可跑数天）；--reset <version> 可重置进度标记（bin/console help postupdate 实测）。稳态回显即上述四行。

4.5 storage——附件后端

实测 bin/console storage list 回显：

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

解读：* 标记当前后端，与 4.1 全量列表尾行 storage.name => Database 一致。storage set <name> 切换后端，storage move [photo|attach] [-n 5000] 分批迁移存量数据（bin/console help storage 实测语法）。切换后端属于重大变更，先备份再 move。

4.6 relocate / autoinstall / developer 组（概要）

bin/console help relocate 实测回显：

Usage
    bin/console relocate <new base URL> [-h|--help|-?] [-v]

Description
    Warning! Advanced function. Could make this server unreachable.

    Change the base URL for this server. Sends relocation message to all the Friendica and Diaspora* contacts of all local users.
    This process updates all the database fields that may contain a URL pointing at the current domain, as a result it takes
    a while and the node will be in maintenance mode for the whole duration.

换站点 URL 必须走 relocate 全库迁移（含通知对端），整个过程节点处于维护模式；URL 损坏事故与修复实录见 《配置参数详解》 Q1。

bin/console help autoinstall 实测节选——非交互安装入口（部署篇的安装路径）：

Synopsis
	bin/console autoinstall [-h|--help|-?] [-v] [-a] [-f]

Description
    Installs Friendica with data based on the local.config.php file or environment variables

Notes
    Not checking .htaccess/URL-Rewrite during CLI installation.

Examples
	bin/console autoinstall --savedb
		Installs Friendica with environment variables and saves them to the 'config/local.config.php' file

参数表覆盖 --dbhost/--dbport/--dbuser/--dbpass/--dbdata/-U <url>/-t <tz>/-L <lang> 等，且逐项标注对应环境变量（MYSQL_HOST、FRIENDICA_URL 等，与 《配置参数详解》 3.1 节映射表一致）。

developer 组 6 命令（createdoxygen/docbloxerrorchecker/extract/php2po/po2php/typo）为源码开发辅助：typo 检查 PHP 文件解析错误，extract 官方已标 deprecated。运维节点无日常需求，本文仅读 help 未执行。

五、节点管理命令详解

5.1 user——用户管理（闭环实测）

bin/console help user 实测回显 19 种形态（照抄）：

Usage
	bin/console user password <nickname> [<password>] [-h|--help|-?] [-v]
	bin/console user add [<name> [<nickname> [<email> [<language> [<avatar_url>]]]]] [-h|--help|-?] [-v]
	bin/console user delete [<nickname>] [-y] [-h|--help|-?] [-v]
	bin/console user allow [<nickname>] [-h|--help|-?] [-v]
	bin/console user deny [<nickname>] [-h|--help|-?] [-v]
	bin/console user block [<nickname>] [-h|--help|-?] [-v]
	bin/console user unblock [<nickname>] [-h|--help|-?] [-v]
	bin/console user list pending [-s|--start=0] [-c|--count=50] [-h|--help|-?] [-v]
	bin/console user list removed [-s|--start=0] [-c|--count=50] [-h|--help|-?] [-v]
	bin/console user list active [-s|--start=0] [-c|--count=50] [-h|--help|-?] [-v]
	bin/console user list all [-s|--start=0] [-c|--count=50] [-h|--help|-?] [-v]
	bin/console user search id <UID> [-h|--help|-?] [-v]
	bin/console user search nick <nick> [-h|--help|-?] [-v]
	bin/console user search mail <mail> [-h|--help|-?] [-v]
	bin/console user search guid <GUID> [-h|--help|-?] [-v]
	bin/console user config list [<nickname>] [<category>] [-h|--help|-?] [-v]
	bin/console user config get [<nickname>] [<category>] [<key>] [-h|--help|-?] [-v]
	bin/console user config set [<nickname>] [<category>] [<key>] [<value>] [-h|--help|-?] [-v]
	bin/console user config delete [<nickname>] [<category>] [<key>] [-h|--help|-?] [-v]

列表与检索实测：

bin/console user list active
bin/console user search nick admin
bin/console user search mail admin@friendica.local
bin/console user search id 2

user list active 回显：

+-------+-------+--------------------------------------+-----------------------+-------------+-------+-----------+
| Nick  | Name  | URL                                  | E-Mail                | Register    | Login | Last Item |
+-------+-------+--------------------------------------+-----------------------+-------------+-------+-----------+
| admin | Admin | http://friendica.local/profile/admin | admin@friendica.local | 2 hours ago | never | never     |
+-------+-------+--------------------------------------+-----------------------+-------------+-------+-----------+

user search 三种方式（nick/mail/id）返回同一行：

+-----+--------------------------------------+-------+-------+-----------------------+---------------------+-------+----------+---------+
| UID | GUID                                 | Name  | Nick  | E-Mail                | Register            | Login | Verified | Blocked |
+-----+--------------------------------------+-------+-------+-----------------------+---------------------+-------+----------+---------+
| 2   | 713dec15-176a-e80e-e662-fd9368243733 | Admin | admin | admin@friendica.local | 2026-11-02 04:17:42 |       | 1        | 0       |
+-----+--------------------------------------+-------+-------+-----------------------+---------------------+-------+----------+---------+

解读：admin 的 UID=2、GUID 为全局身份标识、Verified=1、Blocked=0；Login 空即从未登录（纯 CLI/API 管理的账号常态）。个人配置（pconfig 表）实测：

bin/console user config list admin pconfig

+-----+-------+
| Key | Value |
+-----+-------+
|     |       |
+-----+-------+

新建用户实测：

bin/console user add "CLI Test" clitest2 cli2@example.com en

Enter URL of an image to use as avatar (optional): 
msmtp: account default not found: no configuration file available

⚠️ 两个实测要点：

  • user add 不询问密码（源码 src/Console/User.php 走 UserModel::createMinimal($name, $email, $nick, $lang, $avatar)，密码不在参数与交互项里），新账号需另行 user password 设置后才能登录；
  • msmtp: account default not found 告警来自欢迎邮件发送（邮件客户端未配置），不影响建号——实测创建后 user list active 即出现该用户。

设置口令实测（重置 admin 口令用的就是这条）：

printf 'q1w2e3r4\n' | bin/console user password admin

Enter new password: stty: 'standard input': Inappropriate ioctl for device
stty: 'standard input': Inappropriate ioctl for device

Password changed.

解读：口令为隐藏输入（源码 CliPrompt::hiddenPrompt），非交互管道下 stty 告警无害；Password changed. 即成功标志。也可 user password <nick> <明文口令> 免交互（help 第 1 行形态），但会进 shell history。⚠️ 接管实录：本环境 admin 口令与部署记录不一致，API Basic auth 返回 {"error": "This API requires login"}，用本命令重置为 q1w2e3r4 后 API 恢复（第七章）。

封禁/解封/删除实测：

bin/console user block clitest2
bin/console user unblock clitest2
bin/console user delete clitest2 -y
bin/console user list active

前三条静默（exit 0），末条回显：

+-------+-------+--------------------------------------+-----------------------+-------------+-------------+---------------+
| Nick  | Name  | URL                                  | E-Mail                | Register    | Login       | Last Item     |
+-------+-------+--------------------------------------+-----------------------+-------------+-------------+---------------+
| admin | Admin | http://friendica.local/profile/admin | admin@friendica.local | 3 hours ago | 7 hours ago | 4 minutes ago |
+-------+-------+--------------------------------------+-----------------------+-------------+-------------+---------------+

-y 是非交互确认（源码提示语 Type "yes" to delete <nick>）；allow/deny 用于开放/关闭被批准账号的注册权限。

5.2 contact / archivecontact / mergecontacts

bin/console help contact 实测 Usage：

Usage
	bin/console contact add <user nick> <URL> [<network>] [-h|--help|-?] [-v]
	bin/console contact remove <CID> [-h|--help|-?] [-v]
	bin/console contact search id <CID> [-h|--help|-?] [-v]
	bin/console contact search url <user nick> <URL> [-h|--help|-?] [-v]
	bin/console contact terminate <CID> [-h|--help|-?] [-v]

实测 bin/console contact search id 18（单节点环境尚无联邦联系人）：

+----+-----+---------+------+------+-----+--------+---------+---------+---------+---------+
| ID | UID | Network | Name | Nick | URL | E-Mail | Created | Updated | Blocked | Deleted |
+----+-----+---------+------+------+-----+--------+---------+---------+---------+---------+
|    |     |         |      |      |     |        |         |         |         |         |
+----+-----+---------+------+------+-----+--------+---------+---------+---------+---------+

解读：contact add/search url 的第一个参数是本地用户昵称（在谁的联系人列表里操作），第二个是远端 profile URL。archivecontact <profile_url> 手动归档确认已消亡的远端联系人（官方 help：正常情况几天后自动归档）；mergecontacts 合并重复联系人条目，默认干跑、加 -e 执行（help 实测）。本环境单节点无联邦联系人，后两条仅读 help 未执行。

5.3 addon

bin/console help addon 实测 Usage：

Usage
	bin/console addon list all [-h|--help|-?] [-v]
	bin/console addon list enabled [-h|--help|-?] [-v]
	bin/console addon list disabled [-h|--help|-?] [-v]
	bin/console addon enable <addonname> [-h|--help|-?] [-v]
	bin/console addon disable <addonname> [-h|--help|-?] [-v]

实测：addon list enabled 为空表；addon list all | wc -l → 93（含表格边框，即发行包捆绑 89 个 addon 全部未启用）。addon list disabled 输出节选（实测首尾）：

+----------------------------+
| Name                       |
+----------------------------+
| advancedcontentfilter      |
| birdavatar                 |
| blackout                   |
| blockbot                   |
| bluesky                    |
...
| wppost                     |
| xmppchat                   |
+----------------------------+

解读：addon enable <name> 即启用（写入后管理面板可见配置项，如 s3_storage、ldapauth 需再配参数）；空 enabled 表说明全新安装不捆绑任何 addon。

5.4 cache——节点缓存（⚠️ apcu 进程级陷阱）

bin/console help cache 实测 Synopsis：

Synopsis
	bin/console cache list [-h|--help|-?] [-v]
	bin/console cache get <key> [-h|--help|-?] [-v]
	bin/console cache set <key> <value> [-h|--help|-?] [-v]
	bin/console cache flush [-h|--help|-?] [-v]
	bin/console cache clear [-h|--help|-?] [-v]

Description 标注 cache set <key> <value> [<ttl>] 默认 TTL 五分钟、cache flush 清过期键、cache clear 清全部。全链路实测：

bin/console cache list
bin/console cache set cli_demo_key cli_demo_value
bin/console cache get cli_demo_key
bin/console cache list
bin/console cache flush
bin/console cache clear

Listing all cache keys:
0 keys found
cli_demo_key <= cli_demo_value
cli_demo_key => NULL
Listing all cache keys:
0 keys found
Cache successfully flushed
Cache successfully cleared

解读（陷阱）：本环境 cache_driver => apcu（4.1 实测行）。APCu 是 PHP 进程级共享内存缓存——cache set 在它的进程里写成功，cache get/list 是各自独立的新 PHP 进程，看不到前者，故 get 回 NULL、list 恒 0 keys。这不是命令失败，是驱动语义；跨进程共享由 distributed_cache_driver => database 承担。

💡 技术拓展：Friendica 缓存后端不止 apcu 一种——

驱动作用域特点
apcu单 PHP 进程池最快，不跨进程/跨节点
redis / memcache跨进程、跨节点需外部服务（system.redis_host 等键已内置默认 127.0.0.1:6379）
database跨进程distributed_cache_driver 默认形态，有 DB 写开销

本环境实际 cache_driver => apcu + distributed_cache_driver => database（bin/console config system 实测行）。

5.5 lock

bin/console help lock 实测 Synopsis：

Synopsis
	bin/console lock list [<prefix>] [-h|--help|-?] [-v]
	bin/console lock set <lock> [<timeout> [<ttl>]] [-h|--help|-?] [-v]
	bin/console lock del <lock> [-h|--help|-?] [-v]
	bin/console lock clear [-h|--help|-?] [-v]

实测：bin/console lock（裸命令）不列锁，而是打印上述帮助——列表必须显式 lock list。lock 是进程互斥原语（lock_driver 空 = 文件锁），lock clear 用于异常中断后清理残留锁；lock set 的 TTL 默认五分钟（help 原文）。

5.6 serverblock

bin/console help serverblock 实测 Usage 与模式语法：

Usage
    bin/console serverblock [-h|--help|-?] [-v]
    bin/console serverblock add <pattern> <reason> [-h|--help|-?] [-v]
    bin/console serverblock remove <pattern> [-h|--help|-?] [-v]
    bin/console serverblock export <filename>
    bin/console serverblock import <filename>

    Patterns are case-insensitive shell wildcard comprising the following special characters:
    - * : Any number of characters
    - ? : Any single character
    - [<char1><char2>...] : char1 or char2 or...

实测 bin/console serverblock（裸命令）即列表，空表：

+---------+--------+
| Pattern | Reason |
+---------+--------+
|         |        |
+---------+--------+

解读：与 lock 相反，serverblock 裸命令就是列表。模式为大小写不敏感的 shell 通配；export/import 走 CSV 文件，可在节点间共享黑名单（官方 help 明示此用途）。

5.7 relay

bin/console help relay 实测 Synopsis：

Synopsis
	bin/console relay list [-h|--help|-?] [-v]
	bin/console relay add <actor> [-h|--help|-?] [-v]
	bin/console relay remove <actor> [-f|--force] [-h|--help|-?] [-v]

Description
	bin/console relay add <actor>
		Add a relay actor in the format https://relayserver.tld/actor

实测 bin/console relay list 无任何输出（空 = 未订阅 relay 服务器）。-f|--force 在退订消息失败时仍强制改状态（help 原文）。

5.8 globalcommunityblock / globalcommunitysilence / clearavatarcache / movetoavatarcache

低频治理命令，实测 help 语法：

bin/console globalcommunityblock <profile_url> [<reason>]   # Block remote profile from interacting with this node
bin/console globalcommunitysilence <profile_url>            # Silence a profile from the global community page
bin/console clearavatarcache                                # Clear the file based avatar cache
bin/console movetoavatarcache                               # Move all cached avatars to the file based avatar cache

解读：globalcommunityblock 与 globalcommunitysilence 的差别在作用面——前者拒收该 profile 的帖子与评论进入本节点，后者仅从社区页隐藏（help 原文："This silencing does only affect the display on the community page, accounts following the silenced accounts will still get their postings"）。头像缓存两条命令配合 system.avatar_cache_path 使用（本环境 avatar_cache 空 = 未启用文件头像缓存）。

六、后台进程命令（daemon / worker / jetstream / cron 机制）

6.1 daemon——Friendica 守护进程

bin/console help daemon 实测 Synopsis：

Synopsis
	bin/console daemon start [-h|--help|-?] [-v] [-f]
	bin/console daemon stop [-h|--help|-?] [-v]
	bin/console daemon status [-h|--help|-?] [-v]

Options
    -f|--foreground         Runs the daemon in the foreground

官方发行包 cron 角色的启动脚本 /cron.sh（实测全文）：

#!/bin/sh
trap "break;exit" HUP INT TERM

while [ ! -f /var/www/html/bin/console.php ]; do
  sleep 1
done

echo "Waiting for MySQL $MYSQL_HOST initialization..."
if php /var/www/html/bin/wait-for-connection "$MYSQL_HOST" "${MYSQL_PORT:-3306}" 300; then
  sh /setup_msmtp.sh
  exec gosu www-data:www-data tini -- php /var/www/html/bin/console.php daemon start -f
else
  echo "[ERROR] Waited 300 seconds, no response" >&2
fi

关键行即 php bin/console.php daemon start -f——前台模式运行 daemon（由编排负责重启，不 fork 后台进程）。

⚠️ 陷阱：前台形态下 daemon status 恒显示未运行（实测 web 与 cron 两个角色回显一致）：

bin/console daemon status

Daemon process  isn't running (/var/run/friendica.pid)

cat /var/run/friendica.pid

cat: /var/run/friendica.pid: No such file or directory

源码佐证 src/System/Daemon.php start()（实测节选）——pidfile 只在非前台分支写入：

if (!$foreground) {
    $this->dba->disconnect();

    // fork a daemon process
    $this->pid = pcntl_fork();
    ...
    } elseif ($this->pid) {
        // The parent process continues here
        if (!file_put_contents($this->pidfile, $this->pid)) {

即：daemon start（后台 fork）写 pidfile，status 查询正常；daemon start -f（前台）不写 pidfile，status 依赖 pidfile 恒报 "isn't running"。前台 daemon 的真实验证方式是进程列举（实测）：

ps aux | grep [c]onsole.php

www-data       1  0.0  0.0   2572  1408 ?        Ss   04:21   0:00 tini -- php /var/www/html/bin/console.php daemon start -f
www-data      13  0.0  0.2 157736 48680 ?        S    04:21   0:04 php /var/www/html/bin/console.php daemon start -f

cron 角色日志尾部（实测节选，含启动竞态）：

Waiting for MySQL db initialization...
...
[Error] Friendica isn't properly installed yet
Waiting for MySQL db initialization...

Starting Friendica daemon
[Error] Cannot save process with PID 15.

[Error] Cannot save process with PID 15. 是 daemon 曾早于安装完成启动、尝试保存 pid 失败的告警（与「前台不写 pidfile」同一套逻辑）；竞态处置见 《部署指南》 排障章节。

6.2 worker——前台工作进程

bin/console help worker 实测回显：

Synopsis
	bin/console worker [-h|--help|-?] [-v] [-n|--no_cron] [-s|--spawn]

Description
    Start a worker process

Options
    -h|--help|-?            Show help information
    -v                      Show more debug information.
    -n|--no_cron            Don't executes the Cronjob
    -s|--spawn              Spawn an additional worker

Examples
	bin/console worker -n
		Starts the worker without executing other recurring tasks

	bin/console worker -s
		Starts the worker and immediately spawn another worker process

实测 bin/console worker -n 空输出、exit 0——前台跑一轮队列即返回（队列已空时无回显）。用途：排障时手动消费队列、或不想等 daemon 周期时立即触发一轮任务（-n 跳过 Cron 派发）。

6.3 jetstream——Bluesky 桥接守护

bin/console help jetstream 实测 Synopsis 与 daemon 同构（start/stop/status，-f 前台）。实测 bin/console jetstream status：

[Error] Please set jetstream.pidfile in config/local.config.php. For example:

	'jetstream' => [
		'pidfile' => '/path/to/jetstream.pid',
	],

解读：Jetstream 守护（AT 协议/Bluesky 桥接）默认未启用——4.1 全量列表尾段实测 jetstream.pidfile => 为空，status 直接报错要求配置 pidfile。启用需写入 jetstream.pidfile 配置并另行启动该守护。

6.4 cron 机制——为什么没有 cron 命令

实测 bin/console help cron 回显 [Warning] Command cron doesn't exist（2.3）。Friendica 的周期任务既不是独立 CLI 命令、也没有 cronjob 表，机制如下（全部实测）：

  1. 无 cron 相关表：
SHOW TABLES LIKE '%cron%';

(空结果)

  1. 周期来自配置：bin/console config system cron_interval → system.cron_interval => 5（分钟）。

  2. 源码 src/Worker/Cron.php（实测节选）——Cron worker 派生一组周期任务：

public static function execute()
{
    $basepath = DI::appHelper()->getBasePath();

    $last = DI::keyValue()->get('last_cron');

    $poll_interval = intval(DI::config()->get('system', 'cron_interval'));

    if ($last) {
        $next = $last + ($poll_interval * 60);
        if ($next > time()) {
            DI::logger()->notice('cron interval not reached');
            return;
        }
    }

    DI::logger()->notice('start');
    ...
    // Fork the cron jobs in separate parts to avoid problems when one of them is crashing
    Hook::fork(Worker::PRIORITY_MEDIUM, 'cron');

    // Poll contacts
    Worker::add(Worker::PRIORITY_MEDIUM, 'PollContacts');

    // Update contact information
    Worker::add(Worker::PRIORITY_LOW, 'UpdateContacts');

    // Update server information
    Worker::add(Worker::PRIORITY_LOW, 'UpdateGServers');
    ...
    // Expire and remove user entries
    Worker::add(Worker::PRIORITY_MEDIUM, 'ExpireAndRemoveUsers');

    // Call possible post update functions
    Worker::add(Worker::PRIORITY_LOW, 'PostUpdate');

    // Hourly cron calls
    if ((DI::keyValue()->get('last_cron_hourly') ?? 0) + 3600 < time()) {
        // Update trending tags cache for the community page
        Tag::setLocalTrendingHashtags(24, 20);
        Tag::setGlobalTrendingHashtags(24, 20);
        ...

即：每次执行先按 last_cron + cron_interval*60 判断是否到点（未到则日志 cron interval not reached 直接返回），到点则派生 PollContacts / UpdateContacts / UpdateGServers / ExpireAndRemoveUsers / PostUpdate，整点外加趋势标签等 hourly 任务；Hook::fork 'cron' 给 addon 挂周期钩子。

  1. daemon 侧按同一间隔强制派生 Cron worker（src/System/Daemon.php 实测 grep）：
158:				$wait_interval = intval($this->config->get('system', 'cron_interval', 5)) * 60;
160:				$do_cron   = true;
170:					if (!$do_cron && ($last_cron + $wait_interval) < time()) {
171:						$this->logger->info('Forcing cron worker call.', ['pid' => $this->daemon->getPid()]);
172:						$do_cron = true;
  1. 落库证据——workerqueue 按 command 分组统计（运行数轮后实测）：
SELECT command, COUNT(*) AS c FROM workerqueue GROUP BY command ORDER BY c DESC;

command	c
SpoolPost	13
Cron	13
PollContacts	12
UpdateGServers	12
ExpireAndRemoveUsers	12
UpdateContacts	12
PostUpdate	12
ClearCache	1

Cron 与 PollContacts/UpdateContacts/UpdateGServers/ExpireAndRemoveUsers/PostUpdate 计数一致（12-13），与 Cron.php 派生清单一一对应——每轮 Cron 各派生一次。

结论：「手动跑 cron」没有命令可用，两条路——等 daemon 下一周期（cron_interval 分钟），或前台 bin/console worker 消费一轮队列（6.2）。

七、API 工具实测（curl）

Friendica 内置 Mastodon 兼容 API，是控制台的「对外 CLI」——发帖、查询等日常操作可脚本化。本环境 system.basicauth => 1（4.1 实测行），支持 HTTP Basic auth。

认证与身份验证（实测）：

curl -s -u admin:q1w2e3r4 http://friendica.local/api/account/verify_credentials.json

{"id":3,"id_str":"3","name":"Admin","screen_name":"admin","location":"DFRN","derived":[],"url":"http:\/\/friendica.local\/profile\/admin","entities":{"url":{"urls":[]},"description":{"urls":[]}},"description":"","protected":false,"followers_count":0,"friends_count":0,"listed_count":0,"favourites_count":0,"statuses_count":0,"created_at":"Mon Nov 02 04:17:42 +0000 2026","profile_banner_url":"http:\/\/friendica.local\/photo\/header\/3?ts=1793593062",...

（输出节选（实测首）：单行长 JSON，截于 profile_banner_url 之后）

⚠️ 实测前提：接管时 admin 口令与部署记录不符，Basic auth 返回 {"error": "This API requires login"}；经 bin/console user password admin 重置为 q1w2e3r4（5.1）后 verify_credentials 才通过。注意 API 的 id 是 3，与 console user search 的 UID 2 不同（API 层用联系人 id 体系，别拿错）。

发帖与时间线（实测）：

curl -s -u admin:q1w2e3r4 -X POST http://friendica.local/api/statuses/update.json -d "status=CLI API test post from console doc"

{"text":"CLI API test post from console doc","truncated":false,"created_at":"Mon Nov 02 07:20:49 +0000 2026","in_reply_to_status_id":null,"in_reply_to_status_id_str":null,"source":"api (DFRN (DFRN))","id":2,"id_str":"2",...,"user":{"id":3,"id_str":"3","name":"Admin","screen_name":"admin",...

（输出节选（实测首））

curl -s -u admin:q1w2e3r4 http://friendica.local/api/statuses/public_timeline.json

[{"text":"CLI API test post from console doc","truncated":false,"created_at":"Mon Nov 02 07:20:49 +0000 2026",...,"statuses_count":1,...}]

（输出节选（实测首））

解读：发帖成功返回 id 2（source 标注 api (DFRN (DFRN))）；带认证拉 public_timeline 回显该帖，且 user.statuses_count 已增至 1。匿名访问（实测）：不带凭据请求 public_timeline 返回 HTTP 401——本节点 API 要求登录，匿名拉公共时间线不可行。

两个坑（实测）：

  1. /api/config 不是 JSON 端点：返回完整 HTML 页面（<title>Api | Friendica Social Network</title>、<meta request="api/config">），不是站点配置接口——查配置请用 bin/console config；
  2. 表单 cookie 会话不适合 API：POST 登录表单返回 HTTP 404，带 cookie 再调 API 仍回 "This API requires login"——Basic auth 才是可靠路径。

联邦端点（实测，部署验证与版本审计可用）：

curl -s http://friendica.local/nodeinfo/2.1

{
    "version": "2.1",
    "software": {
        "name": "friendica",
        "version": "2026.05-1595",
        "repository": "https://github.com/friendica/friendica",
        "homepage": "https://friendi.ca"
    },
    "protocols": [
        "dfrn",
        "activitypub"
    ],
    ...

（输出节选（实测首））

curl -s "http://friendica.local/.well-known/webfinger?resource=acct:admin@friendica.local"

{
    "subject": "acct:admin@friendica.local",
    "aliases": [
        "http://friendica.local/~admin",
        "http://friendica.local/profile/admin"
    ],
    "links": [
        {
            "rel": "http://purl.org/macgirvin/dfrn/1.0",
            "href": "http://friendica.local/profile/admin"
        },
        {
            "rel": "http://schemas.google.com/g/2010#updates-from",
            "type": "application/atom+xml",
            "href": "http://friendica.local/feed/admin"
        },

（输出节选（实测首））

解读：nodeinfo software.version 为 2026.05-1595（发行版本-DB build），protocols 含 dfrn, activitypub；webfinger 返回 profile 别名与 Atom feed 链接。

八、注意事项

  1. bin/console 是 bash 包装：直接执行，不要加 php 前缀（第三章）；
  2. maintenance 没有查询子命令：maintenance status 会静默关闭维护模式（4.2），查询用 config system maintenance；
  3. apcu 下 CLI 缓存不可见：cache get 回 NULL、list 恒 0 keys 是预期行为（5.4）；
  4. 前台 daemon 的 status 不可靠：-f 形态不写 pidfile，用 ps aux | grep [c]onsole.php 验证（6.1）；
  5. config 写入一律字符串序列化（s:"..." 形态，4.1），能用 CLI/面板就不要手工 SQL；
  6. user add 不设置密码：建号后必须 user password 才能登录（5.1）；
  7. 裸命令行为不一致：serverblock 裸命令 = 列表，lock 裸命令 = 帮助（5.5/5.6）；
  8. 改配置后重启 cron 角色：daemon/worker 侧才生效（第三章）；
  9. 危险命令先备份：dbstructure update -f（强制重建）、relocate（全库 URL 迁移 + 全程维护模式）、storage move（批量迁移）执行前留底，架构基线可用 dbstructure dumpsql 导出（4.3）；
  10. API id ≠ console UID：verify_credentials 的 id 3 与 user search 的 UID 2 是两套体系（第七章）。

九、常见问题

Q1：bin/console help cron 报 Command cron doesn't exist？

Friendica 没有 cron 命令。周期任务机制 = daemon 按 system.cron_interval（实测 5 分钟）派生 Cron worker，由它派生 PollContacts/UpdateContacts/UpdateGServers/ExpireAndRemoveUsers/PostUpdate 等（6.4 源码 + workerqueue 统计实证）。手动触发：bin/console worker 前台一轮，或等下一周期。

Q2：刚执行 maintenance 1，maintenance status 却说 normal mode？

maintenance status 不是查询命令——源码 intval('status') 得 0，等价 maintenance 0，执行即静默关闭维护模式（4.2 实测证据链：status 之后 config system maintenance 已变回 0）。查询请用 config system maintenance。

Q3：cache set 显示成功，cache get 却回 NULL、list 恒 0 keys？

cache_driver => apcu 进程级缓存的预期表现（5.4）：每条 CLI 命令是独立 PHP 进程，互相看不到 APCu 条目。跨进程共享在 distributed_cache_driver（本环境 database）层。

Q4：daemon status 恒显示 isn't running，但站点联邦、队列都正常？

官方 cron 角色以 daemon start -f 前台运行，不写 pidfile（6.1 源码佐证：pidfile 仅非前台分支写入），status 依赖 pidfile 恒误报。以 ps aux | grep [c]onsole.php 看到 daemon start -f 进程为准。

Q5：API 返回 {"error": "This API requires login"}？

实测三类原因：(a) 口令不符——接管时 admin 口令与记录不一致，bin/console user password admin 重置后恢复（5.1/第七章）；(b) 想用表单 cookie 会话调 API——实测不通，用 Basic auth（第七章坑 2）；(c) 匿名访问需登录端点——实测 HTTP 401。另确认 system.basicauth => 1。

Q6：bin/console config get system url 不报错，但值没变化？

get 被当作类别名写入库（产生 cat='get' 垃圾行），正确读法是两参数 config system url（4.1 要点；垃圾行识别与清理见 《配置参数详解》 Q3）。

十、参考链接

Friendica 2026.05 常用 CLI 命令与工具详解 - Quzuo