# 宝塔面板部署指南

> 阿美巴传统官网1.0 - 完整部署教程

---

## 一、环境要求

### 1.1 服务器配置

| 项目 | 最低要求 | 推荐配置 |
|------|---------|---------|
| 操作系统 | CentOS 7+ / Ubuntu 20+ | CentOS 8 / Ubuntu 22 |
| 内存 | 1GB | 2GB+ |
| 硬盘 | 20GB | 50GB+ |
| Node.js | 18.x | 20.x（better-sqlite3 需要可用的原生构建环境） |

### 1.2 宝塔面板安装

```bash
# CentOS
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh

# Ubuntu
wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh
```

### 1.3 宝塔软件安装

登录宝塔面板后，在 **软件商店** 中安装：

| 软件 | 版本 | 用途 |
|------|------|------|
| **Nginx** | 1.24+ | Web服务器 |
| **PM2管理器** | 5.x | Node.js进程管理 |
| **Node.js版本管理器** | - | 安装Node.js 20 |

---

## 二、项目结构

### 2.1 本地项目结构

```
传统官网升级版/
├── dist/                  ← 前端构建产物
├── cms/
│   ├── server/            ← CMS后端
│   │   ├── src/
│   │   ├── admin/dist/    ← 管理后台构建产物
│   │   ├── cms.db         ← 数据库（运行后生成）
│   │   └── uploads/       ← 上传文件目录
│   └── admin/             ← 管理后台源码（不需要上传）
├── package.json
└── README.md
```

### 2.2 服务器目录结构

```
/www/wwwroot/aiameiba.com/
├── frontend/              ← 前端静态文件
│   ├── index.html
│   └── assets/
├── cms-server/            ← CMS后端
│   ├── src/
│   ├── admin/dist/        ← 管理后台
│   ├── node_modules/
│   ├── cms.db             ← 数据库
│   └── uploads/           ← 上传文件
└── .env                   ← 环境变量（可选）
```

---

## 三、本地构建

### 3.1 安装依赖

```bash
# 前端
npm install

# CMS后端
cd cms/server
npm install

# 管理后台
cd cms/admin
npm install
```

### 3.2 构建前端

```bash
# 在项目根目录执行
npm run build
```

构建完成后会生成 `dist/` 文件夹。

### 3.3 构建管理后台

```bash
cd cms/admin
npm run build
```

构建完成后会在 `cms/admin/` 生成 `dist/` 文件夹。

### 3.4 初始化数据库（可选）

如果想在本地初始化测试数据：

```bash
cd cms/server
npm run seed
```

---

## 四、上传文件到服务器

### 4.1 使用宝塔文件管理器

1. 登录宝塔面板
2. 点击 **文件** 进入文件管理
3. 导航到 `/www/wwwroot/`
4. 创建目录 `aiameiba.com`

### 4.2 上传文件

| 本地路径 | 服务器路径 | 说明 |
|---------|-----------|------|
| `dist/*` | `/www/wwwroot/aiameiba.com/frontend/` | 前端所有文件 |
| `cms/server/*` | `/www/wwwroot/aiameiba.com/cms-server/` | 整个server目录 |

**注意**：
- `node_modules` 不需要上传，服务器上重新安装
- 不要把开发机数据库直接放进版本库；生产数据应通过备份恢复或在服务器初始化

### 4.3 使用 SCP 命令上传（可选）

```bash
# 上传前端
scp -r dist/* root@your-server-ip:/www/wwwroot/aiameiba.com/frontend/

# 上传CMS后端
scp -r cms/server root@your-server-ip:/www/wwwroot/aiameiba.com/cms-server/
```

---

## 五、服务器配置

### 5.1 安装 Node.js

1. 在宝塔面板打开 **Node.js版本管理器**
2. 安装 **Node.js 20.x**（不要用24.x）
3. 设置为默认版本

### 5.2 安装依赖

