Ubuntu 22.04 安装 farmOS 4.0.9 指南

目标：在 Ubuntu 22.04 服务器上从零安装 farmOS 4.0.9（基于 Drupal 11.3.19 的开源农场管理系统），覆盖 PHP 8.4 + GEOS 扩展 + PostgreSQL 16 的完整依赖链、官方预打包 tarball 与 Composer 两种构建方案的实测、Web 安装向导逐步实测、安装后验证、配置调优、排障实录与卸载清理。全部命令与回显均在 Ubuntu 22.04.5 LTS 服务器上实测采集（实测日期：2026-10-23）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（cat /etc/os-release 实测回显：PRETTY_NAME="Ubuntu 22.04.5 LTS"）
farmOS 版本：4.0.9（官方最新稳定版，2026-10-21 发布；查询日期 2026-10-23，来源 GitHub Releases）
Web 服务器：Apache 2.4.52（Server version: Apache/2.4.52 (Ubuntu)）
PHP：8.4.27（sury PPA，php -v 回显见 3.2 节）
数据库：PostgreSQL 16.15（PGDG 官方仓库，psql --version 回显见 3.4 节）
Composer：2.10.3
部署路径：代码库 /opt/drupal，文档根 /opt/drupal/web，站点数据 /opt/drupal/web/sites
监听端口：80（HTTP；生产建议加 HTTPS，见 6.4 节）
farmOS 代码库结构（ls /opt/drupal 实测）：

composer.json
composer.lock
recipes
vendor
web

关键点：文档根不是代码库根目录，而是其中的 web/ 子目录；vendor/ 存放 Composer 依赖（内含 drush），web/sites/ 存放站点设置与上传文件（升级时必须保留）。

二、前置条件与版本选型

2.1 服务器要求（官方口径）

farmOS 基于 Drupal，官方 Requirements 页（查询日期 2026-10-23）给出以下硬性要求：

依赖	要求	说明
PHP	8.4	必须是 8.4 线（farmOS 4.x 对应 Drupal 11.3）
PHP 扩展	BCMath、EXIF、GEOS、SimpleXML	GEOS 为地理计算扩展，Ubuntu 默认仓库只有 PHP 8.1 版本，需源码编译（3.2.3 节实测）
数据库	PostgreSQL 16+（官方推荐）/ MariaDB 10.6+ / MySQL 8.0+ / SQLite 3.45+	任选其一；本文实测 PostgreSQL 16
Web 服务器	Apache（官方镜像内置）或 Nginx	本文实测 Apache + mod_php

官方同时推荐以下 PHP 参数（默认值偏低，调优实测见 6.1 节）：memory_limit=256M、max_execution_time=240、max_input_time=240、max_input_vars=5000、realpath_cache_size=4096K、realpath_cache_ttl=3600。

2.2 版本选择

4.0.9（本文选用）：官方最新稳定版，2026-10-21 发布。4.0.9 相对 4.0.8 的唯一变更是官方 Docker 镜像内置 PHP 升级到 8.4.27（修复 CVE-2026-109618/109619）——非镜像部署也应把 PHP 升到 8.4.27。
3.5.9：3.x 维护线的最新版（基于 Drupal 10），适合暂时无法上 PHP 8.4 的存量站点，不建议新装。
版本对应关系：farmOS 4.x ↔ Drupal 11.3.x ↔ PHP 8.4；farmOS 3.x ↔ Drupal 10.x ↔ PHP 8.1+。

Ubuntu 22.04 自带 PHP 8.1、PostgreSQL 14，均不满足 farmOS 4.x 要求，因此依赖链的关键是：sury PPA 上 PHP 8.4 + PGDG 仓库上 PostgreSQL 16，这也是本章实验中实际走过的路径。

三、安装方案 A：官方预打包 tarball + Apache + PostgreSQL（主线实测）

3.1 方案说明

官方为无 Docker/Composer 的托管环境提供预打包 tarball（farmOS-4.0.9.tar.gz），由官方构建流程用 Composer 预先构建，内容与官方镜像内代码一致。只需解压到 Web 根目录、文档根指向 web/ 子目录即可。适合：单机快速部署、无法引入 Docker 的传统托管。代价：不能方便地加装社区 add-on 模块（官方 prebuilt 页明示该限制）。

