Ubuntu 22.04 安装 grocy 4.7.1 指南

目标：在 Ubuntu 22.04 服务器上从零安装 grocy 4.7.1（官方 Release 包 + Apache 形态），完整覆盖 PHP 8.5 依赖链搭建、SQLite 3.40+ 依赖的两种实测坑与修复、初始化迁移、默认账号改密、验证、升级与卸载。全部命令与回显均在 Ubuntu 22.04（x86_64）实测通过，实测时点 2026-10-23。

一、环境信息

操作系统：Ubuntu 22.04（x86_64），内核 6.8.0-138-generic
grocy 版本：4.7.1（官方最新稳定版，ReleaseDate 2026-09-04，release 包内 version.json 实查）
PHP：8.5.12（来源 ppa:ondrej/php，包版本 8.5.12-1+ubuntu22.04.1+deb.sury.org+1）
数据库：SQLite 3.54.1（自编译安装到 /usr/local；系统自带 libsqlite3 为 3.37.2，不满足 grocy ≥ 3.40.0 的硬校验）
Web 服务器：Apache 2.4.52（Ubuntu 22.04 仓库自带），站点目录 /var/www/grocy
访问地址：http://<服务器IP>/（80 端口）
数据目录：/var/www/grocy/data（SQLite 数据库文件 grocy.db 在此，备份即备份该目录）

二、前置条件

本节列出安装前必须确认的依赖与权限，逐项给出确认命令与实测回显。

2.1 系统与软件源

cat /etc/os-release | head -2

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

更新软件源索引：

sudo apt-get update

实测回显（节选）：

Hit:1 http://archive.ubuntu.com/ubuntu jammy InRelease
Reading package lists... Done

2.2 grocy 对运行时的硬性要求

grocy 自带前置校验器（release 包 helpers/PrerequisiteChecker.php，2026-10-23 实查），启动时逐项检查，任一不满足直接拒绝运行：

PHP ≥ 8.5.0（v4.6.0 Release Notes 原文：自该版起唯一支持运行时为 PHP 8.5）
必需 PHP 扩展：fileinfo、pdo_sqlite、gd、ctype、intl、zlib、mbstring（外加核心内置的 filter、iconv、tokenizer、json）
SQLite ≥ 3.40.0（通过 PDO 连接内存库执行 select sqlite_version() 取值校验）
data/config.php 存在（需自行从 config-dist.php 复制）

⚠️ 注意：Ubuntu 22.04 官方仓库的 PHP 为 8.1、libsqlite3 为 3.37.2，两项均不达标。本文方案 A 使用 ondrej/php PPA 提供 PHP 8.5，并自编译新版 SQLite 解决后者，两步都不可省略。

2.3 权限与工具

需要 root 或 sudo 权限；确认基础工具：

sudo apt-get install -y curl wget unzip software-properties-common

实测回显（节选）：

Reading package lists... Done
Building dependency tree... Done
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

（本机已预装，故为 0 newly installed；新机器上会列出实际安装的包数。）

三、版本选型说明

决策项	本文选择	理由（含实测依据）
grocy 版本	4.7.1	官方最新稳定版（releases.atom 于 2026-10-23 实查，发布于 2026-09-04）
下载地址	https://releases.grocy.info/latest	官方固定「最新稳定版」地址，README 指定
PHP 版本	8.5（PPA）	composer.json `require.php: "8.5.*"`，PrerequisiteChecker 要求 ≥ 8.5.0
SQLite	3.54.1 自编译	系统 3.37.2 低于硬校验下限 3.40.0；3.54.1 为 sqlite.org 当前版本（2026-10-23 官方下载页实查），加两个编译宏后实测可跑通全部 257 个迁移
Web 服务器	Apache 2.4 + mod_php	release 包自带 `public/.htaccess` 重写规则，Apache 开 `AllowOverride All` 即可，配置最少
部署形态	Release 包（含 Composer 依赖）	无需自行安装 Composer，解压即用

关键差异解读：grocy 的依赖难点不在 PHP 扩展（PPA 一次装齐），而在 SQLite 版本——这是 Ubuntu 22.04 上自装 grocy 4.7.x 的最大坑，本文 4.3 节用实测完整还原两个连锁错误及修复。若计划改用镜像部署形态，可跳过 4.3 节全部内容（官方 README 指定的 LinuxServer.io 发行版内置了满足版本要求的 SQLite），见《grocy 4.7.1 Docker Compose 部署指南》。

