开发、验证与 Docker 部署流程

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

1. 本地修改

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

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

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

python scripts/verify.py

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

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

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

通过后创建可回滚提交：

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

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

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

$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，不要在脚本中硬编码密码。

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

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

5. 在阿里云 ECS 上运行

在 ECS 安装 Docker Engine 和 Compose V2，并设置开机启动。
安全组只开放需要的端口：前端默认 80；当前前端架构还需 8002 API 端口。正式 HTTPS 环境建议在两者之前增加 Nginx/SLB 同源反向代理。
把 deploy/ 和 scripts/deploy-aliyun.sh 复制到 ECS。
在 ECS 上登录 ACR，并创建私密配置：

cp deploy/aliyun.env.example deploy/aliyun.env
chmod 600 deploy/aliyun.env
# 编辑 APP_IMAGE、DEEPSEEK_API_KEY 和可选 ERP 连接
docker login --username=<ACR登录名> <ACR Registry域名>
bash scripts/deploy-aliyun.sh

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

发布门禁

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

3.2 KiB Raw Blame History Unescape Escape