Lychee Docker镜像文档

镜像概述

本镜像包含Lychee照片管理系统、nginx和PHP-FPM，其配置（PHP、nginx等）遵循Lychee官方推荐标准。支持amd64、arm64/aarch64、armv6、armv7多种架构，适用于快速搭建个人或家庭照片库，支持多种数据库后端。

镜像内容

可用标签

• latest：最新Lychee发布版
• v[NUMBER]：Lychee稳定版本标签（如v4.7.0）
• nightly（别名dev）：当前主分支标签（Lychee主分支保持稳定，通常可安全使用）
• devtools：包含开发依赖的主分支版本
• testing：用于测试新分支和拉取请求的标签，主要供LycheeOrg内部使用
• alpha：当前alpha分支标签（包含未经过同行评审的前沿变更）
• alpha-devtools：包含开发依赖的alpha分支版本

部署指南

快速启动

若使用内置SQLite支持，无需外部依赖。最简单的启动命令：

docker run -p 80 lycheeorg/lychee:dev

容器将在本地随机端口启动Lychee服务。更多运行选项见下文。

前提条件

若使用MySQL、MariaDB或PostgreSQL，需提前准备外部数据库服务（可通过Docker容器部署，例如在docker-compose.yml中定义）：

1. 创建数据库、用户名及密码
2. 通过以下方式配置环境变量（数据库凭据、语言等）：
   • 在docker run或docker-compose中传递环境变量
   • 创建.env文件并挂载至容器/conf/.env路径
   • 在启动命令中传递-e DB_CONNECTION=，首次访问时通过浏览器完成安装向导

使用Docker运行

确保已连接至数据库容器所在网络！

以下示例使用--net连接数据库所在网络，--link关联数据库容器：

docker run -d \
--name=lychee \
-v /宿主机路径/lychee/conf:/conf \
-v /宿主机路径/lychee/uploads:/uploads \
-v /宿主机路径/lychee/sym:/sym \
-e PUID=1000 \
-e PGID=1000 \
-e PHP_TZ=Asia/Shanghai \
-e TIMEZONE=Asia/Shanghai \
-e DB_CONNECTION=mysql \
-e DB_HOST=mariadb \
-e DB_PORT=3306 \
-e DB_DATABASE=lychee \
-e DB_USERNAME=user \
-e DB_PASSWORD=password \
-p 90:80 \
--net network_name \
--link db_name \
lycheeorg/lychee

注意：若使用MySQL数据库，需确保启用mysql_native_password认证插件。可在启动MySQL时添加--default-authentication-plugin=mysql_native_password选项，或执行以下SQL命令：

alter user 'lychee' identified with mysql_native_password by '<你的密码>';

使用Docker Compose运行

修改示例配置文件中的环境变量以匹配数据库凭据。

为避免明文存储凭据，可创建db_secrets.env文件，并通过env_file指令引用（详见Docker Compose文档）。

首次运行创建管理员账户

若设置ADMIN_USER和ADMIN_PASSWORD（或ADMIN_PASSWORD_FILE）环境变量，首次运行时将自动创建管理员账户。未设置时，首次加载Lychee会在浏览器中提示创建管理员。

Docker密钥支持

除通过环境变量传递敏感信息外，可在部分环境变量后添加_FILE后缀，使初始化脚本从容器内文件加载值（适用于Docker Secrets，文件路径通常为/run/secrets/<secret_name>）。若同时设置原变量和_FILE变量（如DB_PASSWORD和DB_PASSWORD_FILE），将优先使用原变量。

支持的_FILE变量：

• DB_PASSWORD_FILE
• REDIS_PASSWORD_FILE
• MAIL_PASSWORD_FILE
• ADMIN_PASSWORD_FILE

可用环境变量及默认值

若未提供环境变量或.env文件，将使用示例.env文件，其中部分Docker特定变量默认值如下：

高级配置

PHP与nginx自定义

默认配置中，nginx支持最大100MB文件上传（client_max_body_size 100M），PHP参数已按Lychee FAQ推荐优化。如需进一步自定义：

方法1：挂载自定义php.ini

将自定义php.ini挂载至/etc/php/8.2/fpm/php.ini，但此方式会覆盖所有PHP参数，且PHP版本更新时需重新适配。

方法2：通过nginx配置自定义PHP参数（推荐）

1. 以默认配置文件为基础
2. 找到以fastcgi_param PHP_VALUE [...]开头的行
3. 添加新行设置参数（如upload_max_filesize = 200M）
4. 调整其他参数（如client_max_body_size）
5. 将自定义配置挂载至容器/etc/nginx/nginx.conf

如需添加（非修改）nginx指令，可将文件挂载至/etc/nginx/conf.d/，这些文件会在http上下文中被自动包含。