Friendica Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用官方 friendica 发行包以 Docker Compose 从零部署 Friendica 2026.05 "Blutwurz" 单节点，覆盖环境变量自动安装、管理员创建（含 HIBP 弱密码拦截处理）、数据库 schema 升级、WebFinger/NodeInfo 联邦端点验证与 daemon 启动竞态等典型故障排查。已在 Ubuntu 22.04 x86_64 服务器（宿主端口 8134，编排子网 10.89.60.0/24）实测通过，页面、API 端点与后台 worker 全部验证正常。

一、环境信息

项目	实测值
操作系统	Ubuntu 22.04（x86_64）
Docker	29.9.2, build a82e528
Docker Compose	v5.6.1
Friendica	2026.05 "Blutwurz"（friendica:2026.05，1.22GB，内置 Apache/2.4.69 + PHP 8.4.27）
数据库	MariaDB 11（mariadb:11，458MB）
部署目录	/opt/friendica
服务端口	8134（HTTP）
编排栈名	friendica-2026.05-stack（内部网络段 10.89.60.0/24）
站点 URL	http://friendica.local（编排内 alias 解析）
演示账号	admin / q1w2e3r4（管理员）

本方案为 3 角色最小完整形态：web（Apache + PHP，Web/API/管理面板）+ cron（官方 /cron.sh 入口拉起 daemon，消费联邦投递队列）+ db（MariaDB）。Redis 为可选加速项，本方案未启用（配置挂载一节说明接入点）。

二、镜像选型说明

2.1 应用镜像：Docker Hub 官方 friendica 发行包

Friendica 在 Docker Hub 以官方库镜像 friendica 发布，版本 tag 与 GitHub 日期版本号一致（2026.05）。同一镜像承担两个编排角色：默认入口跑 Apache（web 服务），entrypoint: /cron.sh 覆盖入口后跑后台守护进程（cron/daemon 角色）。

docker pull friendica:2026.05

实测回显：

2026.05: Pulling from library/friendica
Digest: sha256:75b27d7e50720464067c9fc8e8769caa3a175587ec9a9303cb90fa558aa36f24
Status: Image is up to date for friendica:2026.05
docker.io/library/friendica:2026.05

镜像内运行时版本以启动横幅实测为准：Apache/2.4.69 (Debian) PHP/8.4.27。

2.2 数据库镜像：MariaDB 11

官方要求 MySQL 兼容库并明确推荐 MariaDB（InnoDB + Barracuda）。本方案用 mariadb:11：

docker pull mariadb:11

实测回显：

Digest: sha256:c4124d1afa875e47f2892edf26b482fa54f796e2f342d3717a04ca091a22a9bd
Status: Image is up to date for mariadb:11
docker.io/library/mariadb:11

2.3 依赖组件版本对照（实测）

组件	镜像/版本	实测体积	角色
应用	friendica:2026.05	1.22GB	web（Apache/PHP）+ cron（daemon），同包双角色
数据库	mariadb:11	458MB	全部业务数据、配置与任务队列（实测 125 张表）

💡 技术拓展：Friendica 容器化部署的镜像来源有三种常见形态——

形态特点适用场景
官方库镜像 friendica（本文）版本 tag 跟随发布，开箱即用，含自动安装逻辑生产与快速验证
官方示例编排 build ./app 源码构建官方文档 example compose 用自定义构建目录需要改 PHP 扩展/打补丁
裸机源码部署 LAMP 直接跑，无编排共享主机/已有 PHP 运维体系

本文采用官方库镜像：版本可固定、首启自动完成安装（见 4.5），无需自行构建。

形态	特点	适用场景
官方库镜像 friendica（本文）	版本 tag 跟随发布，开箱即用，含自动安装逻辑	生产与快速验证
官方示例编排 build ./app 源码构建	官方文档 example compose 用自定义构建目录	需要改 PHP 扩展/打补丁
裸机源码部署	LAMP 直接跑，无编排	共享主机/已有 PHP 运维体系

三、前置条件

