96 lines
4.0 KiB
Markdown
96 lines
4.0 KiB
Markdown
# 开发、验证与 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 和数据备份策略符合目标环境。
|