mosparo 1.5.13 安装部署指南

mosparo 1.5.13 在 Debian 12 上的实测部署:Apache+PHP 8.2+MariaDB 依赖链、发行包下载与校验、虚拟主机配置、安装向导五步、健康检查验证与 5 条排障实录,所有回显均为实测原文。

mosparomosparoPHP 编程信息安全NAS 自托管2026/10/28

mosparo 1.5.13 安装部署指南

本文是 mosparo 专栏的部署篇。以下流程于 2026-10-28 在一台 Debian 12 服务器上实测走通:从系统准备、安装 Apache/PHP/MariaDB、下载官方发行包、配置虚拟主机,到安装向导五步走完、管理后台可登录、健康检查 API 返回正常。文中所有命令与回显均为实测原文(密码类字段已脱敏标注)。组件画像见《mosparo 1.5.13 介绍与选型指南》,参数调优见《mosparo 1.5.13 配置参数详解》,命令运维与备份恢复见《mosparo 1.5.13 常用 CLI 命令详解》。

一、部署前决策

版本:mosparo v1.5.13(2026-10-26 发布的安全版本,官方 Releases 页最新;查询日期 2026-10-28)。

数据库选型:mosparo 支持 MySQL/MariaDB、PostgreSQL、SQLite 三种(官方 README Requirements 节,2026-10-28 查证)。本篇实测采用 MariaDB——Debian 12 仓库自带 10.11,与 mosparo 的 pdo_mysql 驱动组合零额外配置,备份链路成熟(单库 dump 即可,见运维篇)。小型单站点也可在安装向导里直接选 SQLite(零外部依赖,备份只需拷一个文件),两种路径在向导步骤中的差异会标注。

运行时:Apache 2.4 + PHP 8.2(mod_php)。mosparo 要求 PHP ≥ 8.1.10(官方 README,2026-10-28 查证),Debian 12 源里是 8.2,满足要求。

形态:本篇按裸机单机交付:mosparo 与数据库同机部署,mosparo 占用 80 端口(生产建议按官方文档加 TLS 证书,本文以内网 80 端口演示全流程)。

二、系统准备

以下全程在 Debian 12 服务器上以 root 执行。先装齐 Web、PHP 与数据库:

root@mosparo-lab:~# apt-get update -qq

root@mosparo-lab:~# DEBIAN_FRONTEND=noninteractive apt-get install -y -qq apache2 libapache2-mod-php php php-gd php-intl php-curl php-xml php-zip php-mysql php-pgsql php-sqlite3 php-mbstring mariadb-server unzip curl

说明:php-mysql 供 MariaDB 使用;php-pgsql、php-sqlite3 是可选驱动,装上后安装向导三种数据库都能选,不需要可省略;php-gd、php-intl、php-xml、php-zip、php-curl 是官方要求的核心扩展(来源:mosparo 仓库 README Requirements 节,2026-10-28 查证)。

核对版本(实测回显):

root@mosparo-lab:~# php -v | head -1
PHP 8.2.35 (cli) (built: Oct 21 2026 06:29:51) (NTS)
root@mosparo-lab:~# mariadb --version
mariadb  Ver 15.1 Distrib 10.11.19-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper

回显说明:SELECT VERSION()(见第三节)返回的服务端版本 10.11.19-MariaDB-0+deb12u1 才是生效版本,以此为准。

三、初始化数据库

启动 MariaDB 并创建 mosparo 专用库与账号(密码以 q1w2e3r4 为例,生产环境请换成自己的强密码):

root@mosparo-lab:~# service mariadb start
root@mosparo-lab:~# mariadb -e "CREATE DATABASE mosparo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'mosparo'@'localhost' IDENTIFIED BY 'q1w2e3r4'; GRANT ALL PRIVILEGES ON mosparo.* TO 'mosparo'@'localhost'; FLUSH PRIVILEGES; SELECT VERSION();"
VERSION()
10.11.19-MariaDB-0+deb12u1

若选择 SQLite,本节可整段跳过——安装向导里选 SQLite 后,数据库文件由 mosparo 自行创建管理。

四、下载并部署发行包