服务器已安装 Docker 29.x 与 Docker Compose v2+（docker --version、docker compose version 可用，实测版本见第一章表）；
端口 8134 未被占用（ss -ltn | grep 8134 应无输出）；
内存 ≥ 2GB：官方 requirements 明确 1GB 有节点掉线报告；
磁盘 ≥ 5GB（镜像 1.22GB + 数据库与附件增长）；
明确站点对外 URL：本文用 http://friendica.local，需在访问机器的 hosts 中把 friendica.local 指向本服务器（生产环境用真实域名并在反代层终止 TLS）。站点 URL 必须域名根路径，路径前缀（如 /friendica/）形态无法与 diaspora*/GNU Social 联邦（官方明示），且日后换址需跑 bin/console relocate 全库迁移；
若计划开放注册或邮件通知，需备好 SMTP；纯内网演示可跳过（缺 SMTP 仅影响发信，见 FAQ Q4）。

四、部署步骤

4.1 目录准备

mkdir -p /opt/friendica/data/db /opt/friendica/data/html
cd /opt/friendica

两个数据目录分别承载数据库文件与应用目录（含配置），用途见第五、八章。

4.2 编写 docker-compose.yml

在 /opt/friendica 下创建 docker-compose.yml（演示口令统一 q1w2e3r4，生产请替换）：

name: friendica-2026.05-stack

services:
  db:
    image: mariadb:11
    container_name: friendica-db
    restart: unless-stopped
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4
      MARIADB_DATABASE: friendica
      MARIADB_USER: friendica
      MARIADB_PASSWORD: q1w2e3r4
    volumes:
      - ./data/db:/var/lib/mysql
    networks:
      friendica-net:
        ipv4_address: 10.89.60.2

  web:
    image: friendica:2026.05
    container_name: friendica-web
    restart: unless-stopped
    hostname: friendica.local
    ports:
      - "8134:80"
    environment:
      MYSQL_HOST: db
      MYSQL_PORT: "3306"
      MYSQL_DATABASE: friendica
      MYSQL_USER: friendica
      MYSQL_PASSWORD: q1w2e3r4
      FRIENDICA_ADMIN_MAIL: admin@friendica.local
      FRIENDICA_URL: http://friendica.local
      FRIENDICA_TZ: Asia/Shanghai
      FRIENDICA_LANG: en
      FRIENDICA_SITENAME: quzuo Friendica
    volumes:
      - ./data/html:/var/www/html
    depends_on:
      - db
    networks:
      friendica-net:
        ipv4_address: 10.89.60.3
        aliases:
          - friendica.local

  cron:
    image: friendica:2026.05
    container_name: friendica-cron
    restart: unless-stopped
    hostname: friendica.local
    entrypoint: /cron.sh
    environment:
      MYSQL_HOST: db
      MYSQL_PORT: "3306"
      MYSQL_DATABASE: friendica
      MYSQL_USER: friendica
      MYSQL_PASSWORD: q1w2e3r4
      FRIENDICA_ADMIN_MAIL: admin@friendica.local
      FRIENDICA_URL: http://friendica.local
      FRIENDICA_TZ: Asia/Shanghai
      FRIENDICA_LANG: en
      FRIENDICA_SITENAME: quzuo Friendica
    volumes:
      - ./data/html:/var/www/html
    depends_on:
      - db
    networks:
      friendica-net:
        ipv4_address: 10.89.60.4

networks:
  friendica-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.60.0/24

编排要点：

cron 服务与 web 服务同镜像、同挂载，仅入口不同（entrypoint: /cron.sh 起 daemon 而非 Apache）——这是官方示例编排的固定形态，缺 cron 服务则联邦投递不工作；
web 服务的网络 aliases 把 friendica.local 指到容器，宿主访问时在 hosts 里把 friendica.local 指向 127.0.0.1（配合 8134 端口映射）；
固定 IP（10.89.60.2–4）与子网便于排查与防火墙规则编写，非必需项。

4.3 启动

docker compose up -d

实测回显：

 Network friendica-202605-stack_friendica-net Creating 
 Network friendica-202605-stack_friendica-net Created 
 Container friendica-db Creating 
 Container friendica-db Created 
 Container friendica-web Creating 
 Container friendica-cron Creating 
 Container friendica-web Created 
 Container friendica-cron Created 
 Container friendica-db Starting 
 Container friendica-db Started 
 Container friendica-cron Starting 
 Container friendica-web Starting 
 Container friendica-cron Started 
 Container friendica-web Started

docker compose ps

实测回显：

NAME             IMAGE               COMMAND                  SERVICE   CREATED          STATUS          PORTS
friendica-cron   friendica:2026.05   "/cron.sh"               cron      49 seconds ago   Up 43 seconds   80/tcp
friendica-db     mariadb:11          "docker-entrypoint.s…"   db        49 seconds ago   Up 49 seconds   3306/tcp
friendica-web    friendica:2026.05   "/entrypoint.sh apac…"   web       49 seconds ago   Up 48 seconds   0.0.0.0:8134->80/tcp, [::]:8134->80/tcp