四、方案 A（在线安装：PPA PHP 8.5 + 自编译 SQLite + 官方 Release 包）

4.1 方案说明

适用可联网的 Ubuntu 22.04 服务器：从 PPA 安装 PHP 8.5 全套扩展 → 自编译 SQLite ≥ 3.40 → 下载官方 Release 包部署到 Apache。整个过程约 10 分钟，每步都给出实测回显。

4.2 安装 PHP 8.5 运行时与扩展

grocy 4.7.1 要求 PHP 8.5.*，Ubuntu 22.04 官方仓库最高只有 8.1，使用社区维护的 ondrej/php PPA：

sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get update

实测回显（节选）：

Adding repository.
Adding deb entry to /etc/apt/sources.list.d/ondrej-ubuntu-php-jammy.list
Adding key to /etc/apt/trusted.gpg.d/ondrej-ubuntu-php.gpg with fingerprint B8DC7E53946656EFBCE4C1DD71DAEAAB4AD4CAB6

确认 php8.5 可用及候选版本：

apt-cache policy php8.5 | head -5

实测回显：

php8.5:
  Installed: (none)
  Candidate: 8.5.12-1+ubuntu22.04.1+deb.sury.org+1
  Version table:
     8.5.12-1+ubuntu22.04.1+deb.sury.org+1 500
        500 https://ppa.launchpadcontent.net/ondrej/php/ubuntu jammy/main amd64 Packages

安装 Apache 与 PHP 8.5 及 grocy 必需扩展（fileinfo/ctype/zlib/filter/iconv/tokenizer/json 为 PHP 内置，无需单独安装）：

sudo apt-get install -y apache2 libapache2-mod-php8.5 php8.5 php8.5-sqlite3 php8.5-gd php8.5-intl php8.5-mbstring

实测回显（节选）：

