Ubuntu 22.04 安装 Cypht 2.13 指南

‍‍‌> 目标：在 Ubuntu 22.04 服务器上从零安装 Cypht 2.13.0（Nginx + PHP-FPM + MariaDB 生产形态），并完成账号创建、登录验证与 systemd 托管；另附 PHP 内置服务器快速试用方案。全部命令与回显均来自 Ubuntu 22.04.5 LTS 环境实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
软件版本：Cypht v2.13.0（2026-10-16 发布的最新稳定版）
运行时：PHP 8.1.2（Ubuntu 22.04 官方仓库 php8.1，满足 Cypht ≥ 8.1 要求）、Composer 2.10.3
Web 栈：Nginx 1.18.0 + php8.1-fpm（unix socket）
数据库：MariaDB 10.6.23（Ubuntu 22.04 官方仓库）
安装路径：/var/www/cypht；用户数据目录：/var/lib/hm3/；站点入口：/var/www/cypht/site
监听端口：80（Nginx）

二、前置条件

一台可联网的 Ubuntu 22.04 服务器，root 或具备 sudo 权限的账号
至少 1 GB 内存、1 GB 可用磁盘（源码 + 依赖安装后约 210 MB，实测 du -sh /var/www/cypht 为 209M）
如使用 IMAP 认证之外的本地账号登录，需准备数据库（本文用 MariaDB，同机部署）

三、版本选型说明

Cypht 当前有两条发布线（GitHub Releases，2026-10-25 查询）：

发布线	最新版	定位
2.x	v2.13.0（2026-10-16）	当前主线，`.env` 配置体系 + 模块化打包，本文安装对象
1.4.x	v1.4.9（2026-08）	旧线，仅安全维护（`hm3.ini` 时代），新部署不选

Ubuntu 22.04 仓库自带 PHP 8.1.2，恰好满足 Cypht 2.x「PHP ≥ 8.1」的最低要求，无需额外引入第三方 PHP 源；Composer 用官方安装器装 2.x 最新版。

四、方案 A：官方源码包 + Nginx + PHP-FPM + MariaDB（生产推荐）

4.1 方案说明

从 GitHub Releases 下载 v2.13.0 源码包，Composer 安装依赖，.env 配置数据库后端，Nginx 反向解析 PHP-FPM 提供 HTTP 服务，systemd 托管 nginx / php8.1-fpm / mariadb 三个服务。这是官方「Manual Install」的标准落地形态。

4.2 安装系统依赖

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y \
  php-cli php-fpm php-mbstring php-curl php-xml php-gd php-zip \
  php-mysql php-intl php-soap unzip git curl nginx mariadb-server

实测安装完成后关键版本：

php -v | head -1

PHP 8.1.2-1ubuntu2.28 (cli) (built: Oct 19 2026 18:54:45) (NTS)

php -m | grep -iE 'mbstring|curl|gd|zip|pdo_mysql|intl|soap'

curl
gd
intl
mbstring
pdo_mysql
soap
zip

⚠️ 注意：php-soap 必须安装。Cypht 依赖 garethp/php-ews（Exchange Web Services 模块）要求 ext-soap，缺失时 Composer 会直接报错中断（排障实录见「十、常见问题」Q1）。

4.3 安装 Composer

Ubuntu 22.04 仓库的 composer 包版本偏旧，用官方安装器装最新 2.x：

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

Composer version 2.10.3 2026-08-27 13:34:23

4.4 下载并解压 Cypht 源码

cd /tmp
curl -sSL -o cypht-2.13.0.tar.gz https://github.com/cypht-org/cypht/archive/refs/tags/v2.13.0.tar.gz
ls -la cypht-2.13.0.tar.gz

-rw-r--r-- 1 root root 1562088 Oct 25 04:13 cypht-2.13.0.tar.gz

tar -xzf /tmp/cypht-2.13.0.tar.gz -C /var/www/
mv /var/www/cypht-2.13.0 /var/www/cypht

4.5 安装 PHP 依赖

cd /var/www/cypht
composer install --no-dev --optimize-autoloader

实测约安装 45 个 Composer 包，成功尾部回显（输出节选）：

thomaspark/bootswatch suggests:
 - robloach/component-installer: Allows installation of Components via Composer

4.6 准备 MariaDB 数据库

systemctl start mariadb
systemctl is-active mariadb

active

创建库与账号（演示账号口令 q1w2e3r4，生产环境请替换为强口令）：

mysql -e "CREATE DATABASE cypht_db; \
  CREATE USER 'cypht'@'localhost' IDENTIFIED BY 'q1w2e3r4'; \
  GRANT ALL PRIVILEGES ON cypht_db.* TO 'cypht'@'localhost'; \
  FLUSH PRIVILEGES;"

