Cypht 2.13 Docker Compose 部署指南

‍‍‌> 目标：用官方镜像 cypht/cypht:2.13.0 + MariaDB 10 通过 Docker Compose 一键部署 Cypht 聚合 Webmail，含初始管理员、数据库自动建表、持久化与日常运维命令。全文 compose 配置与命令回显均在 Docker 环境实测通过（2026-10-25）。

一、环境信息

Docker 镜像：cypht/cypht:2.13.0（官方镜像，Debian Bookworm 基底，内置 nginx 1.22 + PHP 8.3.36-FPM，supervisord 双进程托管；本地解压后体积约 1.24GB）、mariadb:10
编排：Docker Compose v2（docker compose 子命令）
服务端口：宿主机 8130 → Cypht 容器 80（可按需调整）
数据落点：项目目录 data/mysql（MariaDB 数据）、data/log/*（nginx/php/supervisord 日志）、data/fonts（站点字体）
演示账号：admin / q1w2e3r4（由 AUTH_USERNAME/AUTH_PASSWORD 注入）

二、镜像选型说明

镜像	维护方	说明
`cypht/cypht`	官方	Docker Hub 认证仓库，随版本发布更新；集 nginx+PHP-FPM 于一体，环境变量即配置，本文采用
`sailfrog/cypht-docker`	社区	已被官方镜像取代，官方页面明确标注「replaces sailfrog/cypht-docker」，新部署勿用
`latest` 标签	—	可能对应 master 构建，官方建议固定版本号标签（如 `2.13.0`）

三、前置条件

已安装 Docker Engine 与 Compose v2 插件（docker compose version 可查到版本号）
宿主机 8130 端口空闲；与镜像仓库网络可达
磁盘预留 ≥ 2GB（镜像 + 数据库）

四、部署步骤

4.1 编写 docker-compose.yaml

新建项目目录并写入以下文件（基于官方 docker/docker-compose.yaml 示例，版本号固定为 2.13.0，口令按本文规范设置）：

name: cypht-2.13.0-stack

services:
  db:
    image: mariadb:10
    container_name: cypht-2.13.0-db
    volumes:
      - ./data/mysql:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=cypht
      - MYSQL_USER=cypht
      - MYSQL_PASSWORD=cypht_password
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-ucypht", "-pcypht_password"]
      interval: 10s
      timeout: 5s
      retries: 5

  cypht:
    image: cypht/cypht:2.13.0
    container_name: cypht-2.13.0-web
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8130:80"
    environment:
      - AUTH_USERNAME=admin
      - AUTH_PASSWORD=q1w2e3r4
      - DB_CONNECTION_TYPE=host
      - DB_DRIVER=mysql
      - DB_HOST=db
      - DB_NAME=cypht
      - DB_USER=cypht
      - DB_PASS=cypht_password
      - SESSION_TYPE=DB
      - USER_CONFIG_TYPE=DB
    volumes:
      - ./data/log/nginx:/var/log/nginx
      - ./data/log/php:/var/log/php
      - ./data/log/supervisord:/var/log/supervisord
      - ./data/fonts:/usr/local/share/cypht/site/fonts

关键设计解读：

depends_on: service_healthy：等 MariaDB 健康检查通过后再启动 Cypht，避免首次启动建表失败
AUTH_USERNAME/AUTH_PASSWORD：容器入口脚本检测到 USER_CONFIG_TYPE=DB 且设置了这两个变量时，自动调用 create_account.php 创建初始管理员
DB_HOST=db：Compose 自动把服务名 db 解析到 MariaDB 容器
SESSION_TYPE=DB + USER_CONFIG_TYPE=DB：会话与用户设置都入库，容器重建后登录态与设置不丢

4.2 拉取镜像并启动

docker compose pull
docker compose up -d

实测启动序列（输出节选）：

 Container cypht-2.13.0-db Started
 Container cypht-2.13.0-db Waiting
 Container cypht-2.13.0-db Healthy
 Container cypht-2.13.0-web Started

4.3 验证运行状态

docker compose ps

NAME               IMAGE                STATUS
cypht-2.13.0-db    mariadb:10           Up 5 minutes (healthy)
cypht-2.13.0-web   cypht/cypht:2.13.0   Up 5 minutes (healthy)

curl -sI http://localhost:8130/ | head -4

HTTP/1.1 200 OK
Server: nginx/1.22.1
Content-Type: text/html; charset=UTF-8
X-Powered-By: PHP/8.3.36

4.4 验证建表与初始账号

容器启动时入口脚本会自动执行 setup_database.php（建表迁移）与 create_account.php（创建 admin）：

docker exec cypht-2.13.0-db mysql -ucypht -pcypht_password cypht -e "show tables; select username from hm_user;"

Tables_in_cypht
hm_login_attempts
hm_user
hm_user_session
hm_user_settings
migrations
username
admin

5 张表自动建成、admin 账号落库，说明自动初始化成功。

4.5 登录验证

curl -s -c /tmp/cypht_cookie.txt http://localhost:8130/ -o /dev/null
curl -s -b /tmp/cypht_cookie.txt -c /tmp/cypht_cookie.txt -X POST http://localhost:8130/ \
  -d 'username=admin&password=q1w2e3r4' -o /dev/null -w 'HTTP %{http_code} -> %{redirect_url}\n'

HTTP 303 -> http://localhost:8130/?page=home

浏览器打开 http://<宿主机IP>:8130/，使用 admin / q1w2e3r4 登录即进入聚合收件箱首页。

五、数据持久化说明

数据	位置	丢失影响
账号、会话、用户设置	`./data/mysql`（MariaDB）	全丢，需重建
附件/用户文件（`USER_CONFIG_TYPE=file` 时）	容器内 `/var/lib/hm3/`，建议加挂 `- ./data/hm3:/var/lib/hm3`	附件丢失
运行日志	`./data/log/*`	仅日志
站点字体	`./data/fonts`	自动重新生成

升级镜像版本时只需 docker compose pull && docker compose up -d，数据卷不变；应用内迁移由入口脚本自动执行。

六、环境变量表

cypht/cypht 镜像把 .env 的全部配置项暴露为同名环境变量（完整清单与默认值见本站《Cypht 2.13 配置参数详解》），常用项：

变量	默认值	说明
`APP_NAME`	Cypht	页面标题/品牌名
`AUTH_USERNAME` / `AUTH_PASSWORD`	空	首次启动自动创建的初始账号（需 `USER_CONFIG_TYPE=DB`）
`DB_DRIVER` / `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASS`	mysql / 127.0.0.1 / cypht_db 等	数据库连接；`DB_CONNECTION_TYPE=socket` 时改用 `DB_SOCKET`
`DB_SSL_CA` / `DB_SSL_CERT` / `DB_SSL_KEY` / `DB_SSL_VERIFY_SERVER_CERT`	空 / true	2.13.0 新增：MySQL/MariaDB TLS 加密连接
`SESSION_TYPE`	PHP	会话后端：PHP / DB / Redis / Memcached
`USER_CONFIG_TYPE`	file	用户设置存储：file / DB
`AUTH_TYPE`	DB	认证方式：DB / IMAP / LDAP
`ENABLE_REDIS` / `REDIS_SERVER` / `REDIS_PORT`	true / 127.0.0.1 / 6379	Redis 缓存；本 compose 未配 Redis，可保持默认（连接失败自动降级）或显式 `false`
`ENABLE_MEMCACHED`	true	同上
`ADMIN_USERS`	空	逗号分隔的管理员用户名清单
`DEFAULT_LANGUAGE`	en	默认界面语言（可设 `zh-Hans`）
`CYPHT_MODULES`	内建全量	逗号分隔的模块开关
`ENABLE_DEBUG` / `LOG_LEVEL` / `LOG_FILE`	false / WARNING / 空	调试与日志
`ALLOW_EXTERNAL_IMAGE_SOURCES`	false	是否默认加载邮件外部图片

💡 官方建议：生产环境把变量写进 env 文件（cp .env.example /etc/cypht-prod.env），compose 里用 env_file: 引入，避免 compose 与 env 文件混用造成覆盖困惑。

七、配置参数说明（容器内落点）

应用目录：/usr/local/share/cypht；入口脚本：/usr/local/bin/docker-entrypoint.sh
环境变量在启动时写入 /usr/local/share/cypht/.env 并重建 site/ 资源——改任何环境变量后必须重建容器（docker compose up -d --force-recreate cypht），仅重启不生效
容器内由 supervisord 同时拉起 nginx 与 php-fpm 两个进程：

docker exec cypht-2.13.0-web grep -E 'program' /etc/supervisord.conf

[program:nginx]
[program:php-fpm]

PHP 上传限制：镜像内置 upload_max_filesize = 50M / post_max_size = 60M（/usr/local/etc/php/conf.d/cypht.ini），如需调整可挂载同名文件覆盖

八、配置文件挂载

除环境变量外，常用挂载点：

宿主路径（示例）	容器路径	用途
`./cypht.env`	（用 `env_file:` 引用，不挂载）	全量环境变量
`./data/hm3`	`/var/lib/hm3`	用户设置与附件（file 模式）
`./cypht.ini`	`/usr/local/etc/php/conf.d/cypht.ini`	覆盖 PHP 上传等限制
`./nginx-extra.conf`	不建议	镜像 nginx 配置深度耦合，定制优先走环境变量

九、等价 docker run

不使用 Compose 时，等价命令如下（需先建网络与 MariaDB）：

docker network create cypht-net
docker volume create cypht-mysql

docker run -d --name cypht-db --network cypht-net \
  -v cypht-mysql:/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=root_password \
  -e MYSQL_DATABASE=cypht \
  -e MYSQL_USER=cypht \
  -e MYSQL_PASSWORD=cypht_password \
  mariadb:10

docker run -d --name cypht-web --network cypht-net \
  -p 8130:80 \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD=q1w2e3r4 \
  -e DB_CONNECTION_TYPE=host \
  -e DB_DRIVER=mysql \
  -e DB_HOST=cypht-db \
  -e DB_NAME=cypht \
  -e DB_USER=cypht \
  -e DB_PASS=cypht_password \
  -e SESSION_TYPE=DB \
  -e USER_CONFIG_TYPE=DB \
  cypht/cypht:2.13.0

⚠️ 注意：docker run 形态没有健康检查等待，Cypht 首次启动若早于 MariaDB 就绪会建表失败，需等数据库起来后再重启一次 web 容器，因此生产推荐 Compose 编排。

十、常用运维命令

# 查看日志（nginx/php/supervisord 汇总到容器 stdout）
docker compose logs -f cypht

# 重启 / 重建
docker compose restart cypht
docker compose up -d --force-recreate cypht   # 改环境变量后必须用这个

# 进入应用容器执行 CLI 工具（建号/改密等，详见本站[《Cypht 2.13 常用 CLI 命令与工具详解》](https://www.quzuo.net/document/jfZhVwI5n250)）
docker exec -it cypht-2.13.0-web bash
# 容器内：cd /usr/local/share/cypht && php ./scripts/create_account.php <用户名> <密码>

# 备份数据库
docker exec cypht-2.13.0-db mysqldump -ucypht -pcypht_password cypht > backup_$(date +%F).sql

# 升级到新版（改 compose 里镜像标签后）
docker compose pull
docker compose up -d

# 停止并删除（保留 data/ 数据）
docker compose down

十一、常见问题

Q1：web 容器反复重启、日志提示数据库连接失败？

MariaDB 首次初始化较慢，service_healthy 等待超时所致。确认 db 容器 STATUS 为 healthy 后 docker compose up -d 再拉一次 web 即可；也可把 healthcheck 的 retries 调大。

Q2：登录报「Invalid username or password」？

初始账号只在 USER_CONFIG_TYPE=DB 且首次启动时创建。若首启时这两个变量没配对，账号不会补建，可进入容器手工执行 php ./scripts/create_account.php admin q1w2e3r4。

Q3：改了环境变量没生效？

环境变量只在容器启动时写入 .env，docker compose restart 不重写。用 docker compose up -d --force-recreate cypht 重建。

Q4：Redis/Memcached 报错刷屏？

compose 未带缓存容器而镜像默认 ENABLE_REDIS=true。在 cypht 服务 environment 里加 - ENABLE_REDIS=false 与 - ENABLE_MEMCACHED=false，或补一个 redis 服务并把 SESSION_TYPE 切到 Redis。

十二、参考链接

官方镜像（Docker Hub）：https://hub.docker.com/r/cypht/cypht
官方 compose 示例：https://github.com/cypht-org/cypht/blob/master/docker/docker-compose.yaml
环境变量全量清单：https://github.com/cypht-org/cypht/blob/master/.env.example
裸机安装形态见本站《Ubuntu 22.04 安装 Cypht 2.13 指南》