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

Docker 部署与更新指南

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

目录

• 前提条件
• 初次部署
• 更新应用
• 常用操作
• 故障排除
• 最佳实践

前提条件

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

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

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

docker --version

初次部署

1. 获取代码

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

2. 配置环境变量

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

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

确保以下关键环境变量已正确设置：

• PORT: 应用程序监听端口 (默认: 3225)
• NODE_ENV: 环境 (development/production)
• MONGODB_URI: MongoDB 连接字符串
• 其他应用特定的环境变量

3. 创建 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 的文件，内容如下：

#!/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

添加执行权限：

chmod +x start.sh

5. 构建 Docker 镜像

docker build -t xiaogongju-app .

6. 运行 Docker 容器

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

7. 验证部署

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

# 查看容器日志
docker logs xiaogongju

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

更新应用

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

1. 获取最新代码

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

2. 停止并删除现有容器

docker stop xiaogongju
docker rm xiaogongju

3. 重新构建镜像

docker build -t xiaogongju-app .

4. 运行新容器

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

5. 验证更新

docker logs xiaogongju
curl http://localhost:3225

常用操作

管理脚本

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

#!/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

添加执行权限：

chmod +x manage-docker.sh

使用方法：

./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  # 重建并运行容器

查看容器详细信息

docker inspect xiaogongju

查看容器资源使用情况

docker stats xiaogongju

故障排除

容器无法启动

1. 检查日志：

   docker logs xiaogongju
   

2. 检查环境变量：

   docker exec -it xiaogongju /bin/sh -c "env"
   

3. 检查端口映射：

   docker port xiaogongju
   

4. 检查网络连接：

   docker exec -it xiaogongju /bin/sh -c "wget -O- http://localhost:3225"
   

.env文件权限问题

如果在容器日志中看到类似以下错误：

更新.env文件失败: Error: EACCES: permission denied, open '/app/.env'

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

1. 确保.env文件在容器内有正确的权限：

   docker exec -it xiaogongju chmod 666 /app/.env
   

2. 如果使用docker-compose，确保在docker-compose.yml中正确挂载了.env文件：

   volumes:
     - ./.env:/app/.env
   

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

MongoDB 连接问题

1. 测试 MongoDB 连接：

   # 创建测试脚本
   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. 检查应用程序错误：

   docker logs xiaogongju
   

2. 检查资源限制：

   docker stats xiaogongju
   

3. 尝试以交互方式运行容器：

   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 镜像添加版本标签
   • 记录每次部署的版本和更改

---

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