4.7 编写 .env 配置

cd /var/www/cypht
cp .env.example .env

编辑 .env，关键项改动如下（其余保持默认）：

DB_CONNECTION_TYPE=host
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_NAME=cypht_db
DB_USER=cypht
DB_PASS=q1w2e3r4
SESSION_TYPE=DB
AUTH_TYPE=DB
USER_CONFIG_TYPE=DB
ENABLE_REDIS=false
ENABLE_MEMCACHED=false

逐项说明：

DB_*：本地 MariaDB 连接信息；DB_PORT 留空即走默认 3306
SESSION_TYPE=DB：会话存数据库（多节点/重启不丢登录态）；单机也可用默认 PHP
AUTH_TYPE=DB：用 Cypht 本地账号表登录；若希望「邮箱账号即登录」可改 IMAP（需配置 IMAP_AUTH_*）
USER_CONFIG_TYPE=DB：用户设置存库，便于备份；file 则落 /var/lib/hm3/users
ENABLE_REDIS/MEMCACHED=false：本方案未装缓存服务，显式关闭避免连接报错

4.8 初始化数据库表、生成站点、创建管理员

cd /var/www/cypht
php ./scripts/setup_database.php

Database connection successful ...
Database detected. Running migrations...
Running migrations...
Migrations completed.

Db setup finished

php ./scripts/config_gen.php

site.js file created
dynamic.php file written
creating production site
KindEditor assets copied successfully
copying assets directory...

php ./scripts/create_account.php admin q1w2e3r4

User account created successfully.

验证库表与账号落库：

mysql -ucypht -pq1w2e3r4 cypht_db -e 'show tables; select username from hm_user;'

Tables_in_cypht_db
hm_login_attempts
hm_user
hm_user_session
hm_user_settings
migrations
username
admin

4.9 配置 Nginx + PHP-FPM

新建站点配置 /etc/nginx/sites-available/cypht：