3.2 安装 PHP 8.4 与扩展

3.2.1 接入 sury PPA 并安装 PHP 8.4

Ubuntu 22.04 官方仓库最高只有 PHP 8.1，通过社区维护的 sury PPA（ondrej/php）获取 8.4：

# 安装软件源管理工具
apt-get update && apt-get install -y software-properties-common ca-certificates curl
# 接入 ondrej/php PPA（PHP 8.4 的 Ubuntu 主渠道）
add-apt-repository -y ppa:ondrej/php
# 安装 PHP 8.4 CLI、Apache 模块与 farmOS 所需扩展
apt-get install -y php8.4-cli libapache2-mod-php8.4 \
  php8.4-bcmath php8.4-curl php8.4-gd php8.4-intl php8.4-mbstring \
  php8.4-pgsql php8.4-xml php8.4-zip php8.4-opcache php8.4-dev

验证版本与来源（实测回显）：

php -v

PHP 8.4.27 (cli) (built: Oct 21 2026 14:34:07) (NTS)
Copyright (c) The PHP Group
Built by Ubuntu

apt-cache policy php8.4-cli

php8.4-cli:
  Installed: 8.4.27-1+ubuntu22.04.1+deb.sury.org+1
  Candidate: 8.4.27-1+ubuntu22.04.1+deb.sury.org+1
  Version table:

确认需要的扩展已加载（实测回显节选）：

php -m | grep -iE "bcmath|exif|gd|mbstring|pdo|pgsql|simplexml|xml|curl|zip|intl"

bcmath
curl
exif
gd
intl
libxml
mbstring
PDO
pdo_pgsql
pgsql
SimpleXML
xml
xmlreader
xmlwriter
zip

⚠️ 说明：EXIF 与 SimpleXML 包含在 php8.4-common/xml 包中，装完即有；BCMath 由上面的显式安装提供。还缺 GEOS，下一小节单独处理。

3.2.2 安装 GEOS 系统库

apt-get install -y libgeos-dev
dpkg -l | grep libgeos

实测回显：

ii  libgeos-c1v5:amd64   3.10.2-1  amd64  Geometry Engine, Geographic Information Systems - C library
ii  libgeos-dev          3.10.2-1  amd64  Geometry Engine, Geographic Information Systems - Development files
ii  libgeos3.10.2:amd64  3.10.2-1  amd64  Geometry Engine, Geographic Information Systems - Shared library

3.2.3 编译 GEOS PHP 扩展（关键难点）

Ubuntu 仓库的 php-geos 包只面向默认 PHP 8.1 构建，装上后在 8.4 下不会加载。farmOS 官方 Dockerfile 的做法就是从源码编译（官方锁定提交 dfe1ab1），本节按同样方式实测：

# 下载官方 Dockerfile 锁定的 php-geos 源码
curl -sL -o /tmp/php-geos.tar.gz \
  https://github.com/libgeos/php-geos/archive/dfe1ab17b0f155cc315bc13c75689371676e02e1.tar.gz
cd /tmp && tar xzf php-geos.tar.gz
cd php-geos-dfe1ab17b0f155cc315bc13c75689371676e02e1
# 生成构建脚本并编译
./autogen.sh
./configure
make
make install

编译收尾实测回显（节选）：

Build complete.
Don't forget to run 'make test'.

Installing shared extensions:     /usr/lib/php/20240924/

💡 说明：20240924 是 PHP 8.4 的扩展 API 目录号（8.1 是 20210902），make install 会把 geos.so 装进当前默认 PHP（8.4）的扩展目录。若目录号不对，说明 CLI 默认指向的不是 8.4，可用 update-alternatives --set php /usr/bin/php8.4 修正。

注册扩展并在两个 SAPI 中启用：

printf "extension=geos.so\n" > /etc/php/8.4/mods-available/geos.ini
phpenmod -v 8.4 -s ALL geos
php -r "echo 'GEOS version: '.GEOSVersion().PHP_EOL;"

