故障排查

先记录界面错误码、请求时间和日志中的 requestId。不要把完整凭证或备份文件贴到公开 Issue。

现象	优先检查
没有可选上传配置	是否创建并启用配置；当前用户、令牌或游客是否被允许使用
存储源未就绪	配置、凭证、本地目录权限；修正后重新初始化
上传返回 413	全局、用户、配置和代理限制；大文件应走分片上传
临时缓存空间不足	未完成上传、后台任务保留的源文件、磁盘剩余空间
有链接但副本未全部完成	图片操作详情中的后台任务与副本状态
图片参数没有效果或报错	是否启用参数；值是否合法；图片格式是否受插件支持
删除后还看得到图片	浏览器/CDN 缓存；远端副本是否仍在删除或失败状态
改环境变量没有效果	运行设置首次启动时已自动保存，之后在 Web 修改；密钥、数据库和监听地址等部署参数需重启或重建容器
插件执行一直不结束	取消需要插件配合，不能通过增大并发解决

忘记 Owner 密码

先停止应用，使用同一个 Compose 文件和环境文件运行恢复命令：

docker compose -f compose.yml stop picloom
docker compose -f compose.yml run --rm picloom bun src/cli.ts reset-owner-password
docker compose -f compose.yml up -d

按提示输入新密码。已有 Owner 会话会失效，上传令牌保留。PostgreSQL 部署替换 Compose 文件名。

临时缓存空间占用较高

运行中的后台任务可能仍在使用临时文件，直接清空目录会导致任务失败。先查看任务状态，优先通过界面取消上传或删除文件，让维护流程回收资源。