Files

Script Generator 4fc66345f1 docs(deploy): 设计本地云端单主数据源

2026-07-02 13:56:47 +08:00

6.2 KiB

Raw Blame History

本地服务器与云服务器单主数据源设计

背景

当前生产部署使用 docker-compose.prod.yml，云服务器的数据写入 postgres_data、redis_data、server_data 三个 volume。本地服务器部署使用 docker-compose.local.yml，数据写入 local_postgres_data、local_redis_data、local_server_data 三个独立 volume。

这意味着本地服务器和云服务器默认是两套数据。本地服务器新增或修改产品、项目、版本、任务、测试用例、Bug 后，云服务器不会自动更新。

用户确认本地和云端都会做备份，因此在线业务不需要两套独立主库。备份用于灾备，在线写入源应保持唯一。

目标

云服务器 PostgreSQL 作为唯一业务主数据源。
本地服务器访问和修改的业务数据与云服务器一致。
本地服务器上的写入立即落到云端主库，云端打开后能看到同一份数据。
保留本地服务器备份能力，但默认不把本地 PostgreSQL 当作业务写入库。
避免双主同步、定时合并、手工覆盖等高风险机制。

非目标

不做本地数据库和云端数据库的双向同步。
不支持离线写入后再自动合并到云端。
不把云端 PostgreSQL 裸露到公网。
不在本次改动中迁移 AI Provider 配置文件到数据库。

部署配置设计

1. 新增本地共享主库 env 示例

新增 .env.local-server.cloud-data.example，用于说明本地服务器连接云端主库时应填写的配置。

关键字段：

DATABASE_URL：云端 PostgreSQL 连接串，推荐通过 VPN、专线、内网穿透或 SSH tunnel 暴露给本地服务器。
NEXT_PUBLIC_API_URL=/api/v1：本地浏览器仍访问本地 Nginx。
NEXTAUTH_URL：本地服务器访问地址，例如 http://192.168.1.50:8080。
REDIS_URL=redis://redis:6379：Redis 可继续本地运行，当前业务主数据不依赖 Redis 持久化同步。

2. 调整本地 Compose 的数据库依赖

docker-compose.local.yml 当前强制启动并依赖本地 postgres。这会让本地部署天然变成另一套业务数据。

调整后：

postgres 改为可选 profile，例如 profiles: ['local-db']。
server.depends_on 不再强依赖 postgres，只保留对 redis 的健康依赖。
默认本地服务器部署要求显式提供 DATABASE_URL。
如果确实要跑完全离线的本地演示库，可以通过 profile 启动本地 Postgres。

预期命令：

# 本地服务器连接云端主库
docker compose --env-file .env.local-server.cloud-data -f docker-compose.local.yml up -d

# 完全本地演示库
docker compose --env-file .env.local-server -f docker-compose.local.yml --profile local-db up -d

3. 更新部署文档

docs/deployment.md 增加“本地服务器连接云端主库”章节，明确：

推荐模式是云端单主库。
本地服务器默认不应使用独立业务库。
本地和云端备份是灾备，不是双主同步。
云端数据库连接必须走安全通道。

docs/architecture.md 更新生产部署边界，说明本地服务器可作为云端主库的第二个应用入口。

docs/decisions.md 增加设计决策：在线业务数据采用单主数据源，不做双主同步。

docs/workflow.md 更新部署流程，避免用户把本地服务器误当成独立生产库。

安全边界

推荐连接方式按优先级排序：

VPN 或组网工具，使本地服务器通过私网访问云端数据库。
SSH tunnel，只在本地服务器和云服务器之间建立转发。
云安全组只允许本地服务器固定公网 IP 访问数据库端口。

不推荐：

PostgreSQL 5432 对公网开放给任意来源。
多台服务器共享同一个弱密码数据库账户。
在 Git 中提交真实 DATABASE_URL、数据库密码或 AI Key。

备份策略

备份保留两地：

云端定期备份主库。
本地定期拉取云端主库备份或保存导出的快照。

备份文件不参与实时业务写入。发生故障时由人工选择某个备份恢复为新的主库，恢复前先停止其他写入入口，避免恢复期间出现新的分叉。

数据一致性与冲突

因为只有云端 PostgreSQL 是主库，本地和云端不会出现数据库级双写冲突。

应用层仍保留现有 app_data 乐观锁：

多个用户同时修改同一个业务文档时，后端返回 409 APP_DATA_CONFLICT。
前端不自动覆盖服务端新版本。

该机制继续处理多人同时编辑，而不是处理两套数据库同步。

验证方式

完成实现后需要验证：

本地服务器启动后，curl http://localhost:8080/api/v1/config/ai 返回 200。
本地服务器创建一条业务数据，例如产品或任务。
云服务器页面刷新后能看到同一条数据。
云服务器修改同一条数据后，本地服务器刷新能看到变化。
停止本地 postgres 容器后，本地服务器仍能读写业务数据。
pnpm deploy:verify 通过。
前端和后端类型检查通过。

风险与处理

云端主库不可达时，本地服务器不能写业务数据。这是单主设计的预期行为，错误信息应通过现有 API 失败提示暴露。
如果本地仍误启独立 Postgres 且 DATABASE_URL 指向它，会再次形成两套数据。文档和 env 示例必须把默认推荐改成云端主库。
AI Provider 配置当前仍是 server volume 文件。本地和云端 AI 配置可能不一致；这是本次非目标。后续如果需要，也应把 AI 配置迁入数据库或明确只在云端维护。

6.2 KiB Raw Blame History Unescape Escape