实测回显：

GEOS version: 3.10.2-CAPI-1.16.0

3.3 安装 Composer

Composer 是方案 B 与后续维护（drush 依赖等）的必备工具，按官方安装器安装：

curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer

实测回显：

All settings correct for using Composer
Downloading...

Composer (version 2.10.3 2026-08-27 13:34:23) successfully installed to: /usr/local/bin/composer
Use it: php /usr/local/bin/composer

3.4 安装 PostgreSQL 16 并建库

Ubuntu 22.04 仓库只有 PostgreSQL 14，farmOS 4.x 要求 16+，接入 PGDG 官方仓库：

# 接入 PGDG 仓库
install -d /usr/share/postgresql-common/pgdg
curl -sS -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
  https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt jammy-pgdg main" \
  > /etc/apt/sources.list.d/pgdg.list
apt-get update
apt-get install -y postgresql-16

验证版本与集群状态（实测回显）：

psql --version

psql (PostgreSQL) 16.15 (Ubuntu 16.15-1.pgdg22.04+2)

pg_lsclusters

16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

确认服务在运行（实测回显）：

systemctl is-active postgresql@16-main

active

创建 farmOS 专用角色与数据库（本文示例用户 farm、密码按演示约定 q1w2e3r4，生产请换强密码）：

runuser -u postgres -- psql -c "CREATE USER farm WITH PASSWORD 'q1w2e3r4';"
runuser -u postgres -- psql -c "CREATE DATABASE farm OWNER farm;"

实测回显：

CREATE ROLE
CREATE DATABASE

TCP 连通性验证（farmOS 走 TCP 连库）：

PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -U farm -d farm -c "select current_user, current_database();"

实测回显：

 current_user | current_database
--------------+------------------
 farm         | farm
(1 row)

3.5 配置 Apache 虚拟主机

启用 rewrite 模块（Drupal/farmOS 的 Clean URL 依赖它），创建站点配置：

a2enmod rewrite
cat > /etc/apache2/sites-available/farmos.conf <<'EOF'
<VirtualHost *:80>
    ServerName localhost
    DocumentRoot /opt/drupal/web
    <Directory /opt/drupal/web>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/farmos_error.log
    CustomLog ${APACHE_LOG_DIR}/farmos_access.log combined
</VirtualHost>
EOF
a2dissite 000-default
a2ensite farmos
systemctl reload apache2

逐项说明：DocumentRoot /opt/drupal/web 必须指向 tarball 解压后的 web/ 子目录；AllowOverride All 允许 Drupal 的 .htaccess 生效（隐藏 index.php、保护文件）；生产环境把 ServerName 换成真实域名。

验证模块与站点生效（实测回显）：

apachectl -M | grep rewrite

 rewrite_module (shared)

systemctl is-active apache2

active

此时访问服务器会 404（代码还没部署），先部署代码再访问。

3.6 下载 farmOS 4.0.9 预打包包并部署

wget -O /tmp/farmOS-4.0.9.tar.gz \
  https://github.com/farmOS/farmOS/releases/download/4.0.9/farmOS-4.0.9.tar.gz
sha256sum /tmp/farmOS-4.0.9.tar.gz

实测回显（校验值）：

0c75b95ec527b9c1079cbdc5bec9ac7da25b668722f1383ca25c3da7eabc7ac2  /tmp/farmOS-4.0.9.tar.gz

下载慢可走代理：wget -x http://192.168.1.62:7897 <URL>。解压部署（tarball 顶层目录为 farmOS-4.0.9/，用 --strip-components=1 直接落到 /opt/drupal）：

mkdir -p /opt/drupal
tar -xzf /tmp/farmOS-4.0.9.tar.gz -C /opt/drupal --strip-components=1
chown -R www-data:www-data /opt/drupal/web/sites

确认版本与结构（实测回显）：

ls /opt/drupal
cat /opt/drupal/composer.json | grep -A2 '"name"'

composer.json
composer.lock
recipes
vendor
web

  "name": "farmos/project",