4.4 首启自动安装

官方镜像的 web 服务检测到「数据库未安装 + 环境变量齐备」时会自动完成整站安装（写配置文件、建表、装主题），无需跑 Web 安装向导。观察安装日志：

docker compose logs web

实测回显（完整）：

friendica-web  | Initializing Friendica 2026.05 ...
friendica-web  | Initializing finished
friendica-web  | New Friendica instance
friendica-web  | Installation with environment variables
friendica-web  | Waiting for MySQL db initialization...
friendica-web  | .
friendica-web  | Starting Friendica installation ...
friendica-web  | Initializing setup...
friendica-web  |  Complete!
friendica-web  | 
friendica-web  | Checking environment...
friendica-web  |  NOTICE: Not checking .htaccess/URL-Rewrite during CLI installation.
friendica-web  | 
friendica-web  |  Complete!
friendica-web  | 
friendica-web  | Creating config file...
friendica-web  |  Complete!
friendica-web  | 
friendica-web  | Checking database...
friendica-web  |  Complete!
friendica-web  | 
friendica-web  | Inserting data into database...
friendica-web  | 
friendica-web  |  Complete!
friendica-web  | 
friendica-web  | Installing theme
friendica-web  |  Complete
friendica-web  | 
friendica-web  | 
friendica-web  | Installation is finished
friendica-web  | Installation finished
friendica-web  | [Mon Nov 02 04:16:40.168397 2026] [mpm_prefork:notice] [pid 1:tid 1] AH00163: Apache/2.4.69 (Debian) PHP/8.4.27 configured -- resuming normal operations
friendica-web  | [Mon Nov 02 04:16:40.168427 2026] [core:notice] [pid 1:tid 1] AH00094: Command line: 'apache2 -D FOREGROUND'

自动安装把数据库连接写进 config/local.config.php、把系统初始化项写进数据库 config 表（生成内容见第八章），站点 URL 经环境变量映射层生效，验证：

docker compose exec web bin/console config system url

实测回显：

system.url => http://friendica.local

4.5 创建管理员账号

官方安装不创建任何用户（user list active 此时为空白表）。创建 admin 前注意：Friendica 默认调用 Have I Been Pwned（HIBP）校验密码是否泄露，测试口令 q1w2e3r4 在泄露库名单中会被拒绝（实测报错与原理见 FAQ Q1），演示环境先关闭该开关：

docker compose exec web bin/console config system disable_password_exposed true

实测回显：

system.disable_password_exposed <= true

创建用户（user add 交互补全：先经 stdin 传入两次密码，最后回车跳过可选头像 URL）：

printf 'q1w2e3r4\nq1w2e3r4\n' | docker compose exec -T web bin/console user add Admin admin admin@friendica.local en

实测回显：

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

第二行是发欢迎邮件失败的提示——本方案未配 SMTP，属预期噪音，不影响账号可用性（见 FAQ Q4）。验证用户与版本：

docker compose exec web bin/console --version
docker compose exec web bin/console user list active

实测回显：

Friendica Console version 2026.05
+-------+-------+--------------------------------------+-----------------------+------------------------+-------+-----------+
| Nick  | Name  | URL                                  | E-Mail                | Register               | Login | Last Item |
+-------+-------+--------------------------------------+-----------------------+------------------------+-------+-----------+
| admin | Admin | http://friendica.local/profile/admin | admin@friendica.local | less than a second ago | never | never     |
+-------+-------+--------------------------------------+-----------------------+------------------------+-------+-----------+

4.6 数据库 schema 升级到位

2026.05 发行包内置 schema 为 build 1594，而该版本代码期望 1595（官方安装器不自动跑增量升级）。核对并升级：

docker compose exec web bin/console config system build
docker compose exec web bin/console dbstructure update
docker compose exec web bin/console config system build

实测回显（升级命令本身静默，以 build 值变化验证）：

system.build => 1594
system.build => 1595

⚠️ 注意：schema 停在 1594 时站点表面正常，但联邦对端投递会踩「结构缺列」类隐性故障，部署完成后务必把 build 升到与版本匹配的 1595（dbstructure update 幂等，可放心再跑一次）。

4.7 部署验证