通过宝塔 **终端** 或 SSH 连接服务器：

```bash
cd /www/wwwroot/aiameiba.com/cms-server

# 安装生产依赖
npm install --production

# 如果 better-sqlite3 安装失败，尝试：
npm rebuild better-sqlite3
```

### 5.3 初始化数据库

```bash
cd /www/wwwroot/aiameiba.com/cms-server
npm run seed
```

执行后会：
- 创建数据库表
- 使用 `CMS_ADMIN_PASSWORD` 创建管理员；未设置时生成一次性随机密码并打印
- 插入示例数据

### 5.4 设置目录权限

```bash
chmod -R 755 /www/wwwroot/aiameiba.com/cms-server
chmod -R 777 /www/wwwroot/aiameiba.com/cms-server/uploads
```

---

## 六、使用 PM2 启动服务

### 6.1 通过宝塔 PM2 管理器（推荐）

1. 打开 **软件商店** → **PM2管理器**
2. 点击 **添加项目**
3. 填写配置：

| 配置项 | 值 |
|-------|-----|
| 项目目录 | `/www/wwwroot/aiameiba.com/cms-server` |
| 启动文件 | `src/index.js` |
| 项目名称 | `ameba-cms` |
| Node版本 | 选择已安装的20.x |
| 运行用户 | `www` |

4. 点击 **提交**

### 6.2 通过命令行

```bash
cd /www/wwwroot/aiameiba.com/cms-server

# 启动服务
pm2 start src/index.js --name ameba-cms

# 保存进程列表
pm2 save

# 设置开机自启
pm2 startup
```

### 6.3 常用 PM2 命令

```bash
# 查看所有进程
pm2 list

# 查看日志
pm2 logs ameba-cms

# 重启服务
pm2 restart ameba-cms

# 停止服务
pm2 stop ameba-cms

# 删除服务
pm2 delete ameba-cms
```

---

## 七、配置 Nginx

### 7.1 创建网站

1. 打开宝塔 **网站** → **添加站点**
2. 填写信息：
   - 域名：`aiameiba.com`
   - 根目录：`/www/wwwroot/aiameiba.com/frontend`
   - PHP版本：**纯静态**

### 7.2 配置反向代理

1. 点击网站列表中的 **设置**
2. 选择 **配置文件**
3. 替换为以下内容：

```nginx
server {
    listen 80;
    server_name aiameiba.com www.aiameiba.com;
    
    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
    }
    
    # 前端静态文件
    root /www/wwwroot/aiameiba.com/frontend;
    index index.html;
    
    # 前端路由 - SPA支持
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # CMS后端API反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:13001;
        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;
    }
    
    # CMS管理后台
    location /admin/ {
        proxy_pass http://127.0.0.1:13001;
        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;
    }
    
    # 上传文件访问
    location /uploads/ {
        proxy_pass http://127.0.0.1:13001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    
    # Gzip压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    gzip_min_length 1000;
    gzip_comp_level 6;
}
```

4. 点击 **保存**

### 7.3 重启 Nginx

```bash
nginx -t          # 检查配置
nginx -s reload   # 重载配置
```

或在宝塔面板点击 **重启** Nginx。

---

## 八、配置 SSL 证书（推荐）

### 8.1 申请免费证书

1. 在宝塔 **网站** → 点击站点 **设置**
2. 选择 **SSL** 选项卡
3. 点击 **Let's Encrypt**
4. 选择域名，点击 **申请**
5. 开启 **强制HTTPS**

### 8.2 证书申请成功后

Nginx配置会自动更新，包含443端口监听：

```nginx
server {
    listen 80;
    listen 443 ssl;
    server_name aiameiba.com www.aiameiba.com;
    
    ssl_certificate /www/server/panel/vhost/cert/aiameiba.com/fullchain.pem;
    ssl_certificate_key /www/server/panel/vhost/cert/aiameiba.com/privkey.pem;
    
    # 强制HTTPS
    if ($scheme = http) {
        return 301 https://$host$request_uri;
    }
    
    # ... 其他配置同上
}
```

