Paperless-ngx 怎么启用 Flower 查看 Celery 任务队列与 Worker 状态-育师

Paperless-ngx 怎么启用 Flower 查看 Celery 任务队列与 Worker 状态

【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx

Paperless-ngx 用 Celery 执行异步任务（例如 OCR、邮件处理、文档导入等）。如果你想在 Docker 部署的实例上看到这些任务的运行状态——当前正在执行、排队中、已完成的任务及其耗时——可以启用项目自带的 Celery 监控工具 Flower。完成本文操作后，Flower 会随容器启动，默认监听 5555 端口，你可以在浏览器中查看 Worker 与任务队列详情，它同时也会向 Prometheus 导出指标。

以下操作面向 Docker 安装方式，依据高级用法文档的 "Celery Monitoring" 章节与配置文档中的PAPERLESS_ENABLE_FLOWER条目。

开启 Flower 的环境变量

Flower 不是默认启动的。根据配置文档的说明：

PAPERLESS_ENABLE_FLOWER=<defined>：If this environment variable is defined, the Celery monitoring tool Flower will be started by the container.

注意这里的判定条件是变量被定义（<defined>），而不是取某个特定值。只要在你的 Docker Compose 文件的webserver服务里加上这个环境变量，容器就会在启动时拉起 Flower。文档给出的 compose 片段如下（来自 docs/advanced_usage.md）：

services: # ... webserver: environment: - PAPERLESS_ENABLE_FLOWER ports: - 5555:5555 # (2)! # ... volumes: - /path/to/my/flowerconfig.py:/usr/src/paperless/src/paperless/flowerconfig.py:ro # (1)!

其中：

5555:5555端口映射是把容器内的 Flower 默认端口暴露到宿主机。文档明确说 Flower 默认运行在 5555 端口，但"this can be configured"（可以另行配置）。
volumes一行是可选的：仅当你想进一步自定义 Flower 配置时才需要，见下一节。:ro表示该文件以只读方式挂载。

如果你的 compose 文件使用.env文件管理变量，也可以把PAPERLESS_ENABLE_FLOWER写入.env文件并让 webserver 服务引用它——判定条件只是"变量被定义"，两种写法等效。

可选：挂载 flowerconfig.py 做进一步配置

文档说明：若要进一步配置 Flower，需创建一个flowerconfig.py并放入src/paperless目录；Docker 安装下通过卷挂载实现，目标路径固定为容器内的/usr/src/paperless/src/paperless/flowerconfig.py（如上例中volumes一行所示）。文件本身放在你宿主机的哪个路径都可以，示例中的/path/to/my/flowerconfig.py需要替换为你实际放置文件的位置。

Flower 的具体可配置项（例如修改端口、认证等）文档没有展开，需参考 Flower 自身的说明（原文档指向 Flower 官方文档）。你只需要保证挂载的目标路径正确，容器侧的启动脚本会自动以该文件作为--conf参数加载。

启动后如何确认 Flower 已经运行

修改 compose 配置后，按你平时的方式重新创建/重启容器（例如docker compose up -d），然后做两处确认：

查看容器日志。镜像内由 s6-overlay 的svc-flower服务负责拉起 Flower，其启动脚本是 docker/rootfs/etc/s6-overlay/s6-rc.d/svc-flower/run。该脚本的行为是：
- 未定义PAPERLESS_ENABLE_FLOWER时，输出Not starting flower并停止该服务；
- 已定义时，先等待 5 秒（给 Celery 留出启动时间，脚本注释说明 "Small delay to allow celery to be up first"），然后执行celery --app paperless flower启动 Flower，并加载flowerconfig.py（若存在）。
所以在 webserver 容器日志中看到Starting flower in 5s即说明环境变量生效、Flower 正在被拉起。
访问默认端口。用浏览器打开http://<宿主机地址>:5555，即 compose 中5555:5555映射出来的地址，即可看到 Flower 界面中的 Worker、正在运行 / 排队 / 已完成的任务及耗时等信息。

如果 5555 端口无法访问，先回到第 1 点确认日志里是 "Starting flower" 还是 "Not starting flower"——后者说明环境变量没有被正确定义到 webserver 服务里。

限制与适用条件

该机制是 Docker 镜像内置的：Flower 由容器内服务脚本启动，非 Docker 部署方式不在文档此节的描述范围内。
Flower 是监控组件，不提供额外功能；文档中提到的"当前任务、队列、完成任务、耗时，以及 Prometheus 指标导出"均属于 Flower 自身能力，细节以 Flower 官方文档为准。
若不需要监控，去掉PAPERLESS_ENABLE_FLOWER定义并移除5555:5555端口映射即可恢复到不启动 Flower 的状态（启动脚本对"未定义变量"的处理是直接停掉该服务）。

配置生效后，你得到的结果就是：一个默认运行在 5555 端口、可随时查看 Celery 任务队列与 Worker 状态的 Flower 界面，以及可供 Prometheus 抓取的指标端点。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考