官方主推的安装方式是发行包(zip,Composer 依赖已打包,服务器无需 Composer/Node)。从 GitHub Releases 下载 v1.5.13 发行包(来源:官方下载页 mosparo.io/releases/,2026-10-28 查证):

root@mosparo-lab:~# cd /tmp
root@mosparo-lab:/tmp# curl -LO https://github.com/mosparo/mosparo/releases/download/v1.5.13/mosparo-stable-v1.5.13.zip
root@mosparo-lab:/tmp# ls -la mosparo.zip
-rw-r--r-- 1 root root 21034456 Oct 28 12:58 mosparo.zip
root@mosparo-lab:/tmp# sha256sum mosparo.zip
52f22f66626ab9f0f3ccba73d76eb19aa449ff05239f880e42a4433a63eb7c8b  mosparo.zip

解压到 /var/www/mosparo,并把属主交给 Apache 运行用户 www-data(官方排障文档特别提醒:public 目录属主不对会导致 403 Forbidden):

root@mosparo-lab:/tmp# unzip -q mosparo.zip -d /var/www/mosparo
root@mosparo-lab:/tmp# chown -R www-data:www-data /var/www/mosparo
root@mosparo-lab:/tmp# ls /var/www/mosparo | head
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.md
SECURITY.md
assets
bin
composer.json
composer.lock
config
docker

docker 目录是上游仓库自带的文件,与本文的裸机部署方式无关,忽略即可。

两个发行包内的关键文件(后面排障和配置篇都会用到):

  • .env——环境变量默认值(mosparo 已预设 APP_ENV=prod);
  • config/env.mosparo.php——安装完成后才会生成,存放数据库连接与安装密钥(首次部署时该文件不存在,属正常)。

五、配置 Apache 虚拟主机

要点只有一个:文档根目录必须指向 public 子目录(官方安装文档第一步,2026-10-28 查证)。创建站点配置:

root@mosparo-lab:~# cat > /etc/apache2/sites-available/mosparo.conf <<'EOF'
<VirtualHost *:80>
    ServerName mosparo.example.com
    DocumentRoot /var/www/mosparo/public
    <Directory /var/www/mosparo/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/mosparo_error.log
    CustomLog ${APACHE_LOG_DIR}/mosparo_access.log combined
</VirtualHost>
EOF

启用站点与 rewrite 模块,替换默认站点:

root@mosparo-lab:~# a2dissite 000-default
Site 000-default disabled.
Run 'systemctl reload apache2' to activate new configuration!
root@mosparo-lab:~# a2ensite mosparo
Enabling site mosparo.
To activate the new configuration, you need to run:
  systemctl reload apache2
root@mosparo-lab:~# a2enmod rewrite
Enabling module rewrite.
To activate the new configuration, you need to run:
  systemctl restart apache2
root@mosparo-lab:~# apachectl configtest
AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 10.89.67.2. Set the 'ServerName' directive globally to suppress this message
Syntax OK

AH00558 是无害告警(见排障实录第 1 条),Syntax OK 表示配置合法。启动 Apache:

root@mosparo-lab:~# service apache2 start
Starting Apache httpd web server: apache2AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 10.89.67.2. Set the 'ServerName' directive globally to suppress this message
.
root@mosparo-lab:~# service apache2 status
apache2 is running.

若你的服务器有正式域名,把全局 ServerName 写进 /etc/apache2/conf-available/servername.conf 并 a2enconf servername 即可消除告警;本机测试也可以直接用服务器 IP 访问。

六、安装向导(五步实测)

浏览器访问 http://<服务器IP或域名>/,会 302 跳转到 /setup/ 进入安装向导。以下为实测全流程:

第 1 步 · 欢迎:向导首页,点继续进入 /setup/prerequisites。

第 2 步 · 环境检查(Requirements):自动检测 PHP 版本与全部必需扩展。实测本机两项检测均显示绿色 alert alert-success,页面出现「Continue」按钮。若此处有红色项,按提示补装对应 PHP 扩展后刷新。

第 3 步 · 数据库(Database):表单字段实测如下——

