# 部署脚本使用说明

## 📋 部署脚本改进说明

### 已修复的问题

1. **✅ 数据库密码特殊字符问题**
   - 简化默认密码为 `FamilyTree2024`
   - 添加 `DB_PASSWORD_ENCODED` 变量支持URL编码
   - 使用占位符替换方式生成.env文件，避免变量展开问题

2. **✅ Prisma安装问题**
   - 自动配置国内镜像源
   - 智能检测prisma命令是否可用
   - 失败时自动安装完整依赖
   - 支持 `npx prisma` 和 `pnpm exec prisma` 两种方式

3. **✅ 环境变量配置问题**
   - 使用临时文件+sed替换方式生成.env
   - 避免heredoc中的变量展开问题
   - 确保NEXTAUTH_SECRET正确生成

4. **✅ PM2配置优化**
   - 检查是否已配置开机自启
   - 避免重复配置systemd服务

5. **✅ 部署前检查**
   - 检查必要命令（pnpm, rsync, ssh, nc）
   - 检查本地.env文件是否存在
   - 提前发现问题，避免部署失败

## 🚀 使用方法

### 1. 配置部署参数

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

```bash
# 服务器配置
SERVER_IP="115.190.235.230"      # 服务器IP
SSH_PORT="22"                    # SSH端口
SERVER_USER="root"               # SSH用户
REMOTE_DIR="/var/www/chinese-family-tree"  # 部署目录
APP_PORT="8006"                  # 应用端口

# 数据库配置
DB_NAME="family_tree"
DB_USER="family_tree_user"
DB_PASSWORD="FamilyTree2024"     # 数据库密码
```

### 2. 准备本地环境

确保本地已安装：
- Node.js 18+
- pnpm
- rsync
- ssh客户端

### 3. 执行部署

```bash
chmod +x deploy.sh
./deploy.sh
```

## 📝 部署流程

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

### [0/9] 部署前检查
- 检查必要命令是否安装
- 检查本地.env文件是否存在

### [1/9] 检查SSH密钥
- 检查 `~/.ssh/id_rsa` 是否存在
- 不存在则自动创建4096位RSA密钥

### [2/9] 测试服务器连接
- 使用 `nc` 测试SSH端口是否开放
- 验证服务器可访问性

### [3/9] 配置免密登录
- 检查是否已配置免密登录
- 未配置则使用 `ssh-copy-id` 配置

### [4/9] 本地构建项目
- `pnpm install` - 安装依赖
- `npx prisma generate` - 生成Prisma客户端
- `pnpm build` - 构建Next.js应用

### [5/9] 配置服务器环境
- 安装Node.js 20.x（如未安装）
- 安装pnpm（如未安装）
- 安装PM2（如未安装）
- 创建部署目录

### [6/9] 配置PostgreSQL数据库
- 检查PostgreSQL是否安装
- 检查数据库是否存在
- 创建数据库和用户（如不存在）
- 配置完整权限（兼容PostgreSQL 15+）

### [7/9] 上传文件到服务器
- 使用rsync同步文件
- 自动排除不必要的文件：
  - node_modules
  - .git
  - .next/cache
  - .env（本地配置）
  - *.log, *.md
  - 测试脚本

### [8/9] 配置环境变量
- 检查服务器上.env文件是否存在
- 不存在则自动创建
- 配置内容：
  - DATABASE_URL（自动使用配置的数据库信息）
  - NEXTAUTH_URL（自动使用服务器IP和端口）
  - NEXTAUTH_SECRET（自动生成随机密钥）
  - SMTP配置
  - NODE_ENV=production

### [9/9] 安装依赖并启动应用
- 配置pnpm使用国内镜像
- 安装生产依赖
- 生成Prisma客户端
- 运行数据库迁移
- 使用PM2启动应用（监听指定端口）
- 保存PM2配置
- 配置开机自启动

