LimeSurvey Docker 镜像使用指南

概览

本文档介绍如何使用 martialblog/limesurvey Docker 镜像部署 LimeSurvey（一款开源调查工具）。该镜像基于 Docker 容器平台构建，支持多种部署方式（Apache、FPM 等），并提供完整的配置与持久化方案。

快速参考

• 维护者：[***]
• 获取帮助：GitHub Issues

支持的标签及对应 Dockerfile

以下是当前支持的镜像标签及构建文件链接：

• 6-apache、6.<BUILD-NUMBER>-apache、latest
• 6-fpm、6.<BUILD-NUMBER>-fpm
• 6-fpm-alpine、6.<BUILD-NUMBER>-fpm-alpine
• 5-apache、5.<BUILD-NUMBER>-apache
• 5-fpm、5.<BUILD-NUMBER>-fpm
• 5-fpm-alpine、5.<BUILD-NUMBER>-fpm-alpine

Apache 镜像使用说明

apache 镜像内置 Apache 服务器和 PHP 环境，默认提供无 root 权限版本（以 www-data 为运行用户，Apache 监听 8080 端口，5.0 及以上版本默认启用）。

Apache 配置调整

如需修改 Apache 配置，可将自定义配置文件挂载到容器内路径：
/etc/apache2/sites-available/000-default.conf

示例：参考仓库中提供的默认配置文件进行修改。

端口设置

可通过环境变量 LISTEN_PORT 指定 Apache 监听端口（例如 LISTEN_PORT=8080）。5.0 及以上版本默认端口为 8080（非特权端口）。

FPM 镜像使用说明

FPM 镜像需配合额外的 Web 服务器（如 Nginx）使用，Web 服务器需将 HTTP 请求代理至容器的 FPM 端口。具体配置可参考仓库中的 docker-compose.fpm.yml 示例。

FPM 镜像启用 HTTPS

若需通过 FPM 镜像启用 HTTPS，可使用 Let's Encrypt 免费证书。配置步骤如下：

1. 参考 docker-compose.fpm-certbot.yml 示例文件，该配置会自动获取并安装证书。
2. 注意：需调整 examples/nginx-certbot.conf 中的域名配置。例如，若 HOSTNAMES 设为 example.org [***]，则 nginx-certbot.conf 中需填写主域名 example.org（不含 www 前缀）。

外部数据库配置

LimeSurvey 运行依赖外部数据库（MySQL 或 PostgreSQL），需提前部署数据库服务。具体配置示例可参考仓库中的 docker-compose.yml（包含数据库服务定义）。

数据持久化

为保存上传的调查文件，需将上传目录挂载为卷。路径如下：
/var/www/html/upload/surveys

示例：参考 docker-compose.yml 中的卷挂载配置。

注意：挂载目录需确保归 Web 服务器用户（如 www-data）所有，否则可能导致权限问题。

LimeSurvey 配置说明

容器入口脚本会自动检测配置文件：若未提供 config.php，则自动生成新配置并通过 LimeSurvey 命令行工具完成初始化安装；若已提供，则直接使用现有配置。

配置文件挂载

如需自定义 LimeSurvey 配置，可将本地配置文件挂载到容器内路径：
/my-data/config.php:/var/www/html/application/config/config.php

注意：

• 初始安装后，修改 ADMIN_* 相关环境变量（如管理员账号、密码）将不再生效，建议通过 LimeSurvey 应用内界面进行调整。
• 若挂载的 config.php 在首次启动前已存在，则不会自动运行 Web 安装向导。

数据加密（4.0+ 支持）

LimeSurvey 4.0 及以上版本支持数据加密，可通过以下方式配置：

1. 直接挂载自定义 security.php 文件（推荐）。
2. 通过环境变量提供加密密钥（如 ENCRYPT_KEYPAIR、ENCRYPT_PUBLIC_KEY 等）。
3. 不做任何配置，系统会生成临时 security.php（重启容器后失效，不建议生产环境使用）。

详细配置说明可参考 LimeSurvey 数据加密文档。

反向代理配置

