niumalll/backend/README_DOCKER.md

# Docker部署指南

本文档提供了使用Docker部署活牛采购智能数字化系统后端服务的详细步骤和配置说明。

## 前提条件

在开始部署前，请确保您的系统已安装以下软件：

- [Docker](https://docs.docker.com/get-docker/)
- [Docker Compose](https://docs.docker.com/compose/install/)

## 配置说明

### 环境变量配置

1. 复制`.env.docker`文件为`.env`：

```bash
cp .env.docker .env
```

2. 根据您的实际需求修改`.env`文件中的配置项：

```env
# 数据库配置
DB_USERNAME=niumall_user          # MySQL用户名
DB_PASSWORD=niumall_password      # MySQL密码
DB_NAME=niumall_prod              # MySQL数据库名

# JWT配置
JWT_SECRET=your_secure_jwt_secret_key_change_this_in_production  # JWT密钥，请务必在生产环境中更换为安全的密钥

# 其他配置保持默认即可
```

### 目录结构说明

部署相关的主要文件：

- `Dockerfile`: 定义如何构建Node.js应用镜像
- `docker-compose.yml`: 定义多容器应用的配置
- `.env.docker`: Docker环境变量配置示例
- `.env`: 您的实际环境变量配置（不在版本控制中）

## 部署步骤

### 首次部署

1. 确保您已完成上述环境变量配置

2. 在项目根目录（包含`docker-compose.yml`的目录）执行以下命令启动所有服务：

```bash
docker-compose up -d --build
```

此命令将：
- 构建Node.js应用镜像
- 拉取MySQL和Redis镜像
- 创建并启动所有容器
- 将容器连接到内部网络

3. 查看服务状态：

```bash
docker-compose ps
```

### 初始化数据库（如果需要）

如果您需要初始化数据库表结构和数据，可以使用以下命令运行数据迁移：

```bash
docker-compose exec backend npm run db:migrate
docker-compose exec backend npm run db:seed
```

## 常用命令

### 服务管理

- 启动所有服务：
  ```bash
docker-compose up -d
  ```

- 停止所有服务：
  ```bash
docker-compose down
  ```

- 重启所有服务：
  ```bash
docker-compose restart
  ```

- 查看服务日志：
  ```bash
docker-compose logs -f
  ```

- 查看特定服务日志：
  ```bash
docker-compose logs -f backend
  ```

### 进入容器

- 进入后端应用容器：
  ```bash
docker-compose exec backend sh
  ```

- 进入MySQL容器：
  ```bash
docker-compose exec db mysql -u${DB_USERNAME} -p${DB_PASSWORD} ${DB_NAME}
  ```

### 数据库管理

- 运行数据迁移：
  ```bash
docker-compose exec backend npm run db:migrate
  ```

- 重置数据库（警告：这将删除所有数据）：
  ```bash
docker-compose exec backend npm run db:reset
  ```

## 数据持久化

本配置使用Docker数据卷确保数据持久化：

- `mysql-data`: 存储MySQL数据库数据
- `redis-data`: 存储Redis数据
- `./logs:/app/logs`: 映射日志目录到主机

## 服务访问

部署完成后，您可以通过以下地址访问服务：

- API服务：`http://服务器IP:4330`
- 健康检查：`http://服务器IP:4330/health`

## 生产环境注意事项

1. **安全配置**：
   - 务必修改`.env`文件中的`JWT_SECRET`为安全的随机字符串
   - 不要使用默认的数据库密码
   - 考虑配置HTTPS代理（如Nginx）

2. **资源限制**：
   - 为生产环境配置适当的容器资源限制
   - 调整MySQL和Redis的配置以优化性能

3. **备份策略**：
   - 定期备份MySQL数据卷
   - 考虑实现日志轮转和清理策略

4. **监控**：
   - 配置适当的监控解决方案，如Prometheus和Grafana
   - 设置日志聚合系统

## 常见问题排查

1. **服务启动失败**：
   - 检查环境变量配置是否正确
   - 查看容器日志获取详细错误信息

2. **数据库连接问题**：
   - 确认`DB_HOST`设置为`db`（Docker Compose服务名称）
   - 检查数据库凭证是否正确

3. **端口冲突**：
   - 如果主机端口4330、3306或6379已被占用，可以修改`docker-compose.yml`中的端口映射

## 更新部署

当代码更新后，执行以下命令更新部署：

```bash
docker-compose up -d --build backend
```

## 参考文档

- [Docker官方文档](https://docs.docker.com/)
- [Docker Compose官方文档](https://docs.docker.com/compose/)