# LiteMall 轻商城 - 常见问题 & 故障排查 (FAQ)

---

## 一、安装部署问题

### Q: 启动提示 "port already in use"（端口被占用）？

**原因**：端口3001已被其他程序占用。

**解决方法**：
1. 修改端口号：编辑 `server/config/index.js`，将 `port` 改为其他值（如 3002）
2. 或通过环境变量指定端口：`PORT=3002 node src/app.js`
3. 查找占用端口的进程并关闭：
   ```bash
   lsof -i:3001
   kill -9 <PID>
   ```

### Q: npm install 安装依赖失败？

**常见原因和解决方法：**

1. **网络问题**（国内用户常见）：
   ```bash
   npm install --registry=https://registry.npmmirror.com
   ```

2. **Node.js 版本过低**：
   ```bash
   node --version  # 需要 ≥ v16
   # 使用 nvm 升级
   nvm install 22
   nvm use 22
   ```

3. **权限问题**：
   ```bash
   # 不要使用 sudo npm install
   # 修复权限
   sudo chown -R $(whoami) ~/.npm
   ```

4. **缓存问题**：
   ```bash
   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install
   ```

### Q: 页面显示空白？

**排查步骤：**
1. 打开浏览器开发者工具（F12），查看 Console 面板是否有报错
2. 检查网络请求是否正常加载（Network 面板）
3. 确认静态文件路径是否正确（admin/index.html、mobile/index.html）
4. 清除浏览器缓存后重试
5. 确认 Nginx 反向代理配置正确

### Q: 数据库相关错误？

**现象：** "SQLITE_ERROR: no such table" 或其他数据库错误

**解决方法：**
```bash
# 重新初始化数据库
cd server
node src/init-db.js

# 检查数据库文件是否存在
ls -la data/litemall.db

# 修复数据库文件
cd server && node -e "
const Database = require('better-sqlite3');
const db = new Database('./data/litemall.db');
db.pragma('integrity_check');
console.log('数据库完整性检查通过');
"
```

---

## 二、运营问题

### Q: 如何修改系统名称和LOGO？

1. 登录管理后台
2. 点击左侧「系统设置」
3. 选择「基本信息」标签页
4. 修改站点名称、Logo等
5. 点击「保存」按钮

### Q: 如何关闭某个功能模块？

1. 进入「系统设置」
2. 找到「模块开关」标签页
3. 关闭对应模块的开关（如：分销体系、AI客服等）
4. 关闭后，前台和后台对应入口自动隐藏

### Q: 如何切换测试/正式模式？

在「系统设置」页面顶部，点击模式切换按钮一键切换：
- **测试模式**：模拟支付不扣款，用于调试
- **正式模式**：接入真实支付，正式运营

### Q: 忘记管理员密码？

**方法一**：通过命令行重置（推荐）
```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');
"
```

**方法二**：删除数据库然后重新部署
```bash
cd /path/to/litemall/server
rm -f data/litemall.db
# 重新启动，数据库自动初始化
```

### Q: 如何手动添加测试商品？

在后台「商品管理」→「新增商品」，填写名称、价格、库存等信息即可快速添加。

### Q: 用户无法登录？

**排查方法：**
1. 检查用户输入的用户名和密码是否正确
2. 在后台「系统设置 → 登录日志」查看是否有登录失败记录
3. 检查用户是否被管理员禁用
4. 如果用户连续输错密码过多，等待15分钟后重试

---

## 三、数据问题

### Q: 如何备份数据？

**后台操作**：
1. 进入「数据备份」
2. 点击「立即备份」
3. 系统自动创建数据库快照

**命令行备份**：
```bash
cp server/data/litemall.db server/data/litemall_$(date +%Y%m%d).db
```

**自动备份（推荐）**：
```bash
# 添加 crontab 定时任务
crontab -e
# 每天凌晨3点自动备份
0 3 * * * cp /path/to/litemall/server/data/litemall.db /path/to/litemall/server/data/backup/litemall_$(date +\%Y\%m\%d).db
```

### Q: 如何恢复数据？

**后台操作**：
1. 进入「数据备份」
2. 找到需要恢复的备份文件
3. 点击「恢复」按钮
4. 确认恢复操作
5. **恢复后需要重启服务**

**手动恢复**：
```bash
# 停止服务
systemctl stop litemall

# 恢复数据库
cp server/data/backup/litemall_20260527.db server/data/litemall.db

# 启动服务
systemctl start litemall
```

### Q: 数据库文件在哪？

数据库文件位于：`server/data/litemall.db`

### Q: 数据库文件太大怎么办？

SQLite数据库文件会随业务数据增长而增大。建议：
1. 定期执行 `VACUUM` 回收空间：
   ```bash
   node -e "
   const Database = require('better-sqlite3');
   const db = new Database('./data/litemall.db');
   db.pragma('vacuum');
   console.log('VACUUM完成');
   "
   ```
2. 定期清理不需要的历史数据（如过期的登录日志）
3. 对于高并发场景，建议迁移到MySQL/PostgreSQL

---

## 四、支付问题

### Q: 支付回调收不到？

