PixivFlow
⭐

❓ 常见问题

按场景分组。没有覆盖到的问题请到 Issues 提问,附上 pixivflow health 输出(删掉 token)能大大加快定位。

安装与环境#

支持哪些系统?

任何能跑 Node.js 18+ 的环境:Windows、macOS、Linux,以及 Docker 与 Android Termux。推荐 Node LTS 版本。

需要安装 Python 吗?

不需要。默认登录走 Node.js 实现(pixiv-token-getter),Puppeteer 是回退方案,Python gppt 只是最后备选。

如何升级到新版本?

npm 场景:npm install -g pixivflow@latest;Docker 场景:git pull && docker compose build && docker compose up -d(没有官方镜像仓库,pull 无效)。升级前建议 pixivflow backup。

为什么全局命令装完提示找不到?

确认 npm 全局 bin 目录在 PATH 里(npm bin -g 或 npm config get prefix 查看),或重新打开终端。

登录与认证#

凭据保存在哪里?安全吗?

在当前配置文件(通常 config/standalone.config.json)的 pixiv.refreshToken 字段。它等同密码:不要提交进公开仓库、不要截图。账号密码只在登录那一刻使用,不会落盘。

提示 Authentication Error 怎么办?

refresh token 失效或无效。在桌面环境重新 pixivflow login;服务器上重新 login-headless,或用其他设备上有效的 token 执行 pixivflow refresh <token>。

服务器没有浏览器怎么登录?

两条路:pixivflow login-headless -u 用户名 -p 密码;或在桌面机器登录后把 refreshToken 拿到服务器上执行 pixivflow refresh <token>(Docker 场景推荐后者,见部署指南)。

登录时浏览器打不开或卡住?

公司/校园网络可能拦截授权回调,试试代理后再 login;仍失败就走「桌面登录 → refresh 注入」的路线。

下载行为#

下载了 0 个作品?

按顺序检查:① pixivflow health 确认连通性;② 标签拼写、大小写、语言是否与站内完全一致(日文标签用日文);③ 条件是否过严——先删掉 minBookmarks/startDate 用最小配置跑通,再逐项收紧;④ 是否触发限流,看日志里的 429。

重复执行会不会重复下载?

不会。每幅作品的记录写入 SQLite,已下载的直接跳过;文件存在但缺记录时会自动对账补录。

中断了能接着下吗?

能。断点续传:重新执行同一目标,从上次中断处继续,不会整批重来。

想每天自动收「昨天的新图」?

日期字段写占位符 "YESTERDAY"(或 "TODAY"),配合 cron 每天执行即可自动滚动,见占位符说明。

多标签是 AND 还是 OR?

默认 AND(必须同时包含)。要「任一命中」:多个标签空格分隔 + "tagRelation": "or"。

遇到大量 429 限流?

优先加大 download.requestDelay(默认 500ms)而不是堆并发;dynamicConcurrency 保持开启,程序会自动降速。

能下载 R18 榜单吗?

排行榜模式提供 day_r18 / day_male_r18 / day_female_r18;账号本身需在 Pixiv 设置中允许浏览 R18 内容。

文件与目录#

文件下载到哪了?

pixivflow dirs 直接列出各类文件的真实保存路径;默认在 ./downloads/illustrations 与 ./downloads/novels。

想按画师/日期自动归类?

storage.*Organization 支持 12 种模式(byAuthor、byDay、byDownloadDateAndAuthor……),见配置参考。修改后执行 pixivflow normalize 把已有文件归位。

能改下载盘吗?

可以。storage.downloadDirectory 与 databasePath 都接受绝对路径;Docker 场景改宿主机挂载点即可。

数据库会越来越大吗?

记录很轻量,一般无需担心;挂机数月后可跑 pixivflow maintain 清理日志并优化数据库。

WebUI#

怎么启动?

pixivflow webui,浏览器打开 http://localhost:3000;Docker 场景直接起 compose 里的 pixivflow-webui 服务。

可以远程访问吗?

服务默认监听 0.0.0.0,公网暴露请务必挂在反向代理后面并加访问认证(Nginx Basic Auth、OAuth 代理等),否则任何人都能操作你的下载器。

WebUI 里改的配置没生效/丢了?