---

## 九、配置环境变量（可选）

### 9.1 创建 .env 文件

```bash
cat > /www/wwwroot/aiameiba.com/cms-server/.env << 'EOF'
# CMS服务器端口
CMS_PORT=13001

# JWT密钥（建议修改）
JWT_SECRET=your-random-secret-key-here

# 首次初始化管理员密码（仅 seed 时使用）
CMS_ADMIN_PASSWORD=replace-with-a-strong-password

# 数据库路径（可选，默认当前目录）
# CMS_DB_PATH=/www/wwwroot/aiameiba.com/cms-server/cms.db

# 上传目录（可选）
# UPLOAD_DIR=/www/wwwroot/aiameiba.com/uploads
EOF
```

### 9.2 修改 JWT 密钥（重要）

在生产环境中，务必修改 JWT 密钥：

```bash
# 生成随机密钥
openssl rand -hex 32

# 将生成的密钥填入 .env 的 JWT_SECRET
```

---

## 十、验证部署

### 10.1 检查服务状态

```bash
# 检查PM2进程
pm2 list

# 应该看到：
# ┌─────┬──────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┐
# │ id  │ name         │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │
# ├─────┼──────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┤
# │ 0   │ ameba-cms    │ default     │ 1.0.0   │ fork    │ 12345    │ 5m     │ 0    │ online    │ 0%       │
# └─────┴──────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┘

# 检查端口监听
netstat -tlnp | grep 13001

# 检查CMS健康状态
curl http://localhost:13001/health
```

### 10.2 访问测试

| 项目 | 访问地址 | 说明 |
|------|---------|------|
| 官网首页 | https://aiameiba.com | 应显示网站首页 |
| CMS后台 | https://aiameiba.com/admin | 应显示登录页 |
| 健康检查 | https://aiameiba.com/health | 返回 `{"status":"ok"}` |

### 10.3 登录后台

1. 访问 `https://aiameiba.com/admin`
2. 输入账号密码：
   - 用户名：`admin`
   - 密码：使用 `CMS_ADMIN_PASSWORD` 或 `npm run seed` 输出的一次性密码
3. **首次登录后请立即修改密码**

---

## 十一、常见问题

### 11.1 PM2 启动失败

```bash
# 查看详细日志
pm2 logs ameba-cms --lines 100

# 常见原因：
# 1. better-sqlite3 未编译
npm rebuild better-sqlite3

# 2. 端口被占用
lsof -i :13001
kill -9 <PID>

# 3. 权限问题
chmod -R 755 /www/wwwroot/aiameiba.com/cms-server
```

### 11.2 前端显示空白

```bash
# 检查Nginx配置
nginx -t

# 检查文件是否存在
ls -la /www/wwwroot/aiameiba.com/frontend/

# 检查Nginx错误日志
tail -f /www/wwwroot/aiameiba.com/frontend/error.log
```

### 11.3 API 请求失败

```bash
# 检查CMS服务是否运行
pm2 list

# 检查反向代理配置
curl -I http://localhost:13001/api/cms/public

# 检查防火墙
iptables -L -n | grep 13001
```

### 11.4 上传图片失败

```bash
# 检查目录权限
ls -la /www/wwwroot/aiameiba.com/cms-server/uploads/

# 修复权限
chmod -R 777 /www/wwwroot/aiameiba.com/cms-server/uploads/
```

### 11.5 数据库损坏

```bash
# 备份当前数据库
cp /www/wwwroot/aiameiba.com/cms-server/cms.db /tmp/cms.db.backup

# 检查数据库完整性
sqlite3 /www/wwwroot/aiameiba.com/cms-server/cms.db "PRAGMA integrity_check;"

# 如果损坏，重新初始化
cd /www/wwwroot/aiameiba.com/cms-server
rm cms.db
npm run seed
```

