# LiteMall 轻商城 - 系统部署教程

## 一、服务器环境要求

### 1.1 硬件要求

| 项目 | 最低配置 | 推荐配置 |
|------|---------|---------|
| CPU | 1核 | 2核及以上 |
| 内存 | 1GB | 2GB及以上 |
| 硬盘 | 20GB | 50GB及以上（建议SSD） |
| 带宽 | 1Mbps | 5Mbps及以上 |

### 1.2 软件要求

| 软件 | 最低版本 | 推荐版本 |
|------|---------|---------|
| 操作系统 | Ubuntu 20.04 / CentOS 7+ / Debian 10 | Ubuntu 22.04 LTS |
| Node.js | v16.x | v22.22.2 LTS |
| npm | 8.x | 10.x |
| Nginx（可选） | 1.18 | 1.24+ |

### 1.3 需要安装的软件

```bash
# Node.js 安装（推荐使用 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# 验证安装
node --version  # 应显示 v22.x.x
npm --version   # 应显示 10.x.x

# Nginx（可选，用于域名和SSL）
apt update && apt install nginx -y   # Ubuntu/Debian
# yum install nginx -y               # CentOS
```

---

## 二、一键部署步骤

### 2.1 方式一：快速启动（适合测试）

```bash
# 1. 上传程序到服务器
# 将 litemall 目录上传到 /home/www/ 或任意目录

# 2. 进入项目目录
cd /path/to/litemall

# 3. 安装后端依赖
cd server && npm install && cd ..

# 4. 赋予启动脚本执行权限
chmod +x start.sh

# 5. 启动服务
bash start.sh
```

启动后访问：`http://服务器IP:3001` 即可打开管理后台。

### 2.2 方式二：系统服务（生产环境推荐）

```bash
# 1. 上传程序到服务器
# 假设上传到 /home/www/litemall

# 2. 安装依赖
cd /home/www/litemall/server
npm install --production
cd ..

# 3. 创建 systemd 服务
cat > /etc/systemd/system/litemall.service << 'EOF'
[Unit]
Description=LiteMall 轻商城
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/home/www/litemall/server
ExecStart=/usr/bin/node /home/www/litemall/server/src/app.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3001

[Install]
WantedBy=multi-user.target
EOF

# 4. 启动服务并设置开机自启
systemctl daemon-reload
systemctl enable litemall
systemctl start litemall

# 5. 检查服务状态
systemctl status litemall
```

### 2.3 方式三：使用 PM2 进程管理（推荐）

```bash
# 1. 安装 PM2
npm install -g pm2

# 2. 启动应用
cd /path/to/litemall/server
pm2 start src/app.js --name litemall

# 3. 设置开机自启
pm2 startup
pm2 save

# 4. 常用 PM2 命令
pm2 status          # 查看状态
pm2 logs litemall   # 查看日志
pm2 restart litemall # 重启服务
pm2 stop litemall    # 停止服务
```

---

## 三、域名 + SSL 配置（Nginx）

### 3.1 安装 Nginx

```bash
apt update && apt install nginx -y
```

### 3.2 配置反向代理

创建配置文件 `/etc/nginx/sites-available/litemall`：

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

    # 客户端上传大小限制
    client_max_body_size 20m;

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, no-transform";
    }

    # 反向代理到 Node.js 应用
    location / {
        proxy_pass http://127.0.0.1:3001;
        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;

        # WebSocket 支持（保留备用）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时设置
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
}
```

启用站点：

```bash
# 启用配置
ln -sf /etc/nginx/sites-available/litemall /etc/nginx/sites-enabled/

# 删除默认站点
rm -f /etc/nginx/sites-enabled/default

# 测试配置语法
nginx -t

# 重启 Nginx
systemctl restart nginx
```

### 3.3 配置 SSL（免费证书 - Certbot）

```bash
# 安装 Certbot
apt install certbot python3-certbot-nginx -y

# 申请证书（按提示操作，输入邮箱和域名）
certbot --nginx -d your-domain.com

