开发、验证与 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，并设置开机启动。
本版云端 Compose 的前后端端口均只绑定 ECS 的 127.0.0.1，不在安全组开放 80/8002。原始聊天有通用文件与工具权限，目前仅供 SSH 隧道访问；如需公网访问，必须先配置身份认证、HTTPS 和接口访问控制，不能直接移除本机访问限制。
把 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 连接
# 使用本地已验证的同一模型网关时，还需设置相同 MODEL/BASE_URL 及 CHAT_THINKING_MODE=disabled
docker login --username=<ACR登录名> <ACR Registry域名>
bash scripts/deploy-aliyun.sh

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

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 和数据备份策略符合目标环境。

4.0 KiB Raw Blame History Unescape Escape