项目完整名称为：Filesite/Machete，为求简单下文都以machete代替。
本文目录如下：
1）相册简介
- Filesite/Machete家庭相册系统有哪些特点？
- 用machete家庭相册系统管理我的照片安全吗？
- 相册支持哪些文件类型？
- 怎么升级machete家庭相册代码？
- 系统配置文件在哪里？
- 根目录下的README.md是必须的吗？
2）UI自定义
- 增加照片、修改UI配置后刷新网页怎么看不到最新内容？
- 怎么修改网站简介信息？
- 怎么修改网站标题？
- 怎么修改底部的版权信息？
- 怎么关闭网页底部的二维码？
- 怎么修改浏览器地址栏左侧的小图标？
- 怎么设置一级目录排序？
- 怎么对照片、视频、音乐文件进行排序？
- 怎么设置每页照片、视频、音乐文件数量？
- 怎么设置菜单栏不显示年、月分类？
3）图片控制
4）外网使用相关
5）安全相关
6）性能和其它
- 点了刷新图标怎么等了快1分钟底部扫描进度条还没动静？
- 我的设备cpu性能较差，缩略图显示有点慢且cpu占用较高怎么解决？
- 在启用Imagick扩展后，CPU占用过高或者大图片缩略图无法生成怎么解决？
- 更多问题如何联系？
以下为machete家庭相册的几个与众不同的地方：
- 以你的照片目录为数据源、所见即所得，保留你的照片管理习惯
- 开放源代码，源码公开且免费使用
- 无数据库非常轻量、毫秒级响应
- 点击图片放大浏览时默认使用原图，适合大屏幕欣赏高清图片
- 支持背景音乐播放
- 支持单个目录下所有图片自动循环播放
- 支持单个目录下所有视频自动循环播放
- 支持白天/夜晚两种浏览模式
请放心使用machete家庭相册系统来把本地图片目录转化为一个网站，只要你遵循我们推荐的方式安装部署，它是绝对安全的！
理由如下：
- machete是开源项目，代码公开，接受任何人/机构的安全检测；
- 推荐使用docker安装部署machete，docker的安全机制很完善；
- 只给runtime/目录写入权限，其它文件和目录只读；
Filesite/machete是开放源代码的，它托管在以下几个git网站：
并遵循MIT License，任何个人或公司，只要在保留来源申明的情况下，都可以基于它根据需要做修改后免费使用。
另外，推荐使用docker来安装部署machete家庭相册， 这样基于docker提供的安全沙箱环境，最大程度地保护你的电脑、服务器不受machete程序影响。
最后，machete程序只有临时文件存放目录runtime/需要开放写入权限，其它文件和目录都只需开放“只读”权限即可， 所以你在使用docker为machete配置volume或者本地映射目录时，相册目录只开放只读权限给docker容器， 由此可以进一步确保你的照片目录不会被machete程序修改/删除。
虽然machete自称相册，但实际它除了支持常见的图片之外，还支持几种视频格式，以及一种音乐文件格式。
以下是machete相册支持的文件格式：
| 后缀 | 类型 |
|---|---|
| .jpg | 图片 |
| .png | 图片 |
| .webp | 图片 |
| .gif | 图片 |
| .ico | 图标 |
| .mp4 | 视频 |
| .mov | 视频 |
| .m3u8 | 视频 |
| .ts | 视频 |
| .mp3 | 音乐 |
其中m3u8和ts是配合使用的，详情请搜索苹果的m3u8标准。
执行容器命令即可：
docker exec -it machete_album /var/www/machete/bin/upgrade.sh
说明： 其中容器名称machete_album请更换为你所启动的machete容器名字。
还可以先docker exec进入容器的命令行，再执行：upgrade.sh：
docker exec -it machete_album /bin/sh
upgrade_machete
- 全局配置文件：conf/app.php
- 自定义配置文件：runtime/custom_config.json
系统默认从全局配置文件里读取数据，如果有自定义配置，则优先使用自定义配置文件中的数据。
推荐使用自定义配置文件，以免系统升级后配置被覆盖。
如果是使用docker安装的machete，推荐把runtime/目录映射到本地的一个数据缓存目录，这样可以避免容器删除导致缓存的配置文件、目录封面图等信息丢失。
是的。
因为machete的实现机制，以及filesite.io的标准，相册根目录下的README.md是必须的，它是用来放你的相册的简介。
如果你还没想好怎么介绍你的相册，README.md文件内容可以留空。
machete相册是有一段时间的数据缓存的，所以只要内容或者配置有改变，需要点击网页右上角的“刷新”图标，清空缓存才能看到最新内容。
如果你部署到外网了，网页右上角看不到“刷新”图标，是因为你还没有把本地外网ip加入管理权限的ip白名单。
具体配置方法，参考：外网访问怎么设置允许当前IP访问拥有刷新、设置封面等管理权限？
请修改图片根目录下的README.md文件内容（如果你安装的是老版本，看不到这个文件，请手动创建），它是markdown格式的内容。
保存后，点网页右上角“刷新”图标，清空缓存查看效果。
网站标题显示在网页左上角，以及浏览器tab栏上，系统默认的标题是“家庭相册”或者“Filesite/Machete”。
请确保根目录下README.md存在的情况下，在图片根目录下创建文件README_title.txt，用一行文字来设置，示例如下：
我的相册
请确保根目录下README.md存在的情况下，在图片根目录下创建文件README_copyright.txt，内容参考下面示例代码：
<span>©2022 - 2024</span>
by <a href="https://filesite.io/" target="_blank">FileSite.io</a>
<br>
执行耗时: {page_time_cost} ms
在runtime/custom_config.json中增加以下配置：
"showQRImageInFooter": false
请创建自己的icon文件，命名为favicon.ico，把它复制到你的图片根目录；
以容器目录为例：
/var/www/machete/www/girls/favico.ico
在相册根目录下，确保README.md存在的情况下，创建README_sort.txt文件来配置根目录下的一级子目录排序，内容为子目录名称，格式为一行一个。
示例：
我的照片
我的视频
我的音乐
在runtime/custom_config.json中增加以下配置：
"sortFilesByName": true,
"sortOrderOfFiles": "asc"
其中sortFilesByName设置为true，打开文件按名称排序， sortOrderOfFiles则设定排序方式，asc顺序，desc倒序。
除此之外，还可以在照片目录下增加排序文件：sort.txt， 内容为当前目录下的文件名，格式一行一个，示例：
2_20240406223804.jpg
1_20240406223752.jpg
3_20240406223809.jpg
如果配置了此排序文件，且sortFilesByName为false关闭状态，则系统会按照排序文件中的文件名从上到下排序。
在自定义配置：runtime/custom_config.json里增加以下配置：
"default_page_size": 50
从0.4.0版本开始，filesite/machete相册支持按年、月分类所有图片、视频、音乐文件。
默认按年、月分类菜单是显示的，如需关闭，在自定义配置：runtime/custom_config.json里增加以下配置：
"showYearMonthMenus": false
在自定义配置：runtime/custom_config.json里增加以下配置：
"slide_show_timeout": 10
单位：秒。
系统配置enableSmallImage默认为true打开的，在自定义配置文件中，加入以下配置保存即可关闭所有缩略图功能：
"enableSmallImage": false
从v0.4.4版本开始，PC下支持键盘控制，以下是快捷键：
| 快捷键 | 功能 |
|---|---|
| 上下左右方向键 | 控制元素焦点 |
| Enter回车键 | 进入对应目录，或者开始浏览图片 |
| + | 放大图片 |
| - | 缩小图片 |
| o | 查看1比1原图 |
| f | 切换全屏模式 |
| p | 开始自动播放 |
| s | 停止自动播放 |
| Esc退出键 | 退出图片浏览 |
machete家庭相册默认为局域网使用，配置enableSmallImageForWan开启查看大图显示缩略图是关闭的， 如果你的照片文件大小很大，那么在外网打开可能会很慢。
解决办法，为外网点击图片浏览大图开启缩略图功能， 在自定义配置：runtime/custom_config.json里增加以下配置：
"enableSmallImageForWan": true
在自定义配置：runtime/custom_config.json里增加以下配置：
"adminWhiteIps": [
"你的外网ip地址"
]
可能存在以下几种原因：
- 你获取到的ip并不是你本地真实的外网ip（请使用ip138.com查看本地外网ip）
- 你设置了ipv4的地址，但是你实际访问用的是ipv6的地址，请把v4和v6的地址同时配置好
- 如果你在docker容器之上加了nginx或其它web服务器做反向代理，没有把用户的真实ip传给docker容器
以nginx反向代理为例，请在nginx的反向代理配置中设置转发用户ip地址：
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
以腾讯云cdn为例，需要增加下面 3 个规则：
- 针对静态文件缓存 30 天，文件类型：jpg;jpeg;png;svg;mp4;mov;ts;gif;webp;js;css
- 针对动态缩略图缓存 30 天，网址：/site/smallimg/
- 针对所有文件，不缓存（这个放最下面权重最低，也就是除了上面两类文件之外，其它都不缓存）
补充说明： 如果你的项目还存在其它静态资源需要缓存，可加入第一条规则中。
在自定义配置：runtime/custom_config.json里增加以下配置：
"adminForLanIps": true
系统支持这三类IP：
127.0.0.1
172.17.0.1,
192.168.xxx.xxx
在目录runtime/下创建配置文件：custom_password.json， 可复制conf/custom_password.json到runtime/目录下进行修改。
也可按下面示例创建：
{
"password_auth": {
"enable": true,
"default": "",
"allow": {
"目录1": "hello",
"目录2": "world"
}
}
}
配置说明：
- enable开关设置true则启用，默认为false关闭状态
- default选项配置全局默认密码，针对所有目录生效
- allow里配置单个目录的授权密码，如果default配置为空，则只有allow里所设置的目录需要密码授权访问
最新版相册源码设置了间隔 1 分钟检查一次是否需要扫描所有文件，所以在点击”刷新“图标之后，请耐心等待一会，就会看到底部进度条开始走动。
等到进度条进行到100%由蓝色变为绿色并在几秒之后消失自动刷新网页，就表示文件扫描任务已完成。
machete家庭相册在设计的时候考虑到在嵌入式设备中运行，缩略图功能可由用户的浏览器完成。
在自定义配置中把disableGenerateSmallImageInServer开关打开即可关闭服务器端生成缩略图，从而节省cpu消耗：
"disableGenerateSmallImageInServer": true
Imagick库的特性是生成的缩略图画质更高，但缺点是CPU占用比较高。
使用最新版filesite/machete的docker镜像，在自定义配置中加上开启配置项就能使用Imagick库来生成缩略图：
"enable_lib_imagick": true
请在启动容器的时候根据你的服务器配置，指定容器最大能使用的内存和cpu数量， 这将改善缩略图生成，避免因为过高的CPU占用导致php进程被docker杀死从而无法生成大图片的缩略图。
例如1G内存双核cpu服务器，允许最大使用512M内存，1.5个cpu核心：
docker run --name machete -p 1080:80 \
-m 512m \
--cpus="1.5" \
-v /d/图片目录/:/var/www/machete/www/girls/ \
-itd filesite/machete \
beauty
请打开官方网站查看底部QQ群和微信： FileSite.io