101 lines
4.6 KiB
Markdown
101 lines
4.6 KiB
Markdown
# volcengine-102 正式线部署指南
|
||
|
||
**状态**：已部署并通过正式域名验收（最后验证：2026-08-11）。
|
||
**Compose**：`deploy/volcengine-102/docker-compose.yml`
|
||
**入口脚本**：`scripts/deploy-volcengine-102.sh`
|
||
|
||
## 1. 正式入口与流量路径
|
||
|
||
- 正式地址：<https://agenteval.solahqb22.cn/>
|
||
- DNS：`agenteval.solahqb22.cn` A 记录指向 `47.111.21.147`（`sola-aliyun-147`）。
|
||
- HTTPS：147 Nginx 终止 TLS，并反代到 `101.96.206.102:8002`（`sola-volcengine-102`）。
|
||
- WebSocket：Nginx 为 `/ws` 和 `/openclaw` 配置 HTTP/1.1 Upgrade。
|
||
- 网络边界：102 的 `8002` 仅允许 `47.111.21.147/32` 访问，公网直连超时属于预期行为。
|
||
- 证书：Let's Encrypt，实测有效期为 2026-07-20 至 2026-10-18；147 的 `certbot.timer` 已启用并处于 active 状态。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Browser[浏览器] -->|HTTPS 443| DNS[agenteval.solahqb22.cn]
|
||
DNS --> Nginx[aliyun-147 Nginx]
|
||
Nginx -->|HTTP 8002，仅白名单| App[volcengine-102 AgentEval]
|
||
App --> OpenClaw[openclaw-eval]
|
||
```
|
||
|
||
## 2. 部署边界
|
||
|
||
正式线使用两个容器：`agenteval`（端口 `8002`）和 `openclaw-eval`（端口 `28789`）。SQLite 数据保存在 Docker named volume 中；生产 `.env` 不从代码仓库同步，必须预先放在远端：
|
||
|
||
```text
|
||
/opt/sola/AgentEvalTool/deploy/volcengine-102/.env
|
||
```
|
||
|
||
环境变量模板见 [`deploy/volcengine-102/.env.example`](../../deploy/volcengine-102/.env.example)。API Key、OpenClaw token 和 webhook secret 不得写入 Git；正式域名和公开网络拓扑应记录在本指南中。
|
||
|
||
## 3. 首次准备
|
||
|
||
在正式主机完成 Docker/Compose、SSH 和镜像仓库访问配置，然后建立远端目录并准备 `.env`。本地只需要配置 SSH 别名或地址：
|
||
|
||
```bash
|
||
export AGENTEVAL_PROD_HOST=sola-volcengine-102
|
||
export AGENTEVAL_PROD_DIR=/opt/sola/AgentEvalTool
|
||
export AGENTEVAL_PROD_BACKUP_DIR=/var/backups/agenteval
|
||
```
|
||
|
||
首次正式发布前必须确认：
|
||
|
||
- 生产 `.env` 已填写非空 `AGENTEVAL_API_KEY`、`AGENTEVAL_SECRET_KEY` 和 OpenClaw token。
|
||
- 生产域名已加入 `AGENTEVAL_ALLOWED_ORIGINS`。
|
||
- 正式主机可拉取 `registry.solahqb22.cn/sola/openclaw:latest`。
|
||
- Docker named volume 和备份目录具备写权限。
|
||
|
||
## 4. 发布流程
|
||
|
||
发布必须基于已提交的 Git 版本；脚本会拒绝存在 tracked 未提交修改的工作区。推荐使用版本号加 commit 作为不可变镜像标签：
|
||
|
||
```bash
|
||
scripts/deploy-volcengine-102.sh --dry-run --tag 0.8.0-6248568
|
||
scripts/deploy-volcengine-102.sh --tag 0.8.0-6248568
|
||
```
|
||
|
||
脚本依次执行：SSH 检查 → 版本读取 → 远端 `.env` 检查 → 通过 `git archive HEAD` 生成并同步已提交源代码 → 备份数据 volume → 远端构建带版本元数据的镜像 → 启动双容器 → 等待健康接口 → 校验版本/commit → 鉴权 API 冒烟。
|
||
|
||
后端启动入口 [`scripts/production-entrypoint.sh`](../../scripts/production-entrypoint.sh) 的规则是：
|
||
|
||
- 全新数据库：创建初始 SQLModel schema，记录当前 Alembic 基线，再执行后续迁移。
|
||
- 旧版无 `alembic_version` 的数据库：保留旧数据，标记为 pre-Alembic base，再依次执行全部迁移。
|
||
- 已有 Alembic 版本的数据库：只执行 `alembic upgrade head`。
|
||
|
||
## 5. 回滚
|
||
|
||
回滚只切换应用镜像，不自动降级数据库：
|
||
|
||
```bash
|
||
scripts/deploy-volcengine-102.sh --rollback 0.8.0-previous
|
||
```
|
||
|
||
每次发布和回滚前都会在远端备份 named volume 到 `AGENTEVAL_PROD_BACKUP_DIR`。如果某个版本包含不可逆数据迁移，应先停止服务、恢复匹配的数据备份，再启动旧镜像；不得只回滚代码而忽略数据库版本。
|
||
|
||
## 6. 发布后检查
|
||
|
||
```bash
|
||
ssh "$AGENTEVAL_PROD_HOST" \
|
||
'cd /opt/sola/AgentEvalTool && docker compose -f deploy/volcengine-102/docker-compose.yml ps'
|
||
```
|
||
|
||
至少通过正式域名验证：`/api/health`、`/api/targets`、`/api/scenarios`、`/api/runs`、`/api/campaigns`、`/api/intelligent-evals`、`/api/model-configs` 和 `/openclaw/`。`/ws` 应返回 `101 Switching Protocols`。发现异常时保留部署输出、容器日志和备份文件，再执行回滚判断。
|
||
|
||
## 7. 线路关系
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Commit[已提交 Git 版本] --> Dev[scripts/deploy-t480.sh]
|
||
Dev --> DevCheck[t480 健康检查与业务冒烟]
|
||
DevCheck --> Tag[Gitea Tag / 发布审批]
|
||
Tag --> Prod[scripts/deploy-volcengine-102.sh]
|
||
Prod --> Backup[备份 named volume]
|
||
Backup --> Migrate[Alembic upgrade head]
|
||
Migrate --> Smoke[正式线 API / OpenClaw 冒烟]
|
||
Smoke --> Live[正式服务]
|
||
Smoke --> Rollback[旧镜像 + 数据备份恢复]
|
||
```
|