# Doodle Store v3.5 开发与部署环境

> 更新日期：2026-10-12。
>
> 已确认：PostgreSQL 本地 Docker 开发环境；图片等资源直接使用七牛。

本地验证结果：PostgreSQL 18.6 已启动并通过健康检查，UTF-8 / UTC，密码 TCP 登录成功；NULL exportId 唯一键和大小写匹配行为通过临时表事务验证，检查后已回滚。随后已在用户授权下正式初始化 doodle_dev，public 下业务表共 10 张，current 配置和 homeAutoRefresh 开关已创建。Prisma 与七牛业务接入尚未实施。

> 首期建议：云服务器只常驻生产数据库，不长期部署第二套测试系统；真实微信联调和迁移演练按需开独立测试环境。本次未修改云服务器或配置七牛账户。

## 1. 首期安排

当前项目用户少、后端以 CRUD 为主，已有服务器为 2 核 4 GB。采用本地开发 + 单套线上生产即可起步；上线前仍在隔离数据库完成迁移验证，不拿生产库做自动测试或试导。

| 场景                      | 应用                                        | 数据库                                                                    | 资源                                         |
| ------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
| 日常开发                  | 本机 NestJS watch 模式                      | 本机 Docker PostgreSQL / doodle_dev                                       | 七牛开发资源空间或 dev 前缀                  |
| 数据库自动测试            | 本机测试进程                                | 本机同实例内独立 doodle_test，后续按需创建                                | 测试替身；需要真实上传验证时使用七牛开发资源 |
| 微信体验版联调 / 迁移演练 | 按需部署测试 API，独立 HTTPS 域名及环境变量 | 先在本机试导；真实云端联调时同一云端 PostgreSQL 实例内独立 doodle_staging | 七牛测试资源，禁止覆盖生产对象               |
| 正式用户                  | 云服务器生产 API                            | 云服务器 PostgreSQL / doodle_prod                                         | 七牛生产资源                                 |

**目前无需在云端常驻生产和测试两个数据库，更无需两个 PostgreSQL 容器。** 当云端联调确有需求时，同一 PostgreSQL 实例创建独立 staging 库和独立登录角色即可；测试 API 用另一端口/域名连接 staging，验收后停止测试进程并按保留规则归档临时库。单独数据库主要提供数据与权限隔离，仍共享实例 CPU/内存；试导控制并发，不与生产高峰争抢资源。

微信体验版与正式版不是两个独立 AppID，后端地址须根据客户端版本环境配置。独立测试 API 不接生产库、不使用生产登录 token 签名密钥，生产配置也不回退到测试地址。测试角色不能访问生产库，需通过 PostgreSQL 库级 CONNECT 权限及 schema/对象权限验证；不只依赖连接串约定。

以下情况出现后再考虑长期 staging：连续有真实微信联调需求；频繁修改数据库；新支付、会员或服务端生成流程；多人并行开发；数据规模导致一次迁移演练需要长时间。首期按实际需求启用，避免预先复制完整部署。

## 2. 本地 Docker

参考项目 `/Users/joey-xd/sites/seller-store/atlas-seller-kit/infra/compose.yaml` 使用 PostgreSQL 容器、应用宿主机运行和命名卷持久化。本项目复用这种方式，数据库独立，未修改参考项目。

- Compose 文件：[infra/compose.yaml](../../infra/compose.yaml)。
- 固定镜像：`postgres:18.6-alpine`，与参考项目保持一致；生产部署前验证并固定同一兼容主版本。
- 默认地址：`127.0.0.1:5434`；数据库和用户均为 `doodle_dev`。
- 数据卷挂载 `/var/lib/postgresql`，适配 PostgreSQL 18 的版本子目录布局。
- 使用 UTF-8、C locale 和 UTC；业务任务仍明确采用 Asia/Shanghai。
- 根 `.env` 保存 Compose 配置，服务端连接串保存在 `apps/server/.env`；真实文件均被 Git 忽略。
- 本地已完成 10 张表及初始配置的创建；Prisma 与业务接入后续按 [数据库设计文档](./数据库设计文档.md) 实施。

使用步骤及 SQL 客户端连接见 [infra/README](../../infra/README.md)。本地故障和试导不会写入生产库；数据导入脚本后续应增加目标环境识别、dryRun 和生产写入保护。

## 3. 七牛直接使用与最小隔离

图片、头像、预览、字体及其他对象文件直接使用七牛；本地 PostgreSQL 只保存 assets 元数据与对象引用。开发无需仿真对象存储，不将图片存数据库或容器数据卷。上传 API 与七牛凭证尚待业务模块实施，本次不创建空间或上传文件。

尽量复用同一七牛账户与现有资源域名。访问策略保持公共预览/字体与私有头像区分，空间是否复用取决于现有空间访问属性。生产与开发至少使用不同对象 key 前缀，例如：

```text
prod/previews/<资产ID>/preview.png
prod/avatars/<用户ID>/<资产ID>.png
dev/previews/<资产ID>/preview.png
dev/avatars/<测试用户ID>/<资产ID>.png
staging/...
```

前缀由服务端环境配置生成，客户端不能指定 prod；资源 key 不因重试或重新发布覆盖已有文件。开发可以读取既有公共生产预览/字体，开发上传及删除只作用于 dev/staging；测试私有头像使用测试文件。清理任务同样限制环境和前缀，不能跨环境扫描后删除未在本地数据库引用的生产对象。

**前缀主要防操作混用，不是七牛账户 AK/SK 的权限边界。** 个人首期开发可采用前缀隔离、服务端限制和受控密钥文件；涉及多人开发或自动删除时，应使用能实际限制开发权限的独立凭证/空间。若现有账号权限无法按所需范围限制，则创建独立开发空间及相应权限，不能把改空间名当作凭证权限已经隔离。

七牛配置只放服务端环境变量，包含访问凭证、公共/私有空间、资源域名和环境前缀；具体变量在 assets 模块接入时落实。数据库不保存过期签名 URL；私有资源由 API 按需生成地址。普通小程序用户不能获取账户 AK/SK。

## 4. 上线前最低流程

1. 在本机完成业务检查、数据库事务验证和全量 dryRun/试导，对账正常、合并、隔离及文件映射。
2. 需要微信真实 HTTPS 联调时，临时部署独立测试 API 与 staging 库，体验版用测试数据完成真机验收；测试数据库可用脱敏快照，原始导出只在受控迁移位置处理。
3. 正式迁移前备份生产及旧数据，停止旧任务和写入；按迁移方案最终导入、核对后切换到唯一生产库。
4. 正式 API、定时任务与兼容桥只写 doodle_prod；测试任务关闭，测试上传不进入生产资源前缀。
5. 生产数据库每日备份到服务器之外并演练恢复；生产更新保留上一可运行 API 版本。测试库不充当生产备份。

上述安排保持一套长期生产系统，临时测试仍有明确数据边界，后续需求增加时再扩展部署。切换和回滚详细步骤继续以 [云服务端迁移方案](../云服务端迁移方案.md) 为准。