chinese-family-tree-2/DEPLOY_GUIDE.md

# 部署指南

## 快速部署

### 1. 准备工作

在部署前，请确保：

1. **服务器要求**：
   - 操作系统：Ubuntu 20.04+ / CentOS 7+ / Debian 10+
   - 内存：至少 2GB RAM
   - 磁盘：至少 10GB 可用空间
   - 已安装 PostgreSQL 数据库

2. **本地环境**：
   - 已安装 Node.js 18+
   - 已安装 pnpm
   - 已配置好 `.env` 文件

### 2. 配置服务器信息

编辑 `deploy.sh` 文件，修改以下配置：

```bash
SERVER_IP="115.190.235.230"      # 服务器IP
SERVER_PORT="8006"               # SSH端口
SERVER_USER="root"               # SSH用户名（根据实际情况修改）
REMOTE_DIR="/var/www/chinese-family-tree"  # 部署目录
APP_PORT="3000"                  # 应用端口
```

### 3. 配置服务器环境变量

在服务器上创建 `.env` 文件：

```bash
ssh -p 8006 root@115.190.235.230
cd /var/www/chinese-family-tree
nano .env
```

添加以下内容（根据实际情况修改）：

```env
# 数据库配置
DATABASE_URL="postgresql://user:password@localhost:5432/family_tree"

# NextAuth 配置
# ⚠️ 重要: NEXTAUTH_URL 必须与用户在浏览器中访问的URL完全一致!
# 如果用户通过 http://115.190.235.230:8006 访问,则设置为:
# NEXTAUTH_URL="http://115.190.235.230:8006"
# 如果用户通过 http://115.190.235.230:3000 访问,则设置为:
NEXTAUTH_URL="http://115.190.235.230:3000"
NEXTAUTH_SECRET="your-production-secret-key-here"

# 邮箱服务器配置
SMTP_HOST="smtp.163.com"
SMTP_PORT="465"
SMTP_USER="cftservice@163.com"
SMTP_PASS="SChncqpqS9TDPUD2"
SMTP_FROM="cftservice@163.com"

# 生产环境
NODE_ENV="production"
```

**⚠️ 关于 NEXTAUTH_URL 的重要说明**:
- 如果配置错误,会导致重定向循环 (ERR_TOO_MANY_REDIRECTS)
- 必须包含协议 (http:// 或 https://)
- 必须包含用户实际访问的端口号
- 不要使用 localhost 或 127.0.0.1
- 详细的故障排查请参考 `REDIRECT_LOOP_FIX.md`

### 4. 执行部署

```bash
# 给脚本添加执行权限
chmod +x deploy.sh

# 执行部署
./deploy.sh
```

### 5. 部署流程说明

脚本会自动完成以下步骤：

1. ✓ 检查并创建SSH密钥
2. ✓ 配置免密登录（首次需要输入服务器密码）
3. ✓ 测试SSH连接
4. ✓ 本地构建项目
5. ✓ 配置服务器环境（安装Node.js、pnpm、PM2）
6. ✓ 上传文件到服务器
7. ✓ 启动应用

## 常用命令

### 查看应用状态
```bash
ssh -p 8006 root@115.190.235.230 'pm2 status'
```

### 查看应用日志
```bash
ssh -p 8006 root@115.190.235.230 'pm2 logs chinese-family-tree'
```

### 重启应用
```bash
ssh -p 8006 root@115.190.235.230 'pm2 restart chinese-family-tree'
```

### 停止应用
```bash
ssh -p 8006 root@115.190.235.230 'pm2 stop chinese-family-tree'
```

### 更新部署
```bash
# 直接运行部署脚本即可
./deploy.sh
```

## Nginx 反向代理配置（可选）

如果需要使用域名访问或配置HTTPS，可以安装Nginx：

```bash
# 在服务器上安装Nginx
apt-get update
apt-get install -y nginx

# 创建配置文件
nano /etc/nginx/sites-available/chinese-family-tree
```

添加以下配置：

```nginx
server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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
ln -s /etc/nginx/sites-available/chinese-family-tree /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx
```

## 防火墙配置

确保服务器防火墙开放必要端口：

```bash
# Ubuntu/Debian
ufw allow 8006/tcp  # SSH端口
ufw allow 3000/tcp  # 应用端口
ufw allow 80/tcp    # HTTP（如果使用Nginx）
ufw allow 443/tcp   # HTTPS（如果使用Nginx）

# CentOS
firewall-cmd --permanent --add-port=8006/tcp
firewall-cmd --permanent --add-port=3000/tcp
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload
```

## 数据库配置

### PostgreSQL 安装和配置

```bash
# 安装PostgreSQL
apt-get install -y postgresql postgresql-contrib

# 创建数据库和用户
sudo -u postgres psql << EOF
CREATE DATABASE family_tree;
CREATE USER family_tree_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE family_tree TO family_tree_user;
\q
EOF

# 允许远程连接（如果需要）
nano /etc/postgresql/*/main/postgresql.conf
# 修改：listen_addresses = '*'

nano /etc/postgresql/*/main/pg_hba.conf
# 添加：host all all 0.0.0.0/0 md5

# 重启PostgreSQL
systemctl restart postgresql
```

## 故障排查

### 应用无法启动
```bash
# 查看详细日志
ssh -p 8006 root@115.190.235.230 'pm2 logs chinese-family-tree --lines 100'

# 检查环境变量
ssh -p 8006 root@115.190.235.230 'cd /var/www/chinese-family-tree && cat .env'

# 手动启动测试
ssh -p 8006 root@115.190.235.230 'cd /var/www/chinese-family-tree && npm start'
```

### 数据库连接失败
```bash
# 测试数据库连接
ssh -p 8006 root@115.190.235.230 'cd /var/www/chinese-family-tree && npx prisma db pull'
```

### 端口被占用
```bash
# 查看端口占用
ssh -p 8006 root@115.190.235.230 'lsof -i :3000'

# 杀死占用进程
ssh -p 8006 root@115.190.235.230 'kill -9 <PID>'
```

## 性能优化建议

1. **启用 PM2 集群模式**：
   ```bash
   pm2 start npm --name "chinese-family-tree" -i max -- start
   ```

2. **配置日志轮转**：
   ```bash
   pm2 install pm2-logrotate
   pm2 set pm2-logrotate:max_size 10M
   pm2 set pm2-logrotate:retain 7
   ```

3. **监控应用**：
   ```bash
   pm2 install pm2-server-monit
   ```

## 安全建议

1. 定期更新系统和依赖包
2. 使用强密码和密钥认证
3. 配置防火墙规则
4. 定期备份数据库
5. 使用 HTTPS（配置 SSL 证书）
6. 限制 SSH 登录尝试次数

## 备份和恢复

### 数据库备份
```bash
ssh -p 8006 root@115.190.235.230 'pg_dump -U family_tree_user family_tree > backup_$(date +%Y%m%d).sql'
```

### 数据库恢复
```bash
ssh -p 8006 root@115.190.235.230 'psql -U family_tree_user family_tree < backup_20240101.sql'
```

### 文件备份
```bash
ssh -p 8006 root@115.190.235.230 'tar -czf /backup/app_$(date +%Y%m%d).tar.gz /var/www/chinese-family-tree'
```