zl-q
323 lines
7.4 KiB
Markdown
323 lines
7.4 KiB
Markdown
# 觅爻生产部署指南
|
||
|
||
## 目录说明
|
||
|
||
`deploy/` 用于存放生产环境启动所需文件：
|
||
|
||
- `docker-compose.prod.yml`：生产 Docker Compose 启动配置，只拉取已有镜像，不负责构建。
|
||
- `.env`：生产环境变量文件，本文件包含敏感信息，不应提交到 Git。
|
||
|
||
## 前置条件
|
||
|
||
生产机器需要安装：
|
||
|
||
- Docker
|
||
- Docker Compose v2
|
||
- Docker CLI registry login support
|
||
- Node.js 22+ (前端 SSR 服务)
|
||
- PM2 (前端进程管理)
|
||
|
||
确认命令：
|
||
|
||
```bash
|
||
docker --version
|
||
docker compose version
|
||
node --version # 需要 >= 22.12.0
|
||
pm2 --version
|
||
```
|
||
|
||
## 服务架构
|
||
|
||
生产环境运行以下服务：
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| Nginx | 80, 443 | 反向代理，SSL 终结 |
|
||
| 前端 SSR | 4322 | Node.js + Astro SSR |
|
||
| 后端 API | 5775 | Docker 容器 |
|
||
| Redis | 6379 | Docker 容器 |
|
||
| Worker Agent | - | Docker 容器 |
|
||
|
||
### 端口映射
|
||
|
||
```
|
||
Internet → Nginx (443)
|
||
├── /_astro/* → 静态文件 (client 目录)
|
||
├── /images/* → 静态文件 (client 目录)
|
||
└── /* → 反向代理到 localhost:4322 (前端 SSR)
|
||
|
||
前端 SSR (4322) → /api/* → 反向代理到 localhost:5775 (后端 API)
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
`docker-compose.prod.yml` 默认从当前目录读取 `.env`：
|
||
|
||
```bash
|
||
deploy/.env
|
||
```
|
||
|
||
生产镜像固定从火山云镜像仓库拉取：
|
||
|
||
```text
|
||
linksy-docker-cn-beijing.cr.volces.com/eryao/eryao-backend:latest
|
||
```
|
||
|
||
如果要手动指定完整镜像地址，可在 `.env` 中设置：
|
||
|
||
```text
|
||
ERYAO_BACKEND_IMAGE=<完整镜像地址>
|
||
```
|
||
|
||
Web 服务端口使用项目环境变量：
|
||
|
||
```text
|
||
ERYAO_WEB__PORT=5775
|
||
```
|
||
|
||
默认只绑定本机回环地址：
|
||
|
||
```text
|
||
ERYAO_DEPLOY_BIND_HOST=127.0.0.1
|
||
```
|
||
|
||
如果生产机器没有 Nginx、ALB 或其他反向代理，需要直接对外暴露端口，可改为：
|
||
|
||
```text
|
||
ERYAO_DEPLOY_BIND_HOST=0.0.0.0
|
||
```
|
||
|
||
### 进程配置建议
|
||
|
||
生产 Compose 只启动一个 `worker-agent` 容器。Agent 任务、低频通用任务和反馈日报任务共用 `agent` 队列，不再单独常驻 `worker-general` 进程。
|
||
|
||
2 核 2G 机器建议使用：
|
||
|
||
```text
|
||
ERYAO_WEB__WORKERS=1
|
||
ERYAO_WORKER__GROUPS__AGENT__CONCURRENCY=2
|
||
```
|
||
|
||
4G 以上机器可按流量提高 Web 或 Agent worker 数量：
|
||
|
||
```text
|
||
ERYAO_WEB__WORKERS=2
|
||
ERYAO_WORKER__GROUPS__AGENT__CONCURRENCY=2
|
||
```
|
||
|
||
## 登录火山云镜像仓库
|
||
|
||
进入部署目录，并把 `.env` 加载到当前 shell：
|
||
|
||
```bash
|
||
cd deploy
|
||
set -a
|
||
. ./.env
|
||
set +a
|
||
```
|
||
|
||
在生产机器上配置好火山云仓库用户名和密码后执行：
|
||
|
||
```bash
|
||
printf '%s' "$VOLCENGINE_REGISTRY_PASSWORD" \
|
||
| docker login \
|
||
--username "$VOLCENGINE_REGISTRY_USERNAME" \
|
||
--password-stdin \
|
||
linksy-docker-cn-beijing.cr.volces.com
|
||
```
|
||
|
||
## 启动服务
|
||
|
||
启动 Web、Redis 和 worker：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose --env-file ./.env -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
## 健康检查
|
||
|
||
如果 `ERYAO_WEB__PORT=5775`：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:5775/health
|
||
```
|
||
|
||
期望返回：
|
||
|
||
```json
|
||
{"status":"ok"}
|
||
```
|
||
|
||
## 查看状态和日志
|
||
|
||
```bash
|
||
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-redis
|
||
```
|
||
|
||
## 更新版本
|
||
|
||
当前 CI/CD 会在 `main` 分支构建后自动部署到生产机器：
|
||
|
||
- 在 Gitea runner 构建后端镜像，并推送到火山云 `eryao` 命名空间，同时保留 commit SHA 和 `latest` 标签。
|
||
- 通过 `DEPLOY_SSH_KEY` 登录生产机器。
|
||
- 在生产机器登录火山云仓库，执行 `docker compose pull`、`docker compose up -d`。
|
||
- 健康检查通过后清理 7 天前未使用的本地 Docker 镜像。
|
||
|
||
Gitea Secrets 需要包含：
|
||
|
||
```text
|
||
VOLCENGINE_REGISTRY_USERNAME
|
||
VOLCENGINE_REGISTRY_PASSWORD
|
||
DEPLOY_SSH_KEY
|
||
DEPLOY_HOST
|
||
DEPLOY_USER
|
||
```
|
||
|
||
`DEPLOY_SSH_KEY` 是已加入生产机器 `root` 用户 `~/.ssh/authorized_keys` 的部署专用私钥。
|
||
当前生产机器对应：`DEPLOY_HOST=47.239.107.213`，`DEPLOY_USER=root`。
|
||
|
||
部署脚本会在每次发布前把后端数据库连接更新为觅爻港区 RDS：
|
||
|
||
```text
|
||
ERYAO_DATABASE__HOST=pgm-j6ckocm243gd2997.pg.cnhk.rds.aliyuncs.com
|
||
ERYAO_DATABASE__PORT=5432
|
||
ERYAO_DATABASE__NAME=supabase_db
|
||
ERYAO_DATABASE__USER=postgres
|
||
```
|
||
|
||
`ERYAO_DATABASE__PASSWORD` 保留生产服务器现有值，不写入仓库或 CI 日志。
|
||
|
||
`VOLCENGINE_REGISTRY_USERNAME` 当前为 `洵觅科技2025@2101878614`。`VOLCENGINE_REGISTRY_PASSWORD` 必须配置为火山云仓库访问密码；CI 会先登录 registry，再向 `eryao/eryao-backend` 推送镜像，推送失败时部署停止。
|
||
|
||
如需手动更新，在生产机器执行：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
## 停止服务
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers down
|
||
```
|
||
|
||
如需连 Redis 数据卷一起删除：
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose --env-file ./.env -f docker-compose.prod.yml --profile workers down -v
|
||
```
|
||
|
||
谨慎使用 `down -v`，它会删除 Redis 持久化数据。
|
||
|
||
## 前端部署
|
||
|
||
### 构建前端
|
||
|
||
在本地开发机器上：
|
||
|
||
```bash
|
||
cd web
|
||
PUBLIC_API_URL=https://api.meeyao.com npm run build
|
||
```
|
||
|
||
构建产物在 `web/dist/` 目录：
|
||
- `dist/client/` - 静态资源 (CSS, JS, 图片)
|
||
- `dist/server/` - SSR 服务端代码
|
||
|
||
### 上传到服务器
|
||
|
||
```bash
|
||
# 上传构建产物
|
||
rsync -avz -e "ssh -i 觅爻港区密钥对.pem" web/dist/ root@47.239.107.213:/root/deploy/web/
|
||
|
||
# 上传依赖配置
|
||
rsync -avz -e "ssh -i 觅爻港区密钥对.pem" web/package.json web/package-lock.json root@47.239.107.213:/root/deploy/web/
|
||
|
||
# 安装生产依赖
|
||
ssh -i 觅爻港区密钥对.pem root@47.239.107.213 "cd /root/deploy/web && npm install --omit=dev"
|
||
```
|
||
|
||
### PM2 管理
|
||
|
||
```bash
|
||
# 启动服务
|
||
pm2 start server/entry.mjs --name meeyao-web
|
||
|
||
# 设置端口 (默认 4321，需要改为 4322)
|
||
export HOST=0.0.0.0
|
||
export PORT=4322
|
||
pm2 restart meeyao-web
|
||
|
||
# 保存进程列表 (开机自启)
|
||
pm2 save
|
||
|
||
# 查看状态
|
||
pm2 status
|
||
|
||
# 查看日志
|
||
pm2 logs meeyao-web
|
||
```
|
||
|
||
### Nginx 配置
|
||
|
||
前端 SSR 服务监听 `localhost:4322`，Nginx 配置要点：
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl http2;
|
||
server_name meeyao.com;
|
||
|
||
# 静态资源直接从 client 目录提供
|
||
location /_astro {
|
||
root /root/deploy/web/client;
|
||
expires 30d;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
|
||
location /images {
|
||
root /root/deploy/web/client;
|
||
expires 30d;
|
||
}
|
||
|
||
# 其他请求代理到 Node.js SSR
|
||
location / {
|
||
proxy_pass http://127.0.0.1:4322;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 前端更新流程
|
||
|
||
```bash
|
||
# 1. 本地构建
|
||
cd web && PUBLIC_API_URL=https://api.meeyao.com npm run build
|
||
|
||
# 2. 上传
|
||
rsync -avz -e "ssh -i 觅爻港区密钥对.pem" dist/ root@47.239.107.213:/root/deploy/web/
|
||
|
||
# 3. 重启服务
|
||
ssh -i 觅爻港区密钥对.pem root@47.239.107.213 "pm2 restart meeyao-web"
|
||
```
|