如何为 SurfSense zero-cache 配置 PostgreSQL 逻辑复制wal_level 与 REPLICATION 权限【免费下载链接】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 的实时同步通知、文档处理状态、聊天消息与评论等由 Rocicorp Zero 驱动它运行一个zero-cache服务通过 PostgreSQL逻辑复制logical replication把变更流式同步到本地 SQLite 副本再经 WebSocket 推给浏览器。逻辑复制对 PostgreSQL 有两条硬性要求数据库必须设置wal_level logical连接数据库的用户必须拥有REPLICATION权限用于创建逻辑复制槽。本文针对在自己管理的 PostgreSQL本地安装或托管数据库上部署 SurfSense 的场景给出这两项的完整配置方法、zero_publication前置步骤和逐条验证方式。如果你使用仓库自带的完整 Docker 部署docker/postgresql.conf已包含wal_level logical默认surfsense用户是 superuser、自动拥有所需权限一般无需额外配置参见文末说明。前提条件按 手动安装指南 的 What Youll Need本场景涉及的组件要求PostgreSQL 14并安装pgvector扩展数据库Docker—— 用来运行 zero-cache实时同步服务器Python 3.12与uv—— 运行数据库迁移创建 zero-cache 所需的zero_publication已克隆仓库并完成surfsense_backend的环境配置.env中设置 PostgreSQL 连接串与 JWT secret。本地 PostgreSQL在 postgresql.conf 中设置 wal_level logicalwal_level logical必须写入 PostgreSQL 配置文件并重启数据库才能生效。编辑postgresql.conf文档给出的典型位置Linux/etc/postgresql/version/main/postgresql.confmacOSHomebrew/usr/local/var/postgres/postgresql.confWindowsC:\Program Files\PostgreSQL\version\data\postgresql.conf设置以下三个参数与 SurfSense 仓库随 Docker 部署挂载的 docker/postgresql.conf 中为 Zero 逻辑复制设置的值一致wal_level logical max_replication_slots 10 max_wal_senders 10保存后重启 PostgreSQL。注意重启会中断该实例上的所有数据库连接生产环境请在维护窗口执行。各平台的重启命令# Linux sudo systemctl restart postgresql# macOS (Homebrew) brew services restart postgresql# Windows (PowerShell, 将 17 替换为你的主版本号) Restart-Service postgresql-x64-17验证wal_level是否已生效psql -U postgres -d surfsense -c SHOW wal_level; # Should return: logical返回值为logical说明第一步完成如果仍是其他值说明配置未保存或未重启先排查这一项再继续。托管数据库启用逻辑复制并授予 REPLICATION 权限在 RDS、Supabase、Cloud SQL 等托管数据库上postgresql.conf通常由服务商管理改法是两条通过服务商的参数组启用逻辑复制例如 RDS 上设置rds.logical_replication1给应用用户授予REPLICATION权限。文档给出的授权语句surfsense为示例中的数据库名与用户名替换为你环境中的实际值ALTER USER surfsense WITH REPLICATION; GRANT CREATE ON DATABASE surfsense TO surfsense;文档中对两个权限的用途有明确说明REPLICATION允许 zero-cache 创建逻辑复制槽logical replication slot来流式接收变更CREATE允许 zero-cache 在其元数据所在的内部 schemazero、zero_0中创建对象。仓库自带的 Docker 部署里默认surfsense用户是 PostgreSQL superuser这两项自动满足托管库上应用用户往往不是 superuser才需要显式授予。创建 zero_publication启动 zero-cache 的前置步骤逻辑复制只解决“变更怎么流”zero-cache 复制哪些表则由 PostgreSQL publication 限定——SurfSense 使用名为zero_publication的 publication它由数据库迁移创建# 在 surfsense_backend/ 目录下执行 uv run alembic upgrade head这一步不能跳过。文档明确说明缺少zero_publication时zero-cache 会陷入 crash-loop日志报Unknown or invalid publications. Specified: [zero_publication]后端/ready探针也会因校验不到该 publication 而返回 503。验证 publication 已创建psql -U postgres -d surfsense -c SELECT pubname FROM pg_publication; # Should include: zero_publication查询结果包含zero_publication即可继续。启动 zero-cache 容器wal_level与权限配置就绪后用官方镜像启动 zero-cache。文档给出 Linux/macOS 命令ZERO_QUERY_URL/ZERO_MUTATE_URL指向前端地址生产/自定义域名场景按文档说明改为你的公网前端 URLdocker run -d --name surfsense-zero-cache \ -p 4848:4848 \ --add-hosthost.docker.internal:host-gateway \ -e ZERO_UPSTREAM_DBpostgresql://postgres:postgreshost.docker.internal:5432/surfsense?sslmodedisable \ -e ZERO_CVR_DBpostgresql://postgres:postgreshost.docker.internal:5432/surfsense?sslmodedisable \ -e ZERO_CHANGE_DBpostgresql://postgres:postgreshost.docker.internal:5432/surfsense?sslmodedisable \ -e ZERO_REPLICA_FILE/data/zero.db \ -e ZERO_ADMIN_PASSWORDsurfsense-zero-admin \ -e ZERO_APP_PUBLICATIONSzero_publication \ -e ZERO_NUM_SYNC_WORKERS4 \ -e ZERO_UPSTREAM_MAX_CONNS20 \ -e ZERO_CVR_MAX_CONNS30 \ -e ZERO_QUERY_URLhttp://host.docker.internal:3000/api/zero/query \ -e ZERO_MUTATE_URLhttp://host.docker.internal:3000/api/zero/mutate \ -e ZERO_QUERY_FORWARD_COOKIEStrue \ -v surfsense-zero-cache:/data \ rocicorp/zero:1.6.0Windows 上的等价命令使用 PowerShell 反引号续行其余参数相同。文档明确列出的两处替换将三个*_DB连接串中的postgres:postgres换成你的实际数据库用户与密码——这就是上一步授予REPLICATION权限的那个用户Linux 上没有 Docker Desktop 时host.docker.internal可能无法解析保留--add-hosthost.docker.internal:host-gatewayDocker 20.10或将host.docker.internal替换为主机 IP / 改用--networkhostlocalhost。验证结果按文档给出的顺序确认整条链路zero-cache 存活检查curl http://localhost:4848/keepalive # Should return HTTP 200复制日志检查docker logs -f surfsense-zero-cache文档要求确认“initial replication completed without errors”初始复制完成且无错误而不规定某条固定日志。端到端确认打开前端并登录创建 workspace 并上传文档观察上传状态无需刷新页面即实时更新——文档以此为标准判定 zero-cache 接线正确。前端不在 Docker 捆绑 Caddy 之后时如本地pnpm dev需先设置NEXT_PUBLIC_ZERO_CACHE_URLhttp://localhost:4848并核对surfsense_web/.env中的 zero-cache URL 与正在运行的 zero-cache 地址一致。故障排查与限制现象文档给出的处理wal_level不是logicalzero-cache 无法复制按上文修改postgresql.conf重启 PostgreSQL用SHOW wal_level;复核zero-cache crash-loop报Unknown or invalid publications. Specified: [zero_publication]说明跳过了uv run alembic upgrade head在surfsense_backend/补跑后再docker restart surfsense-zero-cache实时更新不生效、UI 数据过期先确认curl http://localhost:4848/keepalive返回 200再看浏览器 DevTools → Console 有无 WebSocket 错误最后核对前端.env中 zero-cache URL 是否与运行地址一致后端/ready返回 503就绪探针在检查zero_publication是否存在同样补跑uv run alembic upgrade headzero-cache 崩溃并报_zero.tableMetadata错误上次运行遗留了构建到一半的 SQLite 副本。下面命令会删除容器并清空其数据卷zero.db 副本下次启动从零重建副本请知悉后再执行docker rm -f surfsense-zero-cache docker volume rm surfsense-zero-cache然后重新执行启动命令两个边界限制来自文档重启后数据暂旧zero-cache 启动时会从 PostgreSQL 重建 SQLite 副本大库需要一段时间期间表现为“stale data after restart”属文档描述的预期行为高核机器连接数ZERO_NUM_SYNC_WORKERS默认取 CPU 核数可能超出连接池上限而报 Insufficient upstream connections。处理方式是调低ZERO_NUM_SYNC_WORKERS或调高ZERO_UPSTREAM_MAX_CONNS/ZERO_CVR_MAX_CONNS。可选路径让 Docker 托管 PostgreSQL本地开发时仓库提供了 docker/docker-compose.deps-only.yml由 Docker 同时管理 Postgres、Redis 和 zero-cache而 backend 与 frontend 仍在本机运行。前提不变先在宿主机完成迁移保证zero_publication已存在否则 zero-cache 会 crash-loopcd surfsense_backend uv run alembic upgrade head cd ../docker docker compose -f docker-compose.deps-only.yml up -d该栈把 zero-cache 暴露在4848端口随后在前端.env中设置NEXT_PUBLIC_ZERO_CACHE_URLhttp://localhost:4848变量说明见surfsense_web/.env.example注释。完整 Docker 部署docker/docker-compose.yml则无需本文的前两项配置db服务以command: postgres -c config_file/etc/postgresql/postgresql.conf启动并挂载了已含wal_level logical的 docker/postgresql.confcompose 中的migrations服务会在 zero-cache 启动前执行alembic upgrade head并校验zero_publication迁移失败会直接阻断整个栈启动而不是让 zero-cache 顶着漂移的 publication 运行。【免费下载链接】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），仅供参考
如何为 SurfSense zero-cache 配置 PostgreSQL 逻辑复制（wal_level 与 REPLICATION 权限）？
如何为 SurfSense zero-cache 配置 PostgreSQL 逻辑复制wal_level 与 REPLICATION 权限【免费下载链接】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 的实时同步通知、文档处理状态、聊天消息与评论等由 Rocicorp Zero 驱动它运行一个zero-cache服务通过 PostgreSQL逻辑复制logical replication把变更流式同步到本地 SQLite 副本再经 WebSocket 推给浏览器。逻辑复制对 PostgreSQL 有两条硬性要求数据库必须设置wal_level logical连接数据库的用户必须拥有REPLICATION权限用于创建逻辑复制槽。本文针对在自己管理的 PostgreSQL本地安装或托管数据库上部署 SurfSense 的场景给出这两项的完整配置方法、zero_publication前置步骤和逐条验证方式。如果你使用仓库自带的完整 Docker 部署docker/postgresql.conf已包含wal_level logical默认surfsense用户是 superuser、自动拥有所需权限一般无需额外配置参见文末说明。前提条件按 手动安装指南 的 What Youll Need本场景涉及的组件要求PostgreSQL 14并安装pgvector扩展数据库Docker—— 用来运行 zero-cache实时同步服务器Python 3.12与uv—— 运行数据库迁移创建 zero-cache 所需的zero_publication已克隆仓库并完成surfsense_backend的环境配置.env中设置 PostgreSQL 连接串与 JWT secret。本地 PostgreSQL在 postgresql.conf 中设置 wal_level logicalwal_level logical必须写入 PostgreSQL 配置文件并重启数据库才能生效。编辑postgresql.conf文档给出的典型位置Linux/etc/postgresql/version/main/postgresql.confmacOSHomebrew/usr/local/var/postgres/postgresql.confWindowsC:\Program Files\PostgreSQL\version\data\postgresql.conf设置以下三个参数与 SurfSense 仓库随 Docker 部署挂载的 docker/postgresql.conf 中为 Zero 逻辑复制设置的值一致wal_level logical max_replication_slots 10 max_wal_senders 10保存后重启 PostgreSQL。注意重启会中断该实例上的所有数据库连接生产环境请在维护窗口执行。各平台的重启命令# Linux sudo systemctl restart postgresql# macOS (Homebrew) brew services restart postgresql# Windows (PowerShell, 将 17 替换为你的主版本号) Restart-Service postgresql-x64-17验证wal_level是否已生效psql -U postgres -d surfsense -c SHOW wal_level; # Should return: logical返回值为logical说明第一步完成如果仍是其他值说明配置未保存或未重启先排查这一项再继续。托管数据库启用逻辑复制并授予 REPLICATION 权限在 RDS、Supabase、Cloud SQL 等托管数据库上postgresql.conf通常由服务商管理改法是两条通过服务商的参数组启用逻辑复制例如 RDS 上设置rds.logical_replication1给应用用户授予REPLICATION权限。文档给出的授权语句surfsense为示例中的数据库名与用户名替换为你环境中的实际值ALTER USER surfsense WITH REPLICATION; GRANT CREATE ON DATABASE surfsense TO surfsense;文档中对两个权限的用途有明确说明REPLICATION允许 zero-cache 创建逻辑复制槽logical replication slot来流式接收变更CREATE允许 zero-cache 在其元数据所在的内部 schemazero、zero_0中创建对象。仓库自带的 Docker 部署里默认surfsense用户是 PostgreSQL superuser这两项自动满足托管库上应用用户往往不是 superuser才需要显式授予。创建 zero_publication启动 zero-cache 的前置步骤逻辑复制只解决“变更怎么流”zero-cache 复制哪些表则由 PostgreSQL publication 限定——SurfSense 使用名为zero_publication的 publication它由数据库迁移创建# 在 surfsense_backend/ 目录下执行 uv run alembic upgrade head这一步不能跳过。文档明确说明缺少zero_publication时zero-cache 会陷入 crash-loop日志报Unknown or invalid publications. Specified: [zero_publication]后端/ready探针也会因校验不到该 publication 而返回 503。验证 publication 已创建psql -U postgres -d surfsense -c SELECT pubname FROM pg_publication; # Should include: zero_publication查询结果包含zero_publication即可继续。启动 zero-cache 容器wal_level与权限配置就绪后用官方镜像启动 zero-cache。文档给出 Linux/macOS 命令ZERO_QUERY_URL/ZERO_MUTATE_URL指向前端地址生产/自定义域名场景按文档说明改为你的公网前端 URLdocker run -d --name surfsense-zero-cache \ -p 4848:4848 \ --add-hosthost.docker.internal:host-gateway \ -e ZERO_UPSTREAM_DBpostgresql://postgres:postgreshost.docker.internal:5432/surfsense?sslmodedisable \ -e ZERO_CVR_DBpostgresql://postgres:postgreshost.docker.internal:5432/surfsense?sslmodedisable \ -e ZERO_CHANGE_DBpostgresql://postgres:postgreshost.docker.internal:5432/surfsense?sslmodedisable \ -e ZERO_REPLICA_FILE/data/zero.db \ -e ZERO_ADMIN_PASSWORDsurfsense-zero-admin \ -e ZERO_APP_PUBLICATIONSzero_publication \ -e ZERO_NUM_SYNC_WORKERS4 \ -e ZERO_UPSTREAM_MAX_CONNS20 \ -e ZERO_CVR_MAX_CONNS30 \ -e ZERO_QUERY_URLhttp://host.docker.internal:3000/api/zero/query \ -e ZERO_MUTATE_URLhttp://host.docker.internal:3000/api/zero/mutate \ -e ZERO_QUERY_FORWARD_COOKIEStrue \ -v surfsense-zero-cache:/data \ rocicorp/zero:1.6.0Windows 上的等价命令使用 PowerShell 反引号续行其余参数相同。文档明确列出的两处替换将三个*_DB连接串中的postgres:postgres换成你的实际数据库用户与密码——这就是上一步授予REPLICATION权限的那个用户Linux 上没有 Docker Desktop 时host.docker.internal可能无法解析保留--add-hosthost.docker.internal:host-gatewayDocker 20.10或将host.docker.internal替换为主机 IP / 改用--networkhostlocalhost。验证结果按文档给出的顺序确认整条链路zero-cache 存活检查curl http://localhost:4848/keepalive # Should return HTTP 200复制日志检查docker logs -f surfsense-zero-cache文档要求确认“initial replication completed without errors”初始复制完成且无错误而不规定某条固定日志。端到端确认打开前端并登录创建 workspace 并上传文档观察上传状态无需刷新页面即实时更新——文档以此为标准判定 zero-cache 接线正确。前端不在 Docker 捆绑 Caddy 之后时如本地pnpm dev需先设置NEXT_PUBLIC_ZERO_CACHE_URLhttp://localhost:4848并核对surfsense_web/.env中的 zero-cache URL 与正在运行的 zero-cache 地址一致。故障排查与限制现象文档给出的处理wal_level不是logicalzero-cache 无法复制按上文修改postgresql.conf重启 PostgreSQL用SHOW wal_level;复核zero-cache crash-loop报Unknown or invalid publications. Specified: [zero_publication]说明跳过了uv run alembic upgrade head在surfsense_backend/补跑后再docker restart surfsense-zero-cache实时更新不生效、UI 数据过期先确认curl http://localhost:4848/keepalive返回 200再看浏览器 DevTools → Console 有无 WebSocket 错误最后核对前端.env中 zero-cache URL 是否与运行地址一致后端/ready返回 503就绪探针在检查zero_publication是否存在同样补跑uv run alembic upgrade headzero-cache 崩溃并报_zero.tableMetadata错误上次运行遗留了构建到一半的 SQLite 副本。下面命令会删除容器并清空其数据卷zero.db 副本下次启动从零重建副本请知悉后再执行docker rm -f surfsense-zero-cache docker volume rm surfsense-zero-cache然后重新执行启动命令两个边界限制来自文档重启后数据暂旧zero-cache 启动时会从 PostgreSQL 重建 SQLite 副本大库需要一段时间期间表现为“stale data after restart”属文档描述的预期行为高核机器连接数ZERO_NUM_SYNC_WORKERS默认取 CPU 核数可能超出连接池上限而报 Insufficient upstream connections。处理方式是调低ZERO_NUM_SYNC_WORKERS或调高ZERO_UPSTREAM_MAX_CONNS/ZERO_CVR_MAX_CONNS。可选路径让 Docker 托管 PostgreSQL本地开发时仓库提供了 docker/docker-compose.deps-only.yml由 Docker 同时管理 Postgres、Redis 和 zero-cache而 backend 与 frontend 仍在本机运行。前提不变先在宿主机完成迁移保证zero_publication已存在否则 zero-cache 会 crash-loopcd surfsense_backend uv run alembic upgrade head cd ../docker docker compose -f docker-compose.deps-only.yml up -d该栈把 zero-cache 暴露在4848端口随后在前端.env中设置NEXT_PUBLIC_ZERO_CACHE_URLhttp://localhost:4848变量说明见surfsense_web/.env.example注释。完整 Docker 部署docker/docker-compose.yml则无需本文的前两项配置db服务以command: postgres -c config_file/etc/postgresql/postgresql.conf启动并挂载了已含wal_level logical的 docker/postgresql.confcompose 中的migrations服务会在 zero-cache 启动前执行alembic upgrade head并校验zero_publication迁移失败会直接阻断整个栈启动而不是让 zero-cache 顶着漂移的 publication 运行。【免费下载链接】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），仅供参考
