volcengine-102 正式线部署指南

状态：部署流程已实现；正式主机与密钥仍需由运维环境注入。 Compose：deploy/volcengine-102/docker-compose.yml 入口脚本：scripts/deploy-volcengine-102.sh

1. 部署边界

正式线使用两个容器：agenteval（端口 8002）和 openclaw-eval（端口 28789）。SQLite 数据保存在 Docker named volume 中；生产 .env 不从代码仓库同步，必须预先放在远端：

/opt/agenteval/deploy/volcengine-102/.env

环境变量模板见 deploy/volcengine-102/.env.example。正式域名、API Key、OpenClaw token 和 webhook secret 不得写入 Git。

2. 首次准备

在正式主机完成 Docker/Compose、SSH 和镜像仓库访问配置，然后建立远端目录并准备 .env。本地只需要配置 SSH 别名或地址：

export AGENTEVAL_PROD_HOST=volcengine-102
export AGENTEVAL_PROD_DIR=/opt/agenteval
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 和备份目录具备写权限。

3. 发布流程

发布必须基于已提交的 Git 版本；脚本会拒绝存在 tracked 未提交修改的工作区。推荐使用版本号加 commit 作为不可变镜像标签：

scripts/deploy-volcengine-102.sh --dry-run --tag 0.8.0-6248568
scripts/deploy-volcengine-102.sh --tag 0.8.0-6248568

脚本依次执行：SSH 检查 → 版本读取 → 远端 .env 检查 → 同步已提交源代码 → 备份数据 volume → 远端构建带版本元数据的镜像 → 启动双容器 → 等待健康接口 → 校验版本/commit → 鉴权 API 冒烟。

后端启动入口 scripts/production-entrypoint.sh 的规则是：

全新数据库：创建初始 SQLModel schema，记录当前 Alembic 基线，再执行后续迁移。
旧版无 alembic_version 的数据库：保留旧数据，记录基线，再执行后续迁移。
已有 Alembic 版本的数据库：只执行 alembic upgrade head。

4. 回滚

回滚只切换应用镜像，不自动降级数据库：

scripts/deploy-volcengine-102.sh --rollback 0.8.0-previous

每次发布和回滚前都会在远端备份 named volume 到 AGENTEVAL_PROD_BACKUP_DIR。如果某个版本包含不可逆数据迁移，应先停止服务、恢复匹配的数据备份，再启动旧镜像；不得只回滚代码而忽略数据库版本。

5. 发布后检查

ssh "$AGENTEVAL_PROD_HOST" \
  'cd /opt/agenteval && 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/。发现异常时保留部署输出、容器日志和备份文件，再执行回滚判断。

6. 线路关系

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[旧镜像 + 数据备份恢复]

3.6 KiB Raw Blame History Unescape Escape