Roundcube Mail (含CardDAV) Docker镜像文档

1. 镜像概述与主要用途

该Docker镜像基于Roundcube Mail集成CardDAV功能，源自Packagist包roundcube/carddav。Roundcube Mail是一款开源Web邮件客户端，提供直观的Web界面用于邮件管理；CardDAV是一种基于HTTP的地址簿同步协议，该集成版本允许用户通过Web邮件客户端同步、管理CardDAV地址簿，实现邮件与联系人数据的统一管理。

2. 核心功能与特性

2.1 Roundcube Mail基础功能

• 基于Web的邮件访问，支持主流浏览器
• HTML邮件编辑与查看，支持附件管理
• 多文件夹邮件组织（收件箱、发件箱、草稿等）
• 邮件搜索、过滤规则与自动回复功能
• 多语言支持与主题自定义

2.2 CardDAV集成功能

• 地址簿双向同步（支持从CardDAV服务器拉取联系人，本地修改自动推送到服务器）
• 兼容主流CardDAV服务（如Nextcloud、ownCloud、iCloud、FastMail等）
• 联系人分组管理与批量操作
• 地址簿数据本地缓存，提升访问速度

3. 使用场景与适用范围

3.1 适用场景

• 个人用户自托管Web邮件客户端，需同步多设备地址簿
• 小型企业内部邮件系统，需统一管理员工联系人
• 集成自托管邮件服务器（如Postfix、Dovecot），作为前端Web界面
• 替代传统桌面邮件客户端，实现跨设备邮件与联系人访问

3.2 适用范围

• 个人用户或小型团队（1-50人）
• 需轻量级、低维护成本的邮件解决方案
• 已部署CardDAV服务（如Nextcloud）的环境

4. 使用方法与配置说明

4.1 前提条件

• Docker Engine 20.10+ 或 Docker Desktop
• Docker Compose（可选，用于多服务部署）
• 可用的数据库服务（MySQL 5.7+/PostgreSQL 10+，用于存储Roundcube配置与用户数据）
• 邮件服务器（SMTP/IMAP，用于邮件收发）
• CardDAV服务器（可选，如无自有服务器，可使用公共服务或集成在邮件服务器中）

4.2 Docker Run 命令示例

docker run -d \
  --name roundcube-carddav \
  -p 8080:80 \  # 映射容器80端口到主机8080端口
  -e DB_TYPE=mysql \  # 数据库类型（mysql/postgresql/sqlite）
  -e DB_HOST=db \  # 数据库主机地址（需与数据库容器网络互通）
  -e DB_NAME=roundcube \  # 数据库名称
  -e DB_USER=roundcubeuser \  # 数据库用户名
  -e DB_PASS=strongpassword \  # 数据库密码
  -e SMTP_SERVER=smtp.example.com \  # SMTP服务器地址
  -e SMTP_PORT=587 \  # SMTP端口（587/465/25）
  -e IMAP_SERVER=imap.example.com \  # IMAP服务器地址
  -e IMAP_PORT=993 \  # IMAP端口（993/143）
  -e CARDDAV_SERVER_URL=[***] \  # CardDAV服务器地址
  -e CARDDAV_USER=carddavuser \  # CardDAV服务器用户名
  -e CARDDAV_PASS=carddavpassword \  # CardDAV服务器密码
  -v roundcube_data:/var/www/html/data \  # 持久化存储用户数据（联系人、配置等）
  roundcube/carddav:latest

4.3 Docker Compose 配置示例

version: '3.8'

services:
  roundcube:
    image: roundcube/carddav:latest
    container_name: roundcube-carddav
    restart: always
    ports:
      - "8080:80"  # Web访问端口
    environment:
      - DB_TYPE=mysql
      - DB_HOST=db
      - DB_NAME=roundcube
      - DB_USER=roundcubeuser
      - DB_PASS=strongpassword
      - SMTP_SERVER=smtp.example.com
      - SMTP_PORT=587
      - SMTP_ENCRYPTION=tls  # SMTP加密方式（tls/ssl/none）
      - IMAP_SERVER=imap.example.com
      - IMAP_PORT=993
      - IMAP_ENCRYPTION=ssl  # IMAP加密方式（ssl/tls/none）
      - CARDDAV_SERVER_URL=[***]
      - CARDDAV_USER=carddavuser
      - CARDDAV_PASS=carddavpassword
      - DEFAULT_LANGUAGE=zh_CN  # 默认语言（en_US/zh_CN/de等）
    volumes:
      - roundcube_data:/var/www/html/data  # 用户数据持久化
    depends_on:
      - db  # 依赖数据库服务启动

  db:
    image: mysql:8.0
    container_name: roundcube-db
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=roundcube
      - MYSQL_USER=roundcubeuser
      - MYSQL_PASSWORD=strongpassword
    volumes:
      - db_data:/var/lib/mysql  # 数据库数据持久化

volumes:
  roundcube_data:  # Roundcube用户数据卷
  db_data:  # 数据库数据卷

4.4 环境变量说明

4.5 卷挂载说明

4.6 端口映射

容器默认暴露80端口（HTTP），可通过主机端口映射（如8080:80）提供Web访问。生产环境建议搭配反向代理（如Nginx）启用HTTPS，映射容器80端口到代理服务器内部端口。

5. 注意事项

• 数据库初始化：首次启动需确保数据库已创建，Roundcube会自动初始化表结构（依赖DB_*环境变量配置）。
• 敏感信息安全：避免在命令行直接暴露密码，建议通过环境变量文件（如.env）或Docker Secrets管理敏感配置。
• CardDAV兼容性：不同CardDAV服务器地址格式可能不同（如Nextcloud需包含用户路径与地址簿名称），需根据实际服务器文档调整CARDDAV_SERVER_URL。
• 数据备份：定期备份roundcube_data卷与数据库数据，防止数据丢失。
• HTTPS配置：生产环境必须启用HTTPS（通过反向代理或容器内配置SSL），避免数据传输明文泄露。