grep -o '"farmos/farmos": "[^"]*"' /opt/drupal/composer.json

"farmos/farmos": "4.0.9"

3.7 Web 安装向导实测

浏览器访问 http://<服务器IP>/，会自动 302 跳转到安装器（实测：curl -s -o /dev/null -w "%{http_code} %{redirect_url}" http://localhost/ 回显 302 http://localhost/core/install.php）。farmOS 只内置英文界面与 farm 安装 Profile，语言与 Profile 选择步会自动跳过，直接进入数据库配置页。

第 1 步：Database configuration（数据库配置）

页面标题 Database configuration（表单 install_settings_form）。驱动单选框提供 4 个选项（实测表单字段）：

MySQL, MariaDB, Percona Server, or equivalent（默认选中）
MySQL, MariaDB, Percona Server, or equivalent via mysqli (Experimental)
PostgreSQL ← 本文选择
SQLite

选择 PostgreSQL 后填写：

字段	取值	说明
Database name	farm	3.4 节创建的库
Database username	farm	3.4 节创建的角色
Database password	q1w2e3r4	演示口令
Host	127.0.0.1	数据库与本机同置
Port	5432	PG 默认端口

点击 Save and continue。安装器校验连接、检查版本要求，通过后把连接信息写入 /opt/drupal/web/sites/default/settings.php（实测写入片段）：

$databases['default']['default'] = array (
  'database' => 'farm',
  'username' => 'farm',
  'password' => 'q1w2e3r4',
  'prefix' => '',
  'host' => '127.0.0.1',
  'port' => '5432',
  'driver' => 'pgsql',
  'namespace' => 'Drupal\\pgsql\\Driver\\Database\\pgsql',
  'autoload' => 'core/modules/pgsql/src/Driver/Database/pgsql/',
);

同时 URL 进入 core/install.php?rewrite=ok&profile=farm&langcode=en&id=1&op=start——其中 rewrite=ok 即 Apache mod_rewrite 检查通过。

第 2 步：Installing farmOS（模块批量安装）

页面标题 Installing farmOS，进度条从 0% 开始逐步安装 farm profile 的全部模块并导入配置，依据服务器性能耗时数分钟。浏览器端自动推进；命令行环境下也可用 curl 循环请求 op=do_nojs 步进直到出现 Configure site 表单（实测采用此方式推进完毕）。

第 3 步：Configure site（站点配置）

页面标题 Configure site（表单 install_configure_form），实测字段：site_name（站点名）、site_mail（站点邮箱）、account[name]（管理员用户名）、account[pass][pass1/pass2]（管理员密码）、account[mail]（管理员邮箱）、date_default_timezone（时区下拉）、enable_update_status_module / enable_update_status_emails（更新通知，默认勾选）。本文实测取值：

字段	取值
Site name	farmOS Demo
Site e-mail address	admin@example.com
Username	admin
Password	q1w2e3r4
E-mail address	admin@example.com
Default time zone	UTC

点击 Save and continue，安装器完成收尾后 302 回站点首页。实测首页已是登录后的农场仪表盘（<title>Dashboard | farmOS Demo</title>）。

⚠️ 注意：匿名访问 / 返回 403 是正常行为——仪表盘仅对登录用户开放（实测 curl -s -o /dev/null -w "%{http_code}" http://localhost/ 回显 403）。登录页在 /user/login。

3.8 安装后验证

验证 1：Web 登录。 在 /user/login 用 admin / q1w2e3r4 登录，实测提交后 303 跳转 /user/1?check_logged_in=1，/user 返回 302 到 /user/1，页面显示管理员资料页。

验证 2：drush 状态。 drush 随 tarball 内置（/opt/drupal/vendor/bin/drush）：

cd /opt/drupal && vendor/bin/drush status