## ⚙️ 配置说明

### 数据库密码特殊字符

如果数据库密码包含特殊字符，需要URL编码：

```bash
# 原密码
DB_PASSWORD="FamilyTree2024!@#"

# URL编码后（! → %21, @ → %40, # → %23）
DB_PASSWORD_ENCODED="FamilyTree2024%21%40%23"
```

常见特殊字符编码：
- `!` → `%21`
- `@` → `%40`
- `#` → `%23`
- `$` → `%24`
- `%` → `%25`
- `^` → `%5E`
- `&` → `%26`
- `*` → `%2A`

### 自定义SMTP配置

如需修改邮件配置，编辑脚本中的SMTP部分：

```bash
SMTP_HOST="smtp.163.com"
SMTP_PORT="465"
SMTP_USER="your-email@163.com"
SMTP_PASS="your-password"
SMTP_FROM="your-email@163.com"
```

## 🔧 常用管理命令

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

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

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

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

### 查看实时日志
```bash
ssh root@115.190.235.230 'pm2 logs chinese-family-tree --lines 100'
```

### 更新部署
```bash
./deploy.sh
```

## 🐛 故障排查

### 1. pnpm install 失败

**问题**：npm registry连接超时

**解决方案**：
```bash
# 登录服务器
ssh root@115.190.235.230

# 配置国内镜像
pnpm config set registry https://registry.npmmirror.com

# 重新部署
./deploy.sh
```

### 2. Prisma命令找不到

**问题**：`Command "prisma" not found`

**解决方案**：
脚本已自动处理，会安装完整依赖。如果仍有问题：
```bash
ssh root@115.190.235.230
cd /var/www/chinese-family-tree
pnpm install  # 安装所有依赖（包括devDependencies）
```

### 3. 数据库连接失败

**问题**：`P1013: empty host in database URL`

**解决方案**：
检查.env文件中的DATABASE_URL是否正确：
```bash
ssh root@115.190.235.230
cat /var/www/chinese-family-tree/.env
```

确保格式正确：
```
DATABASE_URL="postgresql://family_tree_user:FamilyTree2024@localhost:5432/family_tree"
```

### 4. 端口被占用

**问题**：端口8006已被占用

**解决方案**：
```bash
# 查看端口占用
ssh root@115.190.235.230 'lsof -i :8006'

# 停止占用进程
ssh root@115.190.235.230 'pm2 stop chinese-family-tree'

# 或修改APP_PORT为其他端口
```

### 5. 应用无法访问

**检查清单**：
1. 应用是否正常运行：`pm2 status`
2. 防火墙是否开放端口：`ufw status`
3. 云服务器安全组是否配置
4. 浏览器缓存是否清除

## 📊 性能优化

### 1. 使用PM2集群模式
```bash
ssh root@115.190.235.230
cd /var/www/chinese-family-tree
pm2 delete chinese-family-tree
PORT=8006 pm2 start npm --name "chinese-family-tree" -i max -- start
pm2 save
```

### 2. 配置日志轮转
```bash
ssh root@115.190.235.230
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7
```

### 3. 启用Gzip压缩
在next.config.mjs中添加：
```javascript
const nextConfig = {
  compress: true,
  // ...其他配置
}
```

## 🔒 安全建议

1. **修改默认密码**：部署后立即修改数据库密码
2. **配置防火墙**：只开放必要端口
3. **定期更新**：保持系统和依赖包最新
4. **使用HTTPS**：配置SSL证书
5. **限制SSH访问**：使用fail2ban防止暴力破解
6. **定期备份**：备份数据库和应用文件

## 📞 技术支持

如遇到问题：
1. 查看应用日志：`pm2 logs chinese-family-tree`
2. 查看系统日志：`/var/log/syslog`
3. 检查数据库日志：PostgreSQL日志文件

---

**最后更新**: 2025-11-23
**脚本版本**: v2.0（完善版）