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 時遇到了本文未提到的問題，可以通過以下鏈接解決：

原創內容	坑位	作者	備注
https://github.com/LycheeOrg/Lychee	NA	https://github.com/LycheeOrg	Lychee 4 項目開發者
https://github.com/LycheeOrg/Lychee/issues/760	[5]	https://github.com/pa810p	感謝提問者！好的提問（不重復、描述清楚、及時回復）也是優秀的產出！
https://www.cnblogs.com/php48/p/8763550.html	NA	https://home.cnblogs.com/u/php48/	雖然沒有解決坑位，但在排查 nginx.conf 時，提供了非常大的幫助。
https://ywnz.com/linuxysjk/4467.html	[7]	戴均益
https://blog.csdn.net/hao_ds/article/details/85319377	[7]	https://blog.csdn.net/hao_ds
https://stackoverflow.com/a/19302688	[3]	https://stackoverflow.com/users/470749/ryan
https://stackoverflow.com/a/38814605	[1]	https://stackoverflow.com/users/6688048/shirinkin-denis
https://post.smzdm.com/p/a3g7vmlr/	[6]	https://zhiyou.smzdm.com/member/6001038624/
https://blog.csdn.net/ichen820/article/details/117520360	[4]	https://blog.csdn.net/ichen820
https://github.com/LycheeOrg/Lychee/issues/866 https://lycheeorg.github.io/docs/faq.html#why-dont-my-videos-have-thumbnails			共同解決了視頻縮略圖問題