Admidio 5.0.17 LEMP 安装部署指南

本文是 admidio 专栏的安装篇。全部命令与页面输出均于 2026-10-28 在一台 Ubuntu 22.04.5 LTS 服务器上实测取得，实测版本为 Admidio 5.0.17 + Nginx 1.18.0 + PHP 8.2.35 + MariaDB 10.6.23 + Composer 2.10.3；系统背景与选型判断见《Admidio 5.0.17 介绍与选型指南》。

一、部署前准备

1.1 环境要求与版本核对

Admidio 5.0.17 对环境的硬性要求（依据源码 composer.json 与官方 README，2026-10-28 核查）：

关键前置坑位：Ubuntu 22.04 默认软件源的 PHP 是 8.1，不满足 5.x 的 ^8.2 要求。实测将 Admidio 5.0.17 挂在 PHP 8.1.2 下访问首页时，引导层直接拒绝（HTTP 200，页面显示红字）：

Error: Your PHP version 8.1.2-1ubuntu2.28 does not fulfill
        the minimum requirements for this Admidio version. You need at least PHP 8.2.0 or higher.

因此本文直接采用 ondrej/php 第三方源安装 PHP 8.2，这也是 Ubuntu 22.04 上部署 Admidio 5.x 的标准路径。

1.2 系统初始更新

sudo apt-get update
sudo apt-get install -y curl unzip software-properties-common gnupg2 ca-certificates lsb-release

命令输入如上，预期结果为 apt 列表刷新完成、基础工具装好，无报错即通过。

二、安装 Nginx、MariaDB 与 PHP 8.2

2.1 安装 Web 服务器与数据库

sudo apt-get install -y nginx mariadb-server

实测安装后版本核对输出：

$ nginx -v
nginx version: nginx/1.18.0 (Ubuntu)
$ mariadb --version
mariadb  Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper

2.2 通过 ondrej/php 源安装 PHP 8.2

sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get update
sudo apt-get install -y php8.2-fpm php8.2-mysql php8.2-gd php8.2-xml \
  php8.2-curl php8.2-mbstring php8.2-intl php8.2-ldap php8.2-zip

实测核对：

$ php8.2 -v
PHP 8.2.35 (cli) (built: Oct 21 2026 14:29:22) (NTS)

注意 php8.2-fpm 与系统可能残留的 php8.1-fpm 并存，后续 Nginx 配置必须明确指向 php8.2-fpm.sock，这是同名套接字错接的常见故障点。

2.3 安装 Composer

Admidio 的 GitHub 源码包不包含 vendor 目录，需要用 Composer 拉取依赖：

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

实测输出（节选）：

Composer (version 2.10.3) successfully installed to: /usr/local/bin/composer
Use it: php /usr/local/bin/composer

三、准备数据库与源码

3.1 创建数据库与专用账号

sudo mysql

进入 MariaDB 交互界面后执行（示例密码请按组织安全规范替换）：

CREATE DATABASE admidio CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'admidio'@'localhost' IDENTIFIED BY 'Admidio#2026';
GRANT ALL PRIVILEGES ON admidio.* TO 'admidio'@'localhost';
FLUSH PRIVILEGES;

实测验证：

$ sudo mysql -e 'SHOW DATABASES;' | grep admidio
admidio

3.2 下载并部署源码

从 GitHub 官方标签归档下载 v5.0.17（实测包体 6,679,811 字节）：

curl -sL -o admidio-5.0.17.tar.gz \
  https://github.com/Admidio/admidio/archive/refs/tags/v5.0.17.tar.gz
tar xzf admidio-5.0.17.tar.gz
sudo mkdir -p /var/www
sudo cp -r admidio-5.0.17 /var/www/admidio

3.3 安装 Composer 依赖

cd /var/www/admidio
sudo composer install --no-interaction --no-dev

实测耗时数分钟，完成后 vendor 顶层有 28 个命名空间目录（twbs、smarty、phpoffice、tecnickcom、monolog 等）。这一步不能跳过：vendor 缺失时安装向导可以打开，但 Bootstrap 样式与脚本全部 404，页面呈裸 HTML 状态（实测复现：GET /vendor/twbs/bootstrap/dist/css/bootstrap.min.css 返回 404，依赖装完即恢复 200）。

3.4 修正属主

sudo chown -R www-data:www-data /var/www/admidio/adm_my_files /var/www/admidio/vendor

adm_my_files 是 Admidio 的运行时可写目录（配置、日志、临时文件、邮件模板都写在这里），权限不足时安装向导会在后续步骤报错。

四、配置 Nginx 站点

4.1 站点配置文件

创建 /etc/nginx/sites-available/admidio（实测配置，可直接复用）：

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    root /var/www/admidio;
    index index.php;
    client_max_body_size 20m;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

