fan-random

命令

fan-random 随机壁纸 API 部署运维

补充说明

本教程介绍 fan-random（随机壁纸 API）通过一键脚本安装为 systemd 服务、Docker 部署，以及日常运维、添加图片、内置 CLI 管理命令的完整流程。fan-random 仅依赖 Node.js 内置模块，零第三方运行时依赖。

项目：fan-random｜随机壁纸 API 仓库：https://github.com/meimolihan/fan-random 镜像：https://hub.docker.com/r/mobufan/fan-random

API 端点

端点	说明
`/`	自适应（自动识别手机/电脑）
`/pc`	pc 桌面端（随机横屏壁纸）
`/mp`	mp 移动端（随机竖屏壁纸）
`?type=json`	返回 JSON（含图片 URL、类型、总数）

# 直接获取随机图片（返回完整图片内容，无需跟随跳转）
curl http://your-domain:8588/pc

# 获取 JSON 格式
curl "http://your-domain:8588/pc?type=json"
# {"url":"/pc/pc-117.webp","type":"pc","count":418}

安装与卸载（systemd 一键脚本）

安装 / 升级

# 默认端口 8588，程序目录 /var/lib/fan-random，壁纸目录 {程序目录}/public/{pc,mp}
bash scripts/install.sh

# 远程一键安装（国内网络可加 FAN_RANDOM_REPO=https://ghfast.top/https://github.com/meimolihan/fan-random.git）
bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-random/main/scripts/install.sh)" -p 8588 -y

# 自定义安装目录、端口、pc/mp 壁纸目录，免交互
bash scripts/install.sh -d /opt/fan-random -p 9000 -pc /data/wallpapers/pc -mp /data/wallpapers/mp -y

安装脚本可重复执行，升级等同于重新安装（覆盖程序并重启服务，图片目录保留）。默认优先从 GitHub Releases 下载预编译二进制（无需 Node.js/git）；本地存在源码仓库时自动改用源码编译。

一键脚本参数

参数	说明
`-d, --install-dir`	安装目录（默认 `/var/lib/fan-random`；旧别名 `-a/--appdir`）
`-p, --port`	监听端口（默认 8588）
`-pc, --pc-dir`	pc 桌面端壁纸目录（默认 `{APP_DIR}/public/pc`）
`-mp, --mp-dir`	mp 移动端壁纸目录（默认 `{APP_DIR}/public/mp`）
`-s, --src`	本地源码仓库路径（默认自动探测脚本上级目录）
`-b, --binary`	强制使用预编译二进制（无需 Node.js/git）
`-y, --yes`	免交互，未指定项全部使用默认值

卸载命令

bash scripts/uninstall.sh -y --purge

# 远程一键卸载
bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-random/main/scripts/uninstall.sh)" -y --purge

卸载默认保留壁纸图片目录，--purge 才会一并删除。

Docker 部署

Compose 一键部署（推荐）

bash <(curl -sL gitee.com/meimolihan/cmdbox/raw/master/sh/dc_inst_fan-random.sh)

交互式输入部署目录（默认 /vol1/1000/compose/fan-random）与映射端口（默认 8588）
脚本自动检查并安装 Docker / Docker Compose、开放防火墙端口、清理旧容器、生成 docker-compose.yml 并启动容器

传参部署（先目录后端口，顺序可互换）

bash <(curl -sL gitee.com/meimolihan/cmdbox/raw/master/sh/dc_inst_fan-random.sh) /vol1/1000/compose/fan-random 8588

使用项目自带 Compose

git clone https://github.com/meimolihan/fan-random.git
cd fan-random
docker compose pull && docker compose up -d    # 或本地构建: docker compose build && docker compose up -d

Docker 手动运行

docker run -d --name fan-random --restart always \
  -p 8588:3000 \
  -e TZ=Asia/Shanghai \
  mobufan/fan-random:latest

自定义壁纸目录（宿主机直接管理图片，无需重建镜像）

docker run -d --name fan-random --restart always \
  -p 8588:3000 \
  -e TZ=Asia/Shanghai \
  -v /path/to/your/pc:/fan-random/public/pc \
  -v /path/to/your/mp:/fan-random/public/mp \
  -v /path/to/your/photos:/fan-random/photos \
  mobufan/fan-random:latest

内置 CLI 管理命令

安装后可直接使用 fan-random 命令管理服务（二进制或源码安装均内置）：

命令	说明
`fan-random status`	查看运行方式（systemd / Docker / 直接运行）、PID、端口、访问地址、图片统计、运行时长、内存与路径
`fan-random start` / `stop` / `restart`	启动 / 停止 / 重启 systemd 服务
`fan-random uninstall [-y] [--purge\|--keep-data]`	停止并移除服务/容器/进程，删除程序与安装记录，可选删除图片目录
`fan-random version`	查看版本号
`fan-random help`	查看帮助

fan-random status          # 查看服务状态（含端口、图片数量与访问地址）
sudo fan-random restart    # 重启服务
sudo fan-random uninstall -y --purge   # 免确认卸载并删除图片目录

日常管理命令

操作	命令
启动	`systemctl start fan-random`
关闭	`systemctl stop fan-random`
重启	`systemctl restart fan-random`
状态	`systemctl status fan-random`
查看实时日志	`journalctl -u fan-random -f`
查看最近 30 行日志	`journalctl -u fan-random -n 30 --no-pager`
开启开机自启	`systemctl enable fan-random`（安装时默认已开启）
关闭开机自启	`systemctl disable fan-random`
端口放行	`firewall-cmd --permanent --add-port=8588/tcp && firewall-cmd --reload`（firewalld）
Docker 重启	`docker restart fan-random`

添加 / 替换壁纸

所有部署方式均支持运行时动态扫描：新增/删除图片后目录时间戳变化，服务自动重扫缓存，无需重启服务。

# pc 桌面端（横屏）壁纸
public/pc/my-photo-1.webp

# mp 移动端（竖屏）壁纸
public/mp/my-photo-3.png

批量分类：将原始图片放入 photos/，运行分类脚本自动识别横/竖屏并转换为 WebP 到对应目录

bash classify.sh         # 基于 ffmpeg（缺依赖时自动询问安装）
python3 classify.py      # 基于 Pillow（需 pip install Pillow）

目录说明

默认数据目录：/var/lib/fan-random（含 docker-server.js、public/pc、public/mp）
安装记录：/etc/fan-random.conf（APP_DIR / PORT / PC_DIR / MP_DIR / INSTALL_METHOD）
服务单元：/etc/systemd/system/fan-random.service
内置命令：/usr/local/bin/fan-random
Compose 部署壁纸目录：<部署目录>/public/pc、<部署目录>/public/mp，原始图片 <部署目录>/photos