chore: initialize deployable website and CMS

2026-09-08 11:57:17 +08:00
commit 3a99ae30c5
57 changed files with 11205 additions and 0 deletions
@@ -0,0 +1,696 @@
+# 宝塔面板部署指南
+
+> 阿美巴传统官网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`