gongxiangp2/yedir/docs/docker-deployment-guide.md

# Docker 部署与更新指南

本文档提供了使用 Docker 部署和更新应用程序的详细步骤。

## 目录

- [前提条件](#前提条件)
- [初次部署](#初次部署)
- [更新应用](#更新应用)
- [常用操作](#常用操作)
- [故障排除](#故障排除)
- [最佳实践](#最佳实践)

## 前提条件

在开始部署之前，请确保服务器上已安装以下软件：

- Docker (推荐 20.10.x 或更高版本)
- Git (用于获取代码)

可以使用以下命令检查 Docker 是否已正确安装：

```bash
docker --version
```

## 初次部署

### 1. 获取代码

```bash
# 克隆代码仓库
git clone <repository-url>
cd xiaogongju
```

### 2. 配置环境变量

```bash
# 复制环境变量示例文件
cp .env.example .env

# 编辑环境变量文件，填入正确的配置
nano .env
```

确保以下关键环境变量已正确设置：
- `PORT`: 应用程序监听端口 (默认: 3225)
- `NODE_ENV`: 环境 (development/production)
- `MONGODB_URI`: MongoDB 连接字符串
- 其他应用特定的环境变量

### 3. 创建 Dockerfile

创建一个名为 `Dockerfile` 的文件，内容如下：

```dockerfile
FROM node:14-alpine

WORKDIR /app

# 复制 package.json 和 package-lock.json
COPY package*.json ./

# 安装依赖
RUN npm install

# 创建启动脚本
COPY start.sh ./
RUN chmod +x start.sh

# 复制所有文件
COPY . .

# 设置环境变量
ENV PORT=3225
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV DEBUG=*

# 暴露端口
EXPOSE 3225

# 启动命令
CMD ["./start.sh"]
```

### 4. 创建启动脚本

创建一个名为 `start.sh` 的文件，内容如下：

```bash
#!/bin/sh
echo "Starting application..."
echo "Node version: $(node -v)"
echo "NPM version: $(npm -v)"
echo "Directory listing:"
ls -la
echo "Environment variables:"
env | grep -v PASSWORD | grep -v SECRET
echo "Starting server..."
node server/server.js
```

添加执行权限：

```bash
chmod +x start.sh
```

### 5. 构建 Docker 镜像

```bash
docker build -t xiaogongju-app .
```

### 6. 运行 Docker 容器

```bash
docker run -d -p 3225:3225 --name xiaogongju --restart=always --env-file .env xiaogongju-app
```

### 7. 验证部署

```bash
# 检查容器是否运行
docker ps | grep xiaogongju

# 查看容器日志
docker logs xiaogongju

# 测试应用是否响应
curl http://localhost:3225
```

## 更新应用

当需要更新应用程序时，请按照以下步骤操作：

### 1. 获取最新代码

```bash
git pull origin main  # 或者你使用的分支名
```

### 2. 停止并删除现有容器

```bash
docker stop xiaogongju
docker rm xiaogongju
```

### 3. 重新构建镜像

```bash
docker build -t xiaogongju-app .
```

### 4. 运行新容器

```bash
docker run -d -p 3225:3225 --name xiaogongju --restart=always --env-file .env xiaogongju-app
```

### 5. 验证更新

```bash
docker logs xiaogongju
curl http://localhost:3225
```

## 常用操作

### 管理脚本

为了简化容器管理，可以创建以下管理脚本 `manage-docker.sh`：

```bash
#!/bin/bash

case "$1" in
  start)
    docker start xiaogongju
    ;;
  stop)
    docker stop xiaogongju
    ;;
  restart)
    docker restart xiaogongju
    ;;
  logs)
    docker logs -f xiaogongju
    ;;
  status)
    docker ps | grep xiaogongju
    ;;
  shell)
    docker exec -it xiaogongju /bin/sh
    ;;
  rebuild)
    docker stop xiaogongju || true
    docker rm xiaogongju || true
    docker build -t xiaogongju-app .
    docker run -d -p 3225:3225 --name xiaogongju --restart=always --env-file .env xiaogongju-app
    ;;
  *)
    echo "Usage: $0 {start|stop|restart|logs|status|shell|rebuild}"
    exit 1
    ;;
esac
```

添加执行权限：

```bash
chmod +x manage-docker.sh
```

使用方法：

```bash
./manage-docker.sh start    # 启动容器
./manage-docker.sh stop     # 停止容器
./manage-docker.sh restart  # 重启容器
./manage-docker.sh logs     # 查看日志
./manage-docker.sh status   # 查看状态
./manage-docker.sh shell    # 进入容器shell
./manage-docker.sh rebuild  # 重建并运行容器
```

### 查看容器详细信息

```bash
docker inspect xiaogongju
```

### 查看容器资源使用情况

```bash
docker stats xiaogongju
```

## 故障排除

### 容器无法启动

1. 检查日志：
   ```bash
   docker logs xiaogongju
   ```

2. 检查环境变量：
   ```bash
   docker exec -it xiaogongju /bin/sh -c "env"
   ```

3. 检查端口映射：
   ```bash
   docker port xiaogongju
   ```

4. 检查网络连接：
   ```bash
   docker exec -it xiaogongju /bin/sh -c "wget -O- http://localhost:3225"
   ```

### .env文件权限问题

如果在容器日志中看到类似以下错误：
```
更新.env文件失败: Error: EACCES: permission denied, open '/app/.env'
```

这是由于容器内部无法写入.env文件导致的。解决方法：

1. 确保.env文件在容器内有正确的权限：
   ```bash
   docker exec -it xiaogongju chmod 666 /app/.env
   ```

2. 如果使用docker-compose，确保在docker-compose.yml中正确挂载了.env文件：
   ```yaml
   volumes:
     - ./.env:/app/.env
   ```

3. 如果问题仍然存在，可以修改应用代码，使用环境变量而非.env文件进行配置更新。

### MongoDB 连接问题

1. 测试 MongoDB 连接：
   ```bash
   # 创建测试脚本
   cat > test-mongo.js << 'EOF'
   const mongoose = require('mongoose');
   const uri = process.env.MONGODB_URI;
   
   console.log('Attempting to connect to MongoDB...');
   console.log(`Connection string: ${uri.replace(/\/\/([^:]+):([^@]+)@/, '//***:***@')}`);
   
   mongoose.connect(uri, { useNewUrlParser: true, useUnifiedTopology: true })
     .then(() => {
       console.log('MongoDB connection successful!');
       mongoose.connection.close();
     })
     .catch(err => {
       console.error('MongoDB connection error:', err);
     });
   EOF
   
   # 在容器中运行测试脚本
   docker cp test-mongo.js xiaogongju:/app/
   docker exec -it xiaogongju node /app/test-mongo.js
   ```

2. 确保 MongoDB Atlas IP 白名单已配置（如果使用 MongoDB Atlas）

### 容器频繁重启

1. 检查应用程序错误：
   ```bash
   docker logs xiaogongju
   ```

2. 检查资源限制：
   ```bash
   docker stats xiaogongju
   ```

3. 尝试以交互方式运行容器：
   ```bash
   docker stop xiaogongju
   docker rm xiaogongju
   docker run -it --rm -p 3225:3225 --env-file .env xiaogongju-app /bin/sh
   # 在容器内手动启动应用
   node server/server.js
   ```

## 最佳实践

1. **定期备份**：
   - 定期备份 MongoDB 数据
   - 保存 Dockerfile 和环境配置

2. **监控**：
   - 设置容器监控
   - 配置日志轮转

3. **安全**：
   - 不要在 Dockerfile 中硬编码敏感信息
   - 使用 `.env` 文件管理环境变量
   - 定期更新基础镜像

4. **CI/CD**：
   - 考虑设置自动化部署流程
   - 使用 Docker Compose 或 Kubernetes 进行更复杂的部署

5. **版本控制**：
   - 为 Docker 镜像添加版本标签
   - 记录每次部署的版本和更改

---

如有任何问题或需要进一步的帮助，请联系项目维护人员。