roundcube/roundcubemail

Roundcube Docker镜像技术文档

1. 镜像概述和主要用途

Roundcube Docker镜像是Roundcube Webmail套件的容器化部署方案，提供基于Web的电子邮件客户端功能。该镜像封装了Roundcube Webmail的核心组件，支持通过环境变量快速配置，兼容多种数据库后端，并提供灵活的持久化和扩展能力，适用于个人或企业邮件系统的Web访问层部署。

2. 核心功能和特性

• 多变体支持：基于官方PHP镜像提供apache（含Apache Web服务器）、fpm（FPM模式）和fpm-alpine（Alpine轻量版FPM）三种变体
• 环境变量配置：通过环境变量实现核心参数快速配置，无需手动修改配置文件
• 数据库兼容性：支持SQLite（默认）、MySQL和PostgreSQL存储用户元数据
• 数据持久化：关键目录支持卷挂载，确保配置、数据库和临时文件持久化
• 插件管理：支持内置插件激活和自动安装扩展插件
• Docker Swarm集成：支持Docker Secrets管理敏感信息（如数据库密码、加密密钥）
• 灵活定制：支持通过挂载配置文件实现高级自定义设置和PHP参数调整

3. 使用场景和适用范围

• 个人邮件客户端：快速部署轻量级Web邮件访问界面
• 企业邮件系统：作为企业邮件服务器（如Postfix/Dovecot）的Web前端
• 开发测试环境：快速搭建邮件客户端测试环境，支持多种配置组合
• 容器化部署：适配Docker Swarm、Kubernetes等容器编排平台，支持水平扩展
• 反向代理集成：可配合Nginx等反向代理实现HTTPS和路径自定义

4. 镜像标签和变体

4.1 标签说明

4.2 变体说明

• apache：基于php:*{-apache}镜像，内置Apache Web服务器，开箱即用
• fpm：基于php:*{-fpm}镜像，仅包含PHP-FPM，需配合外部Web服务器（如Nginx）
• fpm-alpine：基于Alpine Linux的FPM变体，镜像体积更小，资源占用更低

5. 详细配置说明

5.1 环境变量配置

5.1.1 基础连接配置

5.1.2 功能与外观配置

5.1.3 数据库配置

5.2 数据库连接配置

5.2.1 SQLite（默认）

默认使用容器内SQLite数据库（路径/var/roundcube/db），适用于测试环境。生产环境需通过卷挂载持久化数据：

sh
docker run -v roundcube-db:/var/roundcube/db -d roundcube/roundcubemail

5.2.2 MySQL/PostgreSQL（推荐生产环境）

配置示例（MySQL）：

sh
docker run \
  -e ROUNDCUBEMAIL_DB_TYPE=mysql \
  -e ROUNDCUBEMAIL_DB_HOST=mysql-host \
  -e ROUNDCUBEMAIL_DB_USER=roundcube \
  -e ROUNDCUBEMAIL_DB_PASSWORD=secret \
  -e ROUNDCUBEMAIL_DB_NAME=roundcube_db \
  -d roundcube/roundcubemail

注意：启动前需确保数据库已存在，且用户具有表创建权限。

5.3 Docker Secrets支持（Swarm环境）

在Docker Swarm中，可通过Docker Secrets管理敏感信息，支持以下secrets：

使用示例：

yaml
version: '3.8'
secrets:
  db_password:
    file: ./db_password.txt
services:
  roundcube:
    image: roundcube/roundcubemail
    secrets:
      - source: db_password
        target: roundcube_db_password

5.4 高级配置

5.4.1 自定义配置文件

通过挂载目录到/var/roundcube/config，添加*.php文件实现配置覆盖（支持PHP语法）：

sh
docker run -v ./custom-config:/var/roundcube/config -d roundcube/roundcubemail

配置参考：https://github.com/roundcube/roundcubemail/wiki/Configuration

5.4.2 PHP参数调整

挂载PHP配置文件到/usr/local/etc/php/conf.d/zzz_roundcube-custom.ini自定义PHP设置：

ini
# custom-php.ini
memory_limit = 128M
upload_max_filesize = 10M

启动命令：

sh
docker run -v ./custom-php.ini:/usr/local/etc/php/conf.d/zzz_roundcube-custom.ini -d roundcube/roundcubemail

6. 持久数据管理

以下目录需通过卷挂载实现数据持久化或多实例共享：

挂载示例（多目录持久化）：

sh
docker run \
  -v roundcube-config:/var/roundcube/config \
  -v roundcube-temp:/tmp/roundcube-temp \
  -v roundcube-html:/var/www/html \
  -d roundcube/roundcubemail

7. 插件安装

通过环境变量启用插件安装：

sh
docker run -e ROUNDCUBEMAIL_INSTALL_PLUGINS=1 -d roundcube/roundcubemail

插件安装逻辑在容器启动时执行，需确保网络通畅。

8. 使用方法

8.1 基本启动命令

sh
docker run \
  -e ROUNDCUBEMAIL_DEFAULT_HOST=imap.example.com \
  -e ROUNDCUBEMAIL_SMTP_SERVER=smtp.example.com \
  -p 8000:80 \
  -d roundcube/roundcubemail

• 将imap.example.com和smtp.example.com替换为实际IMAP/SMTP服务器地址
• 访问http://localhost:8000打开Roundcube界面

8.2 Docker Compose示例（MySQL+Apache）

yaml
version: '3.8'
services:
  roundcube:
    image: roundcube/roundcubemail:latest-apache
    ports:
      - "80:80"
    environment:
      - ROUNDCUBEMAIL_DEFAULT_HOST=imap.example.com
      - ROUNDCUBEMAIL_SMTP_SERVER=smtp.example.com
      - ROUNDCUBEMAIL_DB_TYPE=mysql
      - ROUNDCUBEMAIL_DB_HOST=mysql
      - ROUNDCUBEMAIL_DB_USER=roundcube
      - ROUNDCUBEMAIL_DB_PASSWORD=roundcube-pass
      - ROUNDCUBEMAIL_DB_NAME=roundcube
    volumes:
      - roundcube-temp:/tmp/roundcube-temp
      - roundcube-config:/var/roundcube/config
    depends_on:
      - mysql

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=root-pass
      - MYSQL_DATABASE=roundcube
      - MYSQL_USER=roundcube
      - MYSQL_PASSWORD=roundcube-pass
    volumes:
      - mysql-data:/var/lib/mysql

volumes:
  mysql-data:
  roundcube-temp:
  roundcube-config:

9. 构建自定义镜像

基于官方镜像扩展（例如添加Git和Composer）：

dockerfile
FROM roundcube/roundcubemail:latest

ENV COMPOSER_ALLOW_SUPERUSER=1

RUN set -ex; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        git \
        composer \
    ; \
    rm -rf /var/lib/apt/lists/*

构建命令：

sh
docker build -t custom-roundcube .

10. 示例配置

更多完整部署示例（如Nginx+FPM、PostgreSQL集成等）可参考官方仓库：
https://github.com/roundcube/roundcubemail-docker/tree/master/examples