启用站点并重载：

sudo ln -sf /etc/nginx/sites-available/admidio /etc/nginx/sites-enabled/admidio
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl restart php8.2-fpm

实测 nginx -t 输出：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

4.2 首次连通性验证

$ curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' http://localhost/
303 -> http://localhost/install/index.php

未安装时首页 303 跳转到安装向导，这是预期行为；看到 303 即 Nginx、PHP-FPM、源码部署三者已打通。

五、Web 安装向导五步实录

浏览器打开 http://<服务器地址>/（本节以 localhost 实测），向导共五个交互步骤，每一步提交后由页面脚本自动跳转下一步。

5.1 第一步：选择语言

页面标题为 "Admidio - Installation version 5.0.17"，正文 "Welcome to the installation of Admidio"。语言下拉框内置 26 种语言，选择 Chinese - 中文 后点击 "Database access" 按钮进入下一步。实测该步通过后，后续界面即切换为中文。

5.2 第二步：数据库连接

表单字段与实测填写值：

提交后向导即时校验连接。实测校验通过后自动进入下一步（若报连接失败，优先检查账号密码与 MariaDB 监听地址）。

5.3 第三步：定义组织

实测该步标题显示为"定义部门"（中文翻译词条），需要填写：

组织简称会成为成员列表前缀等场景的标识，建议使用字母与数字。

5.4 第四步：创建管理员

实测表单包含姓氏、名字、邮箱、用户名、密码与密码确认。实测创建账号：

实测核对了源码中的密码校验规则：最短 8 位（PASSWORD_MIN_LENGTH），且经 zxcvbn 强度评估不低于 1 分，两处不满足均会拒绝提交。本例 q1w2e3r4 为 8 位字母数字混合，实测通过；生产环境建议使用更长的强密码。

5.5 第五步：执行安装

确认页点击开始后，向导读取随包分发的 db.sql 脚本在数据库中建表并写入默认数据（角色、档案字段、组织记录、管理员账号）。实测完成后数据库中生成 49 张 adm_ 前缀表，adm_my_files/config.php 由向导自动生成（实测 1158 字节），页面显示 Installation successful。

若中途曾中断安装后重试，实测会出现提示：

The database already contains an Admidio installation. An additional installation is not possible.

此时按 D1 篇的"重装"小节清理数据表后即可重新走一遍向导。

六、安装后验证

6.1 登录测试

访问 http://<服务器地址>/，实测首页 303 跳转到 /modules/overview.php，页面标题：

演示技术协会 - Overview

在右上角登录框输入 admin / q1w2e3r4，实测登录成功：页面出现指向 /system/logout.php 的登出链接，访问"我的资料"模块返回标题 演示技术协会 - My profile，会话生效。

6.2 数据层核对

$ sudo mysql admidio -e 'SELECT com_name, com_version FROM adm_components WHERE com_type="SYSTEM";'
com_name       com_version
Admidio Core   5.0.17

版本记录与所装源码一致即确认安装完整。

6.3 安装产物速览

七、排障实录

故障一：PHP 版本不达标，首页红字报错。 现象：访问返回 200 与红字 "Error: Your PHP version 8.1.2-1ubuntu2.28 does not fulfill the minimum requirements…"。原因：PHP-FPM 仍指向 8.1。处置：按 2.2 节装 php8.2-fpm，并把 Nginx fastcgi_pass 改回 php8.2-fpm.sock 后 reload，实测恢复 303 跳转。

故障二：页面能打开但样式全丢。 现象：安装向导/首页呈裸文本，控制台大量静态资源 404。原因：vendor 目录不存在或不可读。处置：执行 3.3 节 composer install，并确认 vendor 属主可被 www-data 读取，实测 GET /vendor/twbs/bootstrap/dist/css/bootstrap.min.css 由 404 变 200。

故障三：重试安装提示"数据库已包含 Admidio 安装"。 现象：向导在执行步报错并拒绝继续。原因：上次安装已建表（config.php 已生成且组织表有记录）。处置：确认是废弃安装后删库重建（DROP DATABASE admidio; 后按 3.1 节重做）并删除 adm_my_files/config.php，再走一遍向导。

故障四：Composer 安装缓慢或超时。 原因：网络到 Packagist 链路不佳。处置：为当前会话配置 HTTP 代理后再执行 composer install（命令+预期结果：设置环境变量后安装可正常完成，vendor 目录结构与直连一致）。

下一站：安装完成后，系统内部还有 config.php 字段、200 余项组织偏好与 PHP/Nginx 配合参数需要理解，详见《Admidio 5.0.17 配置参数详解》；日常备份、升级与故障处置见《Admidio 5.0.17 常用运维命令详解》。