|
|
Ubuntu 24.04 部署 Discuz X5.0 实战：从环境搭建到注册故障排查
一、项目背景
今天在 Ubuntu 服务器上部署 Discuz 论坛，完成了环境配置、网站安装、数据库初始化以及注册功能验证。
安装过程中遇到了几个比较典型的问题：
- Nginx 的 PHP 解析规则配置错误。
- 最初使用了 WordPress 数据库，导致数据库与论坛业务混用。
- 注册时提示邮箱已被使用，需要区分 WordPress 用户表和 Discuz 用户表。
- Discuz 注册请求返回 HTTP 503，最终定位到 MariaDB 的 JSON 字段校验约束。
通过这次部署，进一步熟悉了 Linux 网站部署流程、Nginx 与 PHP-FPM 的协作方式，以及 MariaDB 数据库故障排查方法。
二、服务器环境
| 项目 | 配置信息 | | 操作系统 | Ubuntu 24.04 | | Web 服务 | Nginx 1.24.0 | | PHP | PHP 8.3.6 | | PHP 运行模式 | PHP-FPM | | 数据库 | MariaDB 10.11.14 | | 论坛程序 | Discuz X5.0.4.Open Release 20261010 | | 数据库名称 | discuz | | 网站目录 | /usr/share/nginx/html/upload | | 网站访问地址 | http://47.238.244.77/ |
说明：以上是本次部署排查中使用的环境信息。正式上线时，建议使用域名、HTTPS，并做好数据库备份与访问控制。
三、安装前检查
3.1 检查操作系统版本
cat /etc/os-releaseuname -rcat /etc/os-release 用于查看 Linux 发行版及版本；uname -r 用于查看当前内核版本。
3.2 检查 Nginx、PHP 和 MariaDB
nginx -vphp -vmariadb --version查看服务运行状态：
systemctl status nginxsystemctl status php8.3-fpmsystemctl status mariadb如果服务未启动，可以执行：
sudo systemctl start nginxsudo systemctl start php8.3-fpmsudo systemctl start mariadb设置开机启动：
sudo systemctl enable nginxsudo systemctl enable php8.3-fpmsudo systemctl enable mariadb3.3 检查网站目录
ls -lah /usr/share/nginx/html/ls -lah /usr/share/nginx/html/upload/通过 ls -lah 可以检查程序文件是否完整、文件权限是否合理。
如果使用其他目录部署，后续 Nginx 配置中的 root 路径必须同步调整。
四、部署 Discuz 程序
4.1 下载并解压安装包
下载 Discuz X5.0 安装包后，先检查文件类型，再解压。
file /tmp/Discuz_X5.0_20261010.zipunzip -l /tmp/Discuz_X5.0_20261010.zip如果服务器尚未安装 unzip：
sudo apt updatesudo apt install unzip解压命令：
unzip /tmp/Discuz_X5.0_20261010.zip -d /tmp/discuz实际解压目录需要根据安装包内部的目录结构确定，避免出现多层嵌套目录。
完成文件整理后，检查网站目录：
find /usr/share/nginx/html/upload -maxdepth 2 -type f | head -50确认目录中包含 Discuz 的入口文件，例如 index.php、member.php 等。
4.2 配置文件权限
Nginx 和 PHP-FPM 需要能够读取程序文件，并对程序要求写入的缓存、附件等目录拥有适当权限。
查看 PHP-FPM 运行用户：
grep -E '^(user|group) =' /etc/php/8.3/fpm/pool.d/www.conf查看目录权限：
namei -l /usr/share/nginx/html/uploadls -ld /usr/share/nginx/html/upload不要直接对整个网站目录执行 chmod -R 777。应该根据 PHP-FPM 的运行用户，为确实需要写入的目录设置最小必要权限。
五、配置 Nginx 与 PHP-FPM
5.1 检查 PHP-FPM 监听地址
grep -E '^(listen|user|group) =' /etc/php/8.3/fpm/pool.d/www.conf本次环境使用的 PHP-FPM Socket 为：
/run/php/php8.3-fpm.sockNginx 必须使用与 PHP-FPM 一致的 Socket 地址，否则 PHP 请求无法正确转发。
5.2 检查 Nginx 网站配置
Ubuntu 上的 Nginx 配置通常位于：
/etc/nginx/nginx.conf/etc/nginx/sites-available//etc/nginx/sites-enabled/检查当前生效配置：
sudo nginx -T网站配置的关键逻辑如下：
server { listen 80; server_name 47.238.244.77; root /usr/share/nginx/html/upload; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.3-fpm.sock; } location ~ /\. { deny all; }}这是一份基础配置示例，具体使用时需要结合现有网站配置进行调整，避免重复定义 server 或覆盖已有规则。
5.3 解决 PHP 解析规则错误
本次排查中曾出现 PHP 请求匹配规则写错的问题：
错误写法：
location ~ \.php& {正确写法：
location ~ \.php$ {这里的 $ 表示匹配以 .php 结尾的 URI；错误的 & 不具备相同的正则表达式含义。
如果 PHP 文件被当作普通文件处理，可能导致浏览器无法正常执行 PHP 页面。因此，必须确认 PHP 请求被转发给 PHP-FPM。
修改配置后执行：
sudo nginx -tsudo systemctl reload nginx如果 PHP 页面无法执行，还应检查：
sudo systemctl status php8.3-fpmsudo tail -n 100 /var/log/nginx/error.log六、初始化 MariaDB 数据库
6.1 登录数据库
sudo mariadb也可以使用数据库账号登录：
mariadb -u root -p6.2 创建独立的 Discuz 数据库
本次部署过程中，最初使用了 WordPress 的数据库，之后重新建立了 discuz 数据库进行安装。
建议不同应用使用独立数据库，避免用户数据、表结构和应用配置相互干扰。
CREATE DATABASE discuz CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;如果数据库已经存在，不要重复创建或删除；先确认其中的数据和表结构。
生产环境建议创建独立的数据库用户，并只授予论坛数据库所需的权限：
CREATE USER 'discuz_user'@'localhost'IDENTIFIED BY '替换为强密码';GRANT ALL PRIVILEGES ON discuz.*TO 'discuz_user'@'localhost';SHOW GRANTS FOR 'discuz_user'@'localhost';这里的账号和密码是配置示例。应使用实际配置的数据库账号，并将强密码保存在安全的位置。
6.3 检查当前数据库
SELECT DATABASE();SHOW DATABASES;USE discuz;SHOW TABLES;注意：SELECT DATABASE() 返回 NULL，表示当前会话还没有选择数据库，并不代表 MariaDB 没有数据库。
执行：
USE discuz;SELECT DATABASE();此时才会切换到 discuz 数据库。
6.4 区分 WordPress 和 Discuz 用户表
WordPress 常见用户表：
wp_userswp_usermetaDiscuz 常见用户表：
pre_common_memberpre_common_member_profilepre_ucenter_members查询 WordPress 用户：
SELECT ID, user_login, user_emailFROM wp_usersLIMIT 10;查询 Discuz 用户：
SELECT uid, username, emailFROM pre_common_memberLIMIT 10;实际字段以当前版本的表结构为准。
关键经验： wp_users 中存在邮箱，不等于 Discuz 的用户表中也存在该邮箱。排查注册问题时，必须先确认应用实际连接的数据库、表前缀以及对应用户表。
七、通过浏览器安装 Discuz
完成 Web 服务、PHP-FPM 和数据库准备后，使用浏览器访问：
http://47.238.244.77/根据安装向导完成以下步骤：
- 阅读并确认安装协议。
- 检查 PHP 扩展、目录权限等环境要求。
- 填写数据库地址、数据库名称、数据库用户名及密码。
- 确认数据表前缀，例如 pre_。
- 设置论坛管理员账号和密码。
- 等待安装程序创建数据表并初始化数据。
- 安装完成后进入论坛首页，检查页面是否正常。
安装完成后检查数据表：
USE discuz;SHOW TABLES;检查用户表是否存在：
SHOW TABLES LIKE '%common_member%';SHOW TABLES LIKE '%ucenter_members%';注意：数据表前缀应以安装时实际填写的内容为准，不能默认所有 Discuz 安装都使用 pre_。
八、注册故障排查：HTTP 503 与数据库 CHECK 约束
这是本次部署最值得记录的一部分。
8.1 故障现象
访问论坛注册页面后，提交注册信息，浏览器没有正常完成注册流程。
Nginx 访问日志显示：
POST /member.php?mod=register&inajax=1 HTTP/1.1 503请求返回 HTTP 503，但数据库中已经可以看到新用户记录。
这种情况说明：注册流程可能已经执行了一部分，不能仅凭 HTTP 503 就认定用户没有创建成功。
8.2 检查 Nginx 访问日志
sudo tail -n 100 /var/log/nginx/access.log持续观察新请求：
sudo tail -f /var/log/nginx/access.log查找注册请求：
sudo grep 'member.php?mod=register' /var/log/nginx/access.log访问日志可以确认请求的 URL、HTTP 状态码、响应大小和请求时间，但通常不能直接显示 SQL 错误的具体原因。
8.3 查看 Discuz 返回的数据库错误
浏览器开发者工具中打开 Network（网络）面板，重新提交注册请求，选择：
POST /member.php?mod=register&inajax=1查看 Response（响应内容），发现错误：
(4025) CONSTRAINT `common_member_profile.fields`failed for `discuz`.`common_member_profile`错误发生在：
REPLACE INTO common_member_profile SET `uid`='6'调用链指向 Discuz 注册模块、用户数据插入逻辑和数据库操作层。
这比单纯观察 503 更有价值：它表明请求已经进入 Discuz 程序，并且失败点在数据库写入阶段。
8.4 检查数据表结构
登录 MariaDB：
sudo mariadb执行：
USE discuz;SHOW CREATE TABLE pre_common_member_profile\GSHOW COLUMNS FROM pre_common_member_profile LIKE 'fields';检查到的关键字段定义如下：
`fields` longtextCHARACTER SET utf8mb4COLLATE utf8mb4_binNOT NULLCHECK (json_valid(`fields`))其中：
- longtext：用于存储较长文本。
- NOT NULL：不允许字段值为 NULL。
- json_valid(fields)：要求字段内容是合法 JSON。
- CHECK：数据写入时必须满足指定条件，否则数据库拒绝操作。
本次问题的关键不是普通邮箱重复，而是注册过程向用户资料表插入数据时，fields 字段没有满足 JSON 校验约束。
8.5 查看数据库 CHECK 约束
执行：
SELECT CONSTRAINT_NAME, CHECK_CLAUSEFROM information_schema.CHECK_CONSTRAINTSWHERE CONSTRAINT_SCHEMA = 'discuz';本次查询结果中包含：
fields | json_valid(`fields`)这说明数据库中存在针对 fields 字段的 JSON 校验规则。
进一步检查表名：
SHOW TABLES LIKE '%common_member_profile%';如果程序报错中的表名与自己查询的表名不一致，应检查数据库表前缀和应用配置，确认应用实际访问的是哪张表。
8.6 故障原因与修复原则
最终定位到：Discuz 注册时写入用户资料表，触发了 MariaDB 的 json_valid(fields) CHECK 约束。
注册 SQL 只写入了 uid，没有显式提供 fields 值。如果字段缺少有效默认值，或者实际写入值不是合法 JSON，就可能导致数据库拒绝该操作。
修复时应重点检查：
- Discuz 程序版本与数据库表结构是否一致。
- fields 字段的默认值是否符合 JSON 校验要求。
- 程序在创建用户资料时，是否初始化了合法的 JSON 内容。
- 应用配置的数据库名称、表前缀和实际表结构是否一致。
对于 JSON 字段，空 JSON 对象 {} 是合法的 JSON 值，而空字符串 '' 不是合法 JSON。
应根据当前 Discuz 版本的安装 SQL、升级脚本和代码逻辑修复默认值或初始化流程。不要为了让注册成功就直接删除 CHECK 约束，否则可能掩盖数据格式错误，并影响其他 JSON 字段的数据完整性。
修复后重新注册一个测试账号，并检查：
SELECT uid, username, emailFROM pre_common_memberORDER BY uid DESCLIMIT 10;再检查对应用户资料记录：
SELECT uid, fieldsFROM pre_common_member_profileORDER BY uid DESCLIMIT 10;如果注册成功，仍需确认页面返回正常、用户资料记录完整，且 Nginx 和 PHP-FPM 日志没有新的错误。
九、Linux 常用排错命令
9.1 查看服务状态
systemctl status nginxsystemctl status php8.3-fpmsystemctl status mariadb9.2 查看实时日志
sudo tail -f /var/log/nginx/access.logsudo tail -f /var/log/nginx/error.logsudo journalctl -u php8.3-fpm -n 100 --no-pagersudo journalctl -u mariadb -n 100 --no-pager9.3 查找配置文件
sudo nginx -Tsudo find /etc/nginx -type fsudo grep -R 'fastcgi_pass' /etc/nginx9.4 检查端口监听
sudo ss -lntp只检查 HTTP 端口：
sudo ss -lntp | grep ':80 '9.5 检查 PHP-FPM Socket
ls -l /run/php/php8.3-fpm.sock如果 Nginx 无法连接 PHP-FPM，应核对 Socket 是否存在、运行服务是否正常，以及相关权限是否正确。
9.6 检查网站文件和权限
ls -lah /usr/share/nginx/html/uploadnamei -l /usr/share/nginx/html/upload/index.phpnamei -l 可以逐级显示路径权限，适合排查父目录不可访问导致的权限问题。
十、MariaDB 常用命令速查
| 目的 | 命令 | | 登录数据库 | mariadb -u root -p | | 查看所有数据库 | SHOW DATABASES; | | 切换数据库 | USE discuz; | | 查看当前数据库 | SELECT DATABASE(); | | 查看数据表 | SHOW TABLES; | | 查看表结构 | DESC pre_common_member_profile; | | 查看建表 SQL | SHOW CREATE TABLE pre_common_member_profile\G | | 查看表字段 | SHOW COLUMNS FROM pre_common_member_profile; | | 查看指定表 | SHOW TABLES LIKE '%common_member%'; | | 查询用户 | SELECT * FROM pre_common_member LIMIT 10; | | 查看表数量 | SELECT COUNT(*) FROM pre_common_member; | | 查看数据库用户权限 | SHOW GRANTS FOR 'discuz_user'@'localhost'; | | 退出数据库 | EXIT; |
注意：在 MariaDB 命令行中，SQL 语句通常需要以分号 ; 结束；\G 可以将查询结果按纵向格式展示，适合查看较长的建表语句。
十一、部署完成后的检查清单
Nginx 服务正常运行。
PHP-FPM 服务正常运行。
PHP 请求由 PHP-FPM 执行，而不是将源码返回给浏览器。
Discuz 首页可以正常访问。
数据库名称、用户名和表前缀配置正确。
注册功能正常，测试账号可以成功创建。
用户表和用户资料表中的记录完整。
Nginx 错误日志、PHP-FPM 日志没有持续出现异常。
安装完成后，按照当前版本的安全要求处理安装目录及其他安装相关文件。
备份数据库和网站配置文件。
十二、总结
本次 Discuz 部署的核心收获有三个。
第一，网站部署不只是把程序文件放到 Web 目录中。Nginx、PHP-FPM、数据库、文件权限和应用配置必须相互匹配。
第二，不同应用应当使用清晰、独立的数据库配置。WordPress 的用户表与 Discuz 的用户表属于不同的应用数据，不能因为字段名称相似，就认为它们可以直接共用。
第三，HTTP 状态码只是排错入口，不能代替根因分析。本次注册请求返回 503，最终通过浏览器 Response、Discuz 调用栈和 MariaDB 建表语句，定位到了 json_valid(fields) CHECK 约束。
今后排查类似问题，可以遵循以下顺序：
浏览器请求异常 ↓检查 Network 和 HTTP 状态码 ↓查看 Nginx / PHP-FPM 日志 ↓检查应用返回的具体错误 ↓确认数据库、表名和表前缀 ↓检查 SQL、字段定义和约束 ↓修复后重新验证业务流程通过这一套流程，可以避免只根据报错表象修改配置，提升 Linux 网站部署和数据库故障定位的效率。
|
|
发表于