Docker Compose(服务器推荐)
定时下载与 WebUI 双容器,健康检查、自动重启、数据卷持久化。查看 →
npm 全局安装
个人电脑与轻量场景,一条命令安装,配合 tmux/nohup 常驻。查看 →
Termux(Android)
旧手机变身收集机,走 Termux 专用安装流程。查看 →
Docker Compose 部署#
1. 准备
git clone https://github.com/redtidev1918/PixivFlow.git
cd PixivFlow
cp docker-env.example .env编辑 .env:至少确认 TZ、存储路径(默认即可);需要代理的话填 HTTP_PROXY / ALL_PROXY。
构建前置(已闭环)主仓库只带
webui-frontend/.gitkeep 占位目录;Dockerfile 构建时若发现前端源码缺失,会自动浅克隆 pixivflow-webui 官方仓库并打包进镜像,无需手动克隆(要求构建机可访问 GitHub)。空气隔离环境可用 docker compose build --build-arg SKIP_WEBUI_BUILD=true 跳过前端、产出仅含 API 的镜像。2. 准备凭据
容器内无法交互式登录(PIXIV_SKIP_AUTO_LOGIN=true)。两条路任选:
- 推荐:宿主机上
npm install -g pixivflow && pixivflow login,然后把生成的pixiv.refreshToken填进config/standalone.config.json(容器只读挂载该目录,宿主机编辑即可); - 或在
.env里设置PIXIV_REFRESH_TOKEN=...(环境变量优先级高于 JSON)。
3. 启动
docker compose up -d pixivflow # 定时下载服务
docker compose up -d pixivflow-webui # WebUI(可选,端口 3000)
docker compose ps # 等待 healthy
docker compose logs -f pixivflow # 观察首次运行日志4. 双服务拓扑
| 服务 | 职责 | 说明 |
|---|---|---|
pixivflow | Cron 定时下载 | 禁用自动登录;PIXIV_SCHEDULER_ENABLED=true |
pixivflow-webui | Web 管理台 | 宿主机端口 WEBUI_PORT(默认 3000)→ 容器 3000;静态前端 + API |
两服务共享数据卷,互不冲突:
| 宿主机目录 | 容器内 | 内容 |
|---|---|---|
./config | /app/config(只读) | 配置文件 |
./data | /app/data | SQLite 数据库、日志 |
./downloads | /app/downloads | 下载成果 |
只读配置的影响
./config 以只读方式挂载:在 WebUI 界面里修改并保存配置不会回写到宿主机文件。要持久化配置改动,请在宿主机直接编辑 config/ 下的 JSON。环境变量参考
| 变量 | 默认 | 说明 |
|---|---|---|
TZ | Asia/Shanghai | 时区 |
PIXIV_REFRESH_TOKEN | — | 凭据注入(优先于配置 JSON) |
PIXIV_CLIENT_ID / PIXIV_CLIENT_SECRET | — | OAuth 凭据覆盖 |
PIXIV_DATABASE_PATH | /app/data/pixiv-downloader.db | 数据库路径(容器内) |
PIXIV_DOWNLOAD_DIR | /app/downloads | 下载目录 |
PIXIV_ILLUSTRATION_DIR / PIXIV_NOVEL_DIR | /app/downloads/... | 类型子目录 |
PIXIV_LOG_LEVEL | info | debug / info / warn / error |
PIXIV_SCHEDULER_ENABLED | true | 调度开关 |
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY(含小写) | — | 代理;宿主机代理用 host.docker.internal,Linux 可用 172.17.0.1 |
WEBUI_PORT | 3000 | WebUI 宿主机端口 |
PORT / HOST / STATIC_PATH | 3000 / 0.0.0.0 / /app/webui-frontend/dist | WebUI 容器内监听参数 |
5. 升级与回滚
git pull
docker compose build
docker compose up -d数据在卷里,重建容器不丢。升级前建议 pixivflow backup(或直接复制 data/)。
6. 故障排查
| 现象 | 检查点 |
|---|---|
| 容器反复重启 | docker compose logs pixivflow 看退出原因;常见为配置缺失或 refreshToken 无效 |
| WebUI 一直显示 unhealthy | start_period(40 秒)内属正常宽限。超期仍异常才需排查:curl localhost:3000/api/health 应返回 ok;后端已注册 /health 别名,compose 探测的就是它 |
| 定时服务 healthcheck 不通过 | 等 start_period(40s)过完;仍失败则检查 /app/data 可写性与数据库初始化日志 |
| 登录失败 | 容器内不能交互登录;确认 refreshToken 已通过配置或 .env 注入 |
| 下载 0 个 | 先看 targets 是否过严;网络是否需要代理(见 .env 代理段) |
| WebUI 打不开 | 确认映射端口与 WEBUI_PORT;防火墙放行;远程访问建议挂反代 + 认证 |
| 代理不生效 | 小写变量(all_proxy)也要填;检查宿主机代理是否监听 0.0.0.0 |
npm 全局安装(桌面 / 轻量服务器)#
npm install -g pixivflow
pixivflow login # 一次性授权
pixivflow setup # 生成配置(可选)
pixivflow scheduler # 常驻定时验证:pixivflow health 全绿即可放心挂机。
常驻运行Linux/macOS 服务器上可用 tmux、nohup 或 systemd 等常规手段托管
pixivflow scheduler 进程;更省心的方案是上面的 Docker Compose(自带重启与健康检查)。Windows 建议任务计划程序或 Docker Desktop。Termux(Android)#
四步概览,逐条命令与踩坑说明见完整 Termux 文档:
pkg update && pkg install nodejs-lts git
termux-setup-storage # 授权文件访问
npm install -g pixivflow
pixivflow login && pixivflow download注意:Android 厂商的后台查杀可能导致调度器休眠,建议在系统设置中给 Termux 关闭电池优化;详细方案见 Termux 文档的「保持后台运行」一节。