若 LimeSurvey 部署在反向代理（如 Apache、Nginx、Traefik）之后，需在代理服务器中添加额外配置以确保正常运行。

常见代理配置示例

• Apache：添加 ProxyPreserveHost On 指令。
• Nginx：设置 fastcgi_param HTTP_HOST my-survey.example.local;。
• Traefik：通过 customRequestHeaders 显式设置 Host 请求头。

Traefik 子路径部署示例

若需将 LimeSurvey 部署在子路径（如 [***] BASE_URL` 并调整容器 Web 服务器配置。示例 Traefik 标签配置如下：

# BASE_URL = /limesurvey
"traefik.http.routers.limesurvey.rule=PathPrefix(`/limesurvey`)",
"traefik.http.routers.limesurvey.middlewares=strip-limesurvey@docker",
"traefik.http.middlewares.strip-limesurvey.stripprefix.prefixes=/limesurvey",

环境变量说明

通过环境变量可配置容器关键参数，常用变量如下表：

使用 docker-compose 部署

推荐使用 docker-compose 快速部署完整环境（包含应用、数据库、卷挂载等）。步骤如下：

1. 克隆仓库，进入项目目录。
2. 运行命令启动服务：

   docker-compose up -d
   

3. 访问前端页面：`[***]
4. 访问管理后台：`[***]

Helm 部署支持

该镜像提供 Helm Chart，可用于 Kubernetes 集群部署。详细说明参考 Helm 仓库：
[***]

升级指南

FPM 镜像升级

使用 docker-compose 部署 FPM 镜像时，升级步骤如下：

1. 停止应用和 Web 服务器容器。
2. 删除应用数据卷（避免旧文件冲突）：

   # 查看卷列表
   docker volume ls
   # 删除对应卷（例如卷名为 docker-limesurvey_lime）
   docker volume rm docker-limesurvey_lime
   

3. 重新启动容器（会拉取新版本镜像并重建卷）。

从 5.x 升级到 6.0

• 6.0 镜像基于 PHP 8.1 构建，需确保依赖环境兼容。
• LimeSurvey 5.x 成为新的 LTS 版本，3.x 版本已停止支持，建议尽快升级。

从 4.x 升级到 5.0

• 运行用户变更：容器默认运行用户改为 www-data（Debian 系统 UID 33，Alpine 系统 UID 82），挂载卷的目录权限需同步调整：

  # Debian 系统示例
  chown -R 33:33 /path/to/upload/surveys
  # Alpine 系统示例
  chown -R 82:82 /path/to/upload/surveys
  

• Apache 端口变更：Apache 镜像默认端口改为 8080，需检查并更新端口映射配置。

已知问题

反向代理子路径部署问题

当 LimeSurvey 部署在反向代理的子路径下（如 example.com/limesurvey），管理后台可能因路由问题无法正常显示（应用会直接重定向到 BASE_URL）。

解决方法：在反向代理中显式设置 HTTP Host 请求头（例如 Nginx 中添加 proxy_set_header Host $host;）。
详细说明参考：#127 issue

参考链接

• LimeSurvey 官网：[***]
• LimeSurvey GitHub 仓库：[***]<|FCResponseEnd|># LimeSurvey Docker 镜像使用指南

概览

本文档介绍基于 Docker 容器平台构建的 LimeSurvey 镜像部署方法，涵盖镜像版本、基础配置、数据持久化、升级维护等关键操作，帮助用户快速搭建 LimeSurvey 调查系统。

快速参考

• 维护者：[***]
• 获取帮助：GitHub Issues

支持的镜像标签

以下是当前可用的镜像标签及对应 Dockerfile 链接（可直接用于拉取镜像）：

• 6-apache、6.<BUILD-NUMBER>-apache、latest
• 6-fpm、6.<BUILD-NUMBER>-fpm
• 6-fpm-alpine、6.<BUILD-NUMBER>-fpm-alpine
• 5-apache、5.<BUILD-NUMBER>-apache
• 5-fpm、5.<BUILD-NUMBER>-fpm
• 5-fpm-alpine、5.<BUILD-NUMBER>-fpm-alpine

Apache 镜像使用说明

apache 镜像内置 Apache 服务器与 PHP 环境，默认提供无 root 权限版本（运行用户 www-data，Apache 监听 8080 端口，5.0+ 版本默认启用）。

配置调整

• Apache 配置文件：如需自定义服务器配置，将本地配置文件挂载至容器路径：
  /etc/apache2/sites-available/000-default.conf
  （参考仓库中默认配置文件修改）。

• 端口设置：通过环境变量 LISTEN_PORT 指定端口（如 LISTEN_PORT=8080），5.0+ 版本默认端口为 8080。

FPM 镜像使用说明

FPM 镜像需配合外部 Web 服务器（如 Nginx）使用，Web 服务器需将请求代理至容器的 FPM 端口。配置示例见仓库 docker-compose.fpm.yml。

启用 HTTPS

通过 Let's Encrypt 实现 HTTPS：

1. 参考 docker-compose.fpm-certbot.yml 配置，自动获取并安装证书。
2. 域名配置：examples/nginx-certbot.conf 需填写主域名（如 HOSTNAMES=example.org [***] 时，配置文件中填 example.org）。

外部数据库配置

LimeSurvey 依赖 MySQL/PostgreSQL 数据库，需提前部署数据库服务。配置示例见 docker-compose.yml（含数据库服务定义）。

数据持久化

上传的调查文件需持久化存储，挂载路径：
/var/www/html/upload/surveys

操作示例：参考 docker-compose.yml 中的卷挂载配置。
注意：挂载目录需归属 www-data 用户（如 chown -R 33:33 /本地路径，Debian 系统 www-data UID 为 33）。

LimeSurvey 配置说明

容器入口脚本会自动处理配置：

• 无 config.php 时，生成新配置并通过 CLI 完成初始化。
• 已挂载 config.php 时，直接使用现有配置（不会触发 Web 安装向导）。

自定义配置

挂载本地配置文件至容器路径：
/my-data/config.php:/var/www/html/application/config/config.php

注意：初始安装后，ADMIN_* 环境变量（管理员账号等）不再生效，需在应用内修改。

数据加密（4.0+）

支持 3 种加密配置方式：

1. 挂载自定义 security.php 文件（推荐）。
2. 通过环境变量提供密钥（如 ENCRYPT_KEYPAIR、ENCRYPT_PUBLIC_KEY）。
3. 自动生成临时 security.php（重启失效，不建议生产环境）。
   详见 LimeSurvey 数据加密文档。

反向代理配置

部署在反向代理后需调整代理设置：

• Apache：添加 ProxyPreserveHost On。
• Nginx：设置 fastcgi_param HTTP_HOST 域名;。
• Traefik：子路径部署（如 /limesurvey）需设置 BASE_URL=/limesurvey 并配置中间件：

  "traefik.http.routers.limesurvey.rule=PathPrefix(`/limesurvey`)",
  "traefik.http.middlewares.strip-limesurvey.stripprefix.prefixes=/limesurvey"
  

环境变量说明

常用配置变量：

使用 docker-compose 部署

快速启动完整环境：

# 克隆仓库后进入目录
docker-compose up -d
# 访问前端：[***] 管理后台：[***] 升级指南
### FPM 镜像升级
1. 停止容器：`docker-compose down`。  
2. 删除应用卷：`docker volume rm 卷名`（如 `docker-limesurvey_lime`）。  
3. 重启容器：`docker-compose up -d`（拉取新版本镜像）。

### 版本升级注意事项
- **5.x → 6.0**：基于 PHP 8.1，3.x 版本停止支持。  
- **4.x → 5.0**：运行用户改为 `www-data`（需调整目录权限），Apache 默认端口改为 8080。


## 已知问题
- **子路径代理问题**：反向代理子路径（如 `example.com/limesurvey`）时，管理后台可能显示异常。  
  **解决**：代理中显式设置 Host 头（如 Nginx 添加 `proxy_set_header Host $host;`）。