依次验证页面、登录入口、联邦发现端点与后台队列：

curl -sI http://localhost:8134 | head -6

实测回显：

HTTP/1.1 200 OK
Date: Mon, 02 Nov 2026 04:17:31 GMT
Server: Apache/2.4.69 (Debian)
X-Powered-By: PHP/8.4.27
Set-Cookie: PHPSESSID=73a561c84dc3a1d1d2fb330397690189; path=/; HttpOnly
Expires: Thu, 19 Nov 1981 08:52:00 GMT

curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: friendica.local' http://localhost:8134/login

实测回显：

WebFinger 账号发现（输出节选，实测首尾）：

curl -s 'http://localhost:8134/.well-known/webfinger?resource=acct:admin@friendica.local' -H 'Host: 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": "self",
            "type": "application/activity+json",
            "href": "http://friendica.local/profile/admin"
        },
        ...
        {
            "rel": "http://purl.org/openwebauth/v1",
            "type": "application/x-zot+json",
            "href": "http://friendica.local/owa"
        }
    ]
}

解读：rel=self 的 ActivityPub Actor URL 即 /profile/admin（2026.05 不使用 /ap/ 前缀路径），同时输出 DFRN/Diaspora* 与 OStatus 兼容链接——双协议网关能力在发现层直接可见。

NodeInfo 实例元数据：

curl -s http://localhost:8134/nodeinfo/2.0 -H 'Host: friendica.local'

实测回显（节选）：

