Zyy
f7f59103a3
Preserve request evidence and cold middleware boundaries across cancellation. Make backup auditing atomic, retain committed account-group results, and serialize restart operations. Unify frontend stream authentication and session recovery, clear stale secrets, and remove redundant runtime paths. Correct CI permissions and database test URL handling. Align documentation with current module responsibilities, APIs, and validation workflows, including both submodules.
3.9 KiB
数据库迁移
sqlx 在服务启动、监听请求之前按编号执行迁移，并把文件 checksum 记入 _sqlx_migrations。
已应用迁移的字节与记录不一致时，服务会拒绝启动
迁移按递增编号组织，完整清单以本目录 SQL 文件和 .frozen-sha256 为准。
业务状态与存储职责见状态所有权，离线恢复见部署文档
命名约定
- 表名使用小写
snake_case，实体集合使用复数，配置与单例状态使用自然语义，如runtime_settings、request_analytics_build_state - 业务归属使用领域前缀，同一实体统一使用
client_api_key、account_group、provider等术语，不添加tbl_等对象类型前缀 - 统计时间粒度使用
15m、1h、1d；只保存计数的表保留_counts后缀 - 表名调整时同步查询、函数体及所属索引和约束名称，已冻结迁移仍保持原样
冻结规则
- 同一大版本内，已合入 main 的迁移文件按字节永久冻结，包括注释和空白。schema 变更及错误修正都须新增编号迁移，使用
alter或回填补偿；修改原文件会导致已部署实例重启时 checksum 失配，且没有自动恢复路径 - 跨大版本不支持在线升级，目标版本必须使用全新数据目录部署；此时可将已完成升级的 schema 折叠为新的初始化基线
- 支持连续升级的预发行线从首次发布起同样冻结迁移。alpha、beta、rc 到对应正式版必须保留 已发布迁移的编号与字节；同一轮 exp 的后续发行也只能追加迁移。发布前以该发行线已发布版本 的数据库验证升级路径，不能只与上一正式版比较。不同 exp 实验线之间、exp 与正式版之间 不保证迁移历史兼容
.frozen-sha256使用sha256sum格式。新增迁移时在同一提交执行sha256sum 000N_xxx.sql >> .frozen-sha256入册；CI 校验文件字节、SQL 登记完整性及 PR 中清单只增不改
从迁移目录检查已登记文件：
cd backend/migrations
sha256sum --check --strict .frozen-sha256
遇到 checksum 不一致，先核对运行版本和文件来源；不要修改数据库中的 checksum 来绕过校验
本地测试库
gateway-store 的 PostgreSQL/Redis 集成测试使用以下环境变量；所需测试服务未配置时，本地相关测试跳过，CI 直接失败：
export CPR_TEST_DATABASE_URL='postgres://<user>:<password>@127.0.0.1:5432/<db>'
export CPR_TEST_REDIS_URL='redis://:<password>@127.0.0.1:6379'
插件 Runtime 的真实子进程与持久化测试优先使用 CPR_PLUGIN_TEST_DATABASE_URL 和
CPR_PLUGIN_TEST_REDIS_URL。设置插件数据库变量时必须同时提供对应 Redis 变量；未设置插件数据库变量时，
使用上述标准测试服务。两种配置遵守相同的密码与隔离要求；缺少服务时的跳过和 CI 失败规则也相同
测试自建随机 schema / key 前缀做隔离，但仍应使用专用开发或测试实例，不要连接生产库。
凭据从自己的部署配置或 CI Secret 中读取，不要粘贴未脱敏的 docker inspect 输出。
环境变量未设置导致的跳过不算数据库测试通过
PostgreSQL 的临时 schema 测试连接使用异步提交，保留事务可见性、回滚和完整迁移检查 需要验证数据库崩溃后的持久性时，使用独立数据库与生产连接配置，不复用这类 fixture
运行包含 StoreBundle 初始化的完整集成测试时，两条测试 URL 都须包含密码，原始密码须满足
Store 密码要求，在测试 URL 中按 URL 规则编码。
仅能连接数据库并不代表该初始化合同通过。专用服务使用对应测试密码，
并在测试进程中清除 CPR_DATABASE_URL、CPR_REDIS_URL、CPR_DATABASE_PASSWORD 和
CPR_REDIS_PASSWORD，避免启动配置被部署环境覆盖