# 测试自动续期
certbot renew --dry-run

# 查看证书状态
certbot certificates
```

### 3.4 完整 Nginx 配置（含 SSL）

```nginx
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:3001;
        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;
    }
}
```

---

## 四、防火墙配置

### 4.1 Ubuntu (UFW)

```bash
# 放行端口
ufw allow 22/tcp        # SSH
ufw allow 80/tcp        # HTTP
ufw allow 443/tcp       # HTTPS
ufw allow 3001/tcp      # 应用端口（内网环境可关闭）

# 启用防火墙
ufw enable

# 查看状态
ufw status verbose
```

### 4.2 CentOS (firewalld)

```bash
# 放行端口
firewall-cmd --permanent --add-port=3001/tcp
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --reload

# 查看规则
firewall-cmd --list-all
```

---

## 五、数据库运维

### 5.1 数据库位置

数据库文件位于 `server/data/litemall.db`，是一个独立的 SQLite 文件。

### 5.2 备份与恢复

**手动备份：**
```bash
# 停止服务
systemctl stop litemall

# 复制数据库文件
cp server/data/litemall.db server/data/backup/litemall_$(date +%Y%m%d_%H%M).db

# 启动服务
systemctl start litemall
```

**自动备份**（添加 cron 任务）：
```bash
crontab -e
# 添加以下行（每天凌晨3点备份）
0 3 * * * cd /home/www/litemall && cp server/data/litemall.db server/data/backup/litemall_$(date +\%Y\%m\%d).db
```

### 5.3 重置管理员密码

```bash
cd /path/to/litemall/server
node -e "
const bcrypt = require('bcryptjs');
const Database = require('better-sqlite3');
const db = new Database('./data/litemall.db');
const hash = bcrypt.hashSync('admin888', 10);
db.prepare('UPDATE users SET password=? WHERE id=1').run(hash);
console.log('管理员密码已重置为: admin888');
"
```

---

## 六、环境适配说明

| 场景 | 访问地址 | 说明 |
|------|---------|------|
| 本地开发 | http://localhost:3001 | 本机访问 |
| 局域网部署 | http://内网IP:3001 | 局域网内访问 |
| 公网上线 | https://your-domain.com | 需要域名+SSL证书 |
| 微信内访问 | https://your-domain.com/mobile | 需要已备案域名+HTTPS |

---

## 七、性能优化建议

### 7.1 Node.js 优化

```bash
# 使用 cluster 模式（修改 start.sh）
# 设置 NODE_ENV=production 开启 Express 性能模式
export NODE_ENV=production
```

### 7.2 Nginx 优化

```nginx
# 在 http 块中添加
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
gzip_min_length 1024;
gzip_comp_level 6;
```

### 7.3 SQLite 优化

SQLite 默认使用 WAL 模式，已在代码中开启。对于高并发场景，建议：
- 定期执行 `VACUUM` 回收空间
- 使用内存缓存层（如 Redis）减少数据库查询

---

## 八、默认账号

| 角色 | 账号 | 密码 | 说明 |
|------|------|------|------|
| 超级管理员 | admin | admin888 | 拥有全部权限 |
| 测试用户 | 13800138000 | 123456 | 普通用户端 |

> ⚠️ **重要安全提示**：首次上线部署后，请务必修改默认管理员密码！
> ⚠️ 生产环境请关闭 `server/config/index.js` 中的调试输出。

---

## 九、故障排查

### 服务无法启动
```bash
# 检查端口占用
lsof -i:3001

# 检查日志
journalctl -u litemall -n 50 --no-pager
# 或
cat server/server.log | tail -50
```

### 页面空白
- 检查浏览器控制台错误信息
- 确认 `admin/index.html` 和 `mobile/index.html` 文件存在
- 确认 Nginx 反向代理配置正确
- 清除浏览器缓存后重试

### 数据库报错
```bash
# 检查数据库完整性
cd server && node -e "const Database=require('better-sqlite3');const db=new Database('./data/litemall.db');console.log('数据库连接正常');"
```