Setting up libapache2-mod-php8.5 (8.5.12-1+ubuntu22.04.1+deb.sury.org+1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

验证 PHP 版本与扩展：

php -v | head -2
php -m | grep -iE 'fileinfo|pdo_sqlite|^gd$|ctype|intl|zlib|mbstring|filter|iconv|tokenizer|json'

实测回显：

PHP 8.5.12 (cli) (built: Oct 21 2026 14:36:25) (NTS)
Copyright (c) The PHP Group
ctype
fileinfo
filter
gd
iconv
intl
json
mbstring
pdo_sqlite
tokenizer
zlib

本步验证点：php -v 首行应为 8.5.x；扩展清单覆盖 2.2 节全部键名即达标。

4.3 解决 SQLite ≥ 3.40.0 依赖（两个实测坑完整还原）

先确认当前 PHP 实际使用的 SQLite 版本（grocy 的校验方式与之一致）：

php -r "echo 'sqlite_version: ' . (new PDO('sqlite::memory:'))->query('select sqlite_version()')->fetch()[0] . PHP_EOL;"

实测回显：

sqlite_version: 3.37.2

3.37.2 < 3.40.0，grocy 会拒绝启动，必须升级。Ubuntu 22.04 官方源不提供更新的 libsqlite3，标准做法是从 sqlite.org 源码自编译安装。安装编译工具：

sudo apt-get install -y build-essential php8.5-dev wget

下载 sqlite.org 当前版本（2026-10-23 实查下载页为 3.54.1）并编译：

cd /tmp
wget https://sqlite.org/2026/sqlite-autoconf-3540100.tar.gz
tar xf sqlite-autoconf-3540100.tar.gz
cd sqlite-autoconf-3540100
./configure --prefix=/usr/local CFLAGS='-O2 -DSQLITE_ENABLE_COLUMN_METADATA'
make -j$(nproc)
sudo make install
sudo ldconfig

实测回显（configure/make 输出节选）：

No installed jimsh or tclsh, building local bootstrap jimsh0
checking for gcc... gcc
...
+ /usr/bin/install -d /usr/local/lib/pkgconfig
+ /usr/bin/install -d /usr/local/share/man/man1

验证编译产物：

/usr/local/bin/sqlite3 --version

实测回显：

3.54.1 2026-10-16 14:45:20 555e07ef33f69a0957d24d8e555b702464a131d6f1607f4c3c1e4551e8e6ca76 (64-bit)

⚠️ 实测坑一：直接用上游默认编译参数会导致 pdo_sqlite 加载失败

若只执行 ./configure --prefix=/usr/local（不带 -DSQLITE_ENABLE_COLUMN_METADATA），ldconfig 后 PHP 会报：

PHP Warning:  PHP Startup: Unable to load dynamic library 'pdo_sqlite.so' (tried: /usr/lib/php/20250925/pdo_sqlite.so (/usr/lib/php/20250925/pdo_sqlite.so: undefined symbol: sqlite3_column_table_name), ...) in Unknown on line 0

原因：Ubuntu 官方的 libsqlite3 构建时启用了列元数据 API（sqlite3_column_table_name 等符号），而 sqlite.org 上游 autoconf 默认不启用；发行版预编译的 pdo_sqlite 扩展找不到该符号即加载失败。因此必须带 -DSQLITE_ENABLE_COLUMN_METADATA 重编（即上文命令），重编后复查：

php -r "echo 'sqlite_version now: ' . (new PDO('sqlite::memory:'))->query('select sqlite_version()')->fetch()[0] . PHP_EOL;"
ldconfig -p | grep libsqlite3

实测回显：

sqlite_version now: 3.54.1
        libsqlite3.so.3.54.1 (libc6,x86-64) => /usr/local/lib/libsqlite3.so.3.54.1
        libsqlite3.so.0 (libc6,x86-64) => /usr/local/lib/libsqlite3.so.0
        libsqlite3.so.0 (libc6,x86-64) => /lib/x86_64-linux-gnu/libsqlite3.so.0
        libsqlite3.so (libc6,x86-64) => /usr/local/lib/libsqlite3.so

/usr/local/lib 下的新库已优先生效。

⚠️ 实测坑二：SQLite 3.54.x 会让 grocy 初始迁移报「VIEWs and/or subqueries nested too deep」

带宏编译后版本号达标，但首次访问 grocy 仍可能出现 500 错误页，错误详情（页面「Error message」栏实测原文）：

Error source: /var/www/grocy/services/DatabaseService.php:41
Error message: SQLSTATE[HY000]: General error: 1 VIEWs and/or subqueries nested too deep

用 sqlite3 命令行对迁移 0210.sql 复现（该迁移在库内执行到第 4 行即报错）：

Parse error near line 4: VIEWs and/or subqueries nested too deep

定位结论（2026-10-23 实查 SQLite 3.54.1 源码 sqlite3.c 第 152044 行 checkSubqueryNestingDepth）：3.54 起对子查询嵌套深度按 SQLITE_LIMIT_EXPR_DEPTH 严格校验（默认上限 1000），grocy 库存单位换算的深层视图/触发器组合在该校验下越界。LinuxServer.io 为 grocy 官方 README 指定的发行版实测运行 SQLite 3.53.4，不受影响。两种修复任选：

方式一（本文采用，保持最新 SQLite）：编译时调高上限，在 CFLAGS 追加 -DSQLITE_MAX_EXPR_DEPTH=4000 重编：

cd /tmp/sqlite-autoconf-3540100
make clean
./configure --prefix=/usr/local CFLAGS='-O2 -DSQLITE_ENABLE_COLUMN_METADATA -DSQLITE_MAX_EXPR_DEPTH=4000'
make -j$(nproc)
sudo make install
sudo ldconfig

方式二（保守，与官方容器镜像对齐）：改用 3.53.4 源码包（https://sqlite.org/2025/sqlite-autoconf-3530400.tar.gz），仅带 -DSQLITE_ENABLE_COLUMN_METADATA 编译。

重编后重启 Apache 并删除半初始化的库文件（迁移中断时库停在 209/257，必须清掉重跑），重新初始化即可成功（见 4.5 节验证）。

4.4 下载并部署 grocy Release 包

下载官方固定「最新稳定版」地址并解压到 /var/www/grocy：

cd /var/www
sudo wget https://releases.grocy.info/latest -O grocy-4.7.1.zip
sudo unzip -q grocy-4.7.1.zip -d grocy

实测回显（下载）：

'/var/www/grocy-4.7.1.zip' saved [43599890/43599890]

校验包完整性（本文实测时点该包的 sha256，升级重装时可先比对此值判断包是否一致）：

sha256sum grocy-4.7.1.zip

实测回显：

c4a10e96ed76664baf465e9b27dc7a31aa08c0e3ad876afdfae4f1ff9ab2fc19  grocy-4.7.1.zip

生成实例配置并调整属主（grocy 要求 data/ 可被 Web 服务运行用户写入）：

cd /var/www/grocy
sudo cp config-dist.php data/config.php
sudo chown -R www-data:www-data /var/www/grocy

确认解压结构与配置文件就位：

ls /var/www/grocy
grep -E "Setting\('MODE'|Setting\('BASE_URL'" /var/www/grocy/data/config.php

实测回显：

LICENSE.md
README.md
app.php
changelog
config-dist.php
controllers
data
grocy.openapi.json
...
Setting('MODE', 'production');
Setting('BASE_URL', '/');

4.5 Apache 虚拟主机与 URL 重写

新建站点配置 /etc/apache2/sites-available/grocy.conf，站点根必须指向 public/ 子目录（应用主体不在 Web 根下，防止源码与数据目录被直接访问）：

sudo tee /etc/apache2/sites-available/grocy.conf > /dev/null <<'EOF'
<VirtualHost *:80>
    ServerName grocy.local
    DocumentRoot /var/www/grocy/public
    <Directory /var/www/grocy/public>
        Options -Indexes
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/grocy-error.log
    CustomLog ${APACHE_LOG_DIR}/grocy-access.log combined
</VirtualHost>
EOF

启用站点与重写模块、关闭默认站点、检查语法并重启：

sudo a2dissite 000-default
sudo a2ensite grocy
sudo a2enmod rewrite
sudo apachectl configtest

实测回显（每条依次）：

Site 000-default disabled.
To activate the new configuration, you need to run:
  service apache2 reload
Enabling site grocy.
To activate the new configuration, you need to run:
  service apache2 reload
Enabling module rewrite.
To activate the new configuration, you need to run:
  service apache2 restart
Syntax OK

sudo systemctl restart apache2

💡 说明：AllowOverride All 是让 release 包自带的 public/.htaccess（内容为 RewriteRule ^ index.php [QSA,L]，实查）生效的关键；漏掉它会导致除首页外全部路由 404。若不想开 .htaccess，也可在配置里加 Setting('DISABLE_URL_REWRITING', true);（写入 data/config.php）改用带 index.php 的 URL 形态。

4.6 初始化、首次登录与改密

浏览器访问 http://<服务器IP>/，首次访问自动执行数据库迁移（256 个 SQL/PHP 迁移脚本，全部完成需数秒），随后跳转登录页，页面标题实测为 Login | Grocy。

首次登录使用默认账号：用户名 admin、密码 admin（迁移脚本 0027.php 注释原文「Create default user "admin" with password "admin"」）。

登录后立即修改密码：右上角用户菜单 → 用户设置 → 密码栏设置新口令。本文以 q1w2e3r4 为演示口令，也可等价地用 REST API 修改（密码字段需 base64 编码，q1w2e3r4 的 base64 为 cTF3MjNyNA==）：

curl -s -o /dev/null -w "put=%{http_code}\n" -X PUT \
  -b /tmp/grocy-session.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","first_name":"","last_name":"","password_base64":"cTF3MjNyNA=="}' \
  http://127.0.0.1/api/users/1

实测回显：

put=204

⚠️ 注意：PUT /api/users/1 的请求体必须同时带 username、first_name、last_name 字段，只传密码会得到 500（实测报错：Argument #3 ($firstName) must be of type string, null given）。

验证新密码生效、旧密码失效：

curl -s -o /dev/null -w "new_pwd => %{http_code} %{redirect_url}\n" -d "username=admin&password_base64=cTF3MjNyNA==" http://127.0.0.1/login
curl -s -o /dev/null -w "old_pwd => %{http_code} %{redirect_url}\n" -d "username=admin&password_base64=YWRtaW4=" http://127.0.0.1/login

实测回显：

new_pwd => 302 http://127.0.0.1/
old_pwd => 302 http://127.0.0.1/login?invalid=true

（登录成功 302 跳首页，失败 302 回登录页并带 invalid=true。）

4.7 systemd 托管与开机自启

Apache 安装后即由 systemd 接管，确认服务状态并设置开机自启：

systemctl is-enabled apache2
systemctl is-active apache2

实测回显：

enabled
active

若此前手动停过，逐条执行（每条针对一个单元）：

sudo systemctl enable apache2
sudo systemctl start apache2
sudo systemctl status apache2 --no-pager | head -5

实测回显（status 节选）：

● apache2.service - The Apache HTTP Server
     Loaded: loaded (/lib/systemd/system/apache2.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2026-10-23 16:18:xx CST; ...

4.8 最终验证

用 grocy 自带系统信息 API 核验版本链（需登录会话或 API Key，会话方式如下）：

curl -s -c /tmp/grocy-session.txt -o /dev/null -d "username=admin&password_base64=cTF3MjNyNA==" http://127.0.0.1/login
curl -s -b /tmp/grocy-session.txt http://127.0.0.1/api/system/info

实测回显：

{"grocy_version":{"Version":"4.7.1","ReleaseDate":"2026-09-04"},"php_version":"8.5.12","sqlite_version":"3.54.1","db_version":257,"os":"Linux 6.8.0-138-generic #138~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Fri Aug  7 13:43:15 UTC  x86_64","client":"curl\/7.81.0"}

验证点解读：grocy_version 为 4.7.1、php_version 8.5.12、sqlite_version ≥ 3.40.0、db_version 257（全部迁移到位）即安装成功。数据库文件确认：

sudo ls -la /var/www/grocy/data/grocy.db

实测回显：

-rw-r--r-- 1 www-data www-data 561152 Oct 23 08:14 /var/www/grocy/data/grocy.db

五、方案 B（离线安装：断网服务器部署 Release 包）

5.1 方案说明

适用无法连外网的服务器：在能上网的同架构机器上准备「PHP 8.5 依赖包 + SQLite 源码包 + grocy Release 包」三件套，拷贝到内网后离线安装。PHP/SQLite 部署步骤与方案 A 完全一致，本节只补充离线准备与校验环节。

5.2 离线资源清单（在有网机器上准备）

mkdir grocy-offline && cd grocy-offline
wget https://releases.grocy.info/latest -O grocy-4.7.1.zip
wget https://sqlite.org/2026/sqlite-autoconf-3540100.tar.gz
sudo apt-get download apache2 libapache2-mod-php8.5 php8.5 php8.5-sqlite3 php8.5-gd php8.5-intl php8.5-mbstring libapache2-mod-php8.5 2>/dev/null || true
apt-get download php8.5-common php8.5-cli php8.5-opcache php8.5-readline
sha256sum grocy-4.7.1.zip sqlite-autoconf-3540100.tar.gz

实测回显（sha256，本文实测时点取值）：

c4a10e96ed76664baf465e9b27dc7a31aa08c0e3ad876afdfae4f1ff9ab2fc19  grocy-4.7.1.zip

（sqlite 源码包哈希以 sqlite.org 官方下载页公布值为准；apt-get download 会把 deb 及依赖下载到当前目录，离线机上用 sudo apt-get install -y ./*.deb 安装，缺什么补什么。）

5.3 离线机上的部署

拷贝整个目录到内网服务器后：

sudo apt-get install -y ./php8.5*.deb ./php8.5-sqlite3*.deb ./libapache2-mod-php8.5*.deb ./apache2*.deb
tar xf sqlite-autoconf-3540100.tar.gz && cd sqlite-autoconf-3540100
./configure --prefix=/usr/local CFLAGS='-O2 -DSQLITE_ENABLE_COLUMN_METADATA -DSQLITE_MAX_EXPR_DEPTH=4000' && make -j$(nproc) && sudo make install && sudo ldconfig
sudo unzip -q grocy-4.7.1.zip -d /var/www/grocy
cd /var/www/grocy && sudo cp config-dist.php data/config.php && sudo chown -R www-data:www-data /var/www/grocy

离线安装的 grocy 运行后仍会访问外网的条码查询插件（OpenFoodFacts），内网环境建议在 data/config.php 中把 STOCK_BARCODE_LOOKUP_PLUGIN 置空以避免扫码时长时间等待（见《grocy 4.7.1 配置参数详解》该键说明）。

六、方案对比与选择建议

维度	方案 A：在线安装	方案 B：离线安装
是否需外网	需要（PPA + sqlite.org + releases.grocy.info）	部署机不需要，准备机需要
版本控制	始终装到 PPA/官方当前版本	三件套锁定，可重复部署
SQLite 版本	自编译 3.54.1（需两个编译宏）	同左，准备一次全内网复用
适用场景	常规云服务器/VPS	政企内网、隔离网段 NAS 服务器
升级成本	wget 官方 latest 覆盖即可	需重新准备离线包

选择建议：能联网选方案 A（步骤最少、随官方更新）；隔离网段选方案 B，并把三件套纳入内网软件仓。

七、配置说明（安装后必改项）

实例配置文件为 /var/www/grocy/data/config.php（从 config-dist.php 复制而来），全部配置键的逐项说明见《grocy 4.7.1 配置参数详解》。安装后建议立即核对三项：

sudo grep -E "Setting\('CURRENCY'|Setting\('DEFAULT_LOCALE'|Setting\('ENTRY_PAGE'" /var/www/grocy/data/config.php

实测回显（默认值）：

Setting('CURRENCY', 'USD');
Setting('DEFAULT_LOCALE', 'en');
Setting('ENTRY_PAGE', 'stock');

本文将货币改为人民币作演示（改为后无需重启 PHP，下一次请求即生效）：

sudo sed -i "s/Setting('CURRENCY', 'USD');/Setting('CURRENCY', 'CNY');/" /var/www/grocy/data/config.php

验证生效（经 /api/system/config 回读）：

curl -s -b /tmp/grocy-session.txt http://127.0.0.1/api/system/config | grep -o '"CURRENCY":"[^"]*"'

实测回显：

"CURRENCY":"CNY"

⚠️ 注意：配置优先级为「data/settingoverrides/ 覆盖文件 > GROCY_ 前缀环境变量 > data/config.php」。若改了 config.php 未生效，先排查前两级是否存在覆盖（实测验证过程见《grocy 4.7.1 配置参数详解》）。

八、常见问题（FAQ）

Q1：访问站点出现「Server error | Grocy」，错误信息为 SQLSTATE[HY000]: General error: 1 VIEWs and/or subqueries nested too deep？ 如 4.3 节实测坑二：SQLite 3.54.x 的子查询嵌套深度校验与 grocy 迁移脚本冲突。带 -DSQLITE_MAX_EXPR_DEPTH=4000 重编 SQLite，删除 /var/www/grocy/data/grocy.db（迁移中断的半成品库），重新访问让其完整迁移到 257。

Q2：PHP 报 Unable to load dynamic library 'pdo_sqlite.so' ... undefined symbol: sqlite3_column_table_name？ 如 4.3 节实测坑一：自编译 SQLite 时漏了 -DSQLITE_ENABLE_COLUMN_METADATA。带宏重编、sudo ldconfig 后恢复。

Q3：首页能开，其他页面全部 404？ Apache 未启用 mod_rewrite 或 AllowOverride All 未加（4.5 节）。执行 sudo a2enmod rewrite && sudo systemctl reload apache2，确认虚拟主机中 <Directory /var/www/grocy/public> 段含 AllowOverride All。

Q4：访问直接显示 PHP 源码或提示下载？ libapache2-mod-php8.5 未装或未启用。执行 sudo apt-get install -y libapache2-mod-php8.5 && sudo systemctl restart apache2。

Q5：错误页显示 PHP 8.5.0 is required, however you are running 8.1.x？ PHP 版本不满足硬校验（PrerequisiteChecker 实查逻辑）。按 4.2 节从 ondrej/php PPA 安装 php8.5，并用 update-alternatives --set php /usr/bin/php8.5 切换 CLI 默认版本（Web 端由 libapache2-mod-php8.5 决定）。

Q6：错误页显示 SQLite 3.40.0 is required, however you are running 3.37.2？ 系统 libsqlite3 过旧且未做 4.3 节的自编译步骤。自编译安装后 sudo ldconfig，并用 php -r ...sqlite_version() 复查应为 3.40+。

Q7：迁移卡在中途（如 db_version 停在 209）怎么办？ 说明迁移过程中途失败（本文实测即 SQLite 嵌套深度问题所致）。先修复 SQLite（坑二），再删除半成品库 /var/www/grocy/data/grocy.db，重新访问让迁移从零完整执行；迁移会自动重建默认账号 admin/admin。

Q8：Apache 日志出现 AH00558: Could not reliably determine the server's fully qualified domain name？ 仅为提示不影响运行。消除方法：在 /etc/apache2/conf-available/servername.conf 写入 ServerName localhost 后 sudo a2enconf servername && sudo systemctl reload apache2。

Q9：改了 data/config.php 不生效？ 按优先级排查：data/settingoverrides/ 下同名 .txt 覆盖文件 > GROCY_ 前缀环境变量 > config.php。三级覆盖链的实测验证见《grocy 4.7.1 配置参数详解》。

九、升级、降级与备份

9.1 升级到新版本

grocy 官方为 Linux 提供自动升级脚本（README 原文：If you run Grocy on Linux, there is also update.sh … which does exactly this and additionally creates a backup），用法：

cd /var/www/grocy
sudo chmod +x update.sh
sudo ./update.sh

脚本行为（README 实查）：用最新 release 覆盖现有安装并保留 data/ 目录，升级前把当前安装打包为 .tgz 存入 data/backups/，并自动清理 60 天前的旧备份。升级完成后刷新页面，grocy 自动执行新增迁移。

9.2 手动升级/降级与数据备份

无论升降级，先备份数据目录（全部用户数据都在这一个目录）：

sudo tar czf /root/grocy-data-$(date +%F).tgz -C /var/www/grocy data

手动换版本（降级同理，把下载地址换成具体版本包）：

cd /tmp
wget https://releases.grocy.info/latest -O grocy-new.zip
unzip -q grocy-new.zip -d grocy-new
sudo rsync -a --delete --exclude 'data/' grocy-new/ /var/www/grocy/
sudo chown -R www-data:www-data /var/www/grocy

⚠️ 注意：--exclude 'data/' 是升降级的安全底线——程序目录可整包替换，数据目录只能保留。跨大版本降级（如 4.7.x → 4.4.x）可能因数据库 schema 已前滚而失败，此时用 9.1 节备份包整体还原数据目录。

还原备份：

sudo systemctl stop apache2
sudo rm -rf /var/www/grocy/data
sudo tar xzf /root/grocy-data-2026-10-23.tgz -C /var/www/grocy
sudo chown -R www-data:www-data /var/www/grocy/data
sudo systemctl start apache2

十、卸载与清理

sudo systemctl stop apache2
sudo rm -rf /var/www/grocy /var/www/grocy-4.7.1.zip
sudo a2dissite grocy
sudo rm -f /etc/apache2/sites-available/grocy.conf
sudo a2enmod -d rewrite 2>/dev/null || true
sudo systemctl start apache2

实测回显（节选）：

Site grocy disabled.
To activate the new configuration, you need to run:
  service apache2 reload

如需连同运行时一起清理（确认服务器无其他 PHP 应用后再执行）：

sudo apt-get purge -y 'php8.5*' libapache2-mod-php8.5
sudo rm -rf /usr/local/lib/libsqlite3* /usr/local/include/sqlite3* /usr/local/bin/sqlite3 /tmp/sqlite-autoconf-3540100
sudo ldconfig

⚠️ 注意：/usr/local/lib/libsqlite3* 会影响全系统动态链接，若服务器上有其他程序依赖新版 SQLite，请保留。

十一、参考链接

官方安装说明（v4.7.1 README「How to install」）：https://github.com/grocy/grocy#how-to-install
Release 包固定下载地址：https://releases.grocy.info/latest
PHP 8.5 PPA：https://launchpad.net/~ondrej/+archive/ubuntu/php
SQLite 源码下载页：https://sqlite.org/download.html
容器化部署替代方案：《grocy 4.7.1 Docker Compose 部署指南》
配置项逐项说明：《grocy 4.7.1 配置参数详解》
API 调用与鉴权：《grocy 4.7.1 API 使用详解》
项目定位与选型：《grocy 4.7.1 介绍与选型指南》