SurfSense zero-cache 卡在 “Unknown or invalid publications“ 怎么处理？

SurfSense zero-cache 卡在 Unknown or invalid publications 怎么处理【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSenseSurfSense 的 Docker 或手动安装环境中zero-cacheRocicorp Zero 实时同步服务启动后反复崩溃、日志中反复出现Unknown or invalid publications. Specified: [zero_publication]前端的通知、文档状态、聊天消息等实时数据就停在旧状态上。这个报错的根因是固定的zero-cache 启动时PostgreSQL 里还不存在它要订阅的zero_publication逻辑复制发布对象——通常是跳过了 Alembic 数据库迁移迁移会创建 schema 和zero_publication或单独先启动了 zero-cache 服务。修复路径就是补跑迁移、必要时清掉半初始化的复制副本再按正确顺序重启。本文给出三条部署形态各自的恢复命令和验证方式。先确认 publication 是否真的缺失在修复前先核对数据库状态。连接 SurfSense 使用的 PostgreSQLDocker 安装里是db服务默认用户/数据库名为postgres/surfsense执行psql -U postgres -d surfsense -c SELECT pubname FROM pg_publication;结果不包含zero_publication说明迁移没跑或没跑完按下面对应部署形态补跑迁移即可。结果包含zero_publication但 zero-cache 仍然报同样的错多半是上次崩溃留下了半初始化的 SQLite 复制副本走清掉 zero-cache 数据卷的恢复步骤见 Docker 栈 和 手动安装。另外可以顺带确认逻辑复制开关是否就绪这是 zero-cache 的硬性前置条件psql -U postgres -d surfsense -c SHOW wal_level; # 应返回: logical如果返回的不是logical需要先按 manual-installation.mdx 中 Configure PostgreSQL for Zero Sync 一节修改postgresql.confwal_level logical并重启 PostgreSQL再处理 publication 问题。Docker Compose 栈清数据卷后整栈重启Docker 安装官方 compose 文件在每次启动时会先运行migrations短生命周期容器并等待其成功zero-cache 才会启动所以正常走docker compose up -d一般不会踩到这个坑。docker-installation/index.mdx 明确指出只有当你逐个单独启动了服务比如先起了 zero-cache、后跑迁移才会出现卡在Unknown or invalid publications的情况。恢复步骤在 SurfSense 的 compose 目录下执行安装脚本用户即./surfsense/手动克隆用户即docker/docker compose down docker volume rm surfsense-zero-cache # 清掉半初始化的复制副本 docker compose up -d # migrations 先跑zero-cache 后启动其中docker volume rm surfsense-zero-cache的副作用要清楚它删除的是 zero-cache 的 SQLite 副本数据卷zero_cache_data主 compose 文件中卷名为surfsense-zero-cache不会删除 PostgreSQL 里的业务数据。副本会在下次启动时从 PostgreSQL 全量重建对大库来说重建需要一点时间属于正常现象。用docker compose ps观察启动过程各服务会经过(health: starting)进入(healthy)。这个恢复流程同时也能修复另一种相关故障——zero-cache 因_zero.tableMetadata崩溃原因同样是上次崩溃遗留的半初始化副本处理办法一致。手动安装补跑迁移并重启 zero-cache手动安装的后端是宿主机上uv run起的而 zero-cache 仍跑在 Docker 容器里。此时按 manual-installation.mdx 的 Troubleshooting 一节缺 publication 的处理是补跑迁移然后重启容器# 从 surfsense_backend/ 目录执行 uv run alembic upgrade head docker restart surfsense-zero-cache迁移命令负责创建 schema 和zero_publication创建zero_publication的迁移是 116_create_zero_publication.py。如果之前迁移只跑了一半重新执行uv run alembic upgrade head会从中断处继续这一步是幂等的。deps-only 部署迁移必须在宿主机先跑如果你用 docker-compose.deps-only.ymlDocker 只跑 Postgres、Redis、zero-cache后端和前端在宿主机原生运行这个 compose 文件没有migrations服务无法自动建 publication。该文件头部的注释明确警告必须在宿主机先执行 Alembic 迁移再启动 compose否则 zero-cache 会以Unknown or invalid publications. Specified: [zero_publication]崩溃循环cd surfsense_backend uv run alembic upgrade head cd ../docker docker compose -f docker-compose.deps-only.yml up -d如果已经起错了顺序先补跑迁移若 zero-cache 已残留坏副本同样可以删除其数据卷后重新up -ddeps-only 文件中该卷名为surfsense-deps-zero-cache。验证是否修好按以下顺序检查全部通过即修复完成publication 存在SELECT pubname FROM pg_publication;结果包含zero_publication。keepalive 健康检查curl http://localhost:4848/keepalive # 应返回 HTTP 200初始复制完成docker logs -f surfsense-zero-cache确认日志中没有继续报Unknown or invalid publications或_zero.tableMetadata错误初始复制正常结束。UI 实时性打开http://localhost:3000Docker 安装经 Caddy 为http://localhost:3929创建 workspace 并上传一个文档观察上传状态能否不刷新页面地实时更新——这是 manual-installation.mdx 给出的安装验证方式直接证明 zero-cache 链路已通。边界与相关排查项后端/ready返回 503该就绪探针会检查zero_publication是否存在报 503 同样是迁移缺失跑uv run alembic upgrade head即可来源manual-installation.mdx Troubleshooting。Docker 主栈为何很少踩坑官方 compose 中migrations服务先于其他服务运行且全部服务等待其成功docker-installation/index.mdx Whats Running所以先补迁移再重启的恢复结果与正常启动顺序是一致的。不要混淆另一个错误Insufficient upstream connections是ZERO_NUM_SYNC_WORKERS超过连接池上限导致的调低ZERO_NUM_SYNC_WORKERS或调高ZERO_UPSTREAM_MAX_CONNS/ZERO_CVR_MAX_CONNS解决与本文的 publication 缺失无关来源zero-sync.mdx Troubleshooting。wal_level不是logical时会表现为 zero-cache 无法建立逻辑复制属于前置配置问题而非本报错确认方式是SHOW wal_level;应返回logical。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考