333 lines
6.7 KiB
Markdown
333 lines
6.7 KiB
Markdown
# EternalAI 部署指南
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
用户浏览器 → Nginx (80/443) → Node.js Express (3001) → PostgreSQL (5432)
|
||
↓
|
||
PM2 进程管理
|
||
```
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `ecosystem.config.js` | PM2 进程配置 |
|
||
| `.env.example` | 环境变量模板 |
|
||
| `deploy/setup-server.sh` | 首次服务器初始化脚本 |
|
||
| `deploy/deploy.sh` | 每次部署脚本 |
|
||
| `deploy/nginx.conf` | Nginx 反向代理配置模板 |
|
||
| `.gitea/workflows/deploy.yml` | Gitea Actions CI/CD 工作流 |
|
||
|
||
---
|
||
|
||
## 一、首次部署（全量部署）
|
||
|
||
### 1.1 准备服务器
|
||
|
||
在目标服务器上执行以下操作。
|
||
|
||
```bash
|
||
# 克隆代码仓库
|
||
cd /opt # 或你选择的部署目录
|
||
git clone http://gitea.fischerai.cn/chigulong/eternalai.git
|
||
cd eternalai
|
||
```
|
||
|
||
### 1.2 运行服务器初始化脚本
|
||
|
||
```bash
|
||
bash deploy/setup-server.sh
|
||
```
|
||
|
||
此脚本会自动完成：
|
||
- 检测并安装 Node.js 20 LTS（如缺失）
|
||
- 检测并安装 PostgreSQL 15（如缺失）
|
||
- 检测并安装 PM2（如缺失）
|
||
- 检测并安装 Nginx（如缺失）
|
||
- 创建数据库 `eternalai` 和用户
|
||
- 自动生成 `.env` 文件（含随机 JWT 密钥和数据库密码）
|
||
- 安装 npm 依赖
|
||
- 生成 Prisma Client
|
||
- 推送数据库 Schema
|
||
- 启动 PM2 进程并配置开机自启
|
||
|
||
**自定义数据库配置**（可选）：
|
||
```bash
|
||
DB_NAME=mydb DB_USER=myuser DB_PASS=mypassword bash deploy/setup-server.sh
|
||
```
|
||
|
||
脚本完成后会输出数据库密码，请妥善保存。
|
||
|
||
### 1.3 配置 Nginx 反向代理
|
||
|
||
```bash
|
||
# 复制 Nginx 配置
|
||
sudo cp deploy/nginx.conf /etc/nginx/sites-available/eternalai
|
||
sudo ln -s /etc/nginx/sites-available/eternalai /etc/nginx/sites-enabled/
|
||
|
||
# 编辑配置，替换 YOUR_DOMAIN 为实际域名
|
||
sudo nano /etc/nginx/sites-enabled/eternalai
|
||
# 将所有 YOUR_DOMAIN 替换为你的域名，如 eternalai.example.com
|
||
|
||
# 测试配置
|
||
sudo nginx -t
|
||
|
||
# 重载 Nginx
|
||
sudo nginx -s reload
|
||
```
|
||
|
||
### 1.4 配置 HTTPS（推荐）
|
||
|
||
```bash
|
||
# 安装 Certbot
|
||
sudo apt-get install -y certbot python3-certbot-nginx # Ubuntu/Debian
|
||
# 或
|
||
sudo yum install -y certbot python3-certbot-nginx # CentOS/RHEL
|
||
|
||
# 自动获取并配置 SSL 证书
|
||
sudo certbot --nginx -d YOUR_DOMAIN
|
||
|
||
# 证书自动续期（Certbot 会自动配置 cron）
|
||
sudo certbot renew --dry-run
|
||
```
|
||
|
||
### 1.5 验证部署
|
||
|
||
```bash
|
||
# 检查 PM2 进程状态
|
||
pm2 status
|
||
|
||
# 查看应用日志
|
||
pm2 logs eternalai
|
||
|
||
# 测试本地访问
|
||
curl http://localhost:3001
|
||
|
||
# 测试 Nginx 代理访问
|
||
curl http://YOUR_DOMAIN
|
||
```
|
||
|
||
---
|
||
|
||
## 二、CI/CD 自动部署（推送即部署）
|
||
|
||
### 2.1 配置 Gitea Secrets
|
||
|
||
在 Gitea 仓库设置中添加 Secret：
|
||
|
||
1. 进入仓库 → Settings → Actions → Secrets
|
||
2. 添加 `DATABASE_URL`，值为 `.env` 文件中的 `DATABASE_URL`
|
||
|
||
### 2.2 配置 Gitea Runner
|
||
|
||
确保已注册 self-hosted runner：
|
||
|
||
```bash
|
||
# 在服务器上注册 runner（如尚未注册）
|
||
# 参考 Gitea 官方文档: https://docs.gitea.com/usage/actions/quickstart
|
||
```
|
||
|
||
### 2.3 自动部署流程
|
||
|
||
每次推送代码到 `master` 分支时，Gitea Actions 会自动：
|
||
|
||
1. 拉取最新代码
|
||
2. 安装 npm 依赖
|
||
3. 生成 Prisma Client
|
||
4. 推送数据库 Schema（`prisma db push`）
|
||
5. 重启 PM2 进程（`pm2 reload`）
|
||
6. 健康检查（等待 HTTP 200）
|
||
7. 重载 Nginx
|
||
|
||
```bash
|
||
# 推送代码触发自动部署
|
||
git push origin master
|
||
```
|
||
|
||
### 2.4 手动触发部署
|
||
|
||
在 Gitea 仓库 → Actions 页面，可手动触发 `Deploy EternalAI` 工作流。
|
||
|
||
---
|
||
|
||
## 三、手动部署（不使用 CI/CD）
|
||
|
||
```bash
|
||
# SSH 登录服务器
|
||
ssh user@your-server
|
||
|
||
# 进入应用目录
|
||
cd /opt/eternalai
|
||
|
||
# 运行部署脚本
|
||
bash deploy/deploy.sh
|
||
```
|
||
|
||
部署脚本会自动完成：拉取代码 → 安装依赖 → 数据库迁移 → 重启 PM2 → 健康检查。
|
||
|
||
---
|
||
|
||
## 四、常用运维命令
|
||
|
||
### PM2 进程管理
|
||
|
||
```bash
|
||
pm2 status # 查看进程状态
|
||
pm2 logs eternalai # 实时查看日志
|
||
pm2 logs eternalai --lines 100 # 查看最近 100 行日志
|
||
pm2 restart eternalai # 重启进程
|
||
pm2 reload eternalai # 零停机重载
|
||
pm2 stop eternalai # 停止进程
|
||
pm2 delete eternalai # 删除进程
|
||
pm2 monit # 监控面板
|
||
```
|
||
|
||
### 数据库操作
|
||
|
||
```bash
|
||
# 推送 Schema 变更
|
||
npx prisma db push
|
||
|
||
# 打开 Prisma Studio（数据库可视化管理）
|
||
npx prisma studio
|
||
|
||
# 连接 PostgreSQL
|
||
psql -U eternalai -d eternalai -h localhost
|
||
```
|
||
|
||
### Nginx 操作
|
||
|
||
```bash
|
||
sudo nginx -t # 测试配置
|
||
sudo nginx -s reload # 重载配置
|
||
sudo systemctl status nginx # 查看状态
|
||
sudo tail -f /var/log/nginx/eternalai_error.log # 查看错误日志
|
||
```
|
||
|
||
### 日志查看
|
||
|
||
```bash
|
||
# 应用日志
|
||
tail -f logs/out.log # 标准输出
|
||
tail -f logs/err.log # 错误输出
|
||
|
||
# Nginx 日志
|
||
sudo tail -f /var/log/nginx/eternalai_access.log
|
||
sudo tail -f /var/log/nginx/eternalai_error.log
|
||
|
||
# PostgreSQL 日志
|
||
sudo tail -f /var/log/postgresql/postgresql-15-main.log
|
||
```
|
||
|
||
---
|
||
|
||
## 五、更新部署
|
||
|
||
### 5.1 日常更新（代码变更）
|
||
|
||
```bash
|
||
# 方法一：推送代码触发 CI/CD（推荐）
|
||
git push origin master
|
||
|
||
# 方法二：手动部署
|
||
bash deploy/deploy.sh
|
||
```
|
||
|
||
### 5.2 数据库 Schema 变更
|
||
|
||
修改 `prisma/schema.prisma` 后：
|
||
|
||
```bash
|
||
# 推送到 master，CI/CD 会自动执行 prisma db push
|
||
git add prisma/schema.prisma
|
||
git commit -m "feat: update schema"
|
||
git push origin master
|
||
|
||
# 或手动执行
|
||
npx prisma db push
|
||
pm2 reload eternalai
|
||
```
|
||
|
||
### 5.3 环境变量变更
|
||
|
||
```bash
|
||
# 编辑 .env 文件
|
||
nano .env
|
||
|
||
# 重启应用使配置生效
|
||
pm2 reload eternalai --update-env
|
||
```
|
||
|
||
---
|
||
|
||
## 六、回滚
|
||
|
||
```bash
|
||
# 查看部署历史
|
||
git log --oneline -10
|
||
|
||
# 回滚到指定版本
|
||
git checkout <commit-hash>
|
||
npm install
|
||
npx prisma db push
|
||
pm2 reload eternalai
|
||
|
||
# 或回滚到上一个版本
|
||
git checkout HEAD~1
|
||
npm install
|
||
npx prisma db push
|
||
pm2 reload eternalai
|
||
```
|
||
|
||
---
|
||
|
||
## 七、故障排查
|
||
|
||
### 应用无法启动
|
||
|
||
```bash
|
||
# 查看错误日志
|
||
pm2 logs eternalai --err --lines 50
|
||
|
||
# 常见原因:
|
||
# 1. .env 文件缺失 → 运行 deploy/setup-server.sh
|
||
# 2. 数据库连接失败 → 检查 DATABASE_URL 和 PostgreSQL 服务
|
||
# 3. 端口被占用 → 检查 PORT 环境变量
|
||
```
|
||
|
||
### 数据库连接失败
|
||
|
||
```bash
|
||
# 检查 PostgreSQL 服务
|
||
sudo systemctl status postgresql
|
||
|
||
# 测试连接
|
||
psql -U eternalai -d eternalai -h localhost -W
|
||
|
||
# 检查 pg_hba.conf 认证配置
|
||
sudo cat /etc/postgresql/15/main/pg_hba.conf | grep -v '^#'
|
||
```
|
||
|
||
### Nginx 502 Bad Gateway
|
||
|
||
```bash
|
||
# 检查 Node.js 进程是否运行
|
||
pm2 status
|
||
|
||
# 检查端口
|
||
curl http://localhost:3001
|
||
|
||
# 检查 Nginx 错误日志
|
||
sudo tail -f /var/log/nginx/eternalai_error.log
|
||
```
|
||
|
||
### PM2 进程未开机自启
|
||
|
||
```bash
|
||
# 重新配置开机自启
|
||
pm2 startup systemd
|
||
# 执行输出的 sudo 命令
|
||
pm2 save
|
||
```
|