**排查步骤：**
1. 检查域名是否正确解析到服务器 IP
2. 检查 Nginx 是否配置了正确的反向代理
3. 查看服务器防火墙是否放行了 80/443 端口
4. 检查支付平台后台的回调URL配置是否正确
5. 查看应用日志确认是否收到回调请求：
   ```bash
   tail -f server/server.log | grep "payment\|notify"
   ```

### Q: 测试模式下如何测试支付？

1. 确保已在「系统设置」开启「测试模式」
2. 用户端正常下单
3. 选择支付方式（微信/支付宝）
4. 点击确认支付
5. 系统自动模拟支付成功，订单状态变为「待发货」

### Q: 支付成功但订单状态未更新？

**可能原因：**
- 测试模式下未正确触发模拟回调
- 订单金额计算异常
- 数据库写入失败

**解决方法：**
1. 检查服务器日志是否有异常
2. 使用支付通知模拟接口：
   ```
   POST /api/payment/mock-notify
   Body: { "order_no": "DD20260527xxxxxx", "payment_method": "wechat" }
   ```
3. 如持续异常，尝试重启服务

### Q: 退款处理流程？

1. **用户在移动端**：订单详情 → 申请退款 → 填写退款原因
2. **管理员在后台**：订单管理 → 找到退款中订单 → 审核
3. **审核通过**：订单标记为已退款
4. **审核驳回**：填写驳回原因，订单恢复原状

---

## 五、系统运维问题

### Q: 日志文件在哪里？

| 日志类型 | 位置 | 说明 |
|---------|------|------|
| 运行日志 | `server/server.log` | 服务端运行日志 |
| 操作日志 | 数据库 `operation_logs` 表 | 管理员操作记录 |
| 登录日志 | 数据库 `login_logs` 表 | 用户登录记录 |
| Nginx日志 | `/var/log/nginx/` | 访问和错误日志 |

### Q: 如何更新系统版本？

```bash
# 1. 备份数据
cp -r server/data server/data_backup

# 2. 备份配置文件
cp server/config/index.js server/config/index.js.bak

# 3. 拉取新版本代码（或重新上传）
git pull  # 或重新上传代码包

# 4. 恢复配置
cp server/config/index.js.bak server/config/index.js

# 5. 更新依赖
cd server && npm install

# 6. 重启服务
systemctl restart litemall
```

### Q: 如何配置 HTTPS？

推荐使用 Let's Encrypt 免费SSL证书：
```bash
apt install certbot python3-certbot-nginx -y
certbot --nginx -d your-domain.com
```
详细配置请参考「01-部署教程.md」中的SSL配置部分。

### Q: 遇到性能问题怎么办？

**常见优化方案：**
1. 增加服务器内存和CPU
2. 启用 Nginx 静态资源缓存
3. 打开 Nginx Gzip 压缩
4. 定期执行数据库 VACUUM
5. 使用 CDN 加速静态资源
6. 考虑迁移到 MySQL 数据库（需自行适配）

---

## 六、移动端问题

### Q: 手机端访问异常？

1. 清除微信浏览器缓存：微信 → 我 → 设置 → 通用 → 存储空间 → 缓存清理
2. 使用系统浏览器（Chrome/Safari）打开测试
3. 确认手机浏览器版本是否过旧
4. 检查页面是否被微信拦截

### Q: 移动端如何调试？

**微信内置浏览器调试：**
1. 打开微信 → 搜索「微信开发者工具」
2. 连接手机进行远程调试
3. 或使用 vConsole 工具（在页面引入vConsole.js）

---

## 七、其他问题

### Q: 支持哪些类型的商品？

LiteMall 支持多种商品类型：
- **实物商品**：需要物流配送的实体商品
- **虚拟商品**：充值卡、电子券等虚拟物品
- **服务类商品**：预约服务、咨询服务等

### Q: 如何申请软件著作权？

1. 准备材料：源代码（前后30页）、用户操作手册、身份证明
2. 访问 [中国版权保护中心](https://www.ccopyright.com.cn) 注册账号
3. 在线填写申请表，上传材料
4. 提交审核（普通免费 / 加急付费）
5. 审核周期：普通30-60工作日 / 加急5-15工作日

本项目已完整提供著作权申请所需的：
- 源代码文档（`docs/soft-copyright/source-backend.txt` 和 `source-frontend.txt`）
- 软件信息说明（`docs/soft-copyright/application-info.md`）
- 完整用户操作手册（本文档）

### Q: 需要技术支持或定制开发？

如有技术支持需求或功能定制需求，请联系项目开发者。

---

## 八、错误码参考

| 错误码 | 含义 | 常见原因 |
|--------|------|---------|
| 0 | 操作成功 | — |
| 1 | 操作失败 | 通用错误，查看message |
| 401 | 未登录/登录过期 | Token无效或过期 |
| 403 | 无权限 | 非管理员访问管理接口 |
| 404 | 接口不存在 | URL错误 |
| 429 | 请求过于频繁 | 超出限流限制 |
| 500 | 服务器内部错误 | 后端代码异常 |

---

## 九、联系方式

如有本FAQ未覆盖的问题，建议：
1. 查看服务器日志定位具体错误
2. 查阅本文档各部分详细说明
3. 检查数据库文件完整性
4. 重新部署并测试