字段实测取值说明
SystemMySQL/MariaDB下拉仅三项:MySQL/MariaDB、PostgreSQL、SQLite
Host127.0.0.1数据库主机
Port3306留空用默认端口
Databasemosparo第三节创建的库名
Usermosparo第三节创建的账号
Passwordq1w2e3r4提交后写入配置文件,不再明文回显

提交后自动跳转到 /setup/other。SQLite 则只需选此项,无连接参数。

第 4 步 · 站点信息(Other information):四个字段——Name of mosparo(实例名,后台标题用,实测 mosparo-lab)、Email address(管理员邮箱,实测 admin@lab.local)、Password/Repeat password(管理员密码,实测 q1w2e3r4)。

第 5 步 · 完成(Installation completed):安装器建表、写入配置并显示完成页。

安装完成后,管理员的登录邮箱就是第 4 步的邮箱。实测登录:

root@mosparo-lab:~# curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://localhost/
302 http://login/

未登录访问首页会跳转登录页 /login/;浏览器访问 http://<服务器IP>/login/,用 admin@lab.local + q1w2e3r4 登录,实测成功进入 Projects 页面,页面标题带上了实例名(mosparo-lab)。

七、部署验证

健康检查 API:mosparo 内置健康检查端点(路径与回显均为实测):

root@mosparo-lab:~# curl -s http://localhost/api/v1/health/check
{"service":"mosparo","healthy":true,"databaseStatus":"connected","error":null,"statusCode":200}

databaseStatus: connected 说明应用与数据库链路正常。注意:该端点默认只对 127.0.0.1,::1 开放,从其他机器访问会得到 404(而非 403,实测如此),放行方法见《mosparo 1.5.13 配置参数详解》中 MOSPARO_HEALTH_ALLOW_LIST 一节。

CLI 健康命令(等价的命令行验证,完整命令族见《mosparo 1.5.13 常用 CLI 命令详解》):

root@mosparo-lab:~# cd /var/www/mosparo && php bin/console mosparo:health

Health check
============

 [OK] Everything okay

下一步:登录后台后先建一个项目(Project),mosparo 以项目为单位发放站点 UUID 与公私钥对,业务站点凭这组凭据接入。建好项目后在项目设置里能拿到三件套:Host、Public key、Private key,以及接入用 UUID。

八、排障实录

1. service apache2 restart 报 failed

实测现象:改完站点配置后执行 service apache2 restart,报 Restarting Apache httpd web server: apache2 failed!,且 service apache2 status 显示 apache2 is not running ... failed!。原因:restart 对已运行实例发 SIGTERM 后新进程拉起竞争失败。处置:确认状态后直接 service apache2 start,实测一次成功。若在真实生产环境遇到,先 apachectl configtest 排除配置语法问题,再看 /var/log/apache2/error.log。

2. 本机 curl 返回 502 Bad Gateway

实测现象:Apache 明明在跑,curl http://localhost/ 却返回 502。原因:终端环境残留 http_proxy/https_proxy 变量,curl 把对 localhost 的请求也发给了代理,代理自然回 502。处置:curl --noproxy '*' http://localhost/ 单次绕过,或 unset http_proxy https_proxy 后再测。这也解释了排障时"浏览器能开、命令行不通"的怪象。

3. 访问 403 Forbidden

官方排障文档给出的典型原因:public 目录属主不正确(常见于上传方式部署,属主应为站点运行用户,如 www-data)。处置:chown -R www-data:www-data /var/www/mosparo(来源:官方文档 Normal installation → Troubleshooting,2026-10-28 查证)。

4. 访问 500 Internal Server Error

官方排障文档列出的两大原因:上传不完整导致文件缺失;PHP 扩展缺失。排查顺序:先看 var/log/prod-YYYY-MM-DD.log,若日志文件都不存在,基本就是扩展缺失,对照环境检查页(向导第 2 步)补齐(来源同上,2026-10-28 查证)。

5. zip 下载后只有 9 字节

实测现象:手拼的下载地址 .../download/v1.5.13/mosparo.zip 得到 9 字节的 "Not Found"。原因:mosparo 的发行包文件名带版本号,正确资产名是 mosparo-stable-v1.5.13.zip。教训:不要手拼资产 URL,从官方下载页或 Releases 页复制直链。

九、后续动作