# 开发、验证与 Docker 部署流程

这套流程把“修改—测试—证据—本地 Docker—阿里云”串成同一条可回滚链路。任何密钥只放在被 Git 忽略的环境文件中。

## 1. 本地修改

```powershell
git switch -c codex/<功能名>
git status --short
```

修改前先阅读 `AGENTS.md`，一次只处理一个需求。每个行为修改必须同时新增或更新对应的 `backend/test_*.py`；纯前端修改至少必须通过生产构建。

## 2. 生成测试计划、执行并保留证据

```powershell
python scripts/verify.py
```

验证器会根据 Git 变更文件生成测试计划，并执行：

1. Git diff 格式检查；
2. 全部后端 `unittest`；
3. Next.js 生产构建（包含 TypeScript 检查）；
4. 本地和阿里云 Compose 配置校验。

每次结果保存在 `test-evidence/<时间>-<commit>/`：`REPORT.md` 供人阅读，`summary.json` 供系统处理，每条命令有独立日志。该目录不提交 Git；GitHub Actions 会保留 30 天构建证据。

通过后创建可回滚提交：

```powershell
git add <本次文件>
git commit -m "feat: 说明修改与结果"
```

## 3. 本地 Docker 部署与真实容器验证

先启动 Docker Desktop，并确保本机 8002 端口没有原生后端占用。

```powershell
$env:DEEPSEEK_API_KEY="<key>"
python scripts/verify.py --docker --keep-docker
```

验证通过后：

- 前端：`http://localhost:3200`
- 后端健康检查：`http://localhost:8002/api/xingbang/health`
- 停止：`docker compose down`

去掉 `--keep-docker` 时，验证结束会自动停止容器，但保留证据。

## 4. 推送到阿里云 ACR

在 ACR 控制台创建实例、命名空间和镜像仓库，复制控制台给出的完整 Registry 域名。新版个人版通常为 `crpi-*.cn-<region>.personal.cr.aliyuncs.com`，不要在脚本中硬编码密码。

```powershell
docker login --username=<ACR登录名> <ACR Registry域名>
.\scripts\publish-acr.ps1 -Registry <ACR Registry域名> -Namespace <命名空间>
```

脚本只有在全部验证通过后才会构建和推送镜像，默认使用 Git 短 SHA 作为不可变版本标签。Linux/macOS 使用 `scripts/publish-acr.sh`。

## 5. 在阿里云 ECS 上运行

1. 在 ECS 安装 Docker Engine 和 Compose V2，并设置开机启动。
2. 本版云端 Compose 的前后端端口均只绑定 ECS 的 127.0.0.1，不在安全组开放 80/8002。原始聊天有通用文件与工具权限，目前仅供 SSH 隧道访问；如需公网访问，必须先配置身份认证、HTTPS 和接口访问控制，不能直接移除本机访问限制。
3. 把 `deploy/` 和 `scripts/deploy-aliyun.sh` 复制到 ECS。
4. 在 ECS 上登录 ACR，并创建私密配置：

```bash
cp deploy/aliyun.env.example deploy/aliyun.env
chmod 600 deploy/aliyun.env
# 编辑 APP_IMAGE、DEEPSEEK_API_KEY 和可选 ERP 连接
# 使用本地已验证的同一模型网关时，还需设置相同 MODEL/BASE_URL 及 CHAT_THINKING_MODE=disabled
docker login --username=<ACR登录名> <ACR Registry域名>
bash scripts/deploy-aliyun.sh
```

本机建立 SSH 隧道（将 `user@ecs-host` 换成实际 SSH 目标）：

```bash
ssh -N -L 3300:127.0.0.1:80 user@ecs-host
```

然后访问 `http://127.0.0.1:3300/`。如果改过 FRONTEND_PORT，同步修改隧道的目标端口。不要将本地 `.env`、真实会话、数据库、原始会谈资料打包进镜像；首次部署由代码内的最小模拟数据集初始化，云端已有数据卷须先备份并保留。Git 提交和镜像准备不等于部署完成，必须留存目标服务器的健康检查结果。

发布新版本时把 `APP_IMAGE` 改为新 SHA 标签，再执行部署脚本。回滚时把 `APP_IMAGE` 改回上一个 SHA 标签并重新执行，数据卷不会被删除。

## 发布门禁

- 没有 `REPORT.md` 或验证失败：不发布。
- 不使用 `latest`；镜像必须用 Git SHA 标签。
- 不把 `.env`、ACR 密码、DeepSeek Key 或 ERP 密码提交 Git。
- 发布前必须确认 CORS、身份认证、TLS 和数据备份策略符合目标环境。