# 部署源真相与发布边界

## 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. 变更流

```mermaid
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/ 发布包"]
```

发布门禁：

```bash
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、后端与前端。验证地址与命令见 [本地环境指南](../../deploy/docker/README.md)。

隔离约束：

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

## 5. 数据库变更与回滚

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