server {
    listen 80 default_server;
    server_name _;
    root /var/www/cypht/site;
    index index.php;

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

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

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

要点：文档根指向 site/（config_gen 生成的生产打包目录，而非仓库根目录）；try_files 把动态请求回退到单入口 index.php。

启用站点、修正属主并启动服务：

ln -sf /etc/nginx/sites-available/cypht /etc/nginx/sites-enabled/cypht
rm -f /etc/nginx/sites-enabled/default
chown -R www-data:www-data /var/www/cypht /var/lib/hm3
nginx -t
systemctl restart php8.1-fpm
systemctl restart nginx
systemctl is-active php8.1-fpm
systemctl is-active nginx

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

开机自启：

systemctl enable nginx
systemctl enable php8.1-fpm
systemctl enable mariadb

4.10 登录验证

curl -sI http://127.0.0.1/ | head -3

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Content-Type: text/html; charset=UTF-8

模拟登录流程（POST 账号密码 → 303 跳转主页 → 主页 200）：

curl -s -c /tmp/c.txt http://127.0.0.1/ -o /dev/null
curl -s -b /tmp/c.txt -c /tmp/c.txt -X POST http://127.0.0.1/ \
  -d 'username=admin&password=q1w2e3r4' -o /dev/null -w 'HTTP %{http_code} -> %{redirect_url}\n'
curl -s -b /tmp/c.txt 'http://127.0.0.1/?page=home' -o /dev/null -w 'home HTTP %{http_code} bytes=%{size_download}\n'

HTTP 303 -> http://127.0.0.1/?page=home
home HTTP 200 bytes=676163

浏览器访问 http://<服务器IP>/，用 admin / q1w2e3r4 登录，首页出现「Add an E-mail Account」即部署成功。

运行态总览（实测）：

systemctl list-units --type=service --state=running | grep -E 'nginx|php|mariadb'

  mariadb.service             loaded active running MariaDB 10.6.23 database server
  nginx.service               loaded active running A high performance web server and a reverse proxy server
  php8.1-fpm.service          loaded active running The PHP 8.1 FastCGI Process Manager

五、方案 B：PHP 内置服务器快速试用（仅本机体验）

5.1 方案说明

利用 PHP 自带的开发服务器，不装 Nginx/MariaDB，5 分钟拉起界面体验功能。官方安装页给出的即此路径（php -S）。仅用于试用，严禁生产。

5.2 步骤

完成「四、方案 A」的 4.2（只需 php-cli 及扩展）、4.3、4.4、4.5、4.7（.env 用默认值即可，不建库时把 AUTH_TYPE 保持默认 DB 并执行 4.8 的建表与建号需数据库；纯体验界面可不建账号直接打开首页）后：

cd /var/www/cypht
php -S 127.0.0.1:7777 -t site

[Sun Oct 25 04:20:34 2026] PHP 8.1.2-1ubuntu2.28 Development Server (http://127.0.0.1:7777) started

curl -sI http://127.0.0.1:7777/ | head -1

HTTP/1.1 200 OK

浏览器访问 http://127.0.0.1:7777/ 即可看到登录页。体验完按 Ctrl+C 停止。

六、方案对比与选择建议

维度	方案 A（Nginx+PHP-FPM+MariaDB）	方案 B（php -S）
用途	生产/长期运行	本地试用、功能预览
依赖	Nginx、PHP-FPM、MariaDB	仅 php-cli
并发能力	高（FPM 进程池）	单进程串行
开机自启	systemd 托管	无
账号体系	数据库持久化	依 .env 配置

结论：正式使用一律选方案 A；只想先看一眼界面用方案 B。若偏好编排化一键交付，见本站《Cypht 2.13 Docker Compose 部署指南》。组件定位与竞品对比见《Cypht 介绍与选型指南》。

七、配置说明

主配置文件：/var/www/cypht/.env（200+ 项，全量参数含义见本站《Cypht 2.13 配置参数详解》）
修改 .env 后必须重跑 php ./scripts/config_gen.php 重建 site/ 生产资源，再 systemctl reload php8.1-fpm 生效
目录权限：/var/www/cypht 与 /var/lib/hm3 属主须为 www-data:www-data
日志：Nginx 访问/错误日志在 /var/log/nginx/；Cypht 自身日志由 .env 的 LOG_LEVEL（默认 WARNING）与 LOG_FILE 控制
附件上传上限受 PHP 限制，按需调整 /etc/php/8.1/fpm/php.ini 的 upload_max_filesize / post_max_size 后重启 php8.1-fpm

八、升级与降级

升级（如 2.13.0 → 后续新版）：

# 1. 备份
mysqldump -ucypht -pq1w2e3r4 cypht_db > /tmp/cypht_db_$(date +%F).sql
tar -czf /tmp/cypht_app_backup.tar.gz -C /var/www cypht
# 2. 下载新版本并替换代码（保留 .env）
curl -sSL -o /tmp/cypht-new.tar.gz https://github.com/cypht-org/cypht/archive/refs/tags/<新版本号>.tar.gz
# 3. 解压替换后重跑依赖与打包
cd /var/www/cypht && composer install --no-dev --optimize-autoloader
php ./scripts/setup_database.php   # 执行增量迁移
php ./scripts/config_gen.php
systemctl reload php8.1-fpm

降级：恢复备份的代码目录与数据库 dump 即可；setup_database.php 的迁移为单向，降级前务必先回滚数据库。

多版本共存：将不同版本解压到不同目录（如 /var/www/cypht-2.13.0），Nginx root 软链切换，属于目录级隔离，互不影响。

九、卸载清理

systemctl stop nginx
systemctl disable nginx
rm -f /etc/nginx/sites-enabled/cypht /etc/nginx/sites-available/cypht
systemctl start nginx            # 若 nginx 还服务其他站点；否则可 apt-get purge nginx
rm -rf /var/www/cypht /var/lib/hm3
mysql -e "DROP DATABASE cypht_db; DROP USER 'cypht'@'localhost';"

PHP/MariaDB 为通用组件，如无其他应用使用再执行 apt-get purge 卸载。

十、常见问题

Q1：composer install 报 garethp/php-ews ... requires ext-soap 中断？

实测回显：

- garethp/php-ews v0.11.2 requires ext-soap * -> it is missing from your system. Install or enable PHP's soap extension.

原因：Cypht 的 Exchange Web Services 模块依赖 SOAP 扩展。解决：apt-get install -y php-soap 后重跑 composer install 即可（本文 4.2 已将其纳入依赖清单）。

Q2：登录页 502 Bad Gateway？

php8.1-fpm 未运行或 socket 路径不对。依次执行 systemctl status php8.1-fpm、ls /run/php/php8.1-fpm.sock，确认 Nginx 配置里 fastcgi_pass 与实际 socket 一致。

Q3：登录后立刻被踢回登录页？

多为会话后端不可用：用 SESSION_TYPE=DB 时确认 hm_user_session 表存在且数据库账号有写权限；目录属主不是 www-data 也会导致 PHP 会话/附件写失败，重新执行 4.9 的 chown。

Q4：改完 .env 界面没变化？

.env 改动需重跑 php ./scripts/config_gen.php 重新打包 site/，浏览器强刷（Ctrl+F5）清除旧 site.js/site.css 缓存。

十一、参考链接

官方安装指南：https://www.cypht.org/install/
GitHub Releases（源码包下载）：https://github.com/cypht-org/cypht/releases
官方文档：https://cypht.org/documentation.html
Composer 安装器：https://getcomposer.org/installer