Docker 部署时 ./config 是只读挂载,界面保存不会回写宿主机文件——请在宿主机直接编辑 JSON,见部署指南说明。

前端源码在哪?

独立仓库 pixivflow-webui(React 18 + Ant Design 5),接口定义见 API 文档。

Docker#

容器内能执行 pixivflow login 吗?

不能,交互式登录需要浏览器。容器部署走「宿主机登录 → token 注入」路线:填进挂载的配置文件,或在 .env 里设 PIXIV_REFRESH_TOKEN。

有官方镜像可以直接 pull 吗?

目前没有。compose 使用本地构建的 pixivflow:latest,升级方式是 git pull && docker compose build。

构建时报错找不到 webui-frontend?

Dockerfile 会复制 webui-frontend/ 目录,主仓库不含它——先克隆 前端仓库到该位置再 build,详见部署指南。

webui 容器一直 unhealthy?

已知问题:compose 的 healthcheck 探测路径与实际端点(/api/health)不符,unhealthy 是误报,不影响服务;用 curl localhost:3000/api/health 验证即可。

两个容器是什么关系?

pixivflow 跑 Cron 定时下载,pixivflow-webui 提供管理界面;共享 ./config(只读)、./data、./downloads 三个卷,互不冲突。
↑ 回到顶部
start_period(40 秒)内属正常。超过后仍异常才需要排查:curl localhost:3000/api/health;compose 现在探测的是正确的 /api/health(后端另有 /health 别名)。`)}!DOCTYPE html> 常见问题 — PixivFlow
PixivFlow
⭐

❓ 常见问题

按场景分组。没有覆盖到的问题请到 Issues 提问,附上 pixivflow health 输出(删掉 token)能大大加快定位。

安装与环境#

支持哪些系统?

任何能跑 Node.js 18+ 的环境:Windows、macOS、Linux,以及 Docker 与 Android Termux。推荐 Node LTS 版本。

需要安装 Python 吗?

不需要。默认登录走 Node.js 实现(pixiv-token-getter),Puppeteer 是回退方案,Python gppt 只是最后备选。

如何升级到新版本?

npm 场景:npm install -g pixivflow@latest;Docker 场景:git pull && docker compose build && docker compose up -d(没有官方镜像仓库,pull 无效)。升级前建议 pixivflow backup。

为什么全局命令装完提示找不到?

确认 npm 全局 bin 目录在 PATH 里(npm bin -g 或 npm config get prefix 查看),或重新打开终端。

登录与认证#

凭据保存在哪里?安全吗?

在当前配置文件(通常 config/standalone.config.json)的 pixiv.refreshToken 字段。它等同密码:不要提交进公开仓库、不要截图。账号密码只在登录那一刻使用,不会落盘。

提示 Authentication Error 怎么办?

refresh token 失效或无效。在桌面环境重新 pixivflow login;服务器上重新 login-headless,或用其他设备上有效的 token 执行 pixivflow refresh <token>。

服务器没有浏览器怎么登录?

两条路:pixivflow login-headless -u 用户名 -p 密码;或在桌面机器登录后把 refreshToken 拿到服务器上执行 pixivflow refresh <token>(Docker 场景推荐后者,见部署指南)。

登录时浏览器打不开或卡住?

公司/校园网络可能拦截授权回调,试试代理后再 login;仍失败就走「桌面登录 → refresh 注入」的路线。

下载行为#

下载了 0 个作品?

按顺序检查:① pixivflow health 确认连通性;② 标签拼写、大小写、语言是否与站内完全一致(日文标签用日文);③ 条件是否过严——先删掉 minBookmarks/startDate 用最小配置跑通,再逐项收紧;④ 是否触发限流,看日志里的 429。

重复执行会不会重复下载?

不会。每幅作品的记录写入 SQLite,已下载的直接跳过;文件存在但缺记录时会自动对账补录。

中断了能接着下吗?

能。断点续传:重新执行同一目标,从上次中断处继续,不会整批重来。

想每天自动收「昨天的新图」?

日期字段写占位符 "YESTERDAY"(或 "TODAY"),配合 cron 每天执行即可自动滚动,见占位符说明。

多标签是 AND 还是 OR?

默认 AND(必须同时包含)。要「任一命中」:多个标签空格分隔 + "tagRelation": "or"。

遇到大量 429 限流?

优先加大 download.requestDelay(默认 500ms)而不是堆并发;dynamicConcurrency 保持开启,程序会自动降速。

能下载 R18 榜单吗?

排行榜模式提供 day_r18 / day_male_r18 / day_female_r18;账号本身需在 Pixiv 设置中允许浏览 R18 内容。

文件与目录#

文件下载到哪了?

pixivflow dirs 直接列出各类文件的真实保存路径;默认在 ./downloads/illustrations 与 ./downloads/novels。

想按画师/日期自动归类?

storage.*Organization 支持 12 种模式(byAuthor、byDay、byDownloadDateAndAuthor……),见配置参考。修改后执行 pixivflow normalize 把已有文件归位。

能改下载盘吗?

可以。storage.downloadDirectory 与 databasePath 都接受绝对路径;Docker 场景改宿主机挂载点即可。

数据库会越来越大吗?

记录很轻量,一般无需担心;挂机数月后可跑 pixivflow maintain 清理日志并优化数据库。

WebUI#

怎么启动?

pixivflow webui,浏览器打开 http://localhost:3000;Docker 场景直接起 compose 里的 pixivflow-webui 服务。

可以远程访问吗?

服务默认监听 0.0.0.0,公网暴露请务必挂在反向代理后面并加访问认证(Nginx Basic Auth、OAuth 代理等),否则任何人都能操作你的下载器。

WebUI 里改的配置没生效/丢了?

Docker 部署时 ./config 是只读挂载,界面保存不会回写宿主机文件——请在宿主机直接编辑 JSON,见部署指南说明。

前端源码在哪?

独立仓库 pixivflow-webui(React 18 + Ant Design 5),接口定义见 API 文档。

Docker#

容器内能执行 pixivflow login 吗?

不能,交互式登录需要浏览器。容器部署走「宿主机登录 → token 注入」路线:填进挂载的配置文件,或在 .env 里设 PIXIV_REFRESH_TOKEN。

有官方镜像可以直接 pull 吗?

目前没有。compose 使用本地构建的 pixivflow:latest,升级方式是 git pull && docker compose build。

构建时报错找不到 webui-frontend?

Dockerfile 会复制 webui-frontend/ 目录,主仓库不含它——先克隆 前端仓库到该位置再 build,详见部署指南。

webui 容器一直 unhealthy?

已知问题:compose 的 healthcheck 探测路径与实际端点(/api/health)不符,unhealthy 是误报,不影响服务;用 curl localhost:3000/api/health 验证即可。

两个容器是什么关系?

pixivflow 跑 Cron 定时下载,pixivflow-webui 提供管理界面;共享 ./config(只读)、./data、./downloads 三个卷,互不冲突。
↑ 回到顶部
pixivflow-webui(要求构建机可访问 GitHub);也可用 --build-arg SKIP_WEBUI_BUILD=true 构建 API-only 镜像。详见部署指南`)}!DOCTYPE html> 常见问题 — PixivFlow
PixivFlow
⭐

