eryao/deploy/README.md

觅爻生产部署指南

目录说明

deploy/ 用于存放生产环境启动所需文件：

• docker-compose.prod.yml：生产 Docker Compose 启动配置，只拉取已有镜像，不负责构建。
• .env：生产环境变量文件，本文件包含敏感信息，不应提交到 Git。

前置条件

生产机器需要安装：

• Docker
• Docker Compose v2
• AWS CLI v2

确认命令：

docker --version
docker compose version
aws --version

环境变量

docker-compose.prod.yml 默认从当前目录读取 .env：

deploy/.env

必须包含 AWS ECR 镜像定位变量：

AWS_ACCOUNT_ID=<你的 AWS 账号 ID>
AWS_REGION=<ECR 所在区域>
ECR_REPOSITORY=<ECR 仓库名>

如果本目录下的 .env 是从项目根目录 .env 复制过来的，通常还需要手动追加以上三个变量。

默认镜像地址会拼接为：

${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${ECR_REPOSITORY}:latest

如果要手动指定完整镜像地址，可以在 .env 中设置：

ERYAO_BACKEND_IMAGE=<完整镜像地址>

Web 服务端口使用项目环境变量：

ERYAO_WEB__PORT=5775

默认只绑定本机回环地址：

ERYAO_DEPLOY_BIND_HOST=127.0.0.1

如果生产机器没有 Nginx、ALB 或其他反向代理，需要直接对外暴露端口，可改为：

ERYAO_DEPLOY_BIND_HOST=0.0.0.0

登录 ECR

进入部署目录，并把 .env 加载到当前 shell：

cd deploy
set -a
. ./.env
set +a

在生产机器上配置好 AWS 凭据后执行：

aws ecr get-login-password --region "$AWS_REGION" \
  | docker login --username AWS --password-stdin \
    "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

启动服务

启动 Web、Redis 和 worker：

cd deploy
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers pull
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers up -d

只启动 Web 和 Redis：

cd deploy
docker compose --env-file ./.env -f docker-compose.prod.yml up -d

健康检查

如果 ERYAO_WEB__PORT=5775：

curl http://127.0.0.1:5775/health

期望返回：

{"status":"ok"}

查看状态和日志

cd deploy
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers ps
docker logs -f eryao-prod-backend
docker logs -f eryao-prod-worker-agent
docker logs -f eryao-prod-worker-general
docker logs -f eryao-prod-redis

更新版本

CI 推送新镜像到 ECR 后，在生产机器执行：

cd deploy
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers pull
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers up -d

停止服务

cd deploy
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers down

如需连 Redis 数据卷一起删除：

cd deploy
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers down -v

谨慎使用 down -v，它会删除 Redis 持久化数据。