lycheeorg/lychee

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支持，无需外部依赖。最简单的启动命令：

bash
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关联数据库容器：

bash
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命令：

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

使用Docker Compose运行

修改https://github.com/LycheeOrg/Lychee-Docker/blob/master/docker-compose.yml%E4%B8%AD%E7%9A%84%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E4%BB%A5%E5%8C%B9%E9%85%8D%E6%95%B0%E6%8D%AE%E5%BA%93%E5%87%AD%E6%8D%AE%E3%80%82

为避免明文存储凭据，可创建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文件，将使用https://github.com/LycheeOrg/Lychee/blob/master/.env.example%EF%BC%8C%E5%85%B6%E4%B8%AD%E9%83%A8%E5%88%86Docker%E7%89%B9%E5%AE%9A%E5%8F%98%E9%87%8F%E9%BB%98%E8%AE%A4%E5%80%BC%E5%A6%82%E4%B8%8B%EF%BC%9A

高级配置

PHP与nginx自定义

默认配置中，nginx支持最大100MB文件上传（client_max_body_size 100M），PHP参数已按https://lycheeorg.github.io/docs/faq.html#i-cant-upload-large-photos%E4%BC%98%E5%8C%96%E3%80%82%E5%A6%82%E9%9C%80%E8%BF%9B%E4%B8%80%E6%AD%A5%E8%87%AA%E5%AE%9A%E4%B9%89%EF%BC%9A

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

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

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

1. 以https://github.com/LycheeOrg/Lychee-Docker/blob/master/default.conf%E4%B8%BA%E5%9F%BA%E7%A1%80
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上下文中被自动包含。