实测回显：

 Drupal version   : 11.3.19
 Site URI         : http://default
 DB driver        : pgsql
 DB hostname      : 127.0.0.1
 DB port          : 5432
 DB username      : farm
 DB name          : farm
 Database         : Connected
 Drupal bootstrap : Successful
 Default theme    : gin
 Admin theme      : seven
 PHP binary       : /usr/bin/php8.4
 PHP config       : /etc/php/8.4/cli/php.ini
 PHP OS           : Linux
 PHP version      : 8.4.27
 Drush script     : /opt/drupal/vendor/bin/drush.php
 Drush version    : 13.8.0.0
 Drush temp       : /tmp
 Drush configs    : /opt/drupal/vendor/drush/drush/drush.yml
 Install profile  : farm

验证 3：模块与数据库更新检查。

cd /opt/drupal && vendor/bin/drush pm:list | grep -c Enabled

实测回显：81（farm profile 默认启用的模块数）。

cd /opt/drupal && vendor/bin/drush updatedb -y

实测回显：

 [success] No pending updates.

四、安装方案 B：Composer 构建代码库（实测）

4.1 方案说明

官方 Composer 项目模板为 Packagist 上的 farmos/project，composer.json 中 farmos/farmos 依赖默认约束 ^4.0。适合需要加装社区模块（如 composer require drupal/farm_bee）或自定义模块的团队。前提：3.2–3.5 节的 PHP/Apache/数据库环境完全一致，只是代码来源不同。

⚠️ 排障实录：farmOS 的模板包名是 farmos/project（项目模板），不是 farmos/composer-project。实测用错包名时 Composer 直接报 Could not find package farmos/composer-project with version 4.0.9.，按官方文档改用 farmos/project 即可。

4.2 create-project 实测

export COMPOSER_MEMORY_LIMIT=-1
composer create-project farmos/project:4.x-dev /opt/farmos --no-interaction --no-dev

命令会下载模板并解析安装全部依赖（数百个包），实测日志尾部正常收尾后验证（实测回显）：

ls /opt/farmos

composer.json  composer.lock  keys  recipes  vendor  web

cd /opt/farmos && composer show farmos/farmos | grep -E "^name|^versions"

name     : farmos/farmos
versions : * 4.0.9

💡 说明：4.x-dev 是模板包自身的版本约束标签，解析到的 farmOS 依赖是 4.x 线最新稳定版 4.0.9（上面 composer show 实测确认）。模板的 ^4.0 约束即"4.x 最新稳定"，想锁死版本可把 composer.json 里的约束改成 4.0.9 再 composer update --no-dev（官方提示 composer update --no-dev 需要连续执行两次，这是其 Composer merge 插件的已知行为）。

4.3 与方案 A 的差异

代码目录：/opt/farmos（文档根 /opt/farmos/web），Apache 虚拟主机只需把 DocumentRoot 与 <Directory> 路径换掉，其余步骤与 3.5–3.8 节完全一致；
升级方式：方案 A 用"新 tarball 覆盖（保留 web/sites）"，方案 B 用 composer update --no-dev 后跑 drush updatedb -y && drush cr；
扩展性：方案 B 可直接 composer require drupal/farm_bee 加装社区模块，方案 A 做不到（tarball 无 Composer 管理层）。

五、方案对比与选择建议

维度	方案 A：预打包 tarball	方案 B：Composer 构建
代码来源	官方预构建 tar.gz	Packagist 模板 farmos/project
是否需 Composer	不需要（但建议装）	必须
安装耗时	最短（下载+解压）	较长（全量解析下载依赖）
加装社区模块	困难（官方明示限制）	一条 `composer require`
升级方式	新 tarball 覆盖（保留 web/sites）	`composer update --no-dev`
与官方镜像一致性	完全一致	默认一致，可自定义
官方支持	无（prebuilt 免责）	社区流程

选择建议：单机自用、追求最快上线选方案 A；计划长期维护、要装 add-on 模块或自定义开发选方案 B；生产环境有运维能力时官方仍首选 Docker（见《farmOS 4.0.9 Docker Compose 部署指南》）。

六、配置说明

6.1 PHP 推荐参数（实测调优）

Ubuntu sury 包的默认值低于官方推荐，实测调优前（Apache SAPI）：memory_limit = 128M、max_execution_time = 30、max_input_time = 60。写入 farmOS 专用配置片段（不动发行版主配置，便于升级）：