❓ 常见问题

按场景分组。没有覆盖到的问题请到 Issues 提问,附上 pixivflow health 输出(删掉 token)能大大加快定位。

安装与环境#

支持哪些系统?

任何能跑 Node.js 18+ 的环境:Windows、macOS、Linux,以及 Docker 与 Android Termux。推荐 Node LTS 版本。

需要安装 Python 吗?

不需要。默认登录走 Node.js 实现(pixiv-token-getter),Puppeteer 是回退方案,Python gppt 只是最后备选。

如何升级到新版本?

npm 场景:npm install -g pixivflow@latest;Docker 场景:git pull && docker compose build && docker compose up -d(没有官方镜像仓库,pull 无效)。升级前建议 pixivflow backup。

为什么全局命令装完提示找不到?

确认 npm 全局 bin 目录在 PATH 里(npm bin -g 或 npm config get prefix 查看),或重新打开终端。

登录与认证#

凭据保存在哪里?安全吗?

在当前配置文件(通常 config/standalone.config.json)的 pixiv.refreshToken 字段。它等同密码:不要提交进公开仓库、不要截图。账号密码只在登录那一刻使用,不会落盘。

提示 Authentication Error 怎么办?

refresh token 失效或无效。在桌面环境重新 pixivflow login;服务器上重新 login-headless,或用其他设备上有效的 token 执行 pixivflow refresh <token>。