---

## 十二、备份与恢复

### 12.1 定期备份脚本

创建备份脚本：

```bash
cat > /www/backup/ameba-backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/www/backup/ameba"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# 备份数据库
cp /www/wwwroot/aiameiba.com/cms-server/cms.db $BACKUP_DIR/cms_$DATE.db

# 备份上传文件
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz -C /www/wwwroot/aiameiba.com/cms-server uploads/

# 备份前端
tar -czf $BACKUP_DIR/frontend_$DATE.tar.gz -C /www/wwwroot/aiameiba.com frontend/

# 删除7天前的备份
find $BACKUP_DIR -name "*.db" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

echo "Backup completed: $DATE"
EOF

chmod +x /www/backup/ameba-backup.sh
```

### 12.2 设置定时备份

在宝塔 **计划任务** 中添加：

| 类型 | Shell脚本 |
|------|----------|
| 执行周期 | 每天 03:00 |
| 脚本内容 | `/www/backup/ameba-backup.sh` |

### 12.3 恢复数据

```bash
# 恢复数据库
cp /www/backup/ameba/cms_20260908_120000.db /www/wwwroot/aiameiba.com/cms-server/cms.db

# 恢复上传文件
tar -xzf /www/backup/ameba/uploads_20260908_120000.tar.gz -C /www/wwwroot/aiameiba.com/cms-server/

# 重启服务
pm2 restart ameba-cms
```

---

## 十三、安全建议

### 13.1 修改默认密码

首次部署后立即修改管理员密码：
- 后台修改：登录后台 → ⚙ 修改密码
- 命令修改：`cd cms-server && npm run passwd`

### 13.2 修改默认端口

编辑 `.env` 文件修改端口：

```env
CMS_PORT=18888  # 改为其他端口
```

同步修改 Nginx 配置中的代理端口。

### 13.3 限制后台访问IP

在 Nginx 配置中添加 IP 白名单：

```nginx
location /admin/ {
    allow 123.456.789.0;  # 你的IP
    deny all;
    
    proxy_pass http://127.0.0.1:13001;
    # ... 其他代理配置
}
```

### 13.4 开启防火墙

```bash
# 只开放必要端口
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload
```

---

## 十四、更新部署

### 14.1 更新前端

```bash
# 本地构建
npm run build

# 上传 dist 到服务器
scp -r dist/* root@server:/www/wwwroot/aiameiba.com/frontend/
```

### 14.2 更新后端

```bash
# 上传新的 cms-server 代码
# ...

# 在服务器上
cd /www/wwwroot/aiameiba.com/cms-server
npm install --production
pm2 restart ameba-cms
```

### 14.3 更新管理后台

```bash
# 本地构建
cd cms/admin
npm run build

# 上传 admin/dist 到服务器
scp -r cms/admin/dist/* root@server:/www/wwwroot/aiameiba.com/cms-server/admin/dist/
```

---

## 附录：完整部署命令汇总

```bash
# ========== 服务器端执行 ==========

# 1. 创建目录
mkdir -p /www/wwwroot/aiameiba.com/{frontend,cms-server}

# 2. 安装Node.js（通过宝塔面板）

# 3. 安装依赖
cd /www/wwwroot/aiameiba.com/cms-server
npm install --production

# 4. 初始化数据库
npm run seed

# 5. 设置权限
chmod -R 755 /www/wwwroot/aiameiba.com/cms-server
chmod -R 777 /www/wwwroot/aiameiba.com/cms-server/uploads

# 6. 启动PM2
pm2 start src/index.js --name ameba-cms
pm2 save
pm2 startup

# 7. 配置Nginx（通过宝塔面板）

# 8. 申请SSL证书（通过宝塔面板）

# 9. 验证
curl http://localhost:13001/health
```

---

**部署完成！** 🎉

如有问题，请查看 PM2 日志：`pm2 logs ameba-cms`