cat > /etc/php/8.4/apache2/conf.d/90-farmos.ini <<'EOF'
memory_limit = 256M
max_execution_time = 240
max_input_time = 240
max_input_vars = 5000
realpath_cache_size = 4096K
realpath_cache_ttl = 3600
EOF
systemctl reload apache2

逐项说明：memory_limit 管单请求内存（安装与批量操作需要 256M）；max_execution_time/max_input_time 放宽长任务与大批量表单；max_input_vars=5000 防止地图/多选表单被截断；realpath_cache_* 加速 Drupal 海量文件路径解析。CLI SAPI 同样拷贝一份（drush 也吃内存）：

cp /etc/php/8.4/apache2/conf.d/90-farmos.ini /etc/php/8.4/cli/conf.d/90-farmos.ini
php -r "echo 'cli memory_limit: '.ini_get('memory_limit').PHP_EOL;"

实测回显：

cli memory_limit: 256M

通过 Web 请求核验 Apache SAPI 实际生效值（临时探针，验证后即删）：

printf '<?php echo ini_get("memory_limit"), "|", ini_get("max_execution_time"), "|", ini_get("max_input_vars"), "|", ini_get("realpath_cache_size"), PHP_EOL;' > /opt/drupal/web/ini-check.php
curl -s http://localhost/ini-check.php
rm -f /opt/drupal/web/ini-check.php

实测回显：

256M|240|5000|4096K

6.2 私有文件目录（官方要求）

farmOS 的文件上传依赖私有文件系统，官方安装文档要求装完后在 settings.php 显式配置：

mkdir -p /opt/drupal/web/sites/default/private/files
chown -R www-data:www-data /opt/drupal/web/sites/default/private
chmod -R 770 /opt/drupal/web/sites/default/private
cat >> /opt/drupal/web/sites/default/settings.php <<'EOF'

// farmOS: private files directory
$settings["file_private_path"] = "/opt/drupal/web/sites/default/private/files";
EOF

逐项说明：目录属主必须是 Web 服务器用户 www-data，权限 770（组内可写、其他用户禁入）；file_private_path 指向 Web 根之外的绝对路径。改完清缓存生效：

cd /opt/drupal && vendor/bin/drush cr

实测回显：

 [success] Cache rebuild complete.

6.3 定时任务（cron）

farmOS 依靠 cron 做数据库清理等例行维护，官方推荐宿主机 crontab 调 drush cron（每周一次即可）。加入 root 计划任务：

crontab -e

# 每周日 00:04 执行 farmOS 例行维护
4 0 * * 0 cd /opt/drupal && vendor/bin/drush cron > /dev/null 2>&1

手工触发验证（实测回显见 7.2 的排障说明）：

cd /opt/drupal && vendor/bin/drush cron

6.4 HTTPS 与反向代理

官方要求：地图上的 Geolocate 定位按钮、传感器数据接入等特性必须 HTTPS。常见做法是 Nginx 做 443 TLS 终结反代到 farmOS 的 80 端口，证书用 Let's Encrypt 自动签发续期（官方 Requirements 页推荐方案）。 farmOS 侧若在反向代理之后，还需在 settings.php 配置反向代理白名单（reverse_proxy 相关设置），确保获取真实客户端 IP。

6.5 升级方法（tarball 路线）

官方 prebuilt 文档要点：新版本发布后下载新 tarball，替换除 web/sites 外的所有文件与目录（注意是替换不是合并，web/sites 内含站点设置与上传文件，严禁覆盖），然后执行数据库更新：

# 1. 备份站点数据
cp -a /opt/drupal/web/sites /root/farmos-sites-backup
# 2. 下载并解压新版（保留 web/sites：先移出，覆盖后放回）
mv /opt/drupal/web/sites /tmp/sites-keep
rm -rf /opt/drupal && mkdir -p /opt/drupal
tar -xzf /tmp/farmOS-4.0.10.tar.gz -C /opt/drupal --strip-components=1
mv /tmp/sites-keep /opt/drupal/web/sites
chown -R www-data:www-data /opt/drupal/web/sites
# 3. 数据库更新 + 清缓存
cd /opt/drupal && vendor/bin/drush updatedb -y && vendor/bin/drush cr