服务器没有浏览器怎么登录?

两条路:pixivflow login-headless -u 用户名 -p 密码;或在桌面机器登录后把 refreshToken 拿到服务器上执行 pixivflow refresh <token>(Docker 场景推荐后者,见部署指南)。

登录时浏览器打不开或卡住?

公司/校园网络可能拦截授权回调,试试代理后再 login;仍失败就走「桌面登录 → refresh 注入」的路线。

下载行为#

下载了 0 个作品?

按顺序检查:① pixivflow health 确认连通性;② 标签拼写、大小写、语言是否与站内完全一致(日文标签用日文);③ 条件是否过严——先删掉 minBookmarks/startDate 用最小配置跑通,再逐项收紧;④ 是否触发限流,看日志里的 429。

重复执行会不会重复下载?

不会。每幅作品的记录写入 SQLite,已下载的直接跳过;文件存在但缺记录时会自动对账补录。

中断了能接着下吗?

能。断点续传:重新执行同一目标,从上次中断处继续,不会整批重来。

想每天自动收「昨天的新图」?

日期字段写占位符 "YESTERDAY"(或 "TODAY"),配合 cron 每天执行即可自动滚动,见占位符说明。

多标签是 AND 还是 OR?

默认 AND(必须同时包含)。要「任一命中」:多个标签空格分隔 + "tagRelation": "or"。

遇到大量 429 限流?

优先加大 download.requestDelay(默认 500ms)而不是堆并发;dynamicConcurrency 保持开启,程序会自动降速。

能下载 R18 榜单吗?

排行榜模式提供 day_r18 / day_male_r18 / day_female_r18;账号本身需在 Pixiv 设置中允许浏览 R18 内容。

文件与目录#

文件下载到哪了?

pixivflow dirs 直接列出各类文件的真实保存路径;默认在 ./downloads/illustrations 与 ./downloads/novels。

想按画师/日期自动归类?

storage.*Organization 支持 12 种模式(byAuthor、byDay、byDownloadDateAndAuthor……),见配置参考。修改后执行 pixivflow normalize 把已有文件归位。

能改下载盘吗?

可以。storage.downloadDirectory 与 databasePath 都接受绝对路径;Docker 场景改宿主机挂载点即可。

数据库会越来越大吗?

记录很轻量,一般无需担心;挂机数月后可跑 pixivflow maintain 清理日志并优化数据库。

WebUI#

怎么启动?

pixivflow webui,浏览器打开 http://localhost:3000;Docker 场景直接起 compose 里的 pixivflow-webui 服务。

可以远程访问吗?

服务默认监听 0.0.0.0,公网暴露请务必挂在反向代理后面并加访问认证(Nginx Basic Auth、OAuth 代理等),否则任何人都能操作你的下载器。

WebUI 里改的配置没生效/丢了?

Docker 部署时 ./config 是只读挂载,界面保存不会回写宿主机文件——请在宿主机直接编辑 JSON,见部署指南说明。

前端源码在哪?

独立仓库 pixivflow-webui(React 18 + Ant Design 5),接口定义见 API 文档。

Docker#

容器内能执行 pixivflow login 吗?

不能,交互式登录需要浏览器。容器部署走「宿主机登录 → token 注入」路线:填进挂载的配置文件,或在 .env 里设 PIXIV_REFRESH_TOKEN。

有官方镜像可以直接 pull 吗?

目前没有。compose 使用本地构建的 pixivflow:latest,升级方式是 git pull && docker compose build。

构建时报错找不到 webui-frontend?

Dockerfile 会复制 webui-frontend/ 目录,主仓库不含它——先克隆 前端仓库到该位置再 build,详见部署指南。

webui 容器一直 unhealthy?

已知问题:compose 的 healthcheck 探测路径与实际端点(/api/health)不符,unhealthy 是误报,不影响服务;用 curl localhost:3000/api/health 验证即可。

两个容器是什么关系?

pixivflow 跑 Cron 定时下载,pixivflow-webui 提供管理界面;共享 ./config(只读)、./data、./downloads 三个卷,互不冲突。
↑ 回到顶部