部署源真相与发布边界

1. 唯一编辑源

类型	唯一编辑源	生成/发布副本	规则
后端	`app/`	`deployment/app/`	禁止直接修复发布副本
数据库脚本	`database/`	`deployment/database/`	先改源脚本，再同步
后端入口	根目录 `wsgi.py`	`deployment/wsgi.py`	两者使用同一 `app.create_app`
前端	`frontend/src/`	`frontend/dist/`	`dist/` 只由构建生成
本地容器	`deploy/docker/`	Docker image/volume	不复用生产容器和卷

app/ 为唯一后端源码。历史上 deployment/app/ 中仍有效的修复已经合并回 app/；此后只允许通过 bash deployment/sync_release.sh 生成发布副本。

2. 变更流

flowchart LR
    APP["app/"] --> TEST["Python tests"]
    DB["database/"] --> TEST
    FE["frontend/src/"] --> BUILD["npm production build"]
    TEST --> SYNC["deployment/sync_release.sh"]
    APP --> DOCKER["local Docker build"]
    DB --> DOCKER
    BUILD --> IMAGE["frontend image"]
    SYNC --> RELEASE["deployment/ 发布包"]

发布门禁：

python -m pytest -q
python -m compileall -q app
npm --prefix frontend run build
bash deployment/sync_release.sh
diff -qr app deployment/app
diff -qr database deployment/database
git diff --check

3. 环境配置

DeepSeek 是当前唯一默认生成模型提供方；密钥只来自环境变量或密钥管理系统。
Qwen 仅用于下一阶段 embedding，不替代 DeepSeek 的生成模型职责。
N8N_API_URL 和 N8N_API_KEY 必须显式配置；缺失时失败关闭，不得回退线上地址。
PostgreSQL、Neo4j、MinIO 默认值仅允许 localhost 开发值；生产发布必须显式注入。
.env.local、密钥、数据库卷和构建日志不得提交。

4. 全本地隔离测试栈

deploy/docker/docker-compose.yml 使用独立项目网络和命名卷启动 PostgreSQL、Neo4j、MinIO、n8n、后端与前端。验证地址与命令见本地环境指南。

隔离约束：

配置中不得出现生产域名、IP 或提交过的 API Key。
本地 PostgreSQL 初始化只使用 database/ 当前脚本和本地验收用户。
本地卷只属于 dataops-test Compose 项目。
模型外联是可选能力；不配置密钥时不得影响基础冒烟测试。
n8n 首次 owner 初始化和 API Key 只存在本地环境。

5. 数据库变更与回滚

本轮删除旧 SQL 文件不授权删除生产表。
下一阶段先引入带版本号的数据库迁移，禁止继续依赖“首次启动自动重放全部 SQL”。
每个迁移包含前置检查、向前迁移、数据验证和可逆回滚说明。
跨 PostgreSQL/Neo4j/MinIO/n8n 变更使用 outbox、幂等消费者和巡检任务；不伪装成单机事务。
发布回滚优先回滚应用镜像；数据库回滚必须单独评估数据兼容性。

DEPLOYMENT_SOURCE_OF_TRUTH.md 2.9 KB Историја Датотека