FreeNAS / TrueNAS / FreeBSD 安装 Lychee 荔枝相册保姆级教程，一站式备份、管理、浏览照片（可能是全网首发）
可能是全网第一篇 FreeNAS / TureNAS / FreeBSD 安装Lychee 荔枝相册的教程，保姆级手把手教你安装！
Lychee 荔枝相册介绍
官网：https://lycheeorg.github.io/
Lychee 荔枝相册是一个开源的、可以安装在任何系统中（只要这个系统可以安装 mysql、nginx 或 apache、php）的相册管理软件，瀑布流式的前端布局非常漂亮，运行速度也是相当之快，还拥有账户管理、照片共享、EXIF 信息查看、敏感相册、密码保护、照片地理位置、标签管理等功能，也支持视频格式，可以作为群晖 Photos 的代餐。
把 Lychee 安装在 NAS 中，配合其他备份软件，可以直接代替各大手机厂商提供的收费的照片云备份功能，而且数据还都在自己的 NAS 中，这无疑也是更安全的。
Tips: 写完后才发现 danb35 写过一键安装的脚本，无独有偶，当初我花了两天好不容易手动安装上的 plex（这篇文章还在鸽着呢......），这位大神也写过脚本。你可以直接访问 https://github.com/danb35/freenas-iocage-lychee 来尝试使用其脚本一键安装。
前言
1. 本文写的比较啰嗦，毕竟是自己一点点摸索爬坑过来的，把过程中遇到的问题、思考过程都写了进来。需要特别注意的点我都会加粗提示，其他文字可以一带而过。事实上，顺利的话，整体安装时间不超过10分钟。请放心食用。
2. 如果你不是很在意过程，可以查看这篇纯操作版本：，除了新建 Jail、挂载目录等操作以外，其他操作一气呵成完成安装。
一、创建 Jail，创建并挂载数据库目录
1. 创建数据库目录
我们需要创建两个目录，一个用来存放 Lychee 的数据库文件，一个用来存放照片，如果你之前在 NAS 中已经存储了不少照片，那么可以直接使用之前存储的路径。
点击存储、池、添加数据集：
输入数据集名称，其他均保持默认，点击保存即可：
在新建的数据集上，点击编辑权限：
把用户和群组都改为 mysql 用户，并且勾选 Apply User 和 Apply Group，点击保存：
（如果你的系统里还没有 mysql 用户，去账户、用户中添加即可）
然后再在这个数据集上创建子数据集，命名为 lychee，同样授予 mysql 权限。
而存放照片的路径的创建，操作方法与上相同，如果你之前已经有了存放照片的数据集，则可以直接使用，不需要再创建。
需要注意的是，你需要保证 www 用户可以读写你存放照片的数据集。我的建议是直接和上图一样，把存放照片数据集的用户和群组都修改为 www。
2. 创建 Jail
请参考本博客 FreeNAS / TrueNAS 创建 Jails 及 Jails 初始优化教程 创建 Jail，注意要手动设置 IP 地址。
3. 挂载数据库目录
点击 Jail，点击停止，等待关机完成后，点击挂载点：
右上角点击动作、添加：
源处选择刚才我们创建的数据库的子数据集 lychee 的路径，目标处我们直接输入 /var/db/mysql
同样的方法，把存储照片的数据集挂载到 /usr/local/www/lychee/public/uploads/import 中。请记住这个路径，之后安装 Lychee 时请和这个路径保持一致。
这一步操作的原因如下：
-
Lychee 数据库的保存位置在：/var/db/mysql 中。我们把这个路径挂载到外部数据集，就可以做到即便删除 Jail，数据库也还在，方便备份、恢复、重装 Jail；
-
Lychee 照片保存位置在：/usr/local/www/public/uploads/big 中，但 Lychee 并不会自动扫描你路径中已有的照片。为了解决这个问题，Lychee 提供了导入功能，将照片放在 /usr/local/www/public/uploads/import 中，点击 “从服务器导入” 即可导入之前的照片。这个路径不是必须的，如果你想从其他地方导入也可以，只是需要多输入一步导入路径，而 import 目录为默认导入目录；
-
请务必注意：Lychee 会把上传或导入的照片原始文件重命名为乱码，而 Lychee 中则还会显示照片原文件名。关于这一点的考虑以及应对措施，请见本文最后的使用章节。
- 鉴于第一点已解决，这里解决方案为：
- 把 upload、dist 目录整体移动到外部目录中；
- 在 public 目录下，创建 upload、dist 软连接：ln -sfn /mnt/xxx/lychee/dist dist
- 直接把所有照片存在外部目录的 upload/import 内
- 重启 php、nginx 服务，点击从服务器导入，勾选 symbolic links ，等待完成即可。
- 在外部目录创建一个/db/mysql/lychee 路径，并挂载到 /var/db/mysql ，来解决数据库存在外部的问题。
- uploads 目录也可以通过这个方式解决，直接把外部存放照片的目录挂载到 /uploads/import 中，再点击导入即可。
这个方案同时解决了以下问题：
- 数据库、照片均存储在外部；
- 日后可以自动识别 import 中的新照片（目前已知手动点击导入，勾选 skip duplicates 即可，自动扫描的方案待探索）；
- 避免了 Lychee 会把照片重命名为乱码的问题，你的原照片仍然是以原文件名存放在 import 目录中。
这个方案存在的问题是：
- 由于是链接导入的方式，在 Lychee 中删除照片并不会实际删除照片本身，而只是删除掉链接、缩略图、以及数据库中的一些记录。
- 这个问题可以通过导入时不勾选 symbolic links，并且勾选 “删除原始图像” 解决。这样就是直接把原照片以乱码形式存储在了 Lychee 中。我个人认为，如果日后想使用 Lychee 来管理照片的话，就选择这种方案，毕竟你上传进去的照片始终都会乱码，不可能永远使用导入功能，那也太麻烦了。如果你只是想使用 Lychee 来作为照片浏览和展示，那么你可以不用管原始照片是否被删除了这回事，你想删除的时候，直接去删除原始照片即可，Lychee 中会自然的因为链接源丢失，看不到这张照片。
二、安装
1. 安装 nginx、mysql 数据库、ffmpeg、git
打开 Jail，打开 MobaXterm，远程登录至 Jail。
pkg install nginx ca_root_nss mariadb104-server ffmpeg git # 注：本文未配置 HTTPS，安装 ca_root_nss 是为日后上 HTTPS 做准备，你也可以不安装。
# 设置 nginx、mysql 开机启动
sysrc nginx_enable=yes
sysrc mysql_enable=yes
2. 安装 php
Lychee V4 要求 PHP 8.0 以上版本，且需要诸多扩展，详见官方 Wiki：https://lycheeorg.github.io/docs/#server-requirements 。鉴于 PHP 8.1 尚未支持部分扩展，我们选择 PHP 8.0 安装。
请注意此处有个巨坑，官方 Wiki 列出的扩展不全[1]，如果只安装这些扩展，会在后续遇到一连串难以解决的问题，我在这里花了两天的时间趟坑，才算是终于摸清楚所有需要安装的扩展。例如：
1. 官方 Wiki 并未要求 simplexml、dom、zlib 扩展，但若不安装，会导致 composer （后续会用到的一个程序）无法正常运行。
2. 未被列出的 session，会导致你反反复复的遇到 404、403 错误，而一般来说这俩错误我们只会怀疑自己的网页代理程序配置错了，于是不断的修改 nginx.conf，怎么改都无法解决问题。在这里我花了整整一天，最终确认是未安装 session 导致。
3. Wiki 虽然声称你在内置 sqlite3、mysql 等数据库中选择其一即可，但事实上 sqlite3 是必须安装的，否则主程序的安装就会失败；而如果你选择了 mysql，那么恭喜你，还有 mysqli、pdo_mysql 这两项未列出的扩展需要安装，否则你就会跟我一样遇到一个极其迷惑的问题：安装页面（共5页）永远停留在第 4 页，每当点击下一页，又会回到第 1 页。
pkg install php80 php80-bcmath php80-ctype php80-exif php80-fileinfo php80-gd php80-mbstring php80-openssl php80-pdo php80-tokenizer php80-xml php80-zip php80-pecl-imagick php80-phar php80-filter php80-zlib php80-simplexml php80-dom php80-session php80-sqlite3 php80-mysqli php80-pdo_mysql
# 设置 php 开机启动
sysrc php_fpm_enable=yes
3. 安装 composer
cd ~
php -r "copy('https://install.phpcomposer.com/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
mv composer.phar /usr/local/bin/composer
4. 获取 Lychee 文件
我真的万万没想到，获取一个开源项目文件，这么简单的一步也能有坑[2]。我大概花了几个小时的时间吧，一直在怀疑自己命令错了，还研究了很久 composer 官方文档，始终不解。
原来，是我惯性思维了，上来就从 release 中下载 zip 文件，然后解压，使用 composer 安装。一开始 composer 有报错信息，还是坑 1 导致的，补齐扩展后没有报错了，但就是进不去网页，甚至访问 index.php 是直接下载下来的。我甚至在怀疑 composer 最后的那一句 “74 packages you are using are looking for funding” 是在说我有74个包还没 “fund” 好，需要重新 “fund”，然后运行 “composer fund” 陷入漫长的等待......（事实上这句话是在说这些插件开通了捐赠通道，你可以去捐赠支持）
就在我百思不得其解的时候，无意间瞥见了我一直选择性忽略的两句报错：”./git path doesn't exist“、”./hook path doesn't exist“，我始终觉得这不是个事儿，仔细一琢磨吧，害！我应该用 git clone 克隆下来整个仓库源码，而不是使用 release 中的压缩包！[2]
cd /usr/local/www/lychee
git clone https://hub.fastgit.xyz/LycheeOrg/Lychee.git tmp
# 注1：git clone 我使用了日本源，国内直连速度较快，若你访问 github 无阻，可直接使用原版源：https://github.com/LycheeOrg/Lychee.git
# 注2：以上网站目录可以自己修改，一般来说是放在 /usr/local/www/下面。请尽量不要放在 nginx 根目录下。
mv -f tmp/* .
mv -f tmp/.* .
mv -f tmp/public/* public/
mv -f tmp/public/.* public/
mv -f tmp/public/uploads/* public/uploads/
mv -f tmp/public/uploads/import/* public/uploads/import/
rm -R tmp
5. 调整 nginx.conf
这也是坑巨多的一步，我差不多花了一下午的时间来解决。最开始，我完全信任并按照 Wiki 中给出的 nginx 配置模板来配置：https://lycheeorg.github.io/docs/installation.html#nginx ，稍微修改一些适合自己系统实际情况的选项，但无奈始终在 403、404、file not found、拒绝连接这四个报错页面中徘徊。
其中，有 session 扩展未安装的坑，填了这个坑以后还是会有这三个问题，于是我又完全按照自己的理解来写配置文件，仍然是在这四个报错页面中徘徊。期间不断用 /var/log/nginx 中的日志来排错，一点点对照自己的配置和官方的配置，一行一行控制变量的来改，最终确认了两个巨坑：
1. index 项必须指定。一开始我就很疑惑，官方配置文档中没有写 index 项，我还以为是什么新特性，可以不用写了，但事实证明还是必须的。[3]
2. DocumentRoot 变量须替换成实际的绝对路径。[4]
以下是我摸索出来的正确配置文件，里面注释较多，直接复制会出现乱码，如需直接复制，请看后面一份无注释版。
cd /usr/local/etc/nginx
cp nginx.conf nginx.conf.backup # 以免万一，备份一份默认配置文件
nano nginx.conf # 改动 server 即可，下面没列出的项目可以直接注释掉或删掉。你可以直接复制我的配置文件，但请注意含有注释的项目，可能需要修改。
server {
listen 80; # 端口可以自己修改
server_name localhost; # 如果你有域名的话，可以改成你的域名
root /usr/local/www/lychee/public/;
index index.php;
if (!-e $request_filename) # 必须开启 rewrite，否则会遇到 找不到 ../public/install 的报错，再次陷入 403、404 循环。[5]
{
rewrite ^/(.*)$ /index.php?/$1 last;
break;
}
location = /index.php {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
fastcgi_param HTTP_PROXY ""; # 建议开启，用于缓解 https://httpoxy.org/ 漏洞
fastcgi_pass 127.0.0.1:9000; # 这一项默认为此，若你需要修改为 ../php-fpm.sock，则请在 php 的 www.conf 中修改对应配置。
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /usr/local/www/lychee/public$fastcgi_script_name; # 请务必将此处绝对路径替换为第四步你 clone 到的路径，如果你使用了跟我一样的 clone 命令，这里可以不用修改。
fastcgi_param PHP_VALUE "post_max_size=10240M # 以下这些限制请根据自己服务器的实际情况修改
max_execution_time=200
upload_max_filesize=10240M
memory_limit=1024M";
fastcgi_param PATH /usr/local/bin:/usr/bin:/bin;
include fastcgi_params;
}
error_log /var/log/nginx/lychee.error.log;
access_log /var/log/nginx/lychee.access.log;
rewrite ^/(.+)/$ /$1 permanent;
location ~ [^/]\.php(/|$) {
return 403;
}
}
无注释版：
server {
listen 80;
server_name localhost;
root /usr/local/www/lychee/public/;
index index.php;
if (!-e $request_filename)
{
rewrite ^/(.*)$ /index.php?/$1 last;
break;
}
location = /index.php {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
fastcgi_param HTTP_PROXY "";
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /usr/local/www/lychee/public$fastcgi_script_name;
fastcgi_param PHP_VALUE "post_max_size=10240M
max_execution_time=200
upload_max_filesize=10240M
memory_limit=1024M";
fastcgi_param PATH /usr/local/bin:/usr/bin:/bin;
include fastcgi_params;
}
error_log /var/log/nginx/lychee.error.log;
access_log /var/log/nginx/lychee.access.log;
rewrite ^/(.+)/$ /$1 permanent;
location ~ [^/]\.php(/|$) {
return 403;
}
}
6. 使用 composer 安装依赖文件
这里的坑在第四点讲过了，不废话，开始安装。
cd /usr/local/www/lychee # 同上，请确保进入你 clone 到的路径
composer install --no-dev # 你也可以不选择 --no-dev 参数——如果你打算二次开发的话。这样还需要补充一些 php 扩展，相信需要二次开发的你不需要我多说了。
# 上面这一步会等待较久，全部结束后应没有红色报错（error）信息。
7. 调整 php 配置文件
这一步算是最神清气爽的一步，经历了 nginx.conf 折磨的几小时后，php 的配置文件居然没有坑！
我们需要修改两个文件，均在下方列出：
cd /usr/local/etc
cp php.ini-production php.ini # 复制一份生产环境的配置文件
nano php.ini # 推荐使用 MobaXterm 或其他带有文件管理的远程 SSH 软件来修改，因为这个文件实在是太长了。
# 取消以下条目开头的 ; 注释，并修改数值如下：
cgi.fix_pathinfo=1
date.timezone ="Asia/Shanghai"
memory_limit = 1024M # 根据自己服务器实际情况修改
post_max_size = 10240M # 同上
upload_max_filesize = 10240M # 同上
cd /usr/local/etc/php-fpm.d
nano www.conf
# 取消注释：
clear_env = no
# 可选：据说使用 xxx.sock 来监听，比默认的 9000 端口监听速度快。如果你需要的话，可以按如下修改。
listen = /tmp/php-fpm.sock # 请注意，这里修改以后，还需要修改第五步 nginx.conf 中的 fastcgi_pass 为 unix:/tmp/php-fpm.sock
listen.mode=0666 # 用于确保生成的 sock 文件可被 www 用户访问，否则会导致整个 php 服务失效。
8. 设置权限
官方给出的建议很谨慎：https://lycheeorg.github.io/docs/installation.html#directory-permissions ，只建议修改个别目录，但我觉得对于自己的私人服务器，直接把整个目录所有者变更为 www 即可。www 用户是 nginx、php-fpm 主进程的执行用户。如果你觉得不安全，也可以按照上述链接手动修改个别目录的权限。
cd /usr/local/www # 确保进入你 clone 到的路径的上一层
chown -R www:www lychee
9. 设置数据库
注意记住自己创建的数据库名、用户名即可。要注意的是：
1. 需要修改 sock 文件路径，否则会初始化失败，这个我目前也没研究原因，初步推测是路径权限问题。[6]
2. 数据库密码按照网上的教程来说是要设置的，但我没有遇到，系统提示我已经给 root 用户设置过密码了，无需再设置。虽然我认为这里的密码理应不是 FreeBSD 系统的 root 账号密码，而是数据库管理员的密码，但经过后续的验证确认，还真就是同一个密码。这个无碍，如果你遇到了需要设置密码，设置，然后记住即可，后面会用到。
nano /usr/local/etc/mysql/my.cnf
socket = /tmp/mysql.sock
# 修改完成后保存退出
service mysql-server start
mysql_secure_installation --socket=/tmp/mysql.sock
# 提示全部输 y ，一定要记住自己设置的密码
mysql -u root
CREATE DATABASE lychee; #可以自己修改数据库名，只要自己能记住就行
CREATE USER 'lychee_admin'@'localhost' IDENTIFIED BY '改成刚刚设置的密码';
GRANT ALL ON lychee.* TO 'lychee_admin'@'localhost'; # 这一步是必须的，否则后面的安装引导页面会无法跳转到第五页。[7]
FLUSH PRIVILEGES;
exit
10. 安装 Lychee，配置时区、语言、防泄漏信息等环境
cd /usr/local/www/lychee # 确保进入你 clone 到的路径
cp .env.example .env # 复制一份环境配置文件
nano .env # 修改下面列出的项目即可
# DB_OLD_LYCHEE_PREFIX= # 把这一行注释掉
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=lychee # 务必注意去掉这里的注释，否则又会遇到坑[7]
DB_USERNAME=lychee_admin # 你刚才设置的用户名是啥，这里就填啥
DB_PASSWORD=11111111111 # 你刚才设置的密码是啥，这里就填啥
TIMEZONE=Asia/Shanghai
# 修改完成后保存退出
cd config
nano app.php # 修改下面列出的项目即可
'timezone' => env('TIMEZONE', 'Asia/Shanghai'),
'locale' => 'zh-CN',
# 拉到最后，中括号内的逗号后，另起一行，然后把下面的配置粘贴进去
/*
| When an exception is uncaught and the APP_DEBUG environment variable
| is true, the debug page will show all environment variables and their
| contents. In some cases you may want to obscure certain variables. You
| may do this by updating the debug_blacklist option in your config/app>
| configuration file.
| Some variables are available in both the environment variables and the
| server / request data. Therefore, you may need to blacklist them for >
| $_ENV and $_SERVER.
*/
'debug_blacklist' => [
'_ENV' => [
'APP_KEY',
'DB_PASSWORD',
],
'_SERVER' => [
'APP_KEY',
'DB_PASSWORD',
],
'_POST' => [
'password',
],
],
# 修改完成后保存退出
cd ..
php artisan key:generate
# 为确保权限无误。最好在这时候检查一遍权限，应当所有文件均为 www 用户和群组拥有。
ll -a
11. 安装引导，修复视频缩略图不显示，速度优化
避开了以上 7 个坑以后，这里你应当可以顺利进入安装引导界面了。在此之前让我们启动 nginx 和 php-fpm 服务：
service php-fpm start
service nginx start
# 若你之前已经启动以上服务（按理说不应该启动），则在这里重启
service php-fpm restart
service nginx restart
若在启动服务时有报错信息，则请按照提示检查自己的配置文件，以及查看 /var/log/nginx 中的报错日志来排查问题。启动成功后，打开浏览器访问 http://你的 Jail 的 IP 地址/ 即可进入引导页面。按照页面提示一步步完成校验、安装即可。
如果你在安装完毕后发现视频缩略图无法正常显示，那么需要按照本博客的这篇文章：https://www.cnblogs.com/dabai0030/articles/16067595.html 来修复。
安装完毕后，如果你想进一步提高 Lychee 的响应速度，可调整以下几项：
1. 让 php-fpm 程序使用 sock 文件来监听，而非本地端口。同时修改 www.conf、nginx.conf 中相关参数即可，上文已多次提及。
2. 你还可以适当提高 php 和 nginx 允许使用的内存大小，上文也有提及。
3. 在你确保所有配置均已完毕，无需修改后，可以在 Lychee 项目路径下，使用如下命令加速：
php artisan config:cache
请一定一定要在所有配置都确认配好，满足了自己所有需求，不再折腾以后，再执行，不要在部署过程中执行。这里加速的原理是，把所有相关的配置文件全部都读取出来，然后打包到一个文件里，系统读取时不再去各个地方读取各个文件，而只读取这一个文件，以此来加速程序的加载。
因此，如果你执行了这条命令以后又修改了配置，那么这个配置是不会生效的。当然如果你还是这样做了，可以通过重建缓存来处理：
php artisan config:clear
三、使用
待补充，我决定全部重新安装一遍，确保教程无问题后，补充截图，然后再来写使用章节。
四、一些仍待填的坑
期间再次补充安装 php80-xmlwriter 扩展（不确定是否必须）
四、参考资料
感谢 Lychee 的作者以及所有贡献者们。我已根据本文中因官方 Wiki 有误或不完整导致的坑，修改 Wiki 并提交了 pull request。
感谢以下作者的原创内容，为我的此次趟坑之旅提供了无数次绝望中的希望，同样也希望阅读本文的你在安装 Lychee 时遇到了本文未提到的问题，可以通过以下链接解决：
|
原创内容 |
坑位 |
作者 |
备注 |
|
NA |
Lychee 4 项目开发者 |
||
|
[5] |
感谢提问者！好的提问（不重复、描述清楚、及时回复）也是优秀的产出！ |
||
|
NA |
虽然没有解决坑位，但在排查 nginx.conf 时，提供了非常大的帮助。 |
||
|
[7] |
戴均益 |
|
|
|
[7] |
|
||
|
[3] |
|
||
|
[1] |
|
||
|
[6] |
|
||
|
[4] |
|
||
|
https://github.com/LycheeOrg/Lychee/issues/866 https://lycheeorg.github.io/docs/faq.html#why-dont-my-videos-have-thumbnails |
|
|
共同解决了视频缩略图问题 |