{
    "version": "2.0",
    "software": {
        "name": "friendica",
        "version": "2026.05-1595"
    },
    "protocols": [
        "dfrn",
        "activitypub"
    ],
    ...
    "openRegistrations": false,

software.version 的 2026.05-1595 同时暴露应用版本与 DB build，是外部快速核对 4.6 是否完成的办法。

后台队列验证（worker 已被 cron 服务消费过至少一轮）：

docker compose exec db mariadb -ufriendica -pq1w2e3r4 friendica -e "SELECT k,v FROM \`key-value\` WHERE k='last_worker_execution'; SELECT COUNT(*) AS pending FROM workerqueue;"

实测回显：

k	v
last_worker_execution	2026-11-02 04:18:23
pending
0

浏览器侧功能验证：hosts 映射 friendica.local 后访问 http://friendica.local:8134，以 admin / q1w2e3r4 登录，进入管理面板（Admin → Site）确认站点名显示为 quzuo Friendica（环境变量生效实测：bin/console config config sitename 回显 config.sitename => quzuo Friendica），发帖后时间线可见即部署闭环。

五、数据持久化说明

编排卷（相对 /opt/friendica）	用途	重建栈后是否保留
./data/db	MariaDB 全部数据（用户/帖子/联系人/配置/队列，实测 125 张表）	是
./data/html	应用目录：config/ 配置分片、addon 状态、日志等（镜像升级时配置随卷保留）	是

💡 说明：Friendica 附件（头像/图片）默认存数据库而非磁盘（发行包内置双后端，实测默认选中 Database：bin/console storage list 回显 * | Database）。因此备份重心是整库导出；若切换 Filesystem 后端，文件落 /var/www/data（zz-docker 配置 storage.filesystem_path），需另加挂载。

备份建议：

# 数据库整库（含全部帖子与配置）
docker compose exec -T db mariadb-dump -uroot -pq1w2e3r4 friendica > friendica-$(date +%F).sql
# 配置目录
tar czf friendica-config-$(date +%F).tar.gz data/html/config

六、环境变量表

官方镜像识别的部署级环境变量（本方案用到的实测值）：

变量	实测取值	说明
MYSQL_HOST / MYSQL_PORT	db / 3306	数据库地址（编排内服务名）
MYSQL_DATABASE / MYSQL_USER / MYSQL_PASSWORD	friendica / friendica / q1w2e3r4	业务库凭据，须与 db 服务 MARIADB_* 一致
MARIADB_ROOT_PASSWORD	q1w2e3r4	数据库 root 口令（备份/排障用）
MARIADB_DATABASE / MARIADB_USER / MARIADB_PASSWORD	friendica / friendica / q1w2e3r4	db 服务初始化建库建用户
FRIENDICA_URL	http://friendica.local	站点 URL，落库后不可随意改（改址用 relocate）
FRIENDICA_ADMIN_MAIL	admin@friendica.local	管理员邮箱（映射 config.admin_email）
FRIENDICA_SITENAME	quzuo Friendica	站点名（映射 config.sitename）
FRIENDICA_TZ	Asia/Shanghai	默认时区
FRIENDICA_LANG	en	默认语言
FRIENDICA_DEBUGGING / FRIENDICA_LOGLEVEL	未启用（可选）	日志总开关与级别，见 FAQ Q6
FRIENDICA_NO_VALIDATION	未启用（可选）	置真则跳过 URL/邮箱格式校验（zz-docker 映射 disable_url_validation/disable_email_validation）
SMTP_DOMAIN / SMTP_FROM	未启用（可选）	设置后 zz-docker 自动生成 sender_email
REDIS_HOST / REDIS_PORT / REDIS_PW / REDIS_DB	未启用（可选）	配置分片 01redis 读取，启用会话/分布式缓存/锁走 Redis

七、配置参数说明

Friendica 的配置分四层，后层覆盖前层（这是排障时最容易踩坑的结构，逐项详解见本专栏配置篇）：

静态默认：镜像内 static/defaults.config.php（实测 210 个键与注释，勿直接改）；
本地配置文件：config/local.config.php 及同目录分片（00apcu、01redis、zz-docker），容器形态由镜像内置模板生成；
环境变量映射层：static/env.config.php 把 FRIENDICA_*/MYSQL_*/REDIS_* 环境变量映射到命名空间配置键（如 FRIENDICA_SITENAME → config.sitename），覆盖文件配置；
数据库 config 表：管理面板与 bin/console config 的写入层，优先级最高——文件里改了但库里已有同名键时，生效的是库值（local.config.php 文件头注释原文即警告 "will be overruled by the admin panel"）。

本地配置分片实测（首次安装后由镜像生成）：

00apcu.config.php：默认把 system.cache_driver 设为 apcu（进程内缓存）；
01redis.config.php：检测到 REDIS_HOST 环境变量才启用 session_handler=cache、distributed_cache_driver=redis、lock_driver=redis；
zz-docker.config.php：固化 system.pidfile=/var/run/friendica.pid、storage.filesystem_path=/var/www/data，并翻译 FRIENDICA_NO_VALIDATION/SMTP_DOMAIN 等变量。

全量参数逐项含义、默认值与修改方式见本专栏《Friendica 2026.05 配置参数详解》（配置篇）。

八、配置文件挂载

./data/html:/var/www/html 挂载的是整个应用目录（而非仅配置），镜像升级时目录内容保留、代码由新镜像覆盖。首启自动安装后目录内生成的配置（实测 ls -l data/html/config/）：

total 20
-rw-r--r-- 1 www-data www-data  165 Nov  2 12:16 00apcu.config.php
-rw-r--r-- 1 www-data www-data  382 Nov  2 12:16 01redis.config.php
-rw-r--r-- 1 www-data www-data 1090 Nov  2 12:16 local.config.php
-rw-r--r-- 1 www-data www-data 1395 Nov  2 12:16 local-sample.config.php
-rw-r--r-- 1 www-data www-data  847 Nov  2 12:16 zz-docker.config.php

生成的 local.config.php 实测内容（环境变量已落位）：

<?php
return [
	'database' => [
		'hostname' => 'db',
		'username' => 'friendica',
		'password' => 'q1w2e3r4',
		'database' => 'friendica',
		'charset' => 'utf8mb4',
	],
	'config' => [
		'php_path' => '/usr/local/bin/php',
		'admin_email' => 'admin@friendica.local',
		'sitename' => 'Friendica Social Network',
		'register_policy' => \Friendica\Module\Register::OPEN,
		'max_import_size' => 200000,
	],
	'system' => [
		'url' => 'http://friendica.local',
		'basepath' => '/var/www/html',
		'default_timezone' => 'Asia/Shanghai',
		'language' => 'en',
	],
];

⚠️ 注意：文件里的 sitename 是出厂默认值「Friendica Social Network」，而 FRIENDICA_SITENAME=quzuo Friendica 走第七章第 3 层环境变量映射（覆盖文件配置、但被数据库 config 表覆盖），所以面板显示 quzuo Friendica——这正是「改文件不生效」类困惑的根源，动手前先想清楚要改哪一层。

九、等价 docker run（理解编排等价形态）

将本编排拆成手工命令的等价形态（用于理解映射关系，实际部署以 compose 为准；需自建网络 docker network create --subnet 10.89.60.0/24 friendica-net）：

# 数据库
docker run -d --name friendica-db --network friendica-net --ip 10.89.60.2 \
  -e MARIADB_ROOT_PASSWORD=q1w2e3r4 -e MARIADB_DATABASE=friendica \
  -e MARIADB_USER=friendica -e MARIADB_PASSWORD=q1w2e3r4 \
  -v /opt/friendica/data/db:/var/lib/mysql \
  mariadb:11 --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

# Web 服务
docker run -d --name friendica-web --network friendica-net --ip 10.89.60.3 \
  --hostname friendica.local -p 8134:80 \
  -e MYSQL_HOST=db -e MYSQL_DATABASE=friendica -e MYSQL_USER=friendica -e MYSQL_PASSWORD=q1w2e3r4 \
  -e FRIENDICA_URL=http://friendica.local -e FRIENDICA_ADMIN_MAIL=admin@friendica.local \
  -e FRIENDICA_TZ=Asia/Shanghai -e FRIENDICA_LANG=en -e FRIENDICA_SITENAME="quzuo Friendica" \
  -v /opt/friendica/data/html:/var/www/html \
  friendica:2026.05

# cron/daemon 服务（同镜像同挂载，仅入口不同）
docker run -d --name friendica-cron --network friendica-net --ip 10.89.60.4 \
  --hostname friendica.local \
  --entrypoint /cron.sh \
  -e MYSQL_HOST=db -e MYSQL_DATABASE=friendica -e MYSQL_USER=friendica -e MYSQL_PASSWORD=q1w2e3r4 \
  -e FRIENDICA_URL=http://friendica.local -e FRIENDICA_ADMIN_MAIL=admin@friendica.local \
  -v /opt/friendica/data/html:/var/www/html \
  friendica:2026.05

手工形态下 friendica.local 的服务名解析需自行处理（compose 的 aliases 自动完成），故生产推荐 compose。

十、常用运维命令

# 状态总览
docker compose ps

# 应用日志（Apache 访问/错误）
docker compose logs -f web

# daemon/worker 日志（联邦投递、抓取、清理在此）
docker compose logs -f cron

# 进入容器跑控制台（命令全集见《Friendica 2026.05 常用 CLI 命令与工具详解》）
docker compose exec web bin/console

# 前台手动跑一轮 worker（排障时立即触发队列消费）
docker compose exec web bin/console worker

# 维护模式
docker compose exec web bin/console maintenance status

# 版本升级：改 compose 中镜像 tag 后
docker compose pull && docker compose up -d
# 升级后必跑 schema 增量（同 4.6）
docker compose exec web bin/console dbstructure update

升级说明：Friendica 日期版本间为增量迁移（dbstructure update 按 build 号逐段升级），跨版本升级前务必整库备份；镜像 tag 不要写 latest，固定 2026.05 形态可重复部署。

十一、常见问题（FAQ）

以下均为本环境实测遇到并定位的故障，按触发顺序排列。

Q1：user add / user password 设置 q1w2e3r4 被拒绝

现象：控制台报密码不合格。原因：Friendica 默认把新设密码送 Have I Been Pwned 泄露库校验，弱测试口令必被拦。解决（4.5 已用）：

docker compose exec web bin/console config system disable_password_exposed true

⚠️ 注意两点实测细节：参数类别是 system 不是 config——写成 bin/console config config disable_password_exposed true 不报错，但会在 config 表留下 cat='config' 的垃圾行且开关不生效；另外该开关生产环境应保持关闭，仅演示环境使用。

Q2：cron 服务首启报 [Error] Friendica isn't properly installed yet

实测 cron 日志：

friendica-cron  | Waiting for MySQL db initialization...
friendica-cron  | ...
friendica-cron  | [Error] Friendica isn't properly installed yet
friendica-cron  | Waiting for MySQL db initialization...
friendica-cron  | 
friendica-cron  | Starting Friendica daemon

原因：web 与 cron 同时启动，cron 先于 web 的自动安装完成而醒来。镜像入口自带等待重试逻辑，安装就绪后 daemon 自动拉起，无需处理；若长期停留该错误，检查 db 服务连通性与 web 安装日志（4.4）。

Q3：daemon status 永远显示未运行，首启日志报 Cannot save process with PID 15

实测 cron 日志与状态：

friendica-cron  | Starting Friendica daemon
friendica-cron  | [Error] Cannot save process with PID 15.

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

两个现象都定位清楚了，均无害：

daemon status 报未运行是前台模式的固有行为：官方 /cron.sh 用 daemon start -f 前台运行，而源码 src/System/Daemon.php 的 start() 只在非前台 fork 分支里写 pidfile——前台模式根本不产生 pidfile，status 自然查不到。daemon 真实状态用进程与队列证据判断（实测）：
```
docker compose exec cron ps aux | grep daemon
```
```
www-data       1  0.0  0.0   2572  1424 ?  Ss  04:21  0:00 tini -- php /var/www/html/bin/console.php daemon start -f
www-data      13  0.2  0.2 157736 48680 ?  S   04:21  0:00 php /var/www/html/bin/console.php daemon start -f
```
配合 4.7 的 last_worker_execution 有值，即证明 daemon 在正常消费。
Cannot save process with PID 15 是首启竞态：该报错来自 worker 进程注册逻辑（src/Core/Worker/Repository/Process.php，往数据库 process 表写进程记录），cron 先于 web 自动安装完成而启动时数据库尚未就绪，插入失败；重启后不再复现（实测 docker compose restart cron 后日志无此行）。无需处理，长期反复出现才需要查数据库连通性。

Q4：创建用户时回显 msmtp: account default not found

原因：user add 成功后尝试发欢迎邮件，本方案未配 SMTP。属预期噪音，账号已创建成功（user list active 可见）。需要真实发信时在编排注入 SMTP_DOMAIN（生成 sender_email）并在管理面板配置 mail 参数。

Q5：bin/console version 报 Command version doesn't exist

原因：version 不是子命令。查版本用全局选项：

docker compose exec web bin/console --version

实测回显：

Friendica Console version 2026.05

同理 dbstructure status 不存在，查 schema 进度用 bin/console config system build（4.6）。

Q6：friendica.log 一直是 0 字节 / 找不到日志

2026.05 行为变更（实测）：system.debugging 为 false 时日志管线直接挂 NullLogger，logfile/loglevel 配得再对也不写。启用方法：编排加 FRIENDICA_DEBUGGING: "true"（或 bin/console config system debugging true）并重启 cron。

⚠️ 安全提示：debugging=true 且 loglevel=debug 时，日志会把系统账户 RSA 私钥明文打出来（实测 System account to be created 调试行含完整 prvkey）。生产如必须开 debugging 排障，loglevel 保持 notice，事后清理日志文件。

Q7：WebFinger 返回 Owner was not found

4.7 的 WebFinger 验证必须在用户创建之后执行；空库时该端点回显 HTML 错误页（实测 <p>Owner was not found for user->uid=admin</p>），不代表部署失败。

Q8：浏览器用 http://localhost:8134 访问后，生成的链接变成 localhost

Friendica 在 URL 配置异常时会回退用请求 Host 推导站点地址，导致帖子内链接/Actor URL 污染（修复历史地址需 bin/console relocate）。始终用与 FRIENDICA_URL 一致的 http://friendica.local:8134（hosts 映射）访问与测试。

十二、参考链接

官方仓库：https://github.com/friendica/friendica
官方镜像：https://hub.docker.com/r/friendica/friendica
系统要求：https://friendi.ca/requirements/
官方示例编排（db/redis/app/cron 形态）：https://github.com/friendica/friendica/blob/2026.05/doc/Debian/docker-compose.yml
2026.05 发布说明：https://github.com/friendica/friendica/releases/tag/2026.05
本专栏相关文档：选型评估见《Friendica 介绍与选型指南》；参数逐项说明见《Friendica 2026.05 配置参数详解》；控制台命令全集见《Friendica 2026.05 常用 CLI 命令与工具详解》。

Friendica 2026.05 Docker Compose 部署指南

Friendica Docker Compose 部署指南

一、环境信息

二、镜像选型说明

2.1 应用镜像：Docker Hub 官方 friendica 发行包

2.2 数据库镜像：MariaDB 11

2.3 依赖组件版本对照（实测）

三、前置条件

四、部署步骤

4.1 目录准备

4.2 编写 docker-compose.yml

4.3 启动

4.4 首启自动安装

4.5 创建管理员账号

4.6 数据库 schema 升级到位

4.7 部署验证

五、数据持久化说明

六、环境变量表

七、配置参数说明

八、配置文件挂载

九、等价 docker run（理解编排等价形态）

十、常用运维命令

十一、常见问题（FAQ）

十二、参考链接