⚠️ 注意：示例中的 4.0.10 以官方 Releases 页届时最新版为准；升级前务必整站备份（含数据库 pg_dump farm > farm.sql）。Composer 路线的升级见 4.3 节。

七、常见问题（FAQ）

7.1 php -m 里看不到 geos，安装向导或状态报告报 GEOS 缺失

现象：Ubuntu 直接 apt install php-geos 后 php -m | grep geos 无输出。定位：仓库里的 php-geos 是给默认 PHP 8.1 编译的（扩展装到 /usr/lib/php/20210902/），8.4 的扩展目录是 /usr/lib/php/20240924/，二进制不兼容。解决：按 3.2.3 节用源码编译（官方 Dockerfile 同款锁定版本），make install 会自动装入 8.4 扩展目录，再用 phpenmod 启用，php -r "echo GEOSVersion();" 出现 3.10.2-CAPI-1.16.0 即成功。

7.2 drush cron 报 "Error sending email"

现象：手工执行 vendor/bin/drush cron，尾部报 [error] Error sending email (from admin@example.com to admin@example.com ...)。定位：cron 会尝试发送系统通知邮件，而服务器未安装 MTA（如 postfix），Drupal 的邮件发送必然失败并写入 watchdog。解决：cron 本身已正常执行（其余任务不受影响），生产环境装并配置好 MTA 或接入 SMTP 模块（如 SMTP Authentication Support）即可消除该报错；仅作定时维护用途时可忽略，或按 6.3 节重定向输出。

7.3 安装向导卡在 Installing farmOS 很久

定位：farm profile 一次性安装 81 个模块并导入全部配置，低配服务器数分钟属正常；若用 curl 步进，每个 op=do_nojs 请求处理一批任务，耐心循环即可。验证：数据库表数量持续增长（实测装完 73 张表）、页面最终出现 Configure site 表单。

7.4 匿名访问首页 403

现象：安装完成后 curl http://服务器IP/ 返回 403 Forbidden。定位：这是 farmOS 的设计行为——仪表盘只对登录用户开放，匿名用户无权访问。解决：从 /user/login 登录后访问；对外站点可另行配置公开首页。

7.5 升级后提示重新安装

定位：升级时把 web/sites 目录覆盖丢了——里面有 settings.php（含数据库连接）与全部上传文件。解决：按 6.5 节流程先移出 sites 再替换代码，务必使用备份恢复；这也是官方文档反复强调"不要覆盖 web/sites"的原因。

八、卸载与清理

按依赖的反向顺序拆除（示例同时清掉代码、数据库、Web 配置与 PHP/数据库服务，按需取舍）：

# 1. 停站点与数据库服务
systemctl stop apache2
systemctl stop postgresql@16-main
# 2. 删除 farmOS 代码与站点数据
rm -rf /opt/drupal
# 3. 删除数据库集群中的 farm 库与角色（如整库不再用，可直接 drop 集群）
rm -rf /var/lib/postgresql/16/main && apt-get purge -y postgresql-16 && apt-get autoremove -y
# 4. 摘除 Apache 站点与模块
a2dissite farmos && rm -f /etc/apache2/sites-available/farmos.conf
# 5. 如需彻底移除 PHP 8.4
apt-get purge -y "php8.4*" libapache2-mod-php8.4 && apt-get autoremove -y

逐项说明：第 3 步 rm -rf /var/lib/postgresql/16/main 会连带删除同集群里所有库，仅在该 PostgreSQL 实例专用于 farmOS 时执行；生产环境先 pg_dump 备份。

九、参考链接

官方安装指南：https://farmos.org/hosting/install
服务器要求：https://farmos.org/hosting/requirements
预打包发行版：https://farmos.org/hosting/prebuilt
Composer 构建：https://farmos.org/hosting/composer
更新指南：https://farmos.org/hosting/update
Releases 下载：https://github.com/farmOS/farmOS/releases
sury PHP 仓库：https://deb.sury.org/
PGDG 仓